@wardby/cli 0.2.0 → 0.3.0

package/dist/providers/coding-proxy/registry/audit.d.ts

@@ -0,0 +1,131 @@
+/**
+ * OSV vulnerability audit for the coding package registry. One query per
+ * package (cached), evaluated against every candidate version with the
+ * ecosystem's own version comparator:
+ *
+ * - only `affected[]` entries for the queried package count: same OSV
+ *   ecosystem, and the same name under the adapter's normalization (PEP 503
+ *   for PyPI, exact for npm). A GHSA advisory lists every package it touches
+ *   (e.g. `lodash-es`, or RubyGems `lodash-rails`), and none of those may
+ *   leak onto the one being installed;
+ * - a version is affected when it is listed in `versions`, or falls inside a
+ *   SEMVER/ECOSYSTEM range (npm GHSA entries carry ranges only). Ranges are
+ *   evaluated per the OSV schema: events sorted by version, `introduced`
+ *   (including "0") opens, `fixed` closes (exclusive), `last_affected`
+ *   closes (inclusive), `limit` bounds;
+ * - a version or event the comparator cannot parse counts as affected
+ *   (fail closed).
+ */
+import { type RegistryAdapter, type UpstreamFetch } from "../../../coding/registry/types.js";
+export declare const DEFAULT_VULN_CACHE_ENTRIES = 10000;
+/** Exact versions whose querybatch results are cached. */
+export declare const DEFAULT_BATCH_CACHE_ENTRIES = 20000;
+interface OsvEvent {
+    introduced?: string;
+    fixed?: string;
+    last_affected?: string;
+    limit?: string;
+}
+interface OsvAffected {
+    package?: {
+        name?: string;
+        ecosystem?: string;
+    };
+    ranges?: {
+        type?: string;
+        events?: OsvEvent[];
+    }[];
+    versions?: string[];
+}
+interface OsvVuln {
+    id: string;
+    aliases?: string[];
+    affected?: (OsvAffected & {
+        database_specific?: Record<string, unknown>;
+    })[];
+    database_specific?: {
+        severity?: string;
+        cwe_ids?: unknown;
+        [key: string]: unknown;
+    };
+}
+/** Whether an advisory reports malicious code: an OSV malicious-packages
+ *  entry (`MAL-…`, which carries no severity at all), one that aliases or
+ *  imports one, or a CWE-506 (embedded malicious code) advisory. Withheld
+ *  whatever its severity says. */
+export declare function isMalware(vuln: OsvVuln): boolean;
+/** What the audit needs from an adapter: which OSV ecosystem to query, how
+ *  names compare, and how versions order. */
+export type AuditAdapter = Pick<RegistryAdapter, "osvEcosystem" | "normalizeName" | "compareVersions">;
+export interface AdvisoryIndex {
+    /** Advisory ids with HIGH or CRITICAL severity that affect `version`. */
+    withheld(version: string): readonly string[];
+    /** Advisory ids of any other severity that affect `version`. */
+    reported(version: string): readonly string[];
+}
+type Compare = (a: string, b: string) => number;
+/** OSV range evaluation: sort events by version, then sweep. A version or
+ *  event the comparator cannot parse makes the version count as affected. */
+export declare function inOsvRange(version: string, events: readonly OsvEvent[], compare: Compare): boolean;
+export declare const DEFAULT_AUDIT_CACHE_ENTRIES = 5000;
+/** One exact package version to audit. */
+export interface AuditedVersion {
+    name: string;
+    version: string;
+}
+/** `name@version` -> the HIGH/CRITICAL advisory ids affecting it; a
+ *  version with none is absent. */
+export type WithheldVersions = Map<string, string[]>;
+export declare const versionKey: (name: string, version: string) => string;
+export declare class OsvAudit {
+    private readonly options;
+    /** Advisories per package, least recently used first. Bounded to
+     *  `maxEntries`; expired entries are dropped on access and before any
+     *  live entry is evicted. A failed query is never cached. */
+    private readonly cache;
+    /** Single-flight: concurrent audits of one package share one OSV query. */
+    private readonly loads;
+    /** Advisory severities by id, with the OSV `modified` time they were
+     *  read at, least recently used first. */
+    private readonly vulns;
+    /** Advisory ids (and their `modified` time) per exact version from
+     *  querybatch, for the audit TTL, least recently used first, so repeated
+     *  plans don't re-query. */
+    private readonly batchCache;
+    private readonly now;
+    private readonly ttlMs;
+    private readonly maxEntries;
+    private readonly fetch;
+    constructor(options: {
+        fetch: UpstreamFetch;
+        failOpen: boolean;
+        now?: () => number;
+        ttlMs?: number;
+        /** Packages kept in the advisory cache (default 5000). */
+        maxEntries?: number;
+        /** Advisory severities kept for exact-version audits (default 10000). */
+        maxVulnEntries?: number;
+        /** Exact versions whose querybatch results are kept (default 20000). */
+        maxBatchEntries?: number;
+        /** Timeout for one OSV request, body included (default 30 s). */
+        timeoutMs?: number;
+        /** Largest OSV response read (default 64 MiB). */
+        maxBytes?: number;
+    });
+    audit(adapter: AuditAdapter, name: string): Promise<AdvisoryIndex>;
+    /** Advisories for exact versions, in as few OSV requests as possible:
+     *  one querybatch per 1000 versions (OSV matches each version itself),
+     *  then each affecting advisory's severity from /v1/vulns/{id}, cached by
+     *  id and OSV's `modified` time. Fails closed like `audit`: any failure
+     *  is a 503 wardby_audit_unavailable, unless configured to fail open. */
+    auditVersions(adapter: AuditAdapter, versions: readonly AuditedVersion[], signal?: AbortSignal): Promise<WithheldVersions>;
+    private loadVersions;
+    private rememberBatch;
+    /** Whether an advisory is HIGH or CRITICAL, cached by id while OSV's
+     *  `modified` time for it is unchanged. */
+    private blocking;
+    private remember;
+    private load;
+    private query;
+}
+export {};

