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,
- at the single-NFT download handler, whose Chromium downloadURL cannot
  fetch the ipfs scheme either,
- in the oversized-image direct-URL fallback of the dapp dialog, whose
  CSP only allows https: and data: images,
- 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';
@@ -435,7 +434,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/api/nftGetMetadata.test.ts

@@ -104,6 +104,20 @@ describe('nftGetImageDataUrl', () => {
     );
   });
 
+  it('falls back to the gateway URL when an oversized image has an ipfs URI', async () => {
+    mockFetchBuffer.mockRejectedValue(
+      new MaxSizeExceededError({
+        'content-type': 'image/gif',
+      }),
+    );
+
+    // the dialog CSP only allows https: and data: images, so the raw ipfs
+    // URI would render as a broken image
+    await expect(nftGetImageDataUrl('ipfs://bafybeigdyrztest/large.gif', '00')).resolves.toBe(
+      'https://ipfs.io/ipfs/bafybeigdyrztest/large.gif',
+    );
+  });
+
   it('rejects an oversized response that is not an image', async () => {
     mockFetchBuffer.mockRejectedValue(
       new MaxSizeExceededError({

packages/gui/src/electron/api/nftGetMetadata.ts

@@ -2,6 +2,7 @@ import crypto from 'node:crypto';
 
 import type Headers from '../../@types/Headers';
 import compareChecksums from '../../util/compareChecksums';
+import ipfsToGatewayUrl from '../../util/ipfs';
 import fetchBuffer, { MaxSizeExceededError } from '../utils/fetchBuffer';
 
 const METADATA_TIMEOUT = 10_000;
@@ -99,8 +100,10 @@ export async function nftGetImageDataUrl(
     // An image too large to inline cannot be hash-verified without unbounded
     // buffering. Fall back to the direct URL — the dialog CSP still allows
     // https: images, matching the pre-verification behavior for these files.
+    // The CSP does not allow the ipfs: scheme, so ipfs URIs fall back to
+    // their gateway form.
     if (error instanceof MaxSizeExceededError && getImageContentType(error.headers)) {
-      return imageUri;
+      return ipfsToGatewayUrl(imageUri);
     }
 
     // image previews are best effort — the confirmation dialog has a fallback

packages/gui/src/electron/main.tsx

@@ -29,6 +29,7 @@ import type { PermissionsNotificationPayload } from '../@types/PermissionsServic
 import { WcError, WcErrorCode, encodeWcErrorForIpc } from '../@types/WcError';
 import AppIcon from '../assets/img/chia64x64.png';
 import { i18n } from '../config/locales';
+import ipfsToGatewayUrl from '../util/ipfs';
 
 import CacheManager, { CACHE_PROTOCOL } from './CacheManager';
 import { checkNFTOwnership } from './api/checkNFTOwnership';
@@ -575,7 +576,9 @@ if (ensureSingleInstance() && ensureCorrectEnvironment()) {
         return;
       }
 
-      mainWindow.webContents.downloadURL(urlLocal);
+      // Chromium's downloader cannot fetch the ipfs: scheme; download ipfs
+      // URIs through the HTTPS gateway like every other network path.
+      mainWindow.webContents.downloadURL(ipfsToGatewayUrl(urlLocal));
     });
 
     ipcMainHandle(AppAPI.START_MULTIPLE_DOWNLOAD, async (tasks: { url: string; filename: string }[]) => {

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';
@@ -100,7 +101,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 });
 }