Make IPFS gateway fetching a user-selectable option

Review feedback on the gateway feature: the gateway URL is technically
not the URI recorded on chain, so translating ipfs:// URIs to
https://ipfs.io/ipfs/... should be something the user opts into rather
than automatic behavior.

- New 'Fetch IPFS content through a gateway' switch in Settings > NFT,
  off by default. While off, ipfs:// URIs behave as before the gateway
  feature: they fail URL validation and are never fetched, and the
  NFTHashStatus badge flags them again.
- The preference is stored as nftIpfsGateway via the existing
  prefs.yaml round-trip; the main process reads the persisted value
  through electron/utils/ipfsGateway.ts (fail-closed when the store is
  unreadable) at every site that translated URLs: isValidURL,
  downloadFile, fetchBuffer, fetchJSON, the single-NFT download
  handler, and the dapp dialog's oversized-image fallback. The ipfs
  scheme check runs before the preference read so non-ipfs requests
  never touch the store.
- The oversized-image fallback returns no preview (instead of a
  CSP-blocked raw ipfs URI) while the option is off.
- Nothing is persisted for a rejected ipfs URL (the outer isValidURL
  guard throws before the cache-info error sidecar is written), so
  enabling the option retries previously failing NFTs cleanly.
- util/ipfs.ts stays a pure translation helper shared with the
  renderer; the preference gate lives only in the electron layer and
  the useIpfsGateway hook.

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

Author: jlobue10

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

@@ -6,6 +6,7 @@ import { Chip, Typography } from '@mui/material';
 import CircularProgress from '@mui/material/CircularProgress';
 import React, { useMemo } from 'react';
 
+import useIpfsGateway from '../../hooks/useIpfsGateway';
 import useNFT from '../../hooks/useNFT';
 import useNFTVerifyHash from '../../hooks/useNFTVerifyHash';
 import ipfsToGatewayUrl from '../../util/ipfs';
@@ -28,6 +29,7 @@ export default function NFTHashStatus(props: NFTHashStatusProps) {
   });
 
   const { nft, isLoading: isLoadingNFT, error: errorNFT } = useNFT(nftId);
+  const [ipfsGateway] = useIpfsGateway();
 
   const isLoading = isLoadingNFTVerifyHash || isLoadingNFT;
   const isVerified = preview ? nftPreview?.isVerified : data?.isVerified;
@@ -40,13 +42,15 @@ export default function NFTHashStatus(props: NFTHashStatusProps) {
     }
 
     if (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));
+      // While the user has IPFS gateway fetching enabled, ipfs:// URIs are
+      // served through an HTTPS gateway by the cache layer, so validate the
+      // gateway form instead of flagging them as invalid. With the option
+      // off they are not fetchable and stay flagged.
+      return isValidURL(ipfsGateway ? ipfsToGatewayUrl(nftPreview.uri) : nftPreview.uri);
     }
 
     return false;
