@zigrivers/scaffold 3.28.0 → 3.30.0

package/dist/knowledge-freshness/source-hash.d.ts

@@ -0,0 +1,39 @@
+import { type Resolver } from './source-url-validator.js';
+/** Production fetch implementation. Tests inject a mock via opts.fetchImpl. */
+export type FetchImpl = (input: string, init?: Record<string, unknown>) => Promise<Response>;
+/** Test-injectable options. Production callers omit this. */
+export interface FetchAndHashOptions {
+    resolver?: Resolver;
+    /** Per-fetch timeout in ms (each hop is bounded separately). Default 30s. */
+    timeoutMs?: number;
+    /** Body size ceiling in bytes. Default 5 MiB. */
+    maxBodyBytes?: number;
+    /**
+     * Override the fetch implementation. Used only by tests so they can
+     * mock responses without going to the network. Production uses undici's
+     * fetch so the pinning Agent dispatcher API matches.
+     */
+    fetchImpl?: FetchImpl;
+}
+/**
+ * GET a URL and sha256 its body. Used by:
+ *   - audit-prefilter: to detect upstream changes (compare fresh hash
+ *     against the frontmatter's stored hash)
+ *   - audit-apply: to compute deterministic hashes for persistence,
+ *     preferring them over LLM-emitted content_hash values
+ *
+ * Validates EVERY hop (initial URL + each redirect target) against the SSRF
+ * guard. A naive `fetch(url)` follows redirects automatically, so a source
+ * pointing at a public URL that 302's to localhost / 169.254.169.254 would
+ * bypass the guard (round-4 F-002). We do redirects manually, validate the
+ * Location header, and cap at MAX_REDIRECT_HOPS.
+ *
+ * Throws on guard failure, network failure, non-2xx final responses, or
+ * redirect-without-Location so callers can decide whether to skip
+ * (pre-filter) or abort (apply).
+ */
+export declare function fetchAndHash(url: string, opts?: FetchAndHashOptions): Promise<{
+    hash: string;
+    body: string;
+}>;
+//# sourceMappingURL=source-hash.d.ts.map

package/dist/knowledge-freshness/source-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-hash.d.ts","sourceRoot":"","sources":["../../src/knowledge-freshness/source-hash.ts"],"names":[],"mappings":"AAOA,OAAO,EAA+C,KAAK,QAAQ,EAAE,MAAM,2BAA2B,CAAA;AAEtG,+EAA+E;AAC/E,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;AAW5F,6DAA6D;AAC7D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAA;CACtB;AA+BD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CA4EzC"}

package/dist/knowledge-freshness/source-hash.js