package/dist/providers/coding-proxy/registry/audit.js

@@ -0,0 +1,380 @@
+/**
+ * OSV vulnerability audit for the coding package registry. One query per
+ * package (cached), evaluated against every candidate version with the
+ * ecosystem's own version comparator:
+ *
+ * - only `affected[]` entries for the queried package count: same OSV
+ *   ecosystem, and the same name under the adapter's normalization (PEP 503
+ *   for PyPI, exact for npm). A GHSA advisory lists every package it touches
+ *   (e.g. `lodash-es`, or RubyGems `lodash-rails`), and none of those may
+ *   leak onto the one being installed;
+ * - a version is affected when it is listed in `versions`, or falls inside a
+ *   SEMVER/ECOSYSTEM range (npm GHSA entries carry ranges only). Ranges are
+ *   evaluated per the OSV schema: events sorted by version, `introduced`
+ *   (including "0") opens, `fixed` closes (exclusive), `last_affected`
+ *   closes (inclusive), `limit` bounds;
+ * - a version or event the comparator cannot parse counts as affected
+ *   (fail closed).
+ */
+import { RegistryError } from "../../../coding/registry/types.js";
+import { boundedMetadataFetch, DEFAULT_MAX_METADATA_BYTES, DEFAULT_METADATA_TIMEOUT_MS } from "./bounded-fetch.js";
+const OSV_QUERY = "https://api.osv.dev/v1/query";
+const OSV_QUERY_BATCH = "https://api.osv.dev/v1/querybatch";
+const OSV_VULN = "https://api.osv.dev/v1/vulns/";
+/** OSV's own limit on queries per querybatch request. */
+const OSV_BATCH_SIZE = 1000;
+/** Rounds of per-query pagination one batch follows before giving up
+ *  (fail closed): a package with that many pages of advisories is not a
+ *  real case. */
+const OSV_BATCH_MAX_PAGES = 20;
+/** Advisory details fetched at once. */
+const OSV_VULN_CONCURRENCY = 8;
+export const DEFAULT_VULN_CACHE_ENTRIES = 10_000;
+/** Exact versions whose querybatch results are cached. */
+export const DEFAULT_BATCH_CACHE_ENTRIES = 20_000;
+const BLOCKING = new Set(["HIGH", "CRITICAL"]);
+const RANGE_TYPES = new Set(["SEMVER", "ECOSYSTEM"]);
+/** Whether an advisory reports malicious code: an OSV malicious-packages
+ *  entry (`MAL-…`, which carries no severity at all), one that aliases or
+ *  imports one, or a CWE-506 (embedded malicious code) advisory. Withheld
+ *  whatever its severity says. */
+export function isMalware(vuln) {
+    if (vuln.id.startsWith("MAL-") || (vuln.aliases ?? []).some((alias) => alias.startsWith("MAL-")))
+        return true;
+    const specific = vuln.database_specific ?? {};
+    if (specific["malicious-packages-origins"] !== undefined)
+        return true;
+    if (Array.isArray(specific.cwe_ids) && specific.cwe_ids.includes("CWE-506"))
+        return true;
+    return (vuln.affected ?? []).some((affected) => {
+        const detail = affected.database_specific ?? {};
+        return (detail["malicious-packages-origins"] !== undefined ||
+            (typeof detail.source === "string" && detail.source.includes("/malicious-packages/")));
+    });
+}
+/** Whether an advisory withholds the versions it affects. */
+function blocks(vuln) {
+    return BLOCKING.has(vuln.database_specific?.severity?.toUpperCase() ?? "") || isMalware(vuln);
+}
+function eventVersion(event) {
+    return event.introduced ?? event.fixed ?? event.last_affected ?? event.limit;
+}
+/** OSV range evaluation: sort events by version, then sweep. A version or
+ *  event the comparator cannot parse makes the version count as affected. */
+export function inOsvRange(version, events, compare) {
+    try {
+        const sorted = events
+            .filter((event) => eventVersion(event) !== undefined)
+            .sort((a, b) => {
+            if (a.introduced === "0")
+                return b.introduced === "0" ? 0 : -1;
+            if (b.introduced === "0")
+                return 1;
+            const order = compare(eventVersion(a), eventVersion(b));
+            if (order !== 0)
+                return order;
+            // Ties are resolved independent of array order: an `introduced` at
+            // the same version as a closing event is processed last, so that
+            // version counts as affected (fail closed).
+            return Number(a.introduced !== undefined) - Number(b.introduced !== undefined);
+        });
+        let affected = false;
+        for (const event of sorted) {
+            if (event.introduced !== undefined) {
+                if (event.introduced === "0" || compare(version, event.introduced) >= 0)
+                    affected = true;
+            }
+            else if (event.fixed !== undefined) {
+                if (compare(version, event.fixed) >= 0)
+                    affected = false;
+            }
+            else if (event.last_affected !== undefined) {
+                if (compare(version, event.last_affected) > 0)
+                    affected = false;
+            }
+            else if (event.limit !== undefined && event.limit !== "*") {
+                if (compare(version, event.limit) >= 0)
+                    affected = false;
+            }
+        }
+        return affected;
+    }
+    catch {
+        return true;
+    }
+}
+function sameVersion(a, b, compare) {
+    if (a === b)
+        return true;
+    try {
+        return compare(a, b) === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function affects(version, affected, compare) {
+    if ((affected.versions ?? []).some((listed) => sameVersion(version, listed, compare)))
+        return true;
+    return (affected.ranges ?? []).some((range) => RANGE_TYPES.has(range.type ?? "") && inOsvRange(version, range.events ?? [], compare));
+}
+function indexOf(advisories, adapter) {
+    const compare = (a, b) => adapter.compareVersions(a, b);
+    const matching = (version, blocking) => advisories
+        .filter((advisory) => advisory.blocking === blocking)
+        .filter((advisory) => advisory.affected.some((affected) => affects(version, affected, compare)))
+        .map((advisory) => advisory.id);
+    return { withheld: (version) => matching(version, true), reported: (version) => matching(version, false) };
+}
+const EMPTY_INDEX = { withheld: () => [], reported: () => [] };
+export const DEFAULT_AUDIT_CACHE_ENTRIES = 5000;
+export const versionKey = (name, version) => `${name}@${version}`;
+export class OsvAudit {
+    options;
+    /** Advisories per package, least recently used first. Bounded to
+     *  `maxEntries`; expired entries are dropped on access and before any
+     *  live entry is evicted. A failed query is never cached. */
+    cache = new Map();
+    /** Single-flight: concurrent audits of one package share one OSV query. */
+    loads = new Map();
+    /** Advisory severities by id, with the OSV `modified` time they were
+     *  read at, least recently used first. */
+    vulns = new Map();
+    /** Advisory ids (and their `modified` time) per exact version from
+     *  querybatch, for the audit TTL, least recently used first, so repeated
+     *  plans don't re-query. */
+    batchCache = new Map();
+    now;
+    ttlMs;
+    maxEntries;
+    fetch;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+        this.ttlMs = options.ttlMs ?? 3_600_000;
+        this.maxEntries = options.maxEntries ?? DEFAULT_AUDIT_CACHE_ENTRIES;
+        // Every OSV request is bounded in time and size; any failure, including
+        // these, makes the audit unavailable (fail closed unless configured open).
+        this.fetch = boundedMetadataFetch(options.fetch, {
+            timeoutMs: options.timeoutMs ?? DEFAULT_METADATA_TIMEOUT_MS,
+            maxBytes: options.maxBytes ?? DEFAULT_MAX_METADATA_BYTES,
+        });
+    }
+    async audit(adapter, name) {
+        const wanted = adapter.normalizeName(name);
+        const key = `${adapter.osvEcosystem}:${wanted}`;
+        const cached = this.cache.get(key);
+        if (cached) {
+            this.cache.delete(key);
+            if (cached.expires > this.now()) {
+                this.cache.set(key, cached); // most recently used
+                return indexOf(cached.advisories, adapter);
+            }
+        }
+        let load = this.loads.get(key);
+        if (!load) {
+            load = this.load(adapter, name, wanted)
+                .then((advisories) => {
+                this.remember(key, advisories);
+                return advisories;
+            })
+                .finally(() => this.loads.delete(key));
+            this.loads.set(key, load);
+        }
+        try {
+            return indexOf(await load, adapter);
+        }
+        catch {
+            if (this.options.failOpen)
+                return EMPTY_INDEX;
+            throw new RegistryError(503, "wardby_audit_unavailable", `the vulnerability audit for "${name}" could not reach OSV; try again later`);
+        }
+    }
+    /** Advisories for exact versions, in as few OSV requests as possible:
+     *  one querybatch per 1000 versions (OSV matches each version itself),
+     *  then each affecting advisory's severity from /v1/vulns/{id}, cached by
+     *  id and OSV's `modified` time. Fails closed like `audit`: any failure
+     *  is a 503 wardby_audit_unavailable, unless configured to fail open. */
+    async auditVersions(adapter, versions, signal) {
+        try {
+            return await this.loadVersions(adapter, versions, signal);
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+            if (this.options.failOpen)
+                return new Map();
+            throw new RegistryError(503, "wardby_audit_unavailable", "the vulnerability audit of the lockfile's versions could not reach OSV; try again later");
+        }
+    }
+    async loadVersions(adapter, versions, signal) {
+        const unique = [...new Map(versions.map((entry) => [versionKey(entry.name, entry.version), entry])).values()];
+        /** Advisory id -> its `modified` time, and the versions it affects. */
+        const found = new Map();
+        const note = (key, vuln) => {
+            const advisory = found.get(vuln.id) ?? { modified: vuln.modified, versions: new Set() };
+            advisory.versions.add(key);
+            found.set(vuln.id, advisory);
+        };
+        const now = this.now();
+        const missing = [];
+        for (const entry of unique) {
+            const key = versionKey(entry.name, entry.version);
+            const cacheKey = `${adapter.osvEcosystem}:${key}`;
+            const cached = this.batchCache.get(cacheKey);
+            if (cached && cached.expires > now) {
+                this.batchCache.delete(cacheKey);
+                this.batchCache.set(cacheKey, cached); // most recently used
+                for (const vuln of cached.vulns)
+                    note(key, vuln);
+            }
+            else
+                missing.push(entry);
+        }
+        const fresh = new Map();
+        for (let start = 0; start < missing.length; start += OSV_BATCH_SIZE) {
+            const chunk = missing.slice(start, start + OSV_BATCH_SIZE);
+            let pending = chunk.map((entry) => ({ entry, pageToken: undefined }));
+            for (let page = 0; pending.length > 0; page += 1) {
+                if (page >= OSV_BATCH_MAX_PAGES)
+                    throw new Error("osv_batch_pages");
+                const response = await this.fetch(OSV_QUERY_BATCH, {
+                    method: "POST",
+                    accept: "application/json",
+                    signal,
+                    body: JSON.stringify({
+                        queries: pending.map(({ entry, pageToken }) => ({
+                            package: { name: entry.name, ecosystem: adapter.osvEcosystem },
+                            version: entry.version,
+                            ...(pageToken ? { page_token: pageToken } : {}),
+                        })),
+                    }),
+                });
+                if (!response.ok)
+                    throw new Error(`osv_status_${response.status}`);
+                const body = (await response.json());
+                const results = body.results ?? [];
+                // One result per query, in order: anything else cannot be matched
+                // to the versions it answers (fail closed).
+                if (results.length !== pending.length)
+                    throw new Error("osv_batch_mismatch");
+                const next = [];
+                results.forEach((result, index) => {
+                    const key = versionKey(pending[index].entry.name, pending[index].entry.version);
+                    const list = fresh.get(key) ?? [];
+                    fresh.set(key, list);
+                    for (const vuln of result.vulns ?? []) {
+                        if (typeof vuln.id !== "string" || vuln.id === "")
+                            throw new Error("osv_batch_vuln_id");
+                        const entry = { id: vuln.id, modified: typeof vuln.modified === "string" ? vuln.modified : "" };
+                        list.push(entry);
+                        note(key, entry);
+                    }
+                    if (typeof result.next_page_token === "string" && result.next_page_token !== "")
+                        next.push({ entry: pending[index].entry, pageToken: result.next_page_token });
+                });
+                pending = next;
+            }
+        }
+        // Cached only once every page of every version was read.
+        for (const [key, vulns] of fresh)
+            this.rememberBatch(`${adapter.osvEcosystem}:${key}`, vulns);
+        const withheld = new Map();
+        const ids = [...found.keys()];
+        let cursor = 0;
+        const worker = async () => {
+            while (cursor < ids.length) {
+                const id = ids[cursor++];
+                const advisory = found.get(id);
+                if (!(await this.blocking(id, advisory.modified, signal)))
+                    continue;
+                for (const key of advisory.versions)
+                    withheld.set(key, [...(withheld.get(key) ?? []), id]);
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(OSV_VULN_CONCURRENCY, ids.length) }, worker));
+        return withheld;
+    }
+    rememberBatch(key, vulns) {
+        const now = this.now();
+        this.batchCache.delete(key);
+        const limit = this.options.maxBatchEntries ?? DEFAULT_BATCH_CACHE_ENTRIES;
+        while (this.batchCache.size >= limit) {
+            const oldest = this.batchCache.keys().next();
+            if (oldest.done)
+                break;
+            this.batchCache.delete(oldest.value);
+        }
+        this.batchCache.set(key, { expires: now + this.ttlMs, vulns });
+    }
+    /** Whether an advisory is HIGH or CRITICAL, cached by id while OSV's
+     *  `modified` time for it is unchanged. */
+    async blocking(id, modified, signal) {
+        const cached = this.vulns.get(id);
+        if (cached && modified !== "" && cached.modified === modified) {
+            this.vulns.delete(id);
+            this.vulns.set(id, cached); // most recently used
+            return cached.blocking;
+        }
+        const response = await this.fetch(`${OSV_VULN}${encodeURIComponent(id)}`, { accept: "application/json", signal });
+        if (!response.ok)
+            throw new Error(`osv_status_${response.status}`);
+        const vuln = (await response.json());
+        if (typeof vuln.id !== "string")
+            throw new Error("osv_vuln_invalid");
+        const blocking = blocks(vuln);
+        this.vulns.delete(id);
+        while (this.vulns.size >= (this.options.maxVulnEntries ?? DEFAULT_VULN_CACHE_ENTRIES)) {
+            const oldest = this.vulns.keys().next();
+            if (oldest.done)
+                break;
+            this.vulns.delete(oldest.value);
+        }
+        this.vulns.set(id, { modified: typeof vuln.modified === "string" ? vuln.modified : modified, blocking });
+        return blocking;
+    }
+    remember(key, advisories) {
+        const now = this.now();
+        for (const [cachedKey, entry] of this.cache)
+            if (entry.expires <= now)
+                this.cache.delete(cachedKey);
+        this.cache.delete(key);
+        while (this.cache.size >= this.maxEntries) {
+            const oldest = this.cache.keys().next();
+            if (oldest.done)
+                break;
+            this.cache.delete(oldest.value);
+        }
+        this.cache.set(key, { expires: now + this.ttlMs, advisories });
+    }
+    async load(adapter, name, wanted) {
+        const vulns = await this.query(adapter.osvEcosystem, name);
+        const advisories = [];
+        for (const vuln of vulns) {
+            const affected = (vuln.affected ?? []).filter((entry) => entry.package?.ecosystem === adapter.osvEcosystem &&
+                typeof entry.package.name === "string" &&
+                adapter.normalizeName(entry.package.name) === wanted);
+            if (affected.length === 0)
+                continue;
+            advisories.push({ id: vuln.id, blocking: blocks(vuln), affected });
+        }
+        return advisories;
+    }
+    async query(ecosystem, name) {
+        const vulns = [];
+        let pageToken;
+        do {
+            const response = await this.fetch(OSV_QUERY, {
+                method: "POST",
+                accept: "application/json",
+                body: JSON.stringify({ package: { name, ecosystem }, ...(pageToken ? { page_token: pageToken } : {}) }),
+            });
+            if (!response.ok)
+                throw new Error(`osv_status_${response.status}`);
+            const page = (await response.json());
+            vulns.push(...(page.vulns ?? []));
+            pageToken = page.next_page_token;
+        } while (pageToken);
+        return vulns;
+    }
+}