-  }, [nftPreview]);
+  }, [nftPreview, ipfsGateway]);
 
   const icon = useMemo(() => {
     if (hideIcon) {

packages/gui/src/components/settings/SettingsNFT.tsx

@@ -16,6 +16,7 @@ import React from 'react';
 
 import useCache from '../../hooks/useCache';
 import useHideObjectionableContent from '../../hooks/useHideObjectionableContent';
+import useIpfsGateway from '../../hooks/useIpfsGateway';
 import useNFTImageFittingMode from '../../hooks/useNFTImageFittingMode';
 import { useNFTVideoLoopGlobal } from '../../hooks/useNFTVideoLoop';
 
@@ -40,6 +41,7 @@ export default function SettingsGeneral() {
   const { cacheSize, clearCache, cacheDirectory, setCacheDirectory } = useCache();
   const [nftImageFittingMode, setNFTImageFittingMode] = useNFTImageFittingMode();
   const [nftVideoLoop, setNFTVideoLoop] = useNFTVideoLoopGlobal();
+  const [ipfsGateway, setIpfsGateway] = useIpfsGateway();
   // const [, setCacheFolder] = usePrefs('cacheFolder', '');
   const openDialog = useOpenDialog();
 
@@ -51,6 +53,10 @@ export default function SettingsGeneral() {
     setNFTVideoLoop(event.target.checked);
   }
 
+  function handleChangeIpfsGateway(event: React.ChangeEvent<HTMLInputElement>) {
+    setIpfsGateway(event.target.checked);
+  }
+
   async function clearNFTCache() {
     openDialog(
       <ConfirmDialog
@@ -144,6 +150,26 @@ export default function SettingsGeneral() {
         </Grid>
       </Grid>
 
+      <Grid container>
+        <Grid item style={{ width: '400px' }}>
+          <SettingsTitle>
+            <Trans>Fetch IPFS content through a gateway</Trans>
+          </SettingsTitle>
+        </Grid>
+        <Grid item container xs justifyContent="flex-end" marginTop="-6px">
+          <FormControlLabel control={<Switch checked={ipfsGateway} onChange={handleChangeIpfsGateway} />} />
+        </Grid>
+        <Grid item style={{ width: '400px' }}>
+          <SettingsText>
+            <Trans>
+              NFT files published with ipfs:// addresses will be downloaded through the public ipfs.io HTTPS gateway.
+              The requested URL differs from the address recorded on chain, but downloaded content is still verified
+              against the NFT's on-chain hash. When disabled, ipfs:// files are not fetched.
+            </Trans>
+          </SettingsText>
+        </Grid>
+      </Grid>
+
       <Grid item style={{ maxWidth: '400px' }}>
         <Flex flexDirection="column" gap={1}>
           <SettingsSection>

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

@@ -11,8 +11,17 @@ jest.mock('../utils/fetchBuffer', () => ({
     jest.requireActual<typeof import('../utils/fetchBuffer')>('../utils/fetchBuffer').MaxSizeExceededError,
 }));
 
+const mockMaybeIpfsToGatewayUrl = jest.fn<string, [string]>();
+
+jest.mock('../utils/ipfsGateway', () => ({
+  __esModule: true,
+  default: mockMaybeIpfsToGatewayUrl,
+}));
+
 const { MaxSizeExceededError } = jest.requireActual<typeof import('../utils/fetchBuffer')>('../utils/fetchBuffer');
 
+const ipfsToGatewayUrl = jest.requireActual<typeof import('../../util/ipfs')>('../../util/ipfs').default;
+
 const { nftGetImageDataUrl, nftGetMetadata } =
   jest.requireActual<typeof import('./nftGetMetadata')>('./nftGetMetadata');
 
@@ -59,6 +68,9 @@ describe('nftGetMetadata', () => {
 describe('nftGetImageDataUrl', () => {
   beforeEach(() => {
     mockFetchBuffer.mockReset();
+    mockMaybeIpfsToGatewayUrl.mockReset();
+    // gateway option off: URLs pass through untranslated
+    mockMaybeIpfsToGatewayUrl.mockImplementation((url) => url);
   });
 
   it('returns an immutable data URL for a verified image response', async () => {
@@ -104,7 +116,8 @@ describe('nftGetImageDataUrl', () => {
     );
   });
 
-  it('falls back to the gateway URL when an oversized image has an ipfs URI', async () => {
+  it('falls back to the gateway URL for an oversized ipfs image when the gateway option is on', async () => {
+    mockMaybeIpfsToGatewayUrl.mockImplementation(ipfsToGatewayUrl);
     mockFetchBuffer.mockRejectedValue(
       new MaxSizeExceededError({
         'content-type': 'image/gif',
@@ -118,6 +131,18 @@ describe('nftGetImageDataUrl', () => {
     );
   });
 
+  it('omits the preview for an oversized ipfs image while the gateway option is off', async () => {
+    mockFetchBuffer.mockRejectedValue(
+      new MaxSizeExceededError({
+        'content-type': 'image/gif',
+      }),
+    );
+
+    // an untranslated ipfs URI would be blocked by the dialog CSP, so no
+    // preview is returned at all
+    await expect(nftGetImageDataUrl('ipfs://bafybeigdyrztest/large.gif', '00')).resolves.toBeUndefined();
+  });
+
   it('rejects an oversized response that is not an image', async () => {
     mockFetchBuffer.mockRejectedValue(
       new MaxSizeExceededError({

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

@@ -2,8 +2,9 @@ import crypto from 'node:crypto';
 
 import type Headers from '../../@types/Headers';
 import compareChecksums from '../../util/compareChecksums';
-import ipfsToGatewayUrl from '../../util/ipfs';
+import { isIpfsUrl } from '../../util/ipfs';
 import fetchBuffer, { MaxSizeExceededError } from '../utils/fetchBuffer';
+import maybeIpfsToGatewayUrl from '../utils/ipfsGateway';
 
 const METADATA_TIMEOUT = 10_000;
 const METADATA_MAX_SIZE = 5 * 1024 * 1024;
@@ -101,9 +102,11 @@ export async function nftGetImageDataUrl(
     // 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.
+    // their gateway form, and only when the user has enabled the gateway —
+    // otherwise they get no preview rather than a CSP-blocked URL.
     if (error instanceof MaxSizeExceededError && getImageContentType(error.headers)) {
-      return ipfsToGatewayUrl(imageUri);
+      const directUrl = maybeIpfsToGatewayUrl(imageUri);
+      return isIpfsUrl(directUrl) ? undefined : directUrl;
     }
 
     // image previews are best effort — the confirmation dialog has a fallback

packages/gui/src/electron/main.tsx

@@ -29,7 +29,6 @@ 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';
@@ -62,6 +61,7 @@ import { dispatchPairRequest } from './utils/dispatchPairRequest';
 import downloadFile from './utils/downloadFile';
 import fetchJSON from './utils/fetchJSON';
 import ipcMainHandle from './utils/ipcMainHandle';
+import maybeIpfsToGatewayUrl from './utils/ipfsGateway';
 import isValidURL from './utils/isValidURL';
 import { loadConfig, checkConfigFileExists } from './utils/loadConfig';
 import { getDefaultLogPath, LogPathValidationError, resolveTrustedLogPath } from './utils/logPath';
@@ -576,9 +576,10 @@ if (ensureSingleInstance() && ensureCorrectEnvironment()) {
         return;
       }
 
-      // 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));
+      // 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));
     });
 
     ipcMainHandle(AppAPI.START_MULTIPLE_DOWNLOAD, async (tasks: { url: string; filename: string }[]) => {

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

@@ -4,9 +4,9 @@ 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 maybeIpfsToGatewayUrl from './ipfsGateway';
 import isValidURL from './isValidURL';
 
 const log = debug('chia-gui:downloadFile');
@@ -101,10 +101,11 @@ export default async function downloadFile(
   }
 
   const tempFilePath = `${localPath}.tmp`;
-  // 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));
+  // ipfs:// URIs are fetched through an HTTPS gateway when the user has
+  // enabled it — 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(maybeIpfsToGatewayUrl(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,8 +1,8 @@
 import { net, type IncomingMessage } from 'electron';
 
 import type Headers from '../../@types/Headers';
-import ipfsToGatewayUrl from '../../util/ipfs';
 
+import maybeIpfsToGatewayUrl from './ipfsGateway';
 import isValidURL from './isValidURL';
 
 const DEFAULT_TIMEOUT = 10 * 60 * 1000; // 10 minutes
@@ -42,9 +42,9 @@ export default async function fetchBuffer(
 
   const request = net.request({
     method: 'GET',
-    // ipfs:// URIs are fetched through an HTTPS gateway — Electron's net
-    // stack cannot request the ipfs scheme.
-    url: ipfsToGatewayUrl(url),
+    // 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),
     headers,
   });
 

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

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

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

@@ -0,0 +1,66 @@
+const mockReadPrefs = jest.fn<Record<string, any>, []>();
+
+jest.mock('../prefs', () => ({
+  readPrefs: mockReadPrefs,
+}));
+
+const {
+  default: maybeIpfsToGatewayUrl,
+  ipfsGatewayEnabled,
+  NFT_IPFS_GATEWAY_PREF,
+} = jest.requireActual<typeof import('./ipfsGateway')>('./ipfsGateway');
+
+describe('ipfsGatewayEnabled', () => {
+  beforeEach(() => {
+    mockReadPrefs.mockReset();
+  });
+
+  it('is disabled when the preference has never been set', () => {
+    mockReadPrefs.mockReturnValue({});
+
+    expect(ipfsGatewayEnabled()).toBe(false);
+  });
+
+  it('is enabled only by an explicit boolean true', () => {
+    mockReadPrefs.mockReturnValue({ [NFT_IPFS_GATEWAY_PREF]: true });
+    expect(ipfsGatewayEnabled()).toBe(true);
+
+    mockReadPrefs.mockReturnValue({ [NFT_IPFS_GATEWAY_PREF]: 'true' });
+    expect(ipfsGatewayEnabled()).toBe(false);
+  });
+
+  it('fails closed when the preferences store cannot be read', () => {
+    mockReadPrefs.mockImplementation(() => {
+      throw new Error('userDataDir needs to be initialized');
+    });
+
+    expect(ipfsGatewayEnabled()).toBe(false);
+  });
+});
+
+describe('maybeIpfsToGatewayUrl', () => {
+  beforeEach(() => {
+    mockReadPrefs.mockReset();
+  });
+
+  it('never consults the preferences store for non-ipfs URLs', () => {
+    expect(maybeIpfsToGatewayUrl('https://example.com/image.png')).toBe('https://example.com/image.png');
+    expect(mockReadPrefs).not.toHaveBeenCalled();
+  });
+
+  it('leaves ipfs URIs untranslated while the gateway option is off', () => {
+    mockReadPrefs.mockReturnValue({});
+
+    expect(maybeIpfsToGatewayUrl('ipfs://QmPK1s3pNYLi9ERiq3BDxKa4XosgWwFRQUydHUtz4YgpqB')).toBe(
+      'ipfs://QmPK1s3pNYLi9ERiq3BDxKa4XosgWwFRQUydHUtz4YgpqB',
+    );
+  });
+
+  it('translates ipfs URIs when the gateway option is on', () => {
+    mockReadPrefs.mockReturnValue({ [NFT_IPFS_GATEWAY_PREF]: true });
+
+    expect(maybeIpfsToGatewayUrl('ipfs://QmPK1s3pNYLi9ERiq3BDxKa4XosgWwFRQUydHUtz4YgpqB/img.png')).toBe(
+      'https://ipfs.io/ipfs/QmPK1s3pNYLi9ERiq3BDxKa4XosgWwFRQUydHUtz4YgpqB/img.png',
+    );
+  });
+});

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

@@ -0,0 +1,32 @@
+import ipfsToGatewayUrl, { isIpfsUrl } from '../../util/ipfs';
+import { readPrefs } from '../prefs';
+
+// Preference key shared with the renderer's useIpfsGateway hook. The renderer
+// persists it through PreferencesAPI.SAVE into prefs.yaml, which is the copy
+// consulted here in the main process.
+export const NFT_IPFS_GATEWAY_PREF = 'nftIpfsGateway';
+
+// Whether ipfs:// NFT resources may be fetched through the public HTTPS
+// gateway. Off by default: the gateway URL is not the URI recorded on chain,
+// so the translation is a user-selectable opt-in. Fails closed when the
+// preferences store is unreadable (e.g. before userData is initialized).
+export function ipfsGatewayEnabled(): boolean {
+  try {
+    return readPrefs()[NFT_IPFS_GATEWAY_PREF] === true;
+  } catch {
+    return false;
+  }
+}
+
+// Translates an ipfs:// URI to its HTTPS gateway equivalent only when the
+// user has enabled gateway fetching; every other URL — and every ipfs URI
+// while the option is off — is returned unchanged, so this can wrap any URL
+// right where it reaches the network layer. The ipfs check runs first so the
+// hot non-ipfs paths never touch the preferences store.
+export default function maybeIpfsToGatewayUrl(url: string): string {
+  if (!isIpfsUrl(url) || !ipfsGatewayEnabled()) {
+    return url;
+  }
+
+  return ipfsToGatewayUrl(url);
+}