@@ -0,0 +1,180 @@
+import { createHash } from 'node:crypto';
+import net from 'node:net';
+// Use undici's own fetch (not Node's built-in) so the Agent dispatcher we
+// pass matches the same undici version. Node's built-in fetch uses its
+// internally-bundled undici which can drift in dispatcher API from the
+// npm-installed package, producing "invalid onError method" at runtime.
+import { fetch as undiciFetch, Agent } from 'undici';
+import { assertSafeSourceUrlWithDns, defaultResolver } from './source-url-validator.js';
+const MAX_REDIRECT_HOPS = 5;
+const DEFAULT_FETCH_TIMEOUT_MS = 30_000;
+/**
+ * Cap on the response body. 5 MiB is comfortably larger than any real spec
+ * page (OWASP Top 10 is ~50 KiB) and small enough that even a malicious
+ * 100 MB response can't exhaust memory (round-7 F-003).
+ */
+const MAX_RESPONSE_BODY_BYTES = 5 * 1024 * 1024;
+/**
+ * Build an undici Agent whose connection lookup is pinned to a specific IP.
+ * Used to close the DNS-rebinding TOCTOU gap: the validator already resolved
+ * the hostname and approved every IP. Pinning fetch to one of those IPs
+ * prevents a second DNS lookup at fetch time from returning a private/
+ * loopback target (round-7 F-002).
+ *
+ * The undici lookup callback follows Node's `dns.lookup` signature, so we
+ * return the pinned IP directly without re-resolving.
+ */
+function pinningAgent(pinnedIp) {
+    const family = net.isIP(pinnedIp) === 6 ? 6 : 4;
+    // Node's `dns.lookup` callback has TWO forms depending on `opts.all`:
+    //   all=true  → callback(err, [{address, family}])
+    //   all=false → callback(err, address, family)
+    // undici can invoke either, so handle both shapes — otherwise we get
+    // `ERR_INVALID_IP_ADDRESS: Invalid IP address: undefined` when undici
+    // passes `{all: true}` and we call the 3-arg form.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const lookup = (_hostname, opts, callback) => {
+        if (opts && opts.all === true) {
+            callback(null, [{ address: pinnedIp, family }]);
+        }
+        else {
+            callback(null, pinnedIp, family);
+        }
+    };
+    return new Agent({ connect: { lookup } });
+}
+/**
+ * GET a URL and sha256 its body. Used by:
+ *   - audit-prefilter: to detect upstream changes (compare fresh hash
+ *     against the frontmatter's stored hash)
+ *   - audit-apply: to compute deterministic hashes for persistence,
+ *     preferring them over LLM-emitted content_hash values
+ *
+ * Validates EVERY hop (initial URL + each redirect target) against the SSRF
+ * guard. A naive `fetch(url)` follows redirects automatically, so a source
+ * pointing at a public URL that 302's to localhost / 169.254.169.254 would
+ * bypass the guard (round-4 F-002). We do redirects manually, validate the
+ * Location header, and cap at MAX_REDIRECT_HOPS.
+ *
+ * Throws on guard failure, network failure, non-2xx final responses, or
+ * redirect-without-Location so callers can decide whether to skip
+ * (pre-filter) or abort (apply).
+ */
+export async function fetchAndHash(url, opts = {}) {
+    const resolver = opts.resolver ?? defaultResolver;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+    const maxBodyBytes = opts.maxBodyBytes ?? MAX_RESPONSE_BODY_BYTES;
+    const doFetch = opts.fetchImpl ?? undiciFetch;
+    let current = url;
+    for (let hop = 0; hop <= MAX_REDIRECT_HOPS; hop++) {
+        // DNS-rebinding guard: also resolve the hostname and check every returned
+        // IP, not just the literal hostname (round-5 F-001). Round-7 F-002 pins
+        // the fetch to the first validated IP. Round-8 F-001/F-002 closes the
+        // residual TOCTOU by having the validator RETURN the validated IP list
+        // — we don't resolve again here.
+        const { url: validated, ips } = await assertSafeSourceUrlWithDns(current, resolver);
+        let host = validated.hostname;
+        if (host.startsWith('[') && host.endsWith(']'))
+            host = host.slice(1, -1);
+        const pinnedIp = ips[0];
+        // Pin only when the host is a hostname, not when the URL already used an
+        // IP literal — that case has no rebinding window. `ips` from the
+        // validator already contains the literal itself in that case.
+        const dispatcher = net.isIP(host) === 0 && pinnedIp ? pinningAgent(pinnedIp) : undefined;
+        // Per-hop timeout (round-6 F-003): a hanging server would otherwise block
+        // the daily cron indefinitely. AbortSignal.timeout is built-in to Node 22+.
+        //
+        // The dispatcher must stay alive until the response body is fully read
+        // (round-9 F-002). Earlier rounds closed it right after fetch() returned
+        // headers, but res.body is a stream — closing the agent mid-stream
+        // would stall or truncate reads. Wrap the entire per-hop handling in
+        // try/finally so the close only happens after body consumption (or after
+        // we decide to follow a redirect, in which case the body is discarded).
+        let res;
+        try {
+            res = await doFetch(current, {
+                redirect: 'manual',
+                signal: AbortSignal.timeout(timeoutMs),
+                // `dispatcher` is an undici extension to the WHATWG fetch standard.
+                ...(dispatcher ? { dispatcher } : {}),
+            });
+            // 3xx with a Location header → re-validate and follow.
+            if (res.status >= 300 && res.status < 400) {
+                const location = res.headers.get('location');
+                if (!location) {
+                    throw new Error(`fetch ${current} returned ${res.status} with no Location header`);
+                }
+                // Drain/cancel the redirect response so the underlying connection is
+                // free before we close the agent. Without this, agent.close() can
+                // race the still-open response body.
+                try {
+                    await res.body?.cancel();
+                }
+                catch { /* noop */ }
+                // Resolve relative redirects against the URL we just hit.
+                current = new URL(location, current).toString();
+                continue;
+            }
+            if (!res.ok) {
+                // Drain the error body so Agent.close() doesn't wait on an active
+                // stream (round-10 F-001). A slow or large error body would otherwise
+                // hang the cron despite the size + timeout guards on success.
+                try {
+                    await res.body?.cancel();
+                }
+                catch { /* noop */ }
+                throw new Error(`fetch ${current} returned HTTP ${res.status}`);
+            }
+            // Read body with a size cap so a malicious or massive response can't
+            // exhaust memory (round-7 F-003). The reader is cancelled on size
+            // overflow inside readBodyWithLimit so Agent.close() won't stall.
+            const body = await readBodyWithLimit(res, maxBodyBytes, current);
+            const hash = `sha256:${createHash('sha256').update(body).digest('hex')}`;
+            return { hash, body };
+        }
+        finally {
+            // Close the agent only AFTER the body has been consumed (or the
+            // redirect response cancelled). Each hop builds a fresh agent because
+            // the hostname can change between hops, so we never reuse one.
+            if (dispatcher)
+                await dispatcher.close();
+        }
+    }
+    throw new Error(`fetch ${url} exceeded ${MAX_REDIRECT_HOPS} redirects`);
+}
+async function readBodyWithLimit(res, max, url) {
+    if (!res.body)
+        return await res.text();
+    const reader = res.body.getReader();
+    const chunks = [];
+    let total = 0;
+    let cancelled = false;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value) {
+                total += value.byteLength;
+                if (total > max) {
+                    // Cancel the reader so the underlying stream closes and
+                    // Agent.close() (called in the caller's finally) doesn't wait on
+                    // an unbounded inflight body (round-10 F-001).
+                    cancelled = true;
+                    try {
+                        await reader.cancel();
+                    }
+                    catch { /* noop */ }
+                    throw new Error(`fetch ${url} response exceeded ${max} bytes (DoS guard)`);
+                }
+                chunks.push(value);
+            }
+        }
+    }
+    finally {
+        if (!cancelled)
+            reader.releaseLock?.();
+    }
+    return new TextDecoder('utf-8').decode(Buffer.concat(chunks));
+}
+//# sourceMappingURL=source-hash.js.map

