@westbayberry/dg 2.0.11 → 2.2.0

package/dist/proxy/server.js

@@ -1,24 +1,33 @@
 import { createHash } from "node:crypto";
 import { EventEmitter } from "node:events";
-import { BufferBudgetError, collectBounded } from "./buffer-budget.js";
+import { BufferBudgetError, collectBounded, maxArtifactBytes } from "./buffer-budget.js";
 import { readFileSync } from "node:fs";
-import { createServer, request as httpRequest } from "node:http";
-import { request as httpsRequest } from "node:https";
+import { Agent as HttpAgent, createServer, request as httpRequest } from "node:http";
+import { Agent as HttpsAgent, request as httpsRequest } from "node:https";
 import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { connect } from "node:net";
-import { createSecureContext, createServer as createTlsServer, connect as tlsConnect } from "node:tls";
+import { createSecureContext, createServer as createTlsServer, connect as tlsConnect, rootCertificates } from "node:tls";
 import { createEphemeralCertificateAuthority } from "./ca.js";
 import { shouldMitmHost } from "./classify-host.js";
-import { enforceProtectedInstall } from "./enforcement.js";
+import { generateProxyAuthToken, proxyAuthorizationValue, verifyProxyAuthorization, writeProxyAuthToken } from "./auth.js";
+import { enforceProtectedInstall, noteEnforcementSideEffectFailure } from "./enforcement.js";
+import { cooldownRequestParam, isCooldownExemptByDgFile } from "../policy/cooldown.js";
+import { loadUserConfig } from "../config/settings.js";
 import { artifactDisplayName, artifactUrlHash, extractRegistryMetadataIdentities, isRegistryIndexRequest, resolveArtifactIdentity } from "./metadata-map.js";
+import { loadPreverifiedMap, preverifiedKey } from "./preverified.js";
 import { authorityFor, connectViaUpstreamProxy, selectUpstreamProxy } from "./upstream-proxy.js";
 import { redactSecrets } from "../launcher/output-redaction.js";
+import { sanitize } from "../security/sanitize.js";
 import { envAuthToken } from "../auth/env-token.js";
 import { identityHeaders } from "../api/analyze.js";
 import { dgVersion } from "../commands/version.js";