package/dist/providers/coding-proxy/registry/bounded-fetch.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The registry core's guard around every metadata and OSV request: a
+ * timeout covering the request and its whole body, and a byte cap on the
+ * body. The body is read here, within both limits, and handed back as an
+ * in-memory Response, so an adapter's (or the audit's) `response.json()`
+ * can neither hang nor buffer an unbounded document. Downloads do not go
+ * through this: they stream with their own size and idle limits.
+ */
+import { type UpstreamFetch } from "../../../coding/registry/types.js";
+export declare const DEFAULT_METADATA_TIMEOUT_MS = 30000;
+export declare const DEFAULT_MAX_METADATA_BYTES: number;
+export interface MetadataFetchLimits {
+    timeoutMs: number;
+    maxBytes: number;
+}
+export declare function boundedMetadataFetch(upstream: UpstreamFetch, limits: MetadataFetchLimits): UpstreamFetch;

package/dist/providers/coding-proxy/registry/bounded-fetch.js

@@ -0,0 +1,77 @@
+/**
+ * The registry core's guard around every metadata and OSV request: a
+ * timeout covering the request and its whole body, and a byte cap on the
+ * body. The body is read here, within both limits, and handed back as an
+ * in-memory Response, so an adapter's (or the audit's) `response.json()`
+ * can neither hang nor buffer an unbounded document. Downloads do not go
+ * through this: they stream with their own size and idle limits.
+ */
+import { RegistryError } from "../../../coding/registry/types.js";
+export const DEFAULT_METADATA_TIMEOUT_MS = 30_000;
+export const DEFAULT_MAX_METADATA_BYTES = 64 * 1024 * 1024;
+function timedOut(signal, error) {
+    if (signal.aborted && signal.reason instanceof Error && signal.reason.name === "TimeoutError")
+        return true;
+    return error instanceof Error && error.name === "TimeoutError";
+}
+function unavailable(url) {
+    return new RegistryError(504, "wardby_upstream_unavailable", `${new URL(url).hostname} did not answer in time`);
+}
+function tooLarge(url, maxBytes) {
+    return new RegistryError(502, "wardby_metadata_too_large", `${new URL(url).hostname} returned more than ${Math.floor(maxBytes / (1024 * 1024))} MiB of metadata`);
+}
+export function boundedMetadataFetch(upstream, limits) {
+    return async (url, init = {}) => {
+        const timeout = AbortSignal.timeout(limits.timeoutMs);
+        const signal = init.signal ? AbortSignal.any([timeout, init.signal]) : timeout;
+        try {
+            const response = await upstream(url, { ...init, signal });
+            const declared = Number(response.headers.get("content-length"));
+            if (Number.isFinite(declared) && declared > limits.maxBytes) {
+                await response.body?.cancel().catch(() => undefined);
+                throw tooLarge(url, limits.maxBytes);
+            }
+            if (!response.body)
+                return response;
+            const chunks = [];
+            let total = 0;
+            const reader = response.body.getReader();
+            // The timeout also bounds a body that trickles: a stalled read is
+            // abandoned when the signal fires, even if the upstream ignores it.
+            const aborted = new Promise((_, reject) => {
+                if (signal.aborted)
+                    reject(signal.reason);
+                signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+            });
+            aborted.catch(() => undefined);
+            try {
+                for (;;) {
+                    const { done, value } = await Promise.race([reader.read(), aborted]);
+                    if (done)
+                        break;
+                    total += value.byteLength;
+                    if (total > limits.maxBytes)
+                        throw tooLarge(url, limits.maxBytes);
+                    chunks.push(value);
+                }
+            }
+            catch (error) {
+                await reader.cancel().catch(() => undefined);
+                throw error;
+            }
+            const nullBody = [101, 204, 205, 304].includes(response.status);
+            return new Response(nullBody ? null : Buffer.concat(chunks), {
+                status: response.status,
+                statusText: response.statusText,
+                headers: response.headers,
+            });
+        }
+        catch (error) {
+            if (error instanceof RegistryError)
+                throw error;
+            if (timedOut(signal, error))
+                throw unavailable(url);
+            throw error;
+        }
+    };
+}

