feat: check against urls with path

eslint-warning-thresholds.json

@@ -297,23 +297,17 @@
     "jsdoc/tag-lines": 1
   },
   "packages/phishing-controller/src/PhishingController.ts": {
-    "jsdoc/check-tag-names": 38,
+    "jsdoc/check-tag-names": 39,
     "jsdoc/tag-lines": 1
   },
-  "packages/phishing-controller/src/PhishingDetector.ts": {
-    "@typescript-eslint/no-unused-vars": 1,
-    "@typescript-eslint/prefer-readonly": 2,
-    "jsdoc/tag-lines": 2
-  },
   "packages/phishing-controller/src/tests/utils.ts": {
     "@typescript-eslint/no-unused-vars": 1
   },
   "packages/phishing-controller/src/utils.test.ts": {
     "import-x/namespace": 5
   },
   "packages/phishing-controller/src/utils.ts": {
-    "@typescript-eslint/no-unsafe-enum-comparison": 1,
-    "@typescript-eslint/no-unused-vars": 1
+    "@typescript-eslint/no-unsafe-enum-comparison": 1
   },
   "packages/polling-controller/src/AbstractPollingController.ts": {
     "@typescript-eslint/prefer-readonly": 1

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

@@ -0,0 +1,225 @@
+import {
+  deleteFromTrie,
+  isTerminalPath,
+  insertToTrie,
+  type PathTrie,
+} from './PathTrie';
+
+const emptyPathTrie: PathTrie = {};
+
+describe('PathTrie', () => {
+  describe('insertToTrie', () => {
+    let pathTrie: PathTrie;
+
+    beforeEach(() => {
+      pathTrie = {};
+    });
+
+    it('inserts a URL to the path trie', () => {
+      insertToTrie('example.com/path1/path2', pathTrie);
+
+      expect(pathTrie).toStrictEqual({
+        'example.com': {
+          path1: {
+            path2: {},
+          },
+        },
+      });
+    });
+
+    it('inserts sibling path', () => {
+      insertToTrie('example.com/path1', pathTrie);
+      insertToTrie('example.com/path2', pathTrie);
+
+      expect(pathTrie).toStrictEqual({
+        'example.com': {
+          path1: {},
+          path2: {},
+        },
+      });
+    });
+
+    it('multiple inserts', () => {
+      insertToTrie('example.com/path1/path2/path31', pathTrie);
+      insertToTrie('example.com/path1/path2/path32', pathTrie);
+      insertToTrie('example.com/path1/path2/path33/path4', pathTrie);
+      insertToTrie('example.com/path2', pathTrie);
+
+      expect(pathTrie).toStrictEqual({
+        'example.com': {
+          path1: {
+            path2: {
+              path31: {},
+              path32: {},
+              path33: {
+                path4: {},
+              },
+            },
+          },
+          path2: {},
+        },
+      });
+    });
+
+    it('idempotent', () => {
+      insertToTrie('example.com/path1/path2', pathTrie);
+      insertToTrie('example.com/path1/path2', pathTrie);
+
+      expect(pathTrie).toStrictEqual({
+        'example.com': {
+          path1: {
+            path2: {},
+          },
+        },
+      });
+    });
+
+    it('prunes descendants when adding ancestor', () => {
+      insertToTrie('example.com/path1/path2/path3', pathTrie);
+      expect(pathTrie).toStrictEqual({
+        'example.com': {
+          path1: {
+            path2: {
+              path3: {},
+            },
+          },
+        },
+      });
+
+      insertToTrie('example.com/path1', pathTrie);
+      expect(pathTrie).toStrictEqual({
+        'example.com': {
+          path1: {},
+        },
+      });
+    });
+
+    it('does not insert path1/path2 if path1 exists', () => {
+      insertToTrie('example.com/path1', pathTrie);
+      insertToTrie('example.com/path1/path2', pathTrie);
+
+      expect(pathTrie).toStrictEqual({
+        'example.com': {
+          path1: {},
+        },
+      });
+    });
+
+    it('does not insert if no path is provided', () => {
+      insertToTrie('example.com', pathTrie);
+
+      expect(pathTrie).toStrictEqual(emptyPathTrie);
+    });
+
+    it('treats trailing slash as equivalent', () => {
+      insertToTrie('example.com/path', pathTrie);
+      insertToTrie('example.com/path/', pathTrie);
+      expect(pathTrie).toStrictEqual({
+        'example.com': { path: {} },
+      });
+    });
+
+    it('accepts URLs with a scheme', () => {
+      insertToTrie('https://example.com/path', pathTrie);
+      expect(pathTrie).toStrictEqual({ 'example.com': { path: {} } });
+    });
+  });
+
+  describe('deleteFromTrie', () => {
+    let pathTrie: PathTrie;
+
+    beforeEach(() => {
+      pathTrie = {
+        'example.com': {
+          path11: {
+            path2: {},
+          },
+          path12: {},
+        },
+      };
+    });
+
+    it('deletes a path', () => {
+      deleteFromTrie('example.com/path11/path2', pathTrie);
+      expect(pathTrie).toStrictEqual({
+        'example.com': {
+          path12: {},
+        },
+      });
+    });
+
+    it('deletes all paths', () => {
+      deleteFromTrie('example.com/path11/path2', pathTrie);
+      deleteFromTrie('example.com/path12', pathTrie);
+      expect(pathTrie).toStrictEqual(emptyPathTrie);
+    });
+
+    it('deletes descendants if the path is not terminal', () => {
+      deleteFromTrie('example.com/path11', pathTrie);
+      expect(pathTrie).toStrictEqual({
+        'example.com': {
+          path12: {},
+        },
+      });
+    });
+
+    it('idempotent', () => {
+      deleteFromTrie('example.com/path11/path2', pathTrie);
+      deleteFromTrie('example.com/path11/path2', pathTrie);
+      expect(pathTrie).toStrictEqual({
+        'example.com': {
+          path12: {},
+        },
+      });
+    });
+
+    it('does nothing if the path does not exist within the trie', () => {
+      deleteFromTrie('example.com/nonexistent', pathTrie);
+      expect(pathTrie).toStrictEqual(pathTrie);
+    });
+
+    it('does nothing if the hostname does not exist', () => {
+      deleteFromTrie('nonexistent.com/path11/path2', pathTrie);
+      expect(pathTrie).toStrictEqual(pathTrie);
+    });
+
+    it('does nothing if no path is provided', () => {
+      deleteFromTrie('example.com', pathTrie);
+      expect(pathTrie).toStrictEqual(pathTrie);
+    });
+
+    it('deletes with a scheme', () => {
+      deleteFromTrie('https://example.com/path11/path2', pathTrie);
+      expect(pathTrie).toStrictEqual({
+        'example.com': {
+          path12: {},
+        },
+      });
+    });
+  });
+
+  describe('isTerminalPath', () => {
+    let pathTrie: PathTrie;
+
+    beforeEach(() => {
+      pathTrie = {
+        'example.com': {
+          path11: {
+            path2: {},
+          },
+        },
+      };
+    });
+
+    it.each([
+      ['terminal path', 'example.com/path11/path2', true],
+      ['ancestor path', 'example.com/path11', false],
+      ['non-existent path', 'example.com/path11/path3', false],
+      ['no path', 'example.com', false],
+      ['no hostname', 'nonexistent.com/path11/path2', false],
+      ['with a scheme', 'https://example.com/path11/path2', true],
+    ])('returns %s if the path is %s', (_name, path, expected) => {
+      expect(isTerminalPath(path, pathTrie)).toBe(expected);
+    });
+  });
+});

packages/phishing-controller/src/PathTrie.ts

@@ -0,0 +1,125 @@
+import { getHostnameAndPathComponents } from './utils';
+
+export type PathNode = {
+  [key: string]: PathNode;
+};
+
+export type PathTrie = Record<string, PathNode>;
+
+const isTerminal = (node: PathNode): boolean => {
+  return Object.keys(node).length === 0;
+};
+
+/**
+ * Insert a URL into the trie.
+ *
+ * @param url - The URL to insert into the trie.
+ * @param pathTrie - The trie to insert the URL into.
+ */
+export const insertToTrie = (url: string, pathTrie: PathTrie) => {
+  const { hostname, pathComponents } = getHostnameAndPathComponents(url);
+
+  if (pathComponents.length === 0 || !hostname) {
+    return;
+  }
+
+  const lowerHostname = hostname.toLowerCase();
+  if (!pathTrie[lowerHostname]) {
+    pathTrie[lowerHostname] = {} as PathNode;
+  }
+
+  let curr: PathNode = pathTrie[lowerHostname];
+  for (let i = 0; i < pathComponents.length; i++) {
+    const pathComponent = pathComponents[i];
+    const isLast = i === pathComponents.length - 1;
+    const exists = curr[pathComponent] !== undefined;
+
+    if (exists) {
+      if (!isLast && isTerminal(curr[pathComponent])) {
+        return;
+      }
+
+      if (isLast) {
+        // Prune descendants if the current path component is not terminal
+        if (!isTerminal(curr[pathComponent])) {
+          curr[pathComponent] = {};
+        }
+        return;
+      }
+      curr = curr[pathComponent];
+      continue;
+    }
+
+    if (isLast) {
+      curr[pathComponent] = {};
+      return;
+    }
+    const next: PathNode = {};
+    curr[pathComponent] = next;
+    curr = next;
+  }
+};
+
+/**
+ * Delete a URL from the trie.
+ *
+ * @param url - The URL to delete from the trie.
+ * @param pathTrie - The trie to delete the URL from.
+ */
+export const deleteFromTrie = (url: string, pathTrie: PathTrie) => {
+  const { hostname, pathComponents } = getHostnameAndPathComponents(url);
+
+  const lowerHostname = hostname.toLowerCase();
+  if (pathComponents.length === 0 || !pathTrie[lowerHostname]) {
+    return;
+  }
+
+  const pathToNode: { node: PathNode; key: string }[] = [
+    { node: pathTrie, key: lowerHostname },
+  ];
+  let curr: PathNode = pathTrie[lowerHostname];
+  for (const pathComponent of pathComponents) {
+    if (!curr[pathComponent]) {
+      return;
+    }
+
+    pathToNode.push({ node: curr, key: pathComponent });
+    curr = curr[pathComponent];
+  }
+
+  const lastEntry = pathToNode[pathToNode.length - 1];
+  delete lastEntry.node[lastEntry.key];
+  for (let i = pathToNode.length - 2; i >= 0; i--) {
+    const { node, key } = pathToNode[i];
+    if (isTerminal(node[key])) {
+      delete node[key];
+    } else {
+      break;
+    }
+  }
+};
+
+/**
+ * Check if a URL is a terminal path i.e. the last path component is a terminal node.
+ *
+ * @param url - The URL to check.
+ * @param pathTrie - The trie to check the URL in.
+ * @returns True if the URL is a terminal path, false otherwise.
+ */
+export const isTerminalPath = (url: string, pathTrie: PathTrie): boolean => {
+  const { hostname, pathComponents } = getHostnameAndPathComponents(url);
+
+  const lowerHostname = hostname.toLowerCase();
+  if (pathComponents.length === 0 || !hostname || !pathTrie[lowerHostname]) {
+    return false;
+  }
+
+  let curr: PathNode = pathTrie[lowerHostname];
+  for (const pathComponent of pathComponents) {
+    if (!curr[pathComponent]) {
+      return false;
+    }
+    curr = curr[pathComponent];
+  }
+  return isTerminal(curr);
+};