+import { recordHeldPackage } from "../state/index.js";
 export async function startProductionHttpProxy(options) {
-    const ca = createEphemeralCertificateAuthority(options.session.files.ca);
+    const onCaRotate = options.onCaRotate;
+    const ca = createEphemeralCertificateAuthority(options.session.files.ca, onCaRotate ? { onRotate: (caCertPem) => safeCaRotateCallback(onCaRotate, caCertPem) } : {});
+    const authToken = generateProxyAuthToken();
+    writeProxyAuthToken(options.session.dir, authToken);
     const state = {
         ready: false,
         port: 0,
@@ -30,6 +39,10 @@ export async function startProductionHttpProxy(options) {
     };
     const activeSockets = new Set();
     const server = createServer((request, response) => {
+        if (!verifyProxyAuthorization(headerValue(request.headers["proxy-authorization"]), authToken)) {
+            sendProxyAuthRequired(response);
+            return;
+        }
         handleProxyRequest(request, response, options, state).catch((error) => {
             const decision = recordDecision(options, state, {
                 verdict: "block",
@@ -43,6 +56,10 @@ export async function startProductionHttpProxy(options) {
     server.on("connection", (socket) => trackSocket(activeSockets, socket));
     server.on("connect", (request, socket, head) => {
         const clientSocket = socket;
+        if (!verifyProxyAuthorization(headerValue(request.headers["proxy-authorization"]), authToken)) {
+            clientSocket.end("HTTP/1.1 407 Proxy Authentication Required\r\nProxy-Authenticate: Basic realm=\"dg\"\r\nConnection: close\r\n\r\n");
+            return;
+        }
         handleConnectRequest(request, clientSocket, head, options, state, ca, activeSockets).catch((error) => {
             const decision = recordDecision(options, state, {
                 verdict: "block",
@@ -63,9 +80,27 @@ export async function startProductionHttpProxy(options) {
     writeProxyState(options.session, state);
     return {
         port: address.port,
+        proxyAuthorization: proxyAuthorizationValue(authToken),
         close: () => closeServer(server, activeSockets)
     };
 }
+function safeCaRotateCallback(onCaRotate, caCertPem) {
+    try {
+        onCaRotate(caCertPem);
+    }
+    catch (error) {
+        noteEnforcementSideEffectFailure(error);
+    }
+}
+function sendProxyAuthRequired(response) {
+    const body = "Dependency Guardian proxy requires the per-session credential issued to the wrapped package manager.\n";
+    response.writeHead(407, {
+        "Proxy-Authenticate": "Basic realm=\"dg\"",
+        "Content-Type": "text/plain; charset=utf-8",
+        "Content-Length": Buffer.byteLength(body)
+    });
+    response.end(body);
+}
 export function readProxySessionState(session) {
     try {
         const parsed = JSON.parse(readFileSync(session.files.proxy, "utf8"));
@@ -134,6 +169,16 @@ async function handleConnectRequest(request, clientSocket, head, options, state,
         clientSocket.end("HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n");
         return;
     }
+    if (isLinkLocalHost(target)) {
+        recordDecision(options, state, {
+            verdict: "block",
+            packageName: target.hostname,
+            cause: "policy",
+            reason: `refusing CONNECT to link-local/metadata address ${target.hostname}`
+        });
+        clientSocket.end("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
+        return;
+    }
     if (!shouldMitmHost(target.hostname, options.env)) {
         state.events = [...state.events, `tunnel:${redactSecrets(authorityFor(target))}`];
         writeProxyState(options.session, state);
@@ -145,22 +190,248 @@ async function handleConnectRequest(request, clientSocket, head, options, state,
     await mitmTunnel(clientSocket, head, target, options, state, ca, activeSockets);
 }
 const REDIRECT_LIMIT = 5;
+// Streaming tail-hold: an OPT-IN fast path for artifacts so large their raw
+// download alone would outlast the client read timeout. It streams bytes while
+// hashing and withholds only the final TAIL bytes until the verdict arrives —
+// so on a block the client receives most of the (unverified) artifact and is
+// relied on to reject the truncated body via its own size/integrity checks.
+// That is a weaker guarantee than the default buffered path, which delivers
+// ZERO bytes until a pass verdict. It is therefore DISABLED by default; the
+// preferred fix for a slow verify is a generous client read timeout (set in
+// buildProxyChildEnv), which keeps the strong buffered guarantee. Enable only
+// for genuinely huge artifacts via DG_STREAM_THRESHOLD_BYTES=<bytes>.
+const STREAM_TAIL_BYTES = 64 * 1024;
+const STREAMING_DISABLED = Number.POSITIVE_INFINITY;
+// A package install fetches dozens-to-hundreds of artifacts from the same few
+// registry hosts. Without connection reuse each is a fresh TCP+TLS handshake
+// (~100-250ms to registry.npmjs.org); keep-alive agents pool sockets per host
+// so an N-tarball install pays one handshake, not N. Reuse is keyed by the full
+// connection option-set (host, port, TLS params), so this never crosses hosts
+// or mixes TLS trust. Purely transport-level — no effect on what gets verified.
+const upstreamHttpAgent = new HttpAgent({ keepAlive: true, maxSockets: 64, scheduling: "fifo" });
+const upstreamHttpsAgent = new HttpsAgent({ keepAlive: true, maxSockets: 64, scheduling: "fifo" });
+function streamThresholdBytes(env) {
+    const raw = env.DG_STREAM_THRESHOLD_BYTES;
+    if (raw === undefined || raw === "") {
+        return STREAMING_DISABLED;
+    }
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : STREAMING_DISABLED;
+}
+function canStreamTarget(target, options) {
+    if (selectUpstreamProxy(target, options.env)) {
+        return false;
+    }
+    if (isRegistryIndexRequest(target)) {
+        return false;
+    }
+    return !hostMatchesList(target.hostname, options.env.DG_PRIVATE_REGISTRY_HOSTS ?? "");
+}
+function shouldStreamArtifactResponse(live, env) {
+    if (live.statusCode < 200 || live.statusCode >= 300 || live.statusCode === 206) {
+        return false;
+    }
+    const contentType = headerValue(live.headers["content-type"]) ?? "";
+    if (/\bjson\b/i.test(contentType)) {
+        return false;
+    }
+    const contentLength = Number(headerValue(live.headers["content-length"]) ?? "");
+    return Number.isFinite(contentLength) && contentLength > streamThresholdBytes(env);
+}
+async function fetchUpstreamHeadersFollowingRedirects(request, target, env) {
+    let current = target;
+    let live = await fetchUpstreamHeaders(request, current, env);
+    for (let hop = 0; isRedirectStatus(live.statusCode); hop += 1) {
+        live.stream.resume();
+        if (hop >= REDIRECT_LIMIT) {
+            throw new Error(`registry redirect chain exceeded ${REDIRECT_LIMIT} hops for ${current.host}`);
+        }
+        const location = headerValue(live.headers.location);
+        if (!location) {
+            throw new Error(`registry returned a ${live.statusCode} redirect with no Location header for ${current.host}`);
+        }
+        const next = new URL(location, current);
+        if (next.protocol !== "http:" && next.protocol !== "https:") {
+            throw new Error(`registry redirected to unsupported protocol ${next.protocol}`);
+        }
+        if (isPrivateNetworkHost(next) && !isPrivateNetworkHost(target)) {
+            throw new Error(`registry redirected a public artifact request into a private address (${next.hostname})`);
+        }
+        live = await fetchUpstreamHeaders(syntheticGetRequest(redirectHopHeaders(request, current, next)), next, env);
+        current = next;
+    }
+    return live;
+}
+function fetchUpstreamHeaders(request, target, env) {
+    return new Promise((resolve, reject) => {
+        const isHttps = target.protocol === "https:";
+        const requester = isHttps ? httpsRequest : httpRequest;
+        let liveStream = null;
+        const upstream = requester({
+            hostname: upstreamHostname(target, env),
+            port: target.port ? Number(target.port) : isHttps ? 443 : 80,
+            path: `${target.pathname}${target.search}`,
+            method: request.method,
+            agent: isHttps ? upstreamHttpsAgent : upstreamHttpAgent,
+            headers: isHttps ? upstreamRequestHeaders(request, target) : stripProxyHopHeaders(request.headers),
+            ...(isHttps ? upstreamTlsOptions(env) : {})
+        }, (upstreamResponse) => {
+            liveStream = upstreamResponse;
+            resolve({
+                statusCode: upstreamResponse.statusCode ?? 502,
+                headers: responseHeaders(upstreamResponse),
+                stream: upstreamResponse
+            });
+        });
+        applyUpstreamTimeBudget(upstream, target, env, (error) => {
+            liveStream?.destroy(error);
+            reject(error);
+        });
+        upstream.on("error", reject);
+        request.on("data", (chunk) => upstream.write(chunk));
+        request.on("end", () => upstream.end());
+        request.on("error", reject);
+        request.once("close", () => {
+            if (!request.complete) {
+                upstream.destroy();
+            }
+        });
+    });
+}
+async function streamArtifactWithTailHold(response, target, options, state, live) {
+    const identityResolution = resolveArtifactIdentity(target, state.identities, options.classification);
+    if (identityResolution.kind === "ambiguous") {
+        live.stream.destroy();
+        const decision = recordDecision(options, state, {
+            verdict: "block",
+            packageName: identityResolution.packageName,
+            cause: "policy",
+            reason: identityResolution.reason
+        });
+        sendBlocked(response, decision);
+        return;
+    }
+    const identity = identityResolution.identity;
+    const inflightName = artifactDisplayName(identity);
+    state.inflight = [...state.inflight, inflightName];
+    writeProxyState(options.session, state);
+    const limit = maxArtifactBytes(options.env);
+    const hash = createHash("sha256");
+    const tail = [];
+    let tailSize = 0;
+    let total = 0;
+    response.writeHead(live.statusCode, live.headers);
+    response.once("close", () => {
+        if (!response.writableEnded) {
+            live.stream.destroy();
+        }
+    });
+    const finishInflight = () => {
+        state.inflight = removeFirst(state.inflight, inflightName);
+    };
+    try {
+        await new Promise((resolve, reject) => {
+            live.stream.on("data", (chunk) => {
+                total += chunk.length;
+                if (total > limit) {
+                    reject(new BufferBudgetError(`artifact exceeded the ${limit}-byte streaming budget for ${target.host}`));
+                    return;
+                }
+                hash.update(chunk);
+                tail.push(chunk);
+                tailSize += chunk.length;
+                while (tail.length > 1 && tailSize - (tail[0]?.length ?? 0) >= STREAM_TAIL_BYTES) {
+                    const released = tail.shift();
+                    if (released) {
+                        tailSize -= released.length;
+                        response.write(released);
+                    }
+                }
+            });
+            live.stream.once("end", () => resolve());
+            live.stream.once("error", reject);
+        });
+    }
+    catch (error) {
+        finishInflight();
+        live.stream.destroy();
+        recordDecision(options, state, {
+            verdict: "block",
+            packageName: artifactDisplayName(identity),
+            cause: error instanceof BufferBudgetError ? "proxy-setup-failure" : "registry-timeout",
+            reason: error instanceof Error ? error.message : "registry stream failed"
+        });
+        response.destroy();
+        return;
+    }
+    const sha256 = hash.digest("hex");
+    state.hashes = [...state.hashes, {
+            url: redactSecrets(target.toString()),
+            sha256,
+            identity
+        }];
+    writeProxyState(options.session, state);
+    const verdict = await lookupVerdict(options, target, sha256, { statusCode: live.statusCode, headers: live.headers }, identity).catch((error) => ({
+        verdict: "block",
+        packageName: artifactDisplayName(identity),
+        cause: "api-timeout",
+        reason: error instanceof Error ? error.message : "Dependency Guardian API verdict lookup failed"
+    }));
+    finishInflight();
+    const decision = recordDecision(options, state, verdict);
+    if (decision.action === "block") {
+        response.destroy();
+        return;
+    }
+    for (const chunk of tail) {
+        response.write(chunk);
+    }
+    response.end();
+}
 function isRedirectStatus(statusCode) {
     return [301, 302, 303, 307, 308].includes(statusCode);
 }
-function isPrivateNetworkHost(url) {
-    const host = url.hostname.toLowerCase().replace(/^\[/, "").replace(/\]$/, "");
-    if (host === "localhost" || host.endsWith(".localhost") || host === "0.0.0.0" || host === "::" || host === "::1") {
-        return true;
+// Node's WHATWG URL parser canonicalizes an IPv4-mapped IPv6 literal to the hex
+// hextet form ([::ffff:169.254.169.254] -> [::ffff:a9fe:a9fe]), so a guard that
+// only string-matches the dotted-decimal form silently lets the cloud-metadata
+// IP through as "public". Recover the embedded IPv4 (both forms) before
+// classifying so the IPv4 ranges below cover the mapped address too.
+function recoverIpv4MappedHost(host) {
+    const dotted = /^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i.exec(host);
+    if (dotted?.[1]) {
+        return dotted[1];
+    }
+    const hex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i.exec(host);
+    if (hex?.[1] && hex?.[2]) {
+        const hi = parseInt(hex[1], 16);
+        const lo = parseInt(hex[2], 16);
+        return `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
     }
-    if (/^(127|10|0)\./.test(host) || /^192\.168\./.test(host) || /^169\.254\./.test(host) || /^172\.(1[6-9]|2[0-9]|3[01])\./.test(host)) {
+    return host;
+}
+function isPrivateIpv4(host) {
+    return (/^(127|10|0)\./.test(host) ||
+        /^192\.168\./.test(host) ||
+        /^169\.254\./.test(host) ||
+        /^172\.(1[6-9]|2[0-9]|3[01])\./.test(host) ||
+        /^100\.(6[4-9]|[7-9][0-9]|1[01][0-9]|12[0-7])\./.test(host));
+}
+export function isPrivateNetworkHost(url) {
+    const raw = url.hostname.toLowerCase().replace(/^\[/, "").replace(/\]$/, "");
+    const host = recoverIpv4MappedHost(raw);
+    if (host === "localhost" || host.endsWith(".localhost") || host === "0.0.0.0" || host === "::" || host === "::1") {
         return true;
     }
-    if (/^::ffff:(127|10|0)\./.test(host) || /^::ffff:192\.168\./.test(host) || /^::ffff:169\.254\./.test(host) || /^::ffff:172\.(1[6-9]|2[0-9]|3[01])\./.test(host)) {
+    if (isPrivateIpv4(host)) {
         return true;
     }
     return /^(fe80|f[cd][0-9a-f]{2}):/.test(host);
 }
+export function isLinkLocalHost(url) {
+    const raw = url.hostname.toLowerCase().replace(/^\[/, "").replace(/\]$/, "");
+    const host = recoverIpv4MappedHost(raw);
+    return /^169\.254\./.test(host) || /^fe80:/.test(host);
+}
 function syntheticGetRequest(headers) {
     const request = new EventEmitter();
     request.method = "GET";
@@ -202,12 +473,40 @@ async function fetchUpstreamFollowingRedirects(request, target, env) {
 }
 const ARTIFACT_CONDITIONAL_HEADERS = ["range", "if-range", "if-none-match", "if-modified-since"];
 async function handleArtifactRequest(request, response, target, options, state) {
+    if (isLinkLocalHost(target)) {
+        const decision = recordDecision(options, state, {
+            verdict: "block",
+            packageName: packageNameFromUrl(target),
+            cause: "policy",
+            reason: `refusing to fetch from link-local/metadata address ${target.hostname}`
+        });
+        sendBlocked(response, decision);
+        return;
+    }
     if (!isRegistryIndexRequest(target)) {
         for (const header of ARTIFACT_CONDITIONAL_HEADERS) {
             delete request.headers[header];
         }
     }
-    const upstream = await fetchUpstreamFollowingRedirects(request, target, options.env).catch((error) => {
+    let upstream;
+    try {
+        if (canStreamTarget(target, options)) {
+            const live = await fetchUpstreamHeadersFollowingRedirects(request, target, options.env);
+            if (shouldStreamArtifactResponse(live, options.env)) {
+                await streamArtifactWithTailHold(response, target, options, state, live);
+                return;
+            }
+            upstream = {
+                statusCode: live.statusCode,
+                headers: live.headers,
+                body: await collectBounded(live.stream, { label: target.toString() })
+            };
+        }
+        else {
+            upstream = await fetchUpstreamFollowingRedirects(request, target, options.env);
+        }
+    }
+    catch (error) {
         const message = error instanceof Error ? error.message : "registry request failed";
         const decision = recordDecision(options, state, {
             verdict: "block",
@@ -216,8 +515,8 @@ async function handleArtifactRequest(request, response, target, options, state)
             reason: message
         });
         sendBlocked(response, decision);
-        return null;
-    });
+        return;
+    }
     if (!upstream) {
         return;
     }
@@ -287,7 +586,7 @@ async function handleArtifactRequest(request, response, target, options, state)
         reason: error instanceof Error ? error.message : "Dependency Guardian API verdict lookup failed"
     }));
     state.inflight = removeFirst(state.inflight, inflightName);
-    const decision = recordDecision(options, state, verdict);
+    const decision = recordDecision(options, state, verdict, identity.identity);
     if (decision.action === "block") {
         sendBlocked(response, decision);
         return;
@@ -386,6 +685,9 @@ function upstreamHostname(target, env = process.env) {
     return testUpstreamHostMap(env).get(hostname) ?? hostname;
 }
 function testUpstreamHostMap(env) {
+    if (env.NODE_ENV !== "test") {
+        return new Map();
+    }
     const entries = (env.DG_TEST_UPSTREAM_HOST_MAP ?? "")
         .split(",")
         .map((entry) => entry.trim())
@@ -403,7 +705,7 @@ function testUpstreamHostMap(env) {
 function fetchUpstream(request, target, env) {
     const upstreamProxy = selectUpstreamProxy(target, env);
     if (upstreamProxy && target.protocol === "http:") {
-        return fetchHttpViaProxy(request, target, upstreamProxy);
+        return fetchHttpViaProxy(request, target, upstreamProxy, env);
     }
     if (upstreamProxy && target.protocol === "https:") {
         return fetchHttpsViaProxy(request, target, upstreamProxy, env);
@@ -417,7 +719,8 @@ function fetchUpstream(request, target, env) {
             port: target.port ? Number(target.port) : 80,
             path: `${target.pathname}${target.search}`,
             method: request.method,
-            headers: request.headers
+            agent: upstreamHttpAgent,
+            headers: stripProxyHopHeaders(request.headers)
         }, (upstreamResponse) => {
             collectBounded(upstreamResponse, { label: target.toString() })
                 .then((body) => resolve({
@@ -427,6 +730,7 @@ function fetchUpstream(request, target, env) {
             }))
                 .catch(reject);
         });
+        applyUpstreamTimeBudget(upstream, target, env, reject);
         upstream.on("error", reject);
         request.on("data", (chunk) => upstream.write(chunk));
         request.on("end", () => upstream.end());
@@ -438,10 +742,10 @@ function fetchUpstream(request, target, env) {
         });
     });
 }
-function fetchHttpViaProxy(request, target, upstreamProxy) {
+function fetchHttpViaProxy(request, target, upstreamProxy, env) {
     return new Promise((resolve, reject) => {
         const headers = {
-            ...request.headers,
+            ...stripProxyHopHeaders(request.headers),
             ...(upstreamProxy.authorizationHeader ? { "Proxy-Authorization": upstreamProxy.authorizationHeader } : {})
         };
         const upstream = httpRequest({
@@ -459,6 +763,7 @@ function fetchHttpViaProxy(request, target, upstreamProxy) {
             }))
                 .catch(reject);
         });
+        applyUpstreamTimeBudget(upstream, target, env, reject);
         upstream.on("error", reject);
         request.on("data", (chunk) => upstream.write(chunk));
         request.on("end", () => upstream.end());
@@ -477,6 +782,7 @@ function fetchHttpsDirect(request, target, env) {
             port: target.port ? Number(target.port) : 443,
             path: `${target.pathname}${target.search}`,
             method: request.method,
+            agent: upstreamHttpsAgent,
             headers: upstreamRequestHeaders(request, target),
             ...upstreamTlsOptions(env)
         }, (upstreamResponse) => {
@@ -488,6 +794,7 @@ function fetchHttpsDirect(request, target, env) {
             }))
                 .catch(reject);
         });
+        applyUpstreamTimeBudget(upstream, target, env, reject);
         upstream.on("error", reject);
         request.on("data", (chunk) => upstream.write(chunk));
         request.on("end", () => upstream.end());
@@ -514,9 +821,35 @@ function connectTlsOverSocket(socket, target, env) {
             ALPNProtocols: ["http/1.1"],
             ...upstreamTlsOptions(env)
         }, () => resolve(tlsSocket));
+        applyUpstreamTimeBudget(tlsSocket, target, env);
         tlsSocket.once("error", reject);
     });
 }
+function upstreamIdleTimeoutMs(env) {
+    return parsePositiveInteger(env.DG_UPSTREAM_IDLE_TIMEOUT_MS, 30_000);
+}
+function upstreamTotalTimeoutMs(env) {
+    return parsePositiveInteger(env.DG_UPSTREAM_TOTAL_TIMEOUT_MS, 600_000);
+}
+function applyUpstreamTimeBudget(upstream, target, env, onTimeout) {
+    const idleMs = upstreamIdleTimeoutMs(env);
+    const totalMs = upstreamTotalTimeoutMs(env);
+    const expire = (detail) => {
+        const error = new Error(`upstream registry request for ${target.host} timed out: ${detail}`);
+        onTimeout?.(error);
+        upstream.destroy(error);
+    };
+    upstream.setTimeout(idleMs, () => expire(`no data for ${idleMs}ms`));
+    const totalTimer = setTimeout(() => expire(`exceeded the ${totalMs}ms total budget`), totalMs);
+    totalTimer.unref();
+    upstream.once("close", () => clearTimeout(totalTimer));
+}
+function stripProxyHopHeaders(headers) {
+    const stripped = { ...headers };
+    delete stripped["proxy-authorization"];
+    delete stripped["proxy-connection"];
+    return stripped;
+}
 function writeRawHttpRequest(tlsSocket, request, target, requestBody) {
     return new Promise((resolve, reject) => {
         collectBounded(tlsSocket, { label: target.toString() }).then(resolve).catch(reject);
@@ -589,7 +922,7 @@ function upstreamTlsOptions(env) {
     }
     try {
         return {
-            ca: readFileSync(caPath, "utf8")
+            ca: [...rootCertificates, readFileSync(caPath, "utf8")]
         };
     }
     catch {
@@ -625,6 +958,11 @@ async function lookupVerdict(options, target, sha256, upstream, identity) {
     if (shouldUseScanTarball(options, target, identity)) {
         return lookupScanTarballVerdict(options, target, sha256, upstream, identity);
     }
+    const preverified = preverifiedVerdict(options, target, sha256, identity);
+    if (preverified) {
+        return preverified;
+    }
+    const cooldown = resolveCooldownRequest(options, identity);
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), options.verdictTimeoutMs ?? installVerdictTimeoutMs(options.env));
     try {
@@ -638,7 +976,7 @@ async function lookupVerdict(options, target, sha256, upstream, identity) {
             body: JSON.stringify({
                 manager: options.classification.manager,
                 action: options.classification.action,
-                url: target.toString(),
+                url: redactSecrets(target.toString()),
                 artifactUrlHash: artifactUrlHash(target),
                 ecosystem: identity.ecosystem,
                 name: identity.name,
@@ -647,7 +985,8 @@ async function lookupVerdict(options, target, sha256, upstream, identity) {
                 sourceKind: identity.sourceKind,
                 sha256,
                 statusCode: upstream.statusCode,
-                contentType: headerValue(upstream.headers["content-type"])
+                contentType: headerValue(upstream.headers["content-type"]),
+                ...(cooldown ? { cooldown } : {})
             }),
             signal: controller.signal
         });
@@ -658,7 +997,7 @@ async function lookupVerdict(options, target, sha256, upstream, identity) {
                 packageName: artifactDisplayName(identity),
                 cause: "quota-exceeded",
                 reason: "You've reached your monthly scan limit. Upgrade at westbayberry.com/pricing or wait for it to reset.",
-                ...(typeof body.resetsAt === "string" ? { resetsAt: body.resetsAt } : {}),
+                ...(typeof body.resetsAt === "string" ? { resetsAt: sanitize(body.resetsAt) } : {}),
                 quotaBehavior: body.quotaBehavior === "pass" ? "pass" : "block"
             };
         }
@@ -744,6 +1083,31 @@ async function lookupScanTarballVerdict(options, target, sha256, upstream, ident
         clearTimeout(timeout);
     }
 }
+// A preflight batch-analyze already verdicted this exact name@version (and the
+// user accepted any warns), so a per-artifact API round-trip would re-answer
+// the same question. Trust it only when the identity came from registry
+// metadata and the preflight applied the same cooldown gate the proxy would;
+// the synthesized verdict goes through normalizeVerdict so the scanned-SHA
+// cross-check blocks tampered bytes exactly like a server response would.
+function preverifiedVerdict(options, target, streamedSha256, identity) {
+    if (identity.sourceKind !== "registry-metadata") {
+        return null;
+    }
+    const entry = loadPreverifiedMap(options.session.dir).get(preverifiedKey(identity.ecosystem, identity.name, identity.version));
+    if (!entry) {
+        return null;
+    }
+    if (!entry.cooldownEvaluated && resolveCooldownRequest(options, identity) !== undefined) {
+        return null;
+    }
+    return normalizeVerdict({
+        verdict: entry.action,
+        cause: entry.action,
+        packageName: `${identity.name}@${identity.version}`,
+        reason: entry.reason ?? (entry.action === "pass" ? "verified before install" : "flagged for review"),
+        ...(entry.scannedSha256 ? { scannedSha256: entry.scannedSha256 } : {})
+    }, target, identity, streamedSha256);
+}
 function normalizeVerdict(value, target, identity, streamedSha256) {
     if (!isRecord(value)) {
         throw new Error("Dependency Guardian API returned a malformed verdict");
@@ -762,13 +1126,53 @@ function normalizeVerdict(value, target, identity, streamedSha256) {
         };
     }
     const cause = typeof value.cause === "string" ? value.cause : undefined;
+    const cooldown = parseCooldownInfo(value.cooldown);
+    const dashboardUrl = safeDashboardUrl(value.dashboardUrl);
     return {
         verdict,
-        packageName: typeof value.packageName === "string" ? value.packageName : artifactDisplayName(identity) || packageNameFromUrl(target),
+        packageName: typeof value.packageName === "string" ? sanitize(value.packageName) : artifactDisplayName(identity) || packageNameFromUrl(target),
         ...(isProxyCause(cause) ? { cause } : {}),
-        reason: typeof value.reason === "string" ? value.reason : `API verdict ${verdict}`,
-        ...(typeof value.dashboardUrl === "string" ? { dashboardUrl: value.dashboardUrl } : {}),
-        ...(value.unauthenticated === true ? { unauthenticated: true } : {})
+        reason: typeof value.reason === "string" ? sanitize(value.reason) : `API verdict ${verdict}`,
+        ...(dashboardUrl ? { dashboardUrl } : {}),
+        ...(value.unauthenticated === true ? { unauthenticated: true } : {}),
+        ...(cooldown ? { cooldown } : {})
+    };
+}
+function safeDashboardUrl(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    try {
+        const url = new URL(sanitize(value));
+        return url.protocol === "https:" ? url.toString() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolveCooldownRequest(options, identity) {
+    if (identity.ecosystem === "unknown" || identity.version === "unknown") {
+        return undefined;
+    }
+    if (isCooldownExemptByDgFile(identity.name, identity.ecosystem, options.cooldownExemptions ?? [])) {
+        return undefined;
+    }
+    try {
+        return cooldownRequestParam(loadUserConfig(options.env), options.env, identity.ecosystem, identity.name);
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseCooldownInfo(value) {
+    if (!isRecord(value) || typeof value.requiredDays !== "number" || !Number.isFinite(value.requiredDays)) {
+        return undefined;
+    }
+    return {
+        requiredDays: value.requiredDays,
+        ...(typeof value.ageDays === "number" && Number.isFinite(value.ageDays) ? { ageDays: value.ageDays } : {}),
+        ...(typeof value.publishedAt === "string" ? { publishedAt: sanitize(value.publishedAt) } : {}),
+        ...(typeof value.eligibleAt === "string" ? { eligibleAt: sanitize(value.eligibleAt) } : {})
     };
 }
 function normalizeScanTarballVerdict(value, target, identity, streamedSha256) {
@@ -829,7 +1233,7 @@ function mergeIdentities(existing, next) {
     }
     return merged;
 }
-function recordDecision(options, state, verdict) {
+function recordDecision(options, state, verdict, identity) {
     const decision = enforceProtectedInstall({
         classification: options.classification,
         env: options.env,
@@ -839,10 +1243,28 @@ function recordDecision(options, state, verdict) {
     state.decisions = [...state.decisions, decision];
     state.events = [...state.events, `${decision.action}:${decision.cause}:${redactSecrets(decision.packageName)}`];
     writeProxyState(options.session, state);
+    if (identity && decision.action === "block" && decision.cause === "cooldown" && decision.cooldown) {
+        try {
+            recordHeldPackage({
+                ecosystem: identity.ecosystem,
+                name: identity.name,
+                version: identity.version,
+                requiredDays: decision.cooldown.requiredDays,
+                ...(decision.cooldown.ageDays !== undefined ? { ageDays: decision.cooldown.ageDays } : {}),
+                ...(decision.cooldown.publishedAt ? { publishedAt: decision.cooldown.publishedAt } : {}),
+                ...(decision.cooldown.eligibleAt ? { eligibleAt: decision.cooldown.eligibleAt } : {}),
+                manager: options.classification.manager
+            }, options.env);
+        }
+        catch (error) {
+            noteEnforcementSideEffectFailure(error);
+        }
+    }
     return decision;
 }
 function sendBlocked(response, decision) {
-    const body = `Dependency Guardian blocked ${redactSecrets(decision.packageName)}: ${redactSecrets(decision.reason)}\n`;
+    const breadcrumb = decision.cause === "cooldown" ? " · holds: dg cooldown" : "";
+    const body = `Dependency Guardian blocked ${redactSecrets(decision.packageName)}: ${redactSecrets(decision.reason)}${breadcrumb}\n`;
     response.writeHead(403, {
         "Content-Type": "text/plain; charset=utf-8",
         "Content-Length": Buffer.byteLength(body)
@@ -875,24 +1297,29 @@ function packageNameFromUrl(url) {
     return name ? decodeURIComponent(name) : url.hostname;
 }
 function writeProxyState(session, state) {
-    mkdirSync(dirname(session.files.proxy), {
-        recursive: true,
-        mode: 0o700
-    });
-    const tempPath = `${session.files.proxy}.${process.pid}.${process.hrtime.bigint().toString(36)}.tmp`;
     try {
-        writeFileSync(tempPath, `${JSON.stringify(state, null, 2)}\n`, {
-            encoding: "utf8",
-            flag: "wx",
-            mode: 0o600
+        mkdirSync(dirname(session.files.proxy), {
+            recursive: true,
+            mode: 0o700
         });
-        renameSync(tempPath, session.files.proxy);
+        const tempPath = `${session.files.proxy}.${process.pid}.${process.hrtime.bigint().toString(36)}.tmp`;
+        try {
+            writeFileSync(tempPath, `${JSON.stringify(state, null, 2)}\n`, {
+                encoding: "utf8",
+                flag: "wx",
+                mode: 0o600
+            });
+            renameSync(tempPath, session.files.proxy);
+        }
+        catch (error) {
+            rmSync(tempPath, {
+                force: true
+            });
+            throw error;
+        }
     }
     catch (error) {
-        rmSync(tempPath, {
-            force: true
-        });
-        throw error;
+        noteEnforcementSideEffectFailure(error);
     }
 }
 function removeFirst(items, value) {
@@ -905,7 +1332,7 @@ function removeFirst(items, value) {
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
-function isProxyCause(value) {
+export function isProxyCause(value) {
     return [
         "pass",
         "warn",
@@ -920,6 +1347,7 @@ function isProxyCause(value) {
         "api-timeout",
         "registry-timeout",
         "analysis-incomplete",
+        "cooldown",
         "unsupported-manager",
         "proxy-setup-failure"
     ].includes(value ?? "");