package/dist/knowledge-freshness/source-hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-hash.js","sourceRoot":"","sources":["../../src/knowledge-freshness/source-hash.ts"],"names":[],"mappings":"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"}

package/dist/knowledge-freshness/source-hash.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=source-hash.test.d.ts.map

package/dist/knowledge-freshness/source-hash.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-hash.test.d.ts","sourceRoot":"","sources":["../../src/knowledge-freshness/source-hash.test.ts"],"names":[],"mappings":""}

package/dist/knowledge-freshness/source-hash.test.js

@@ -0,0 +1,63 @@
+import { describe, it, expect, vi } from 'vitest';
+import { fetchAndHash } from './source-hash.js';
+// Stub resolver: every public hostname resolves to a single public IP.
+// Tests that want to exercise DNS-rebinding rejection inject a different
+// resolver that returns a private IP.
+const publicResolver = async () => ['93.184.216.34'];
+// Build a FetchImpl mock that returns a queue of pre-built Responses.
+function mockFetch(...responses) {
+    const queue = [...responses];
+    return vi.fn(async () => {
+        const next = queue.shift();
+        if (!next)
+            throw new Error('mock fetch: no more queued responses');
+        return next;
+    });
+}
+describe('fetchAndHash', () => {
+    it('returns a sha256:-prefixed hex digest of the response body', async () => {
+        const fetchImpl = mockFetch(new Response('hello world', { status: 200 }));
+        const { hash, body } = await fetchAndHash('https://example.org/anything', { resolver: publicResolver, fetchImpl });
+        expect(hash).toBe('sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9');
+        expect(body).toBe('hello world');
+    });
+    it('throws on non-2xx response', async () => {
+        const fetchImpl = mockFetch(new Response('', { status: 503 }));
+        await expect(fetchAndHash('https://example.org/down', { resolver: publicResolver, fetchImpl })).rejects.toThrow(/503/);
+    });
+    // Round-4 F-002: redirect validation
+    it('follows a redirect to a public URL and hashes the final body', async () => {
+        const fetchImpl = mockFetch(new Response('', { status: 302, headers: { Location: 'https://example.org/final' } }), new Response('hello world', { status: 200 }));
+        const { hash } = await fetchAndHash('https://example.org/start', { resolver: publicResolver, fetchImpl });
+        expect(hash).toBe('sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9');
+    });
+    it('rejects a redirect that targets a private network (SSRF via 302)', async () => {
+        const fetchImpl = mockFetch(new Response('', { status: 302, headers: { Location: 'http://169.254.169.254/latest/meta-data/' } }));
+        await expect(fetchAndHash('https://example.org/looks-fine', { resolver: publicResolver, fetchImpl })).rejects.toThrow(/refusing to fetch/);
+    });
+    it('rejects a redirect chain ending in localhost', async () => {
+        const fetchImpl = mockFetch(new Response('', { status: 302, headers: { Location: 'https://b.example.org/' } }), new Response('', { status: 302, headers: { Location: 'http://localhost:8080/' } }));
+        await expect(fetchAndHash('https://a.example.org/', { resolver: publicResolver, fetchImpl })).rejects.toThrow(/refusing to fetch/);
+    });
+    it('errors when a 3xx response is missing a Location header', async () => {
+        const fetchImpl = mockFetch(new Response('', { status: 302 }));
+        await expect(fetchAndHash('https://example.org/x', { resolver: publicResolver, fetchImpl })).rejects.toThrow(/no Location header/);
+    });
+    it('errors after exceeding the redirect-hop limit', async () => {
+        // 6 consecutive redirects → 1 initial + 5 follow-ups = 6 fetches, then bail.
+        const fetchImpl = vi.fn(async () => new Response('', { status: 302, headers: { Location: 'https://hop.example.org/' } }));
+        await expect(fetchAndHash('https://example.org/start', { resolver: publicResolver, fetchImpl })).rejects.toThrow(/exceeded/);
+    });
+    // Round-5 F-001: DNS-rebinding guard
+    it('rejects a hostname that resolves to a private IPv4 (DNS-rebinding)', async () => {
+        const rebindingResolver = async () => ['127.0.0.1'];
+        const fetchImpl = mockFetch(new Response('', { status: 200 }));
+        await expect(fetchAndHash('https://attacker.example/', { resolver: rebindingResolver, fetchImpl })).rejects.toThrow(/DNS-rebinding/);
+    });
+    it('rejects a hostname that resolves to a private IPv6 (DNS-rebinding)', async () => {
+        const rebindingResolver = async () => ['fe80::1'];
+        const fetchImpl = mockFetch(new Response('', { status: 200 }));
+        await expect(fetchAndHash('https://attacker.example/', { resolver: rebindingResolver, fetchImpl })).rejects.toThrow(/DNS-rebinding/);
+    });
+});
+//# sourceMappingURL=source-hash.test.js.map

