@x12i/content-fetcher 0.1.0

package/dist/robots/robots-txt.js

@@ -0,0 +1,91 @@
+/**
+ * robots.txt parsing and evaluation (practical subset of RFC 9309):
+ * agent groups, allow/disallow rules, `*` wildcards, and `$` anchors.
+ * Longest matching pattern wins; ties favour "allow".
+ */
+export function parseRobotsTxt(text) {
+    const groups = [];
+    let current = null;
+    let lastWasAgent = false;
+    for (const rawLine of text.split(/\r\n|\r|\n/)) {
+        const line = rawLine.replace(/#.*$/, "").trim();
+        if (line === "")
+            continue;
+        const colon = line.indexOf(":");
+        if (colon === -1)
+            continue;
+        const field = line.slice(0, colon).trim().toLowerCase();
+        const value = line.slice(colon + 1).trim();
+        if (field === "user-agent") {
+            if (current === null || !lastWasAgent) {
+                current = { agents: new Set(), rules: [] };
+                groups.push(current);
+            }
+            if (value !== "")
+                current.agents.add(value.toLowerCase());
+            lastWasAgent = true;
+            continue;
+        }
+        lastWasAgent = false;
+        if (current === null)
+            continue; // rule lines before any user-agent are ignored
+        if (field === "disallow" && value !== "") {
+            current.rules.push({ allow: false, path: value });
+        }
+        else if (field === "allow" && value !== "") {
+            current.rules.push({ allow: true, path: value });
+        }
+    }
+    return groups;
+}
+function ruleMatches(rulePath, target) {
+    let pattern = "^";
+    for (let i = 0; i < rulePath.length; i++) {
+        const ch = rulePath[i];
+        if (ch === "*") {
+            pattern += "[\\s\\S]*";
+        }
+        else if (ch === "$" && i === rulePath.length - 1) {
+            pattern += "$";
+        }
+        else {
+            pattern += ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        }
+    }
+    try {
+        return new RegExp(pattern).test(target);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Evaluate `target` (path + query) for the given user agent.
+ * Agent groups are matched against the full user-agent token, its product
+ * name (the part before "/"), and finally the `*` group.
+ */
+export function robotsAllows(groups, userAgent, target) {
+    const full = userAgent.trim().toLowerCase();
+    const firstToken = full.split(/\s+/)[0] ?? "";
+    const productName = firstToken.split("/")[0] ?? "";
+    const candidates = new Set([full, firstToken, productName].filter((c) => c !== ""));
+    let matched = groups.filter((g) => [...candidates].some((token) => g.agents.has(token)));
+    if (matched.length === 0) {
+        matched = groups.filter((g) => g.agents.has("*"));
+    }
+    const rules = matched.flatMap((g) => g.rules);
+    if (rules.length === 0)
+        return { allowed: true, matchedPath: null };
+    let best = null;
+    for (const rule of rules) {
+        if (!ruleMatches(rule.path, target))
+            continue;
+        if (best === null ||
+            rule.path.length > best.path.length ||
+            (rule.path.length === best.path.length && rule.allow && !best.allow)) {
+            best = { allow: rule.allow, path: rule.path };
+        }
+    }
+    return best === null ? { allowed: true, matchedPath: null } : { allowed: best.allow, matchedPath: best.path };
+}
+//# sourceMappingURL=robots-txt.js.map

package/dist/robots/robots-txt.js.map

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

package/dist/runtime-utils.d.ts

@@ -0,0 +1,11 @@
+/** Minimal runtime type guards (the package has zero runtime dependencies). */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function isNonEmptyString(value: unknown): value is string;
+export declare function isStringArray(value: unknown): value is string[];
+export declare function isPositiveInteger(value: unknown): value is number;
+export declare function isNonNegativeInteger(value: unknown): value is number;
+export declare function isBoolean(value: unknown): value is boolean;
+export declare function isUint8Array(value: unknown): value is Uint8Array;
+export declare function isMimeTypeLike(value: unknown): value is string;
+export declare function isValidHostnamePattern(value: string): boolean;
+//# sourceMappingURL=runtime-utils.d.ts.map

package/dist/runtime-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-utils.d.ts","sourceRoot":"","sources":["../src/runtime-utils.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAE/E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,EAAE,CAE/D;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEjE;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEpE;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAE1D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE;AAKD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE9D;AAID,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE7D"}

package/dist/runtime-utils.js

@@ -0,0 +1,32 @@
+/** Minimal runtime type guards (the package has zero runtime dependencies). */
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+export function isStringArray(value) {
+    return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+export function isPositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+export function isNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+export function isBoolean(value) {
+    return typeof value === "boolean";
+}
+export function isUint8Array(value) {
+    return value instanceof Uint8Array;
+}
+// Accepts concrete MIME types and wildcard patterns ("application/*", "*/*").
+const MIME_TYPE_RE = /^[\w.+\-*]+\/[\w.+\-*]+$/;
+export function isMimeTypeLike(value) {
+    return typeof value === "string" && MIME_TYPE_RE.test(value.trim());
+}
+const HOSTNAME_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
+export function isValidHostnamePattern(value) {
+    return HOSTNAME_RE.test(value.toLowerCase());
+}
+//# sourceMappingURL=runtime-utils.js.map

package/dist/runtime-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-utils.js","sourceRoot":"","sources":["../src/runtime-utils.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAE/E,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,OAAO,OAAO,KAAK,KAAK,SAAS,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,KAAK,YAAY,UAAU,CAAC;AACrC,CAAC;AAED,8EAA8E;AAC9E,MAAM,YAAY,GAAG,0BAA0B,CAAC;AAEhD,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;AACtE,CAAC;AAED,MAAM,WAAW,GAAG,mEAAmE,CAAC;AAExF,MAAM,UAAU,sBAAsB,CAAC,KAAa;IAClD,OAAO,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;AAC/C,CAAC"}

package/dist/security/dns.d.ts

@@ -0,0 +1,33 @@
+import type { DnsResolver } from "../types.js";
+/** System resolver used by default. */
+export declare class SystemDnsResolver implements DnsResolver {
+    lookup(hostname: string): Promise<{
+        addresses: string[];
+    }>;
+}
+export type DnsFailureReason = "hostname_blocked" | "resolution_failed" | "unsafe_address";
+/**
+ * One security gate for every outbound target. Runs:
+ * 1. blocked-hostname check (localhost, cloud metadata, *.internal),
+ * 2. IP-literal validation, or
+ * 3. DNS resolution followed by validation of every resolved address.
+ *
+ * `resolution_failed` is returned (not thrown) so callers can map it to a
+ * status; hostname/address violations throw UnsafeUrlError (fail closed).
+ */
+export declare class AddressValidator {
+    private readonly resolver;
+    private readonly now;
+    private readonly cache;
+    private static readonly CACHE_TTL_MS;
+    constructor(resolver: DnsResolver, now: () => number);
+    /** Validate `hostname` and return the addresses that were approved. */
+    validate(hostname: string): Promise<{
+        ok: true;
+        addresses: string[];
+    } | {
+        ok: false;
+        reason: Extract<DnsFailureReason, "resolution_failed">;
+    }>;
+}
+//# sourceMappingURL=dns.d.ts.map

package/dist/security/dns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dns.d.ts","sourceRoot":"","sources":["../../src/security/dns.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAI/C,uCAAuC;AACvC,qBAAa,iBAAkB,YAAW,WAAW;IAC7C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAIjE;AAED,MAAM,MAAM,gBAAgB,GAAG,kBAAkB,GAAG,mBAAmB,GAAG,gBAAgB,CAAC;AAE3F;;;;;;;;GAQG;AACH,qBAAa,gBAAgB;IAKzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,GAAG;IALtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0D;IAChF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAU;gBAG3B,QAAQ,EAAE,WAAW,EACrB,GAAG,EAAE,MAAM,MAAM;IAGpC,uEAAuE;IACjE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC,gBAAgB,EAAE,mBAAmB,CAAC,CAAA;KAAE,CAAC;CAmCrJ"}

package/dist/security/dns.js

@@ -0,0 +1,60 @@
+import { lookup as dnsLookup } from "node:dns/promises";
+import { UnsafeUrlError } from "../errors.js";
+import { areResolvedAddressesSafe, isBlockedHostname } from "./net-guards.js";
+import { isIP } from "node:net";
+/** System resolver used by default. */
+export class SystemDnsResolver {
+    async lookup(hostname) {
+        const result = await dnsLookup(hostname, { all: true });
+        return { addresses: result.map((r) => r.address) };
+    }
+}
+/**
+ * One security gate for every outbound target. Runs:
+ * 1. blocked-hostname check (localhost, cloud metadata, *.internal),
+ * 2. IP-literal validation, or
+ * 3. DNS resolution followed by validation of every resolved address.
+ *
+ * `resolution_failed` is returned (not thrown) so callers can map it to a
+ * status; hostname/address violations throw UnsafeUrlError (fail closed).
+ */
+export class AddressValidator {
+    resolver;
+    now;
+    cache = new Map();
+    static CACHE_TTL_MS = 60_000;
+    constructor(resolver, now) {
+        this.resolver = resolver;
+        this.now = now;
+    }
+    /** Validate `hostname` and return the addresses that were approved. */
+    async validate(hostname) {
+        if (isBlockedHostname(hostname)) {
+            throw new UnsafeUrlError("Hostname is blocked from outbound requests.", "hostname_blocked");
+        }
+        if (isIP(hostname) !== 0) {
+            if (areResolvedAddressesSafe([hostname]))
+                return { ok: true, addresses: [hostname] };
+            throw new UnsafeUrlError("Address falls into a blocked range.", "unsafe_address");
+        }
+        const cached = this.cache.get(hostname);
+        if (cached && this.now() - cached.at < AddressValidator.CACHE_TTL_MS) {
+            // Cached resolutions were validated when stored; only blocked answers are cached.
+            return { ok: true, addresses: cached.addresses };
+        }
+        let addresses;
+        try {
+            const resolved = await this.resolver.lookup(hostname);
+            addresses = resolved.addresses ?? [];
+        }
+        catch {
+            return { ok: false, reason: "resolution_failed" };
+        }
+        if (!areResolvedAddressesSafe(addresses)) {
+            throw new UnsafeUrlError("Hostname resolves into a blocked address range.", "unsafe_resolved_address");
+        }
+        this.cache.set(hostname, { addresses, at: this.now() });
+        return { ok: true, addresses };
+    }
+}
+//# sourceMappingURL=dns.js.map

package/dist/security/dns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dns.js","sourceRoot":"","sources":["../../src/security/dns.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAEhC,uCAAuC;AACvC,MAAM,OAAO,iBAAiB;IAC5B,KAAK,CAAC,MAAM,CAAC,QAAgB;QAC3B,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACrD,CAAC;CACF;AAID;;;;;;;;GAQG;AACH,MAAM,OAAO,gBAAgB;IAKR;IACA;IALF,KAAK,GAAG,IAAI,GAAG,EAA+C,CAAC;IACxE,MAAM,CAAU,YAAY,GAAG,MAAM,CAAC;IAE9C,YACmB,QAAqB,EACrB,GAAiB;QADjB,aAAQ,GAAR,QAAQ,CAAa;QACrB,QAAG,GAAH,GAAG,CAAc;IACjC,CAAC;IAEJ,uEAAuE;IACvE,KAAK,CAAC,QAAQ,CAAC,QAAgB;QAC7B,IAAI,iBAAiB,CAAC,QAAQ,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,cAAc,CACtB,6CAA6C,EAC7C,kBAAkB,CACnB,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,IAAI,wBAAwB,CAAC,CAAC,QAAQ,CAAC,CAAC;gBAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC;YACrF,MAAM,IAAI,cAAc,CACtB,qCAAqC,EACrC,gBAAgB,CACjB,CAAC;QACJ,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACxC,IAAI,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,EAAE,GAAG,gBAAgB,CAAC,YAAY,EAAE,CAAC;YACrE,kFAAkF;YAClF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;QACnD,CAAC;QACD,IAAI,SAAmB,CAAC;QACxB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YACtD,SAAS,GAAG,QAAQ,CAAC,SAAS,IAAI,EAAE,CAAC;QACvC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;QACpD,CAAC;QACD,IAAI,CAAC,wBAAwB,CAAC,SAAS,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,cAAc,CACtB,iDAAiD,EACjD,yBAAyB,CAC1B,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACxD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IACjC,CAAC"}

package/dist/security/headers.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Response header handling: case-insensitive lookup, a strict retention
+ * allowlist, and Retry-After parsing. Everything outside the allowlist is
+ * redacted before anything is stored or returned.
+ */
+export declare function getHeader(headers: Record<string, string>, name: string): string | undefined;
+/**
+ * Copy only retention-permitted headers. Authentication, cookies, and any
+ * other potentially sensitive header never survive this filter.
+ */
+export declare function retainedResponseHeaders(headers: Record<string, string>): Record<string, string>;
+/** Header names whose presence in any stored record is a bug. */
+export declare const REDACTED_HEADER_NAMES: string[];
+/** Parse Retry-After (delta-seconds or HTTP-date) into whole seconds. */
+export declare function parseRetryAfter(headers: Record<string, string>, now: Date): number | undefined;
+//# sourceMappingURL=headers.d.ts.map

package/dist/security/headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../../src/security/headers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI3F;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQ/F;AAED,iEAAiE;AACjE,eAAO,MAAM,qBAAqB,UAAuF,CAAC;AAE1H,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAa9F"}

package/dist/security/headers.js

@@ -0,0 +1,54 @@
+/**
+ * Response header handling: case-insensitive lookup, a strict retention
+ * allowlist, and Retry-After parsing. Everything outside the allowlist is
+ * redacted before anything is stored or returned.
+ */
+const RETAINED_RESPONSE_HEADERS = new Set([
+    "content-type",
+    "content-length",
+    "etag",
+    "last-modified",
+    "date",
+    "cache-control",
+    "expires",
+    "content-encoding",
+    "x-archive-capture-timestamp",
+    "x-archive-original-url",
+]);
+export function getHeader(headers, name) {
+    const lower = name.toLowerCase();
+    const direct = Object.entries(headers).find(([key]) => key.toLowerCase() === lower);
+    return direct?.[1];
+}
+/**
+ * Copy only retention-permitted headers. Authentication, cookies, and any
+ * other potentially sensitive header never survive this filter.
+ */
+export function retainedResponseHeaders(headers) {
+    const out = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (RETAINED_RESPONSE_HEADERS.has(key.toLowerCase())) {
+            out[key.toLowerCase()] = value;
+        }
+    }
+    return out;
+}
+/** Header names whose presence in any stored record is a bug. */
+export const REDACTED_HEADER_NAMES = ["set-cookie", "authorization", "cookie", "proxy-authorization", "www-authenticate"];
+/** Parse Retry-After (delta-seconds or HTTP-date) into whole seconds. */
+export function parseRetryAfter(headers, now) {
+    const raw = getHeader(headers, "retry-after");
+    if (raw === undefined)
+        return undefined;
+    const trimmed = raw.trim();
+    if (/^\d+$/.test(trimmed)) {
+        return Math.min(Number(trimmed), 86_400);
+    }
+    const asDate = Date.parse(trimmed);
+    if (!Number.isNaN(asDate)) {
+        const seconds = Math.ceil((asDate - now.getTime()) / 1000);
+        return seconds > 0 ? Math.min(seconds, 86_400) : 0;
+    }
+    return undefined;
+}
+//# sourceMappingURL=headers.js.map

package/dist/security/headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.js","sourceRoot":"","sources":["../../src/security/headers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,yBAAyB,GAAG,IAAI,GAAG,CAAC;IACxC,cAAc;IACd,gBAAgB;IAChB,MAAM;IACN,eAAe;IACf,MAAM;IACN,eAAe;IACf,SAAS;IACT,kBAAkB;IAClB,6BAA6B;IAC7B,wBAAwB;CACzB,CAAC,CAAC;AAEH,MAAM,UAAU,SAAS,CAAC,OAA+B,EAAE,IAAY;IACrE,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACjC,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC,CAAC;IACpF,OAAO,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAA+B;IACrE,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,IAAI,yBAAyB,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YACrD,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,GAAG,KAAK,CAAC;QACjC,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,iEAAiE;AACjE,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,qBAAqB,EAAE,kBAAkB,CAAC,CAAC;AAE1H,yEAAyE;AACzE,MAAM,UAAU,eAAe,CAAC,OAA+B,EAAE,GAAS;IACxE,MAAM,GAAG,GAAG,SAAS,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IAC9C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;QAC3D,OAAO,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/security/net-guards.d.ts

@@ -0,0 +1,9 @@
+export declare function isBlockedHostname(hostname: string): boolean;
+/**
+ * True when the address (IPv4 or IPv6 literal) falls into a blocked range.
+ * Non-IP strings are treated as blocked (fail closed).
+ */
+export declare function isBlockedAddress(address: string): boolean;
+/** True when every resolved address is safe to contact. */
+export declare function areResolvedAddressesSafe(addresses: string[]): boolean;
+//# sourceMappingURL=net-guards.d.ts.map

package/dist/security/net-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"net-guards.d.ts","sourceRoot":"","sources":["../../src/security/net-guards.ts"],"names":[],"mappings":"AAsEA,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAI3D;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAoBzD;AAED,2DAA2D;AAC3D,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAErE"}

package/dist/security/net-guards.js

@@ -0,0 +1,102 @@
+import { isIP } from "node:net";
+import { BlockList } from "node:net";
+/**
+ * Address guards implementing the package's outbound-request policy:
+ * loopback, private, link-local, cloud-metadata, shared, multicast,
+ * reserved, and documentation ranges are never contacted.
+ *
+ * IPv4 and IPv6 use separate BlockLists: Node represents IPv4 addresses as
+ * IPv4-mapped IPv6 internally, so a "::ffff:0:0/96" subnet would match every
+ * IPv4 address (mapped literals are handled explicitly below instead).
+ */
+const v4List = new BlockList();
+const v6List = new BlockList();
+function addV4(cidr) {
+    const [address, bits] = cidr.split("/");
+    v4List.addSubnet(address, Number(bits), "ipv4");
+}
+function addV6(cidr) {
+    const [address, bits] = cidr.split("/");
+    v6List.addSubnet(address, Number(bits), "ipv6");
+}
+// IPv4: loopback, private, shared (CGNAT), link-local (incl. cloud metadata
+// 169.254.169.254), reserved, benchmarking, documentation, multicast, broadcast.
+for (const cidr of [
+    "0.0.0.0/8",
+    "10.0.0.0/8",
+    "100.64.0.0/10",
+    "127.0.0.0/8",
+    "169.254.0.0/16",
+    "172.16.0.0/12",
+    "192.0.0.0/24",
+    "192.0.2.0/24",
+    "192.88.99.0/24",
+    "192.168.0.0/16",
+    "198.18.0.0/15",
+    "198.51.100.0/24",
+    "203.0.113.0/24",
+    "224.0.0.0/4",
+    "240.0.0.0/4",
+]) {
+    addV4(cidr);
+}
+v4List.addAddress("255.255.255.255", "ipv4");
+// IPv6: unspecified, loopback, ULA (incl. fd00:ec2::254 metadata),
+// link-local, multicast, documentation. IPv4-mapped space is handled below.
+for (const cidr of [
+    "::/128",
+    "::1/128",
+    "fc00::/7",
+    "fe80::/10",
+    "ff00::/8",
+    "2001:db8::/32",
+]) {
+    addV6(cidr);
+}
+/** Hostnames blocked regardless of DNS answers. */
+const BLOCKED_HOSTNAMES = new Set([
+    "localhost",
+    "metadata.google.internal",
+    "metadata.goog",
+    "instance-data",
+]);
+export function isBlockedHostname(hostname) {
+    const host = hostname.toLowerCase();
+    if (BLOCKED_HOSTNAMES.has(host))
+        return true;
+    return host.endsWith(".localhost") || host.endsWith(".internal");
+}
+function checkV4(address) {
+    return v4List.check(address, "ipv4");
+}
+/**
+ * True when the address (IPv4 or IPv6 literal) falls into a blocked range.
+ * Non-IP strings are treated as blocked (fail closed).
+ */
+export function isBlockedAddress(address) {
+    const family = isIP(address);
+    if (family === 0)
+        return true;
+    if (family === 6) {
+        const lower = address.toLowerCase();
+        // IPv4-mapped IPv6 in dotted form: ::ffff:127.0.0.1
+        const dotted = lower.match(/^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/);
+        if (dotted?.[1] !== undefined)
+            return checkV4(dotted[1]);
+        // IPv4-mapped IPv6 in hex form: ::ffff:7f00:1
+        const hex = lower.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+        if (hex?.[1] !== undefined && hex[2] !== undefined) {
+            const high = Number.parseInt(hex[1], 16);
+            const low = Number.parseInt(hex[2], 16);
+            const embedded = [(high >> 8) & 0xff, high & 0xff, (low >> 8) & 0xff, low & 0xff].join(".");
+            return checkV4(embedded);
+        }
+        return v6List.check(address, "ipv6");
+    }
+    return checkV4(address);
+}
+/** True when every resolved address is safe to contact. */
+export function areResolvedAddressesSafe(addresses) {
+    return addresses.length > 0 && addresses.every((a) => !isBlockedAddress(a));
+}
+//# sourceMappingURL=net-guards.js.map

package/dist/security/net-guards.js.map

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

package/dist/security/url.d.ts

@@ -0,0 +1,32 @@
+export interface ParsedTargetUrl {
+    url: URL;
+    /** Lowercase hostname, no brackets (IPv6 literal without square brackets). */
+    hostname: string;
+    protocol: string;
+}
+/**
+ * Parse a resource URL for outbound use.
+ *
+ * Throws UnsafeUrlError for non-HTTP(S) schemes and embedded credentials.
+ * Malformed or relative URLs throw UnsafeUrlError as well; callers that want
+ * request-level errors for those should pre-validate with
+ * {@link isAbsoluteHttpUrl}.
+ */
+export declare function parseOutboundUrl(raw: string): ParsedTargetUrl;
+/** Loose pre-check used during request-shape validation. */
+export declare function isAbsoluteHttpUrl(raw: string): boolean;
+/** True when `hostname` equals an allowed domain or is a subdomain of it. */
+export declare function hostMatchesAllowedDomains(hostname: string, allowedDomains: readonly string[]): boolean;
+/**
+ * Strip everything that must never be persisted: credentials, query strings,
+ * and fragments. Applies to stored URLs, results, and audit records.
+ */
+export declare function sanitizeUrl(raw: string): string;
+/**
+ * Derive a safe artifact file name from a URL path.
+ * Falls back to "artifact" when the path has no usable final segment.
+ */
+export declare function fileNameFromUrl(raw: string): string;
+/** Sanitize a caller-supplied file name using the same rules as {@link fileNameFromUrl}. */
+export declare function sanitizeFileName(name: string): string;
+//# sourceMappingURL=url.d.ts.map

package/dist/security/url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../src/security/url.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,GAAG,CAAC;IACT,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAwB7D;AAED,4DAA4D;AAC5D,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOtD;AAED,6EAA6E;AAC7E,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,SAAS,MAAM,EAAE,GAChC,OAAO,CAIT;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO/C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAWnD;AAED,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKrD"}

package/dist/security/url.js

@@ -0,0 +1,82 @@
+import { UnsafeUrlError } from "../errors.js";
+/**
+ * Parse a resource URL for outbound use.
+ *
+ * Throws UnsafeUrlError for non-HTTP(S) schemes and embedded credentials.
+ * Malformed or relative URLs throw UnsafeUrlError as well; callers that want
+ * request-level errors for those should pre-validate with
+ * {@link isAbsoluteHttpUrl}.
+ */
+export function parseOutboundUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new UnsafeUrlError("Resource URL could not be parsed.", "url_unparseable");
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new UnsafeUrlError("Resource URL must use http or https.", "url_protocol_forbidden");
+    }
+    if (url.username !== "" || url.password !== "") {
+        throw new UnsafeUrlError("Resource URL must not contain credentials.", "url_credentials_forbidden");
+    }
+    const hostname = url.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    if (hostname === "") {
+        throw new UnsafeUrlError("Resource URL has no host.", "url_missing_host");
+    }
+    return { url, hostname, protocol: url.protocol.replace(":", "") };
+}
+/** Loose pre-check used during request-shape validation. */
+export function isAbsoluteHttpUrl(raw) {
+    try {
+        const u = new URL(raw);
+        return (u.protocol === "https:" || u.protocol === "http:") && u.hostname !== "";
+    }
+    catch {
+        return false;
+    }
+}
+/** True when `hostname` equals an allowed domain or is a subdomain of it. */
+export function hostMatchesAllowedDomains(hostname, allowedDomains) {
+    return allowedDomains.some((domain) => domain !== "" && (hostname === domain || hostname.endsWith(`.${domain}`)));
+}
+/**
+ * Strip everything that must never be persisted: credentials, query strings,
+ * and fragments. Applies to stored URLs, results, and audit records.
+ */
+export function sanitizeUrl(raw) {
+    const url = new URL(raw);
+    url.username = "";
+    url.password = "";
+    url.hash = "";
+    url.search = "";
+    return url.toString();
+}
+/**
+ * Derive a safe artifact file name from a URL path.
+ * Falls back to "artifact" when the path has no usable final segment.
+ */
+export function fileNameFromUrl(raw) {
+    let pathname;
+    try {
+        pathname = new URL(raw).pathname;
+    }
+    catch {
+        return "artifact";
+    }
+    const segment = decodeURIComponent(pathname.split("/").filter(Boolean).pop() ?? "");
+    const safe = segment.replace(/[^A-Za-z0-9._-]+/g, "_").replace(/^\.+/, "");
+    if (safe === "" || safe === "." || safe.length > 128)
+        return "artifact";
+    return safe;
+}
+/** Sanitize a caller-supplied file name using the same rules as {@link fileNameFromUrl}. */
+export function sanitizeFileName(name) {
+    const base = name.split("/").pop() ?? "";
+    const safe = base.replace(/[^A-Za-z0-9._-]+/g, "_").replace(/^\.+/, "");
+    if (safe === "" || safe === "." || safe.length > 128)
+        return "artifact";
+    return safe;
+}
+//# sourceMappingURL=url.js.map

