fix: address release review feedback

Author: antonio-orionus

.github/workflows/release.yml

@@ -9,7 +9,6 @@ on:
 permissions:
   contents: write
   id-token: write
-  attestations: write
 
 env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'
@@ -113,6 +112,11 @@ jobs:
     needs: build-native
     if: startsWith(github.ref, 'refs/tags/')
     runs-on: ubuntu-latest
+    # Upload release assets and mint GitHub artifact attestations.
+    permissions:
+      contents: write
+      id-token: write
+      attestations: write
     steps:
       - uses: actions/checkout@v6
       - uses: actions/download-artifact@v8
@@ -126,8 +130,9 @@ jobs:
           cp scripts/install.ps1 release-assets/url-sanitize-installer.ps1
           chmod +x release-assets/url-sanitize-installer.sh
           (cd release-assets && sha256sum * > SHA256SUMS)
+      # actions/attest@v4 pinned on 2026-06-01.
       - name: Attest release assets
-        uses: actions/attest@v4
+        uses: actions/attest@281a49d4cbb0a72c9575a50d18f6deb515a11deb
         with:
           subject-path: release-assets/*
       - uses: softprops/action-gh-release@v3

docs/spec.md

@@ -293,6 +293,7 @@ serializes to identical JSON via `serde`.
 ## 8. Versioning
 
 All packages (`@url-sanitize/core`, `@url-sanitize/clearurls`, `@url-sanitize/cli`,
-`@url-sanitize/fetch`, `url-sanitize-core` crate, `url-sanitize` crate) version-bump together. The
-public API is governed by **semver of the result schema and CLI contract**, not
-by any single language binding. Breaking the schema is a major bump everywhere.
+`@url-sanitize/fetch`, `url-sanitize-core` crate, `url-sanitize` crate, and the
+Python package in `pyproject.toml`) version-bump together. The public API is
+governed by **semver of the result schema and CLI contract**, not by any single
+language binding. Breaking the schema is a major bump everywhere.

docs/threat-model.md

@@ -23,8 +23,13 @@ For consumers who need stronger guarantees (e.g. security-sensitive SaaS, regula
 ```ts
 import { fetchClearurlsCatalog } from '@url-sanitize/fetch';
 
+const pinnedHash = process.env.CLEARURLS_RULES_HASH;
+if (!pinnedHash) {
+  throw new Error('CLEARURLS_RULES_HASH is required');
+}
+
 const { catalog } = await fetchClearurlsCatalog({
-  pinnedHash: process.env.CLEARURLS_RULES_HASH
+  pinnedHash
 });
 ```
 

packages/core/test/catalog.test.ts

@@ -94,10 +94,15 @@ describe('JSON Schema exports', () => {
     const sanitize = compileSanitizer(mergeCatalogs(customCatalog, secondCatalog), {
       domainBlocking: true
     });
+    const redirected = sanitize(
+      `https://redirect.example/?to=${encodeURIComponent('https://target.example/')}`
+    );
+    expect(redirected.kind).toBe('redirected');
+
     const results: SanitizeResult[] = [
       sanitize('https://example.com/clean'),
       sanitize('https://example.com/?utm_source=newsletter&id=123'),
-      sanitize(`https://redirect.example/?to=${encodeURIComponent('https://target.example/')}`),
+      redirected,
       sanitize('https://blocked.example/')
     ];
 

packages/core/test/fuzz.test.ts

@@ -15,17 +15,36 @@ describe('fuzz — deterministic ReDoS guard', () => {
     });
     const rng = mulberry32(0x5eed_2026);
     let maxMs = 0;
+    let slowestInput = '';
+    let thrown:
+      | {
+          error: unknown;
+          index: number;
+          input: string;
+        }
+      | undefined;
 
     for (let index = 0; index < CASES; index += 1) {
       const input = randomUrl(rng, index);
       const started = performance.now();
-      expect(() => sanitize(input), `fuzz input ${index}: ${input}`).not.toThrow();
+      try {
+        sanitize(input);
+      } catch (error) {
+        thrown = { error, index, input };
+      }
       const elapsed = performance.now() - started;
-      maxMs = Math.max(maxMs, elapsed);
-      expect(elapsed, `fuzz input ${index}: ${input}`).toBeLessThan(MAX_SANITIZE_MS);
+      if (elapsed > maxMs) {
+        maxMs = elapsed;
+        slowestInput = `fuzz input ${index}: ${input}`;
+      }
+      if (thrown) break;
     }
 
-    expect(maxMs).toBeLessThan(MAX_SANITIZE_MS);
+    if (thrown) {
+      const message = thrown.error instanceof Error ? thrown.error.message : String(thrown.error);
+      throw new Error(`fuzz input ${thrown.index}: ${thrown.input}: ${message}`);
+    }
+    expect(maxMs, slowestInput).toBeLessThan(MAX_SANITIZE_MS);
   }, 20_000);
 });
 

packages/fetch/README.md

@@ -25,7 +25,8 @@ console.log(sanitize('https://example.com/?utm_source=x'));
 ```
 
 `pinnedHash` is optional. When set, the downloaded rules must match both the
-upstream `rules.minify.hash` and the consumer-provided pin.
+upstream `rules.minify.hash` and the consumer-provided pin. `timeoutMs` defaults
+to `10000` and bounds each rules/hash request.
 
 ## License
 

packages/fetch/src/index.ts

@@ -10,6 +10,7 @@ export interface FetchClearurlsCatalogOptions {
   rulesUrl?: string;
   hashUrl?: string;
   fetch?: typeof globalThis.fetch;
+  timeoutMs?: number;
 }
 
 export interface FetchClearurlsCatalogResult {
@@ -23,19 +24,21 @@ export async function fetchClearurlsCatalog(
 ): Promise<FetchClearurlsCatalogResult> {
   const rulesUrl = options.rulesUrl ?? DEFAULT_CLEARURLS_RULES_URL;
   const hashUrl = options.hashUrl ?? DEFAULT_CLEARURLS_HASH_URL;
-  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const fetchImpl =
+    options.fetch ?? (globalThis.fetch ? globalThis.fetch.bind(globalThis) : undefined);
+  const timeoutMs = options.timeoutMs ?? 10_000;
 
   if (!fetchImpl) {
     throw new Error('fetchClearurlsCatalog requires a fetch implementation');
   }
 
   const [rulesTextRaw, expectedHashRaw] = await Promise.all([
-    fetchText(fetchImpl, rulesUrl),
-    fetchText(fetchImpl, hashUrl)
+    fetchText(fetchImpl, rulesUrl, timeoutMs),
+    fetchText(fetchImpl, hashUrl, timeoutMs)
   ]);
   const rulesText = rulesTextRaw.trim();
   const expectedHash = normalizeSha256(expectedHashRaw, 'published hash');
-  const actualHash = await sha256Hex(rulesText);
+  const actualHash = await sha256Hex(rulesTextRaw);
 
   if (actualHash !== expectedHash) {
     throw new Error(`ClearURLs rules hash mismatch: expected ${expectedHash}, got ${actualHash}`);
@@ -63,14 +66,53 @@ export async function fetchClearurlsCatalog(
   };
 }
 
-async function fetchText(fetchImpl: typeof globalThis.fetch, url: string): Promise<string> {
-  const response = await fetchImpl(url);
+async function fetchText(
+  fetchImpl: typeof globalThis.fetch,
+  url: string,
+  timeoutMs: number
+): Promise<string> {
+  const { signal, cleanup } = createTimeoutSignal(timeoutMs);
+  let response: Response;
+  try {
+    response = await fetchImpl(url, { signal });
+  } catch (error) {
+    if (isAbortError(error)) {
+      throw new Error(`Fetch ${url} timed out after ${timeoutMs}ms`);
+    }
+    throw error;
+  } finally {
+    cleanup();
+  }
+
   if (!response.ok) {
     throw new Error(`Fetch ${url} failed: ${response.status} ${response.statusText}`.trim());
   }
   return response.text();
 }
 
+function createTimeoutSignal(timeoutMs: number): { cleanup: () => void; signal: AbortSignal } {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error('fetchClearurlsCatalog timeoutMs must be a positive finite number');
+  }
+
+  if (typeof AbortSignal.timeout === 'function') {
+    return { signal: AbortSignal.timeout(timeoutMs), cleanup: () => {} };
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  return {
+    signal: controller.signal,
+    cleanup: () => clearTimeout(timer)
+  };
+}
+
+function isAbortError(error: unknown): boolean {
+  return (
+    error instanceof DOMException && (error.name === 'AbortError' || error.name === 'TimeoutError')
+  );
+}
+
 function normalizeSha256(hash: string, label: string): string {
   const normalized = hash.trim().toLowerCase();
   if (!/^[0-9a-f]{64}$/.test(normalized)) {

packages/fetch/test/fetch.test.ts

@@ -37,6 +37,22 @@ describe('fetchClearurlsCatalog', () => {
     });
   });
 
+  it('hashes the raw rules text before parsing', async () => {
+    const rulesTextWithNewline = `${rulesText}\n`;
+    const rulesHashWithNewline = sha256(rulesTextWithNewline);
+
+    const result = await fetchClearurlsCatalog({
+      rulesUrl,
+      hashUrl,
+      fetch: fakeFetch({
+        [rulesUrl]: rulesTextWithNewline,
+        [hashUrl]: rulesHashWithNewline
+      })
+    });
+
+    expect(result.metadata.hash).toBe(rulesHashWithNewline);
+  });
+
   it('uses the injected fetch implementation', async () => {
     const seen: string[] = [];
     await fetchClearurlsCatalog({
@@ -51,6 +67,49 @@ describe('fetchClearurlsCatalog', () => {
     expect(seen.sort()).toEqual([hashUrl, rulesUrl].sort());
   });
 
+  it('binds the default fetch implementation to globalThis', async () => {
+    const originalFetch = globalThis.fetch;
+    const seenThisValues: unknown[] = [];
+    globalThis.fetch = async function (
+      this: typeof globalThis,
+      url: Parameters<typeof globalThis.fetch>[0]
+    ): Promise<Response> {
+      seenThisValues.push(this);
+      return textResponse(String(url) === rulesUrl ? rulesText : rulesHash);
+    } as typeof globalThis.fetch;
+
+    try {
+      await fetchClearurlsCatalog({ rulesUrl, hashUrl });
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+
+    expect(seenThisValues).toEqual([globalThis, globalThis]);
+  });
+
+  it('throws a timeout-specific error when a fetch stalls', async () => {
+    await expect(
+      fetchClearurlsCatalog({
+        rulesUrl,
+        hashUrl,
+        timeoutMs: 1,
+        fetch: (_url, init) =>
+          new Promise<Response>((_resolve, reject) => {
+            const signal = init?.signal;
+            if (!signal) {
+              reject(new Error('missing timeout signal'));
+              return;
+            }
+            signal.addEventListener(
+              'abort',
+              () => reject(new DOMException('timed out', 'TimeoutError')),
+              { once: true }
+            );
+          })
+      })
+    ).rejects.toThrow(/timed out after 1ms/);
+  });
+
   it('throws on HTTP failures', async () => {
     await expect(
       fetchClearurlsCatalog({
@@ -127,5 +186,5 @@ function textResponse(body: string, status = 200): Response {
 }
 
 function sha256(text: string): string {
-  return createHash('sha256').update(text.trim()).digest('hex');
+  return createHash('sha256').update(text).digest('hex');
 }

scripts/verify-release.mjs

@@ -56,16 +56,20 @@ if (uniqueVersions.size !== 1) {
 }
 
 const version = [...uniqueVersions][0];
-if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
-  errors.push(`invalid release version: ${version}`);
-}
+if (!version) {
+  errors.push('failed to resolve a release version from manifests');
+} else {
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+    errors.push(`invalid release version: ${version}`);
+  }
 
-if (!isStableReleaseVersion(version)) {
-  errors.push(`release version must be >= 1.0.0, got ${version}`);
-}
+  if (!isStableReleaseVersion(version)) {
+    errors.push(`release version must be >= 1.0.0, got ${version}`);
+  }
 
-if (args.tag && args.tag !== `v${version}`) {
-  errors.push(`tag ${args.tag} does not match release version v${version}`);
+  if (args.tag && args.tag !== `v${version}`) {
+    errors.push(`tag ${args.tag} does not match release version v${version}`);
+  }
 }
 
 const platforms = loadReleasePlatforms();