package/dist/knowledge-freshness/source-hash.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-hash.test.js","sourceRoot":"","sources":["../../src/knowledge-freshness/source-hash.test.ts"],"names":[],"mappings":"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"}

package/dist/knowledge-freshness/source-url-validator.d.ts

@@ -0,0 +1,57 @@
+export type ValidationResult = {
+    ok: true;
+    url: URL;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function validateSourceUrl(raw: string): ValidationResult;
+/**
+ * Resolve a hostname to its A/AAAA records. Pulled out as an injectable type
+ * so tests can stub DNS without hitting the network. The real resolver uses
+ * Node's `dns.promises`.
+ */
+export type Resolver = (host: string) => Promise<string[]>;
+export declare const defaultResolver: Resolver;
+/**
+ * Same as `assertSafeSourceUrl`, but ALSO resolves the hostname and checks
+ * every returned IP against the IPv4/IPv6 blocklists. Prevents DNS-rebinding
+ * attacks where a public hostname resolves to a private IP (round-5 F-001).
+ *
+ * Returns BOTH the URL and the validated IPs so callers can pin the fetch
+ * to one of those IPs without resolving again (round-8 F-001/F-002).
+ * Performing a second DNS lookup at fetch time would re-open the TOCTOU
+ * window the validator was supposed to close.
+ *
+ * For raw IP literals, `ips` contains the literal itself (no DNS lookup).
+ */
+export interface DnsValidatedUrl {
+    url: URL;
+    ips: string[];
+}
+export declare function assertSafeSourceUrlWithDns(raw: string, resolver?: Resolver): Promise<DnsValidatedUrl>;
+/**
+ * Throws if the URL would route to a restricted target. Use at every external
+ * fetch boundary; the helper is intentionally identical for prefilter, apply,
+ * and meta-prompt dispatch so one guard covers all three callsites.
+ */
+export declare function assertSafeSourceUrl(raw: string): URL;
+/**
+ * Load the allowlist from `docs/knowledge-freshness/authoritative-sources.yaml`
+ * (relative to `projectRoot`). Used by the operations / CI gate to flag
+ * out-of-list sources as warnings (not hard blocks per resolved decision #4).
+ * Returns an empty Set when the file is missing so the caller treats every
+ * host as out-of-list and warns — the safer default than "silently allow".
+ */
+interface Allowlist {
+    hosts: string[];
+    github_repos: string[];
+}
+export declare function loadAuthoritativeAllowlist(projectRoot: string): Allowlist;
+/**
+ * Returns true if `url`'s host (or github repo path) appears in the allowlist.
+ * Decision #4 (locked): off-allowlist sources warn, not block.
+ */
+export declare function isAllowlistedSource(url: URL, allowlist: Allowlist): boolean;
+export {};
+//# sourceMappingURL=source-url-validator.d.ts.map

package/dist/knowledge-freshness/source-url-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-url-validator.d.ts","sourceRoot":"","sources":["../../src/knowledge-freshness/source-url-validator.ts"],"names":[],"mappings":"AAmIA,MAAM,MAAM,gBAAgB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,GAAG,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAErF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAwC/D;AAED;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;AAE1D,eAAO,MAAM,eAAe,EAAE,QAY7B,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAAG,GAAG,EAAE,GAAG,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE;AAE5D,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,QAA0B,GACnC,OAAO,CAAC,eAAe,CAAC,CA+B1B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAUpD;AAED;;;;;;GAMG;AACH,UAAU,SAAS;IAAG,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE;AAE/D,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAkBzE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAsB3E"}