Fetch ipfs:// NFT resources through an HTTPS gateway

Some NFTs are minted with bare ipfs://<CID>/<path> data, metadata, or
license URIs instead of an HTTPS gateway URL. Every such URI failed
validation in the GUI cache layer with "Invalid URL: ipfs://...":
validator's isURL applies an FQDN check to the host, and a CID has no
top-level domain, so listing 'ipfs' as an allowed protocol never
actually accepted anything. Even when a caller ignored the validation
error, Electron's net stack cannot request the ipfs scheme, so the
media could never be fetched, verified, or cached.

Translate ipfs:// URIs to their HTTPS gateway form
(https://ipfs.io/ipfs/<CID>/<path>) in one shared helper and apply it

- in the electron isValidURL, which now validates the gateway form (the
  URL that is actually requested),
- at the outgoing request sites (downloadFile, fetchBuffer, fetchJSON)
  right where the URL reaches net.request,
- in the NFTHashStatus badge so ipfs URIs are no longer flagged as
  invalid in the renderer.

The original on-chain URI remains the cache key everywhere, so existing
cache entries, cache-info sidecars, and renderer lookups are unaffected.
The redundant ipfs://ipfs/<CID> form produced by some minting tools is
tolerated, and CID case is preserved (CIDv0 is case-sensitive base58).
The gateway does not need to be trusted for integrity: everything the
cache serves is verified against the NFT's on-chain hash.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vai5yNzPZwUSgid2nhQvys

Author: jlobue10

packages/gui/src/components/nfts/NFTHashStatus.tsx

@@ -8,6 +8,7 @@ import React, { useMemo } from 'react';
 
 import useNFT from '../../hooks/useNFT';
 import useNFTVerifyHash from '../../hooks/useNFTVerifyHash';
+import ipfsToGatewayUrl from '../../util/ipfs';
 
 export type NFTHashStatusProps = {
   nftId: string;
@@ -39,7 +40,9 @@ export default function NFTHashStatus(props: NFTHashStatusProps) {
     }
 
     if (nftPreview.uri) {
-      return isValidURL(nftPreview.uri);
+      // ipfs:// URIs are served through an HTTPS gateway by the cache layer,
+      // so validate the gateway form instead of flagging them as invalid.
+      return isValidURL(ipfsToGatewayUrl(nftPreview.uri));
     }
 
     return false;

packages/gui/src/electron/CacheManager.ts

@@ -7,7 +7,6 @@ import path from 'node:path';
 import { Readable } from 'node:stream';
 
 import debug from 'debug';
-import isURL from 'validator/lib/isURL';
 
 import type CacheInfo from '../@types/CacheInfo';
 import type CacheInfoBase from '../@types/CacheInfoBase';
@@ -417,7 +416,7 @@ export default class CacheManager extends EventEmitter {
 
         const normalizedURL = decodeURI(url) === url ? encodeURI(url) : url;
 
-        if (!isURL(normalizedURL)) {
+        if (!isValidURL(normalizedURL)) {
           throw new Error(`Invalid URL: ${normalizedURL}`);
         }
 

packages/gui/src/electron/utils/downloadFile.ts

@@ -4,6 +4,7 @@ import { promises as fs, createWriteStream, type WriteStream } from 'node:fs';
 import debug from 'debug';
 
 import type Headers from '../../@types/Headers';
+import ipfsToGatewayUrl from '../../util/ipfs';
 
 import fileExists from './fileExists';
 import isValidURL from './isValidURL';
@@ -91,7 +92,10 @@ export default async function downloadFile(
   }
 
   const tempFilePath = `${localPath}.tmp`;
-  const request = net.request(url);
+  // ipfs:// URIs are fetched through an HTTPS gateway — Electron's net stack
+  // cannot request the ipfs scheme. Only this outgoing request uses the
+  // translated URL; callers keep the original URI as the cache key.
+  const request = net.request(ipfsToGatewayUrl(url));
   const outputStream = new WriteStreamPromise(tempFilePath, overrideFile);
 
   // set when we abort the request ourselves, so abort events can be reported

packages/gui/src/electron/utils/fetchBuffer.ts

@@ -1,6 +1,7 @@
 import { net, type IncomingMessage } from 'electron';
 
 import type Headers from '../../@types/Headers';
+import ipfsToGatewayUrl from '../../util/ipfs';
 
 import isValidURL from './isValidURL';
 
@@ -41,7 +42,9 @@ export default async function fetchBuffer(
 
   const request = net.request({
     method: 'GET',
-    url,
+    // ipfs:// URIs are fetched through an HTTPS gateway — Electron's net
+    // stack cannot request the ipfs scheme.
+    url: ipfsToGatewayUrl(url),
     headers,
   });
 

packages/gui/src/electron/utils/fetchJSON.ts

@@ -1,5 +1,7 @@
 import { net, IncomingMessage } from 'electron';
 
+import ipfsToGatewayUrl from '../../util/ipfs';
+
 import isValidURL from './isValidURL';
 
 const DEFAULT_TIMEOUT = 10 * 60 * 1000; // 10 minutes
@@ -17,7 +19,9 @@ export default async function fetchJSON<TData>(
 
   const request = net.request({
     method,
-    url,
+    // ipfs:// URIs are fetched through an HTTPS gateway — Electron's net
+    // stack cannot request the ipfs scheme.
+    url: ipfsToGatewayUrl(url),
     headers,
   });
 

packages/gui/src/electron/utils/isValidURL.test.ts

@@ -0,0 +1,25 @@
+import isValidURL from './isValidURL';
+
+describe('isValidURL', () => {
+  it('accepts https URLs', () => {
+    expect(isValidURL('https://example.com/image.png')).toBe(true);
+  });
+
+  it('requires the protocol and rejects non-https schemes', () => {
+    expect(isValidURL('example.com/image.png')).toBe(false);
+    expect(isValidURL('http://example.com/image.png')).toBe(false);
+    expect(isValidURL('ftp://example.com/image.png')).toBe(false);
+  });
+
+  it('accepts ipfs:// URIs with a CID host', () => {
+    // validator's isURL rejects CID hosts (no TLD), so these pass only via
+    // the gateway translation
+    expect(isValidURL('ipfs://bafybeiceg2gltyhlkukwetn26k7t2zdvthg4u4c6uj23rpni2adzgvo5si/020.png')).toBe(true);
+    expect(isValidURL('ipfs://ipfs/QmPK1s3pNYLi9ERiq3BDxKa4XosgWwFRQUydHUtz4YgpqB')).toBe(true);
+  });
+
+  it('rejects a bare ipfs scheme and non-strings', () => {
+    expect(isValidURL('ipfs://')).toBe(false);
+    expect(isValidURL(undefined as unknown as string)).toBe(false);
+  });
+});

packages/gui/src/electron/utils/isValidURL.ts

@@ -1,9 +1,15 @@
 import isURL from 'validator/lib/isURL';
 
+import ipfsToGatewayUrl from '../../util/ipfs';
+
 export default function isValidURL(url: string) {
   if (typeof url !== 'string') {
     return false;
   }
 
-  return isURL(url, { protocols: ['https', 'ipfs'], require_protocol: true });
+  // isURL applies an FQDN check to the host, which every ipfs://<CID> URI
+  // fails (a CID has no top-level domain), so listing 'ipfs' as an allowed
+  // protocol is not enough. Validate the HTTPS gateway form instead — it is
+  // also the URL the network layer will actually request.
+  return isURL(ipfsToGatewayUrl(url), { protocols: ['https'], require_protocol: true });
 }

packages/gui/src/util/ipfs.test.ts

@@ -0,0 +1,53 @@
+import ipfsToGatewayUrl, { IPFS_GATEWAY_BASE, getIpfsPath, isIpfsUrl } from './ipfs';
+
+// CID taken from a real mainnet NFT whose on-chain data URI is ipfs://
+const CID_V1 = 'bafybeiceg2gltyhlkukwetn26k7t2zdvthg4u4c6uj23rpni2adzgvo5si';
+const CID_V0 = 'QmPK1s3pNYLi9ERiq3BDxKa4XosgWwFRQUydHUtz4YgpqB';
+
+describe('isIpfsUrl', () => {
+  it('matches the ipfs scheme case-insensitively', () => {
+    expect(isIpfsUrl(`ipfs://${CID_V1}/020.png`)).toBe(true);
+    expect(isIpfsUrl(`IPFS://${CID_V1}`)).toBe(true);
+  });
+
+  it('does not match other schemes', () => {
+    expect(isIpfsUrl(`https://ipfs.io/ipfs/${CID_V1}`)).toBe(false);
+    expect(isIpfsUrl('')).toBe(false);
+  });
+});
+
+describe('getIpfsPath', () => {
+  it('returns the CID and path', () => {
+    expect(getIpfsPath(`ipfs://${CID_V1}/020.png`)).toBe(`${CID_V1}/020.png`);
+    expect(getIpfsPath(`ipfs://${CID_V1}`)).toBe(CID_V1);
+  });
+
+  it('strips the redundant ipfs/ prefix some minting tools produce', () => {
+    expect(getIpfsPath(`ipfs://ipfs/${CID_V1}/020.png`)).toBe(`${CID_V1}/020.png`);
+  });
+
+  it('preserves the case of CIDv0 base58 hashes', () => {
+    expect(getIpfsPath(`ipfs://${CID_V0}/image.png`)).toBe(`${CID_V0}/image.png`);
+  });
+
+  it('returns undefined for non-ipfs URLs and a bare scheme', () => {
+    expect(getIpfsPath(`https://example.com/${CID_V1}`)).toBeUndefined();
+    expect(getIpfsPath('ipfs://')).toBeUndefined();
+  });
+});
+
+describe('ipfsToGatewayUrl', () => {
+  it('translates ipfs:// URIs to the HTTPS gateway', () => {
+    expect(ipfsToGatewayUrl(`ipfs://${CID_V1}/020.png`)).toBe(`${IPFS_GATEWAY_BASE}${CID_V1}/020.png`);
+    expect(ipfsToGatewayUrl(`ipfs://ipfs/${CID_V1}`)).toBe(`${IPFS_GATEWAY_BASE}${CID_V1}`);
+  });
+
+  it('returns non-ipfs URLs unchanged', () => {
+    const url = 'https://example.com/image.png?size=large';
+    expect(ipfsToGatewayUrl(url)).toBe(url);
+  });
+
+  it('returns an unusable bare scheme unchanged so validation rejects it', () => {
+    expect(ipfsToGatewayUrl('ipfs://')).toBe('ipfs://');
+  });
+});

packages/gui/src/util/ipfs.ts

@@ -0,0 +1,33 @@
+// The public HTTPS gateway used to serve ipfs:// resources. Electron's net
+// stack has no IPFS support, so ipfs:// URIs are fetched through a gateway.
+// The gateway does not need to be trusted for integrity: everything the cache
+// serves is checked against the NFT's on-chain hash before it is shown.
+export const IPFS_GATEWAY_BASE = 'https://ipfs.io/ipfs/';
+
+const IPFS_SCHEME = /^ipfs:\/\//i;
+
+export function isIpfsUrl(url: string): boolean {
+  return typeof url === 'string' && IPFS_SCHEME.test(url);
+}
+
+// Returns the `<CID>[/path]` part of an ipfs:// URI, tolerating the redundant
+// `ipfs://ipfs/<CID>` form produced by some minting tools. CIDv0 hashes are
+// case-sensitive base58, so the value is never case-normalized.
+export function getIpfsPath(url: string): string | undefined {
+  if (!isIpfsUrl(url)) {
+    return undefined;
+  }
+
+  const ipfsPath = url.replace(IPFS_SCHEME, '').replace(/^ipfs\//i, '');
+
+  return ipfsPath.length > 0 ? ipfsPath : undefined;
+}
+
+// Translates an ipfs:// URI to its HTTPS gateway equivalent. Anything else
+// (including an unusable bare `ipfs://`) is returned unchanged, so this can
+// wrap any URL right where it reaches the network layer.
+export default function ipfsToGatewayUrl(url: string): string {
+  const ipfsPath = getIpfsPath(url);
+
+  return ipfsPath === undefined ? url : `${IPFS_GATEWAY_BASE}${ipfsPath}`;
+}