feat: path-based scanning of urls (MetaMask#8662)

## Explanation

Why: Dapp scanning now supports path-level dapp scanning. Without this
client-side change, the API never receives paths and the path-scanning
capability goes unused.
<!--
Thanks for your contribution! Take a moment to answer these questions so
that reviewers have the information they need to properly understand
your changes:

* What is the current state of things and why does it need to change?
* What is the solution your changes offer and how does it work?
* Are there any changes whose purpose might not obvious to those
unfamiliar with the domain?
* If your primary goal was to update one package but you found you had
to update another one along the way, why did you do so?
* If you had to upgrade a dependency, why did you do so?
-->

## References

<!--
Are there any issues that this pull request is tied to?
Are there other links that reviewers should consult to understand these
changes better?
Are there client or consumer pull requests to adopt any breaking
changes?

For example:

* Fixes #12345
* Related to #67890
-->

Fixes:
https://consensyssoftware.atlassian.net/jira/software/c/projects/PSAFE/boards/1950?selectedIssue=PSAFE-419
Extension PR: MetaMask/metamask-extension#42311

## Screenshots
I've ran MetaMask Extension locally with these changes. Paths are now
included in the API request.
<img width="483" height="119" alt="image"
src="https://github.com/user-attachments/assets/ce278da6-fa90-4e7c-9ac2-90e4ecfd671f"
/>


## Checklist

- [ ] I've updated the test suite for new or updated code as appropriate
- [ ] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [ ] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md)
- [ ] I've introduced [breaking
changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md)
in this PR and have prepared draft pull requests for clients and
consumer packages to resolve them



<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Modifies `scanUrl` request/caching semantics to sometimes key on
`hostname+pathname`, which can change phishing detection outcomes and
cache behavior for gateway domains and could affect API load if
misclassified.
> 
> **Overview**
> **Adds path-aware phishing URL scanning for shared gateway hosts.**
`PhishingController.scanUrl` now sends `hostname+pathname` (instead of
hostname-only) for a curated set of gateway root domains and subdomains,
and caches results by this scan parameter.
> 
> Introduces new utilities/constants
(`PHISHING_DETECTION_PATH_BASED_ROOT_DOMAINS`,
`isPhishingDetectionPathBasedHostname`,
`getPhishingDetectionScanUrlParam`), exports them from `index.ts`, and
updates tests/changelog to cover the new request format and per-path
caching behavior.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
74ef4dc. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: mindofmar