package/dist/security/url.js.map

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

package/dist/storage.d.ts

@@ -0,0 +1,38 @@
+import type { AcquisitionResult, ArtifactStore, FetchRequest, RightsProfile, Sha256ContentHash, SourcePolicy } from "./types.js";
+export interface PersistArtifactInput {
+    acquisitionId: string;
+    sourceId: string;
+    fileName: string;
+    contentType: string;
+    bytes: Uint8Array;
+    rights: RightsProfile;
+}
+export interface PersistArtifactOutcome {
+    /** Present only when raw retention is permitted. */
+    artifact?: {
+        artifactId: string;
+        fileName: string;
+        contentType: string;
+        contentHash: Sha256ContentHash;
+        byteLength: number;
+    };
+    duplicateOfArtifactId?: string;
+}
+/**
+ * Rights-gated, deduplicating persistence of raw artifacts:
+ * - raw bytes are stored only when the rights profile allows retention;
+ * - content already known for this source is never re-stored or overwritten;
+ * - every acquisition keeps its own record via putMetadata.
+ */
+export declare class ArtifactPersistence {
+    private readonly store;
+    constructor(store: ArtifactStore);
+    persistArtifact(input: PersistArtifactInput): Promise<PersistArtifactOutcome>;
+    /** Resolve a previous version's artifactId when the caller supplied its content hash. */
+    resolvePreviousVersionId(request: Pick<FetchRequest, "previousVersion">, policy: Pick<SourcePolicy, "sourceId">): Promise<string | undefined>;
+    /** Metadata + rights decision for one acquisition event. Never contains raw content or credentials. */
+    writeAcquisitionMetadata(result: AcquisitionResult, extras: object): Promise<void>;
+    /** Compact audit record for every completed request. Sanitized by construction. */
+    writeAuditRecord(result: AcquisitionResult, requestedAt: Date, completedAt: Date): Promise<void>;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACrC,oDAAoD;IACpD,QAAQ,CAAC,EAAE;QACT,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,iBAAiB,CAAC;QAC/B,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAcD;;;;;GAKG;AACH,qBAAa,mBAAmB;IAClB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,aAAa;IAE3C,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAyCnF,yFAAyF;IACnF,wBAAwB,CAC5B,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE,iBAAiB,CAAC,EAC9C,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,GACrC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAS9B,uGAAuG;IACjG,wBAAwB,CAAC,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBxF,mFAAmF;IAC7E,gBAAgB,CACpB,MAAM,EAAE,iBAAiB,EACzB,WAAW,EAAE,IAAI,EACjB,WAAW,EAAE,IAAI,GAChB,OAAO,CAAC,IAAI,CAAC;CAqBjB"}