Gate only IPFS fetching on the gateway option, not cached content

isValidURL treated ipfs:// URIs as invalid whenever the gateway option
was off, and CacheManager consults that check before every cache path
lookup. Content that was downloaded and hash-verified while the option
was on therefore became unservable the moment it was switched off —
the cached bytes could not be served, checksummed, or evicted even
though serving a local file involves no gateway request (Bugbot,
PR Chia-Network#3029).

- isValidURL is now a structural check only: ipfs URIs are validated
  via their gateway form regardless of the preference.
- Fetching is gated where it happens instead: downloadFile,
  fetchBuffer, and fetchJSON resolve their request URL through a new
  toFetchableUrl, which throws IpfsGatewayDisabledError for ipfs URIs
  while the option is off.
- CacheManager rethrows that error instead of persisting it as a cache
  ERROR entry, so flipping the option on retries cleanly - a persisted
  'disabled' error would have poisoned the entry (only transient errors
  are ever retried).
- The single-download IPC handler drops ipfs URLs while the option is
  off instead of handing Chromium a URL it silently fails on.

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

Author: jlobue10

packages/gui/src/electron/CacheManager.ts

@@ -19,6 +19,7 @@ import downloadFile, { MAX_FILE_SIZE_EXCEEDED_ERROR } from './utils/downloadFile
 import ensureDirectoryExists from './utils/ensureDirectoryExists';
 import getChecksum from './utils/getChecksum';
 import ipcMainHandle from './utils/ipcMainHandle';
+import { IpfsGatewayDisabledError } from './utils/ipfsGateway';
 import isValidURL from './utils/isValidURL';
 import sanitizeFilename from './utils/sanitizeFilename';
 import sanitizeNumber from './utils/sanitizeNumber';
@@ -506,6 +507,15 @@ export default class CacheManager extends EventEmitter {
 
         return await this.#downloadLimit<CacheInfo>(() => limitedRemoteFileDownload());
       } catch (error) {
+        // Not a property of the URL, just of the current preference: while
+        // the IPFS gateway option is off the fetch is refused before it
+        // starts. Persisting that as a cache error would keep the entry
+        // poisoned after the user turns the option on, so it propagates
+        // instead — already-cached content was served above regardless.
+        if (error instanceof IpfsGatewayDisabledError) {
+          throw error;
+        }
+
         const currentError = (error as Error) ?? new Error('Unknown fetchRemoteContent error');
 
         return await this.setCacheInfo(url, {

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 { isIpfsUrl } from '../util/ipfs';
 
 import CacheManager, { CACHE_PROTOCOL } from './CacheManager';
 import { checkNFTOwnership } from './api/checkNFTOwnership';
@@ -578,8 +579,15 @@ if (ensureSingleInstance() && ensureCorrectEnvironment()) {
 
       // Chromium's downloader cannot fetch the ipfs: scheme; when the user
       // has enabled the gateway, download ipfs URIs through it like every
-      // other network path.
-      mainWindow.webContents.downloadURL(maybeIpfsToGatewayUrl(urlLocal));
+      // other network path. With the option off there is nothing the
+      // downloader could fetch, so the request is dropped instead of handing
+      // Chromium a URL it silently fails on.
+      const downloadUrl = maybeIpfsToGatewayUrl(urlLocal);
+      if (isIpfsUrl(downloadUrl)) {
+        return;
+      }
+
+      mainWindow.webContents.downloadURL(downloadUrl);
     });
 
     ipcMainHandle(AppAPI.START_MULTIPLE_DOWNLOAD, async (tasks: { url: string; filename: string }[]) => {

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

@@ -6,7 +6,7 @@ import debug from 'debug';
 import type Headers from '../../@types/Headers';
 
 import fileExists from './fileExists';
-import maybeIpfsToGatewayUrl from './ipfsGateway';
+import { toFetchableUrl } from './ipfsGateway';
 import isValidURL from './isValidURL';
 
 const log = debug('chia-gui:downloadFile');
@@ -102,10 +102,11 @@ export default async function downloadFile(
 
   const tempFilePath = `${localPath}.tmp`;
   // ipfs:// URIs are fetched through an HTTPS gateway when the user has
-  // enabled it — Electron's net stack cannot request the ipfs scheme. Only
+  // enabled it — Electron's net stack cannot request the ipfs scheme, and
+  // with the option off toFetchableUrl refuses the fetch outright. Only
   // this outgoing request uses the translated URL; callers keep the original
   // URI as the cache key.
-  const request = net.request(maybeIpfsToGatewayUrl(url));
+  const request = net.request(toFetchableUrl(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

@@ -2,7 +2,7 @@ import { net, type IncomingMessage } from 'electron';
 
 import type Headers from '../../@types/Headers';
 
-import maybeIpfsToGatewayUrl from './ipfsGateway';
+import { toFetchableUrl } from './ipfsGateway';
 import isValidURL from './isValidURL';
 
 const DEFAULT_TIMEOUT = 10 * 60 * 1000; // 10 minutes
@@ -43,8 +43,9 @@ export default async function fetchBuffer(
   const request = net.request({
     method: 'GET',
     // ipfs:// URIs are fetched through an HTTPS gateway when the user has
-    // enabled it — Electron's net stack cannot request the ipfs scheme.
-    url: maybeIpfsToGatewayUrl(url),
+    // enabled it — Electron's net stack cannot request the ipfs scheme, and
+    // with the option off toFetchableUrl refuses the fetch outright.
+    url: toFetchableUrl(url),
     headers,
   });
 

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

@@ -1,6 +1,6 @@
 import { net, IncomingMessage } from 'electron';
 
-import maybeIpfsToGatewayUrl from './ipfsGateway';
+import { toFetchableUrl } from './ipfsGateway';
 import isValidURL from './isValidURL';
 
 const DEFAULT_TIMEOUT = 10 * 60 * 1000; // 10 minutes
@@ -19,8 +19,9 @@ export default async function fetchJSON<TData>(
   const request = net.request({
     method,
     // ipfs:// URIs are fetched through an HTTPS gateway when the user has
-    // enabled it — Electron's net stack cannot request the ipfs scheme.
-    url: maybeIpfsToGatewayUrl(url),
+    // enabled it — Electron's net stack cannot request the ipfs scheme, and
+    // with the option off toFetchableUrl refuses the fetch outright.
+    url: toFetchableUrl(url),
     headers,
   });
 

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

@@ -7,6 +7,8 @@ jest.mock('../prefs', () => ({
 const {
   default: maybeIpfsToGatewayUrl,
   ipfsGatewayEnabled,
+  toFetchableUrl,
+  IpfsGatewayDisabledError,
   NFT_IPFS_GATEWAY_PREF,
 } = jest.requireActual<typeof import('./ipfsGateway')>('./ipfsGateway');
 
@@ -64,3 +66,30 @@ describe('maybeIpfsToGatewayUrl', () => {
     );
   });
 });
+
+describe('toFetchableUrl', () => {
+  beforeEach(() => {
+    mockReadPrefs.mockReset();
+  });
+
+  it('passes non-ipfs URLs through without consulting the preferences store', () => {
+    expect(toFetchableUrl('https://example.com/image.png')).toBe('https://example.com/image.png');
+    expect(mockReadPrefs).not.toHaveBeenCalled();
+  });
+
+  it('translates ipfs URIs when the gateway option is on', () => {
+    mockReadPrefs.mockReturnValue({ [NFT_IPFS_GATEWAY_PREF]: true });
+
+    expect(toFetchableUrl('ipfs://QmPK1s3pNYLi9ERiq3BDxKa4XosgWwFRQUydHUtz4YgpqB/img.png')).toBe(
+      'https://ipfs.io/ipfs/QmPK1s3pNYLi9ERiq3BDxKa4XosgWwFRQUydHUtz4YgpqB/img.png',
+    );
+  });
+
+  it('refuses ipfs URIs while the gateway option is off', () => {
+    mockReadPrefs.mockReturnValue({});
+
+    expect(() => toFetchableUrl('ipfs://QmPK1s3pNYLi9ERiq3BDxKa4XosgWwFRQUydHUtz4YgpqB')).toThrow(
+      IpfsGatewayDisabledError,
+    );
+  });
+});

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

@@ -30,3 +30,27 @@ export default function maybeIpfsToGatewayUrl(url: string): string {
 
   return ipfsToGatewayUrl(url);
 }
+
+// Thrown instead of attempting a fetch that cannot happen: with the gateway
+// option off there is no URL Electron's net stack could request for an
+// ipfs:// URI. CacheManager treats this error as non-persistent — flipping
+// the option on must retry cleanly, so it never poisons a cache entry.
+export class IpfsGatewayDisabledError extends Error {
+  constructor() {
+    super('IPFS gateway fetching is disabled');
+    this.name = 'IpfsGatewayDisabledError';
+  }
+}
+
+// The URL the network layer may actually request. The gateway option gates
+// only fetching: structural URL validation and serving already-cached content
+// stay independent of it, so every network call site funnels through here
+// instead of checking the option itself.
+export function toFetchableUrl(url: string): string {
+  const requestUrl = maybeIpfsToGatewayUrl(url);
+  if (isIpfsUrl(requestUrl)) {
+    throw new IpfsGatewayDisabledError();
+  }
+
+  return requestUrl;
+}

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

@@ -5,7 +5,6 @@ jest.mock('../prefs', () => ({
 }));
 
 const isValidURL = jest.requireActual<typeof import('./isValidURL')>('./isValidURL').default;
-const { NFT_IPFS_GATEWAY_PREF } = jest.requireActual<typeof import('./ipfsGateway')>('./ipfsGateway');
 
 describe('isValidURL', () => {
   beforeEach(() => {
@@ -23,23 +22,18 @@ describe('isValidURL', () => {
     expect(isValidURL('ftp://example.com/image.png')).toBe(false);
   });
 
-  it('accepts ipfs:// URIs with a CID host when the gateway option is on', () => {
-    mockReadPrefs.mockReturnValue({ [NFT_IPFS_GATEWAY_PREF]: true });
-
+  it('accepts ipfs:// URIs with a CID host regardless of the gateway option', () => {
     // validator's isURL rejects CID hosts (no TLD), so these pass only via
-    // the gateway translation
+    // the gateway-form translation. The check is structural on purpose: the
+    // gateway option gates fetching (toFetchableUrl), not validity — cache
+    // lookups for already-downloaded ipfs content must keep working while
+    // the option is off.
     expect(isValidURL('ipfs://bafybeiceg2gltyhlkukwetn26k7t2zdvthg4u4c6uj23rpni2adzgvo5si/020.png')).toBe(true);
     expect(isValidURL('ipfs://ipfs/QmPK1s3pNYLi9ERiq3BDxKa4XosgWwFRQUydHUtz4YgpqB')).toBe(true);
-  });
-
-  it('rejects ipfs:// URIs while the gateway option is off', () => {
-    expect(isValidURL('ipfs://bafybeiceg2gltyhlkukwetn26k7t2zdvthg4u4c6uj23rpni2adzgvo5si/020.png')).toBe(false);
-    expect(isValidURL('ipfs://ipfs/QmPK1s3pNYLi9ERiq3BDxKa4XosgWwFRQUydHUtz4YgpqB')).toBe(false);
+    expect(mockReadPrefs).not.toHaveBeenCalled();
   });
 
   it('rejects a bare ipfs scheme and non-strings', () => {
-    mockReadPrefs.mockReturnValue({ [NFT_IPFS_GATEWAY_PREF]: true });
-
     expect(isValidURL('ipfs://')).toBe(false);
     expect(isValidURL(undefined as unknown as string)).toBe(false);
   });

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

@@ -1,17 +1,22 @@
 import isURL from 'validator/lib/isURL';
 
-import maybeIpfsToGatewayUrl from './ipfsGateway';
+import ipfsToGatewayUrl, { isIpfsUrl } from '../../util/ipfs';
 
+// Structural validation only — deliberately independent of the IPFS gateway
+// preference. CacheManager consults this check before every cache path
+// lookup, so tying it to the preference would strand content that was
+// downloaded and hash-verified while the option was on: the cached bytes
+// could no longer be served, checksummed, or evicted after switching it off,
+// even though serving a local file involves no gateway request. Whether an
+// ipfs URI may actually be FETCHED is decided at the network call sites via
+// toFetchableUrl (electron/utils/ipfsGateway.ts).
 export default function isValidURL(url: string) {
   if (typeof url !== 'string') {
     return false;
   }
 
   // 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. When the user has enabled gateway fetching,
-  // validate the HTTPS gateway form instead — it is also the URL the network
-  // layer will actually request; while the option is off, ipfs URIs stay
-  // invalid and are never fetched.
-  return isURL(maybeIpfsToGatewayUrl(url), { protocols: ['https'], require_protocol: true });
+  // protocol is not enough — validate the HTTPS gateway form instead.
+  return isURL(isIpfsUrl(url) ? ipfsToGatewayUrl(url) : url, { protocols: ['https'], require_protocol: true });
 }