packages/phishing-controller/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Support path-based phishing lists (`blocklistPaths`, `whitelistPaths`) and path-aware URL scanning for shared gateways (for example IPFS gateways and `sites.google.com`) via `getPhishingDetectionScanUrlParam`, `isPhishingDetectionPathBasedHostname`, and `PHISHING_DETECTION_PATH_BASED_ROOT_DOMAINS` ([#8662](https://github.com/MetaMask/core/pull/8662))
+
 ### Changed
 
 - Bump `@metamask/controller-utils` from `^12.0.0` to `^12.1.0` ([#8774](https://github.com/MetaMask/core/pull/8774))

packages/phishing-controller/src/PhishingController-method-action-types.ts

@@ -59,8 +59,9 @@ export type PhishingControllerBypassAction = {
 };
 
 /**
- * Scan a URL for phishing. It will only scan the hostname of the URL. It also only supports
- * web URLs.
+ * Scan a URL for phishing. For most hosts only the hostname is sent to the API; for known
+ * shared gateways the pathname is included (see `PHISHING_DETECTION_PATH_BASED_ROOT_DOMAINS`).
+ * Only supports web URLs (`http:` / `https:`).
  *
  * @param url - The URL to scan.
  * @returns The phishing detection scan result.

packages/phishing-controller/src/PhishingController.test.ts

@@ -2813,7 +2813,7 @@ describe('PhishingController', () => {
     it('should return a PhishingDetectionScanResult with a fetchError on timeout', async () => {
       const scope = nock(PHISHING_DETECTION_BASE_URL)
         .get(`/${PHISHING_DETECTION_SCAN_ENDPOINT}`)
-        .query({ url: testUrl })
+        .query({ url: 'example.com' })
         .delayConnection(10000)
         .reply(200, {});
 
@@ -2935,6 +2935,56 @@ describe('PhishingController', () => {
       expect(response).toMatchObject(mockResponse);
       expect(scope.isDone()).toBe(true);
     });
+
+    it('should send hostname and path for path-based gateways and cache per path', async () => {
+      const urlA = 'https://ipfs.io/ipfs/QmAAA';
+      const urlB = 'https://ipfs.io/ipfs/QmBBB';
+
+      const scopeA = nock(PHISHING_DETECTION_BASE_URL)
+        .get(`/${PHISHING_DETECTION_SCAN_ENDPOINT}`)
+        .query({ url: 'ipfs.io/ipfs/QmAAA' })
+        .reply(200, {
+          recommendedAction: RecommendedAction.Warn,
+        });
+
+      const scopeB = nock(PHISHING_DETECTION_BASE_URL)
+        .get(`/${PHISHING_DETECTION_SCAN_ENDPOINT}`)
+        .query({ url: 'ipfs.io/ipfs/QmBBB' })
+        .reply(200, {
+          recommendedAction: RecommendedAction.Block,
+        });
+
+      const fetchSpy = jest.spyOn(global, 'fetch');
+
+      const resultA1 = await rootMessenger.call(
+        'PhishingController:scanUrl',
+        urlA,
+      );
+      const resultB = await rootMessenger.call(
+        'PhishingController:scanUrl',
+        urlB,
+      );
+      const resultA2 = await rootMessenger.call(
+        'PhishingController:scanUrl',
+        urlA,
+      );
+
+      expect(resultA1).toMatchObject({
+        hostname: 'ipfs.io',
+        recommendedAction: RecommendedAction.Warn,
+      });
+      expect(resultB).toMatchObject({
+        hostname: 'ipfs.io',
+        recommendedAction: RecommendedAction.Block,
+      });
+      expect(resultA2).toStrictEqual(resultA1);
+
+      expect(scopeA.isDone()).toBe(true);
+      expect(scopeB.isDone()).toBe(true);
+      expect(fetchSpy).toHaveBeenCalledTimes(2);
+
+      fetchSpy.mockRestore();
+    });
   });
 
   describe('bulkScanUrls', () => {

packages/phishing-controller/src/PhishingController.ts

@@ -48,6 +48,7 @@ import {
   getHostnameFromUrl,
   roundToNearestMinute,
   getHostnameFromWebUrl,
+  getPhishingDetectionScanUrlParam,
   buildCacheKey,
   splitCacheHits,
   resolveChainName,
@@ -910,31 +911,34 @@ export class PhishingController extends BaseController<
   }
 
   /**
-   * Scan a URL for phishing. It will only scan the hostname of the URL. It also only supports
-   * web URLs.
+   * Scan a URL for phishing. For most hosts only the hostname is sent to the API; for known
+   * shared gateways the pathname is included (see `PHISHING_DETECTION_PATH_BASED_ROOT_DOMAINS`).
+   * Only supports web URLs (`http:` / `https:`).
    *
    * @param url - The URL to scan.
    * @returns The phishing detection scan result.
    */
   async scanUrl(url: string): Promise<PhishingDetectionScanResult> {
-    const [hostname, ok] = getHostnameFromWebUrl(url);
-    if (!ok) {
+    const [scanUrlParam, scanParamOk] = getPhishingDetectionScanUrlParam(url);
+    if (!scanParamOk) {
       return {
         hostname: '',
         recommendedAction: RecommendedAction.None,
         fetchError: 'url is not a valid web URL',
       };
     }
 
-    const cachedResult = this.#urlScanCache.get(hostname);
+    const [hostname] = getHostnameFromWebUrl(url);
+
+    const cachedResult = this.#urlScanCache.get(scanUrlParam);
     if (cachedResult) {
       return cachedResult;
     }
 
     const apiResponse = await safelyExecuteWithTimeout(
       async () => {
         const res = await fetch(
-          `${PHISHING_DETECTION_BASE_URL}/${PHISHING_DETECTION_SCAN_ENDPOINT}?url=${encodeURIComponent(hostname)}`,
+          `${PHISHING_DETECTION_BASE_URL}/${PHISHING_DETECTION_SCAN_ENDPOINT}?url=${encodeURIComponent(scanUrlParam)}`,
           {
             method: 'GET',
             headers: {
@@ -974,7 +978,7 @@ export class PhishingController extends BaseController<
       recommendedAction: apiResponse.recommendedAction,
     };
 
-    this.#urlScanCache.set(hostname, result);
+    this.#urlScanCache.set(scanUrlParam, result);
 
     return result;
   }

packages/phishing-controller/src/index.ts

@@ -29,6 +29,11 @@ export {
   ApprovalFeatureType,
 } from './types';
 export type { CacheEntry } from './CacheManager';
+export {
+  PHISHING_DETECTION_PATH_BASED_ROOT_DOMAINS,
+  getPhishingDetectionScanUrlParam,
+  isPhishingDetectionPathBasedHostname,
+} from './utils';
 
 export type {
   PhishingControllerMaybeUpdateStateAction,

packages/phishing-controller/src/utils.test.ts

@@ -10,6 +10,8 @@ import {
   getHostnameAndPathComponents,
   getHostnameFromUrl,
   getHostnameFromWebUrl,
+  getPhishingDetectionScanUrlParam,
+  isPhishingDetectionPathBasedHostname,
   matchPartsAgainstList,
   processConfigs,
   processDomainList,
@@ -981,6 +983,54 @@ describe('getHostnameFromWebUrl', () => {
   );
 });
 
+describe('isPhishingDetectionPathBasedHostname', () => {
+  it('returns true for registered roots and subdomains', () => {
+    expect(isPhishingDetectionPathBasedHostname('ipfs.io')).toBe(true);
+    expect(isPhishingDetectionPathBasedHostname('gateway.ipfs.io')).toBe(true);
+    expect(isPhishingDetectionPathBasedHostname('dweb.link')).toBe(true);
+    expect(isPhishingDetectionPathBasedHostname('sites.google.com')).toBe(true);
+  });
+
+  it('is case-insensitive', () => {
+    expect(isPhishingDetectionPathBasedHostname('IPFS.IO')).toBe(true);
+    expect(isPhishingDetectionPathBasedHostname('Gateway.IPFS.IO')).toBe(true);
+  });
+
+  it('returns false for unrelated hosts', () => {
+    expect(isPhishingDetectionPathBasedHostname('example.com')).toBe(false);
+    expect(isPhishingDetectionPathBasedHostname('evil-ipfs.io')).toBe(false);
+  });
+});
+
+describe('getPhishingDetectionScanUrlParam', () => {
+  it('returns hostname only for non-gateway hosts', () => {
+    expect(
+      getPhishingDetectionScanUrlParam('https://example.com/path?q=1#h'),
+    ).toStrictEqual(['example.com', true]);
+  });
+
+  it('returns hostname plus path for path-based gateway hosts', () => {
+    expect(
+      getPhishingDetectionScanUrlParam(
+        'https://ipfs.io/ipfs/QmAAA/foo?x=1#frag',
+      ),
+    ).toStrictEqual(['ipfs.io/ipfs/QmAAA/foo', true]);
+  });
+
+  it('does not append path when pathname is /', () => {
+    expect(
+      getPhishingDetectionScanUrlParam('https://dweb.link/'),
+    ).toStrictEqual(['dweb.link', true]);
+  });
+
+  it('returns ok false for invalid web URLs', () => {
+    expect(getPhishingDetectionScanUrlParam('not-a-url')).toStrictEqual([
+      '',
+      false,
+    ]);
+  });
+});
+
 /**
  * Extracts the domain name (e.g., example.com) from a given hostname.
  *

packages/phishing-controller/src/utils.ts

@@ -365,6 +365,60 @@ export const getHostnameFromWebUrl = (url: string): [string, boolean] => {
   return [hostname || '', Boolean(hostname)];
 };
 
+/**
+ * Hosts where PDS single-URL scans include the URL path (shared gateways / hosts where many sites
+ * share one origin). For all other hosts, only the hostname is sent.
+ */
+export const PHISHING_DETECTION_PATH_BASED_ROOT_DOMAINS = [
+  'ipfs.io',
+  'dweb.link',
+  'cf-ipfs.com',
+  'cloudflare-ipfs.com',
+  'irys.xyz',
+  'sites.google.com',
+] as const;
+
+/**
+ * @param hostname - Lowercase normalization is applied for matching registered roots and subdomains.
+ * @returns Whether {@link getPhishingDetectionScanUrlParam} appends pathname for this hostname.
+ */
+export function isPhishingDetectionPathBasedHostname(
+  hostname: string,
+): boolean {
+  const normalizedHost = hostname.toLowerCase();
+  return PHISHING_DETECTION_PATH_BASED_ROOT_DOMAINS.some(
+    (root) => normalizedHost === root || normalizedHost.endsWith(`.${root}`),
+  );
+}
+
+/**
+ * Builds the `url` query parameter for {@link PhishingController.scanUrl}. For hosts in
+ * {@link PHISHING_DETECTION_PATH_BASED_ROOT_DOMAINS} (and their subdomains), the value is hostname
+ * plus pathname, without protocol, query, or fragment. For all other hosts, only hostname is used.
+ *
+ * @param url - A web URL string (must use `http:` or `https:` — same rules as {@link getHostnameFromWebUrl}).
+ * @returns A tuple of `[scanUrlParam, ok]` where `ok` is false when the URL is not a valid web URL.
+ */
+export const getPhishingDetectionScanUrlParam = (
+  url: string,
+): [scanUrlParam: string, ok: boolean] => {
+  const [hostname, ok] = getHostnameFromWebUrl(url);
+  if (!ok) {
+    return ['', false];
+  }
+
+  if (!isPhishingDetectionPathBasedHostname(hostname)) {
+    return [hostname, true];
+  }
+
+  // `getHostnameFromWebUrl` already required a successful `new URL(url)` parse.
+  const { pathname } = new URL(url);
+  const pathSuffix = pathname === '/' ? '' : pathname;
+  const scanUrlParam = pathSuffix ? `${hostname}${pathSuffix}` : hostname;
+
+  return [scanUrlParam, true];
+};
+
 export const getPathnameFromUrl = (url: string): string => {
   try {
     const { pathname } = new URL(url);