package/dist/providers/coding-proxy/registry/plan.d.ts

@@ -0,0 +1,58 @@
+import { type AllowlistEntry, type LockfilePlanSupport, type ParsedLockfile, type RegistryAdapter, type UpstreamFetch } from "../../../coding/registry/types.js";
+import { type AuditedVersion, type WithheldVersions } from "./audit.js";
+import type { ApprovedVersion, StoredVersionFact } from "./store.js";
+export declare const DEFAULT_PLAN_MAX_ENTRIES = 5000;
+export declare const DEFAULT_PLAN_TIMEOUT_MS = 120000;
+/** Per-version documents fetched at once (each is a few KB). */
+export declare const DEFAULT_PLAN_FACT_CONCURRENCY = 16;
+/** Full package documents streamed at once for publish times (each may be
+ *  tens of MB, never held). */
+export declare const DEFAULT_PLAN_TIME_CONCURRENCY = 8;
+/** Largest (decompressed) package document streamed for publish times. */
+export declare const DEFAULT_PLAN_MAX_DOCUMENT_BYTES: number;
+export interface PlanRefusal {
+    name: string;
+    version: string;
+    code: string;
+    reason: string;
+    /** A verdict about the registry's name@version itself (too new, an
+     *  advisory, not published, no integrity, hosted elsewhere), true of it
+     *  whatever lockfile names it. Only these answer later downloads; a
+     *  lockfile-dependent verdict (unreachable, an integrity or source the
+     *  lockfile claims) never does. */
+    intrinsic?: boolean;
+    /** For a too-new refusal: the version's publish time, so whoever answers
+     *  from it can re-check the age against the cutoff at that time. */
+    publishedAt?: Date;
+}
+export interface PlanResult {
+    approved: ApprovedVersion[];
+    refused: PlanRefusal[];
+}
+export interface PlanFacts {
+    getVersionFacts(versions: readonly {
+        name: string;
+        version: string;
+    }[]): Promise<StoredVersionFact[]>;
+    putVersionFacts(facts: readonly StoredVersionFact[]): Promise<void>;
+}
+export interface PlanInput {
+    adapter: RegistryAdapter;
+    support: LockfilePlanSupport;
+    lockfile: ParsedLockfile;
+    roots: readonly AllowlistEntry[];
+    /** Latest publish time a version may have (the release-age cutoff). */
+    cutoff: Date;
+    facts: PlanFacts;
+    /** Bounded fetch for small per-version documents. */
+    upstream: UpstreamFetch;
+    /** Unbuffered fetch for streamed package documents. */
+    streamUpstream: UpstreamFetch;
+    audit(versions: readonly AuditedVersion[], signal: AbortSignal): Promise<WithheldVersions>;
+    hostAllowed(url: string): boolean;
+    signal: AbortSignal;
+    factConcurrency?: number;
+    timeConcurrency?: number;
+    maxDocumentBytes?: number;
+}
+export declare function verifyLockfilePlan(input: PlanInput): Promise<PlanResult>;