@counterfact-labs/cli 0.1.3 → 0.2.4

package/dist/gatekeeper/cli-api.js

@@ -0,0 +1,174 @@
+import { cliRefusals, refusalExitCode } from "../contract/cli-refusals.js";
+import { CLI_VERSION } from "../contract/cli-version.js";
+import { consoleSchemeAllowed } from "../contract/console-url.js";
+import { cliApiMessages } from "../contract/cli-api-messages.js";
+import { emailSignInMessages } from "../contract/email-sign-in-messages.js";
+import { CLI_BODY_LIMIT } from "../cli/api-types.js";
+export { DEFAULT_CONSOLE_URL as DEFAULT_URL } from "../setup-pings/client.js";
+export class ApiError extends Error {
+    status;
+    code;
+    retryAfterMs;
+    constructor(status, code, message, retryAfterMs = 0) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+const emailRoutes = {
+    "email/start": { fields: ["email"], successStatus: 202, failures: { invalid_email: 400 }, jsonCooldown: true },
+    "email/verify": { fields: ["email", "code", "clientName"], successStatus: 200,
+        failures: { wrong_code: 400, expired: 400, too_many_attempts: 429 }, jsonCooldown: false },
+};
+// Longer cooldowns keep the server's delay but use the sentence without a duration.
+const MAX_DISPLAYED_EMAIL_COOLDOWN_MS = 24 * 60 * 60 * 1000;
+function retryAfterMs(value, rejectNegativeSeconds = false) {
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    // Date parsing also accepts negative number strings, which are not valid email cooldowns.
+    if (rejectNegativeSeconds && seconds < 0)
+        return undefined;
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1000;
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : undefined;
+}
+function requestBody(path, body, emailRoute) {
+    if ((path === "balance" || path === "checks/mode" || /^findings\/[a-zA-Z0-9_-]+$/.test(path)) && body === undefined)
+        return undefined;
+    if (body && typeof body === "object" && !Array.isArray(body)) {
+        const fields = Object.keys(body);
+        if (path === "device" && fields.length === 0)
+            return {};
+        if (path === "device/token" && fields.length === 1 && fields[0] === "deviceCode") {
+            const deviceCode = body.deviceCode;
+            if (typeof deviceCode === "string")
+                return { deviceCode };
+        }
+        if (emailRoute && fields.length === emailRoute.fields.length && fields.every(field => emailRoute.fields.includes(field))) {
+            const selected = {};
+            for (const field of emailRoute.fields) {
+                const value = body[field];
+                if (typeof value !== "string")
+                    throw new Error(cliApiMessages.request_failed);
+                selected[field] = value;
+            }
+            return selected;
+        }
+    }
+    throw new Error(cliApiMessages.request_failed);
+}
+function emailFailure(route, response, value) {
+    if (response.status === 404)
+        return new ApiError(404, "email_unavailable", emailSignInMessages.email_unavailable);
+    const failure = value && typeof value === "object" && !Array.isArray(value)
+        ? value : undefined;
+    const code = failure?.error;
+    if (typeof code === "string" && Object.hasOwn(route.failures, code) && route.failures[code] === response.status) {
+        return new ApiError(response.status, code, emailSignInMessages[code]);
+    }
+    if (response.status === 429 && code === "rate_limited") {
+        let cooldown = retryAfterMs(response.headers.get("retry-after"), true);
+        if (route.jsonCooldown && typeof failure?.retryAfter === "number" && failure.retryAfter >= 0 && Number.isFinite(failure.retryAfter * 1000)) {
+            cooldown = failure.retryAfter * 1000;
+        }
+        if (cooldown !== undefined && !Number.isFinite(cooldown))
+            cooldown = undefined;
+        return new ApiError(429, code, cooldown === undefined || cooldown > MAX_DISPLAYED_EMAIL_COOLDOWN_MS ? emailSignInMessages.rate_limited
+            : emailSignInMessages.rate_limited_with_cooldown(Math.ceil(cooldown / 1000)), cooldown ?? 0);
+    }
+    return new ApiError(response.status, "request_failed", emailSignInMessages.request_failed);
+}
+export class ApiClient {
+    token;
+    fetcher;
+    signal;
+    baseUrl;
+    constructor(baseUrl, token, fetcher = fetch, signal) {
+        this.token = token;
+        this.fetcher = fetcher;
+        this.signal = signal;
+        const url = new URL(baseUrl);
+        if (!consoleSchemeAllowed(url) || url.username || url.password || url.search || url.hash)
+            throw new Error("COUNTERFACT_URL must be an HTTP or HTTPS address without credentials or query fields.");
+        this.baseUrl = url.href.replace(/\/+$/, "");
+    }
+    async request(path, body, authenticated = true) {
+        const emailRoute = Object.hasOwn(emailRoutes, path) ? emailRoutes[path] : undefined;
+        const throwIfAborted = () => {
+            if (emailRoute && this.signal?.aborted)
+                throw new DOMException(emailSignInMessages.cancelled, "AbortError");
+            this.signal?.throwIfAborted();
+        };
+        throwIfAborted();
+        const safeBody = requestBody(path, body, emailRoute);
+        const headers = { accept: "application/json", "x-counterfact-cli-version": CLI_VERSION };
+        if (authenticated) {
+            const token = await this.token();
+            if (!token)
+                throw new Error("Not signed in. Run counterfact-labs login.");
+            headers.authorization = `Bearer ${token}`;
+        }
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        const serialized = body === undefined ? undefined : JSON.stringify(safeBody);
+        if (serialized !== undefined && Buffer.byteLength(serialized, "utf8") > CLI_BODY_LIMIT) {
+            throw new ApiError(413, "body_too_large", cliRefusals.body_too_large);
+        }
+        const controller = new AbortController();
+        const cancel = () => controller.abort(this.signal?.reason);
+        const timeout = setTimeout(() => controller.abort(), 120_000);
+        timeout.unref();
+        this.signal?.addEventListener("abort", cancel, { once: true });
+        try {
+            throwIfAborted();
+            let response;
+            try {
+                response = await this.fetcher(`${this.baseUrl}/api/cli/${path}`, {
+                    method: body === undefined ? "GET" : "POST", headers,
+                    body: serialized,
+                    redirect: "error", signal: controller.signal,
+                });
+            }
+            catch {
+                throwIfAborted();
+                throw new ApiError(0, "unreachable", cliApiMessages.unreachable);
+            }
+            throwIfAborted();
+            if (emailRoute && response.ok && response.status !== emailRoute.successStatus) {
+                // Cleanup failures must not replace the safe invalid-response sentence.
+                await response.body?.cancel().catch(() => undefined);
+                throw new Error(emailSignInMessages.invalid_response);
+            }
+            let value;
+            try {
+                value = await response.json();
+            }
+            catch (error) {
+                throwIfAborted();
+                if (response.ok) {
+                    if (error instanceof SyntaxError)
+                        throw new Error(cliApiMessages.invalid_response);
+                    throw new ApiError(0, "unreachable", cliApiMessages.unreachable);
+                }
+            }
+            throwIfAborted();
+            if (emailRoute && !response.ok)
+                throw emailFailure(emailRoute, response, value);
+            if (!response.ok) {
+                const error = value;
+                throw new ApiError(response.status, error?.code ?? "request_failed", error?.code && Object.hasOwn(cliRefusals, error.code) ? cliRefusals[error.code]
+                    : typeof error?.error === "string" ? error.error : cliApiMessages.request_failed, retryAfterMs(response.headers.get("retry-after")) ?? 0);
+            }
+            return value;
+        }
+        finally {
+            clearTimeout(timeout);
+            this.signal?.removeEventListener("abort", cancel);
+        }
+    }
+}
+export function errorCode(error) { return refusalExitCode(error instanceof ApiError ? error.code : undefined); }
+export function errorText(error) { return error instanceof Error ? error.message : cliApiMessages.request_failed; }

package/dist/gatekeeper/client.js

@@ -0,0 +1,76 @@
+import { randomBytes } from "node:crypto";
+import { relayAnswer, relayRequest } from "../contract/messages.js";
+import { verifyAttestation } from "./attestation.js";
+const BUSY_INITIAL_BACKOFF_MS = 250;
+const BUSY_MAX_BACKOFF_MS = 5_000;
+export class GatekeeperClientError extends Error {
+    name = "GatekeeperClientError";
+}
+export class GatekeeperClient {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async call(request, sendOptions = {}) {
+        const beforeSend = () => {
+            if (sendOptions.signal?.aborted || this.options.deadlineMs && this.options.deadlineMs() <= Date.now())
+                throw new GatekeeperClientError("Relay request cancelled");
+            sendOptions.beforeSend?.();
+        };
+        beforeSend();
+        const outgoing = relayRequest.safeParse({ ...request, nonce: randomBytes(32).toString("hex") });
+        if (!outgoing.success)
+            throw new GatekeeperClientError("Invalid relay request");
+        const options = this.options;
+        if (options.mode === "development") {
+            let token;
+            try {
+                token = await options.connection.attestation();
+            }
+            catch {
+                throw new GatekeeperClientError("Unable to read relay attestation");
+            }
+            verifyAttestation(token, options.connection.channelPublicKey, options.policy);
+        }
+        let backoffMs = BUSY_INITIAL_BACKOFF_MS;
+        while (true) {
+            let incoming;
+            try {
+                beforeSend();
+                incoming = await options.connection.send(outgoing.data, { ...sendOptions, beforeSend });
+            }
+            catch {
+                // Transport errors can include request bodies, so do not retain their text or cause.
+                throw new GatekeeperClientError("Unable to send relay request");
+            }
+            const answer = relayAnswer.safeParse(incoming);
+            if (!answer.success)
+                throw new GatekeeperClientError("Invalid relay answer");
+            if (answer.data.nonce !== outgoing.data.nonce)
+                throw new GatekeeperClientError("Relay answer nonce mismatch");
+            if (answer.data.ok || answer.data.code !== "busy" || !options.deadlineMs)
+                return answer.data;
+            const remainingMs = options.deadlineMs() - Date.now();
+            if (remainingMs <= 0)
+                return answer.data;
+            // Busy has not started provider work. Keep its call identity and retry only within this run's lease.
+            await this.waitForCapacity(Math.min(backoffMs, remainingMs), sendOptions.signal);
+            if (options.deadlineMs() <= Date.now())
+                return answer.data;
+            backoffMs = Math.min(backoffMs * 2, BUSY_MAX_BACKOFF_MS);
+            outgoing.data = { ...outgoing.data, nonce: randomBytes(32).toString("hex") };
+        }
+    }
+    async waitForCapacity(waitMs, signal) {
+        if (signal?.aborted)
+            throw new GatekeeperClientError("Relay request cancelled");
+        await new Promise((resolve, reject) => {
+            const abort = () => {
+                clearTimeout(timer);
+                reject(new GatekeeperClientError("Relay request cancelled"));
+            };
+            const timer = setTimeout(() => { signal?.removeEventListener("abort", abort); resolve(); }, waitMs);
+            signal?.addEventListener("abort", abort, { once: true });
+        });
+    }
+}

package/dist/gatekeeper/connection-exchange.js

@@ -0,0 +1,61 @@
+import { RELAY_MAX_FRAME_BYTES, deliveryReceipt, relayAnswer, relayAnswerFrame, relayRequest } from "../contract/messages.js";
+export class RelayConnectionError extends Error {
+    name = "RelayConnectionError";
+    constructor() { super("Relay connection failed"); }
+}
+/** Calls and delivery retries share the authenticated transport and run in input order. */
+export function createRelayExchange(options) {
+    let queue = Promise.resolve();
+    async function sendOne(input) {
+        try {
+            options.valid();
+            const request = relayRequest.parse(input);
+            if (!request.callId)
+                throw new Error();
+            // Provider work can exceed a network-body timeout; evidence expiry still closes this exact socket.
+            const response = await options.exchange("/relay", request, RELAY_MAX_FRAME_BYTES, options.remainingEvidenceMs());
+            const legacy = options.development ? relayAnswer.safeParse(response.body) : undefined;
+            const frame = legacy?.success ? { answer: legacy.data, delivery: undefined } : relayAnswerFrame.parse(response.body);
+            if (frame.answer.nonce !== request.nonce)
+                throw new Error();
+            if (frame.delivery) {
+                const { confirmation } = frame.delivery;
+                if (confirmation.callId !== request.callId)
+                    throw new Error();
+                // The relay enforces its deadline on its own clock; local clock drift must not discard a paid answer.
+                let acknowledged = false;
+                for (let attempt = 0; attempt < 2; attempt++) {
+                    options.valid();
+                    const receipt = await options.exchange("/delivery", confirmation, 1024);
+                    if (receipt.status === 200) {
+                        deliveryReceipt.parse(receipt.body);
+                        acknowledged = true;
+                        break;
+                    }
+                }
+                if (!acknowledged)
+                    throw new Error();
+            }
+            return frame.answer;
+        }
+        catch {
+            options.close();
+            throw new RelayConnectionError();
+        }
+    }
+    return (request, sendOptions = {}) => {
+        // Snapshot before queuing so overlapping callers cannot alter later writes.
+        const parsed = relayRequest.safeParse(request);
+        if (!parsed.success)
+            return Promise.reject(new RelayConnectionError());
+        const pending = queue.then(() => {
+            // Cancellation stops queued work, but a dispatched answer must finish delivery before closing.
+            if (sendOptions.signal?.aborted)
+                throw new RelayConnectionError();
+            sendOptions.beforeSend?.();
+            return sendOne(parsed.data);
+        });
+        queue = pending.catch(() => { });
+        return pending;
+    };
+}

package/dist/gatekeeper/connection.js

@@ -0,0 +1,140 @@
+import { isLoopbackHost } from "./loopback.js";
+import { randomBytes, X509Certificate } from "node:crypto";
+import { Agent, request as httpsRequest } from "node:https";
+import { connect } from "node:tls";
+import { PRODUCTION_EVIDENCE_VERSION, RELAY_MAX_FRAME_BYTES, RELAY_URL } from "../contract/messages.js";
+import { requestBoundedResponse } from "../transport/http-response.js";
+import { relayExportedKeyMaterial } from "../transport/tls-exporter.js";
+import { createRelayExchange, RelayConnectionError } from "./connection-exchange.js";
+export { RelayConnectionError } from "./connection-exchange.js";
+import { verifyProductionAttestation } from "./production-attestation.js";
+import { verifyAttestation } from "./attestation.js";
+import { validateProductionTrust } from "./trust/policy.js";
+export function relayOrigin(value) {
+    const origin = new URL(value);
+    if (origin.protocol !== "https:" || origin.username || origin.password || origin.pathname !== "/" || origin.search || origin.hash)
+        throw new Error();
+    return origin;
+}
+/** A self-signed leaf establishes encryption provisionally; the selected attestation policy authenticates the workload. */
+export async function connectRelay(url = RELAY_URL, policy) {
+    let socket, agent;
+    let closed = false, expiryTimer;
+    const close = () => {
+        closed = true;
+        clearTimeout(expiryTimer);
+        agent?.destroy();
+        socket?.destroy();
+    };
+    try {
+        const trust = policy.development ? undefined : validateProductionTrust(policy.trust);
+        const origin = relayOrigin(url);
+        const timeoutMs = policy.timeoutMs ?? 30_000;
+        const nowMs = policy.now ? () => policy.now() * 1000 : Date.now;
+        const now = () => Math.floor(nowMs() / 1000);
+        if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120_000)
+            throw new Error();
+        let hostname = origin.hostname.replace(/^\[|\]$/g, "");
+        if (policy.development) {
+            if (!policy.development.allowDevelopment || policy.trust ||
+                !isLoopbackHost(hostname))
+                throw new Error();
+            // Resolve the conventional name locally so DNS cannot move development trust off the machine.
+            if (hostname === "localhost")
+                hostname = "127.0.0.1";
+        }
+        socket = await new Promise((resolve, reject) => {
+            // Attestation authenticates this exact TLS socket before any customer request is sent.
+            // nosemgrep: problem-based-packs.insecure-transport.js-node.bypass-tls-verification.bypass-tls-verification
+            const provisional = connect({ host: hostname, port: Number(origin.port || 443),
+                rejectUnauthorized: false, minVersion: "TLSv1.3", ALPNProtocols: ["http/1.1"] });
+            // Install ownership before connection establishment so even a handshake timeout destroys the socket.
+            socket = provisional;
+            const timer = setTimeout(() => { provisional.destroy(); reject(new RelayConnectionError()); }, timeoutMs);
+            provisional.once("error", () => { clearTimeout(timer); reject(new RelayConnectionError()); });
+            provisional.once("close", () => { clearTimeout(timer); reject(new RelayConnectionError()); });
+            provisional.once("secureConnect", () => { clearTimeout(timer); resolve(provisional); });
+        });
+        socket.on("error", close);
+        socket.once("close", close);
+        socket.disableRenegotiation();
+        // A new handshake must never replace exporter material on an authenticated socket.
+        socket.on("secure", close);
+        if (closed || socket.destroyed || (socket.alpnProtocol && socket.alpnProtocol !== "http/1.1"))
+            throw new Error();
+        const actualSocket = socket;
+        const exportedKeyMaterial = relayExportedKeyMaterial(actualSocket);
+        // The agent may hand out this socket once. It has no path that dials a replacement connection.
+        agent = new Agent({ keepAlive: true, maxSockets: 1, maxCachedSessions: 0 });
+        let assigned = false;
+        agent.createConnection = () => {
+            if (assigned || closed || actualSocket.destroyed)
+                throw new RelayConnectionError();
+            assigned = true;
+            return actualSocket;
+        };
+        let expires = 0;
+        const valid = () => {
+            if (closed || actualSocket.destroyed || expires <= now())
+                throw new RelayConnectionError();
+        };
+        async function exchange(path, input, maxBytes, authenticated, waitMs = timeoutMs) {
+            if (authenticated)
+                valid();
+            if (closed || actualSocket.destroyed)
+                throw new RelayConnectionError();
+            const body = JSON.stringify(input);
+            if (Buffer.byteLength(body) > RELAY_MAX_FRAME_BYTES)
+                throw new RelayConnectionError();
+            const developmentAttestation = !!policy.development && path === "/attestation";
+            try {
+                const result = await requestBoundedResponse(receive => {
+                    const req = httpsRequest({ hostname, port: origin.port || 443, method: developmentAttestation ? "GET" : "POST", path, agent,
+                        maxHeaderSize: 16 * 1024,
+                        headers: { "content-type": "application/json", "content-length": developmentAttestation ? 0 : Buffer.byteLength(body), "cache-control": "no-store" } }, receive);
+                    req.on("socket", supplied => { if (supplied !== actualSocket)
+                        req.destroy(new RelayConnectionError()); });
+                    return req;
+                }, { maxBytes, timeoutMs: waitMs, bodyTimeoutMs: timeoutMs, requestBody: developmentAttestation ? "" : body, validate: response => {
+                        const status = response.statusCode ?? 0;
+                        if (response.socket !== actualSocket || (status !== 200 && !(path === "/delivery" && status === 503)) ||
+                            !(developmentAttestation ? /^application\/jwt(?:;|$)/i : /^application\/json(?:;|$)/i).test(response.headers["content-type"] ?? ""))
+                            throw new Error();
+                    } });
+                if (authenticated)
+                    valid();
+                const text = new TextDecoder("utf-8", { fatal: true }).decode(result.body);
+                const answer = developmentAttestation ? text : JSON.parse(text);
+                return { status: result.response.statusCode ?? 0, body: answer };
+            }
+            catch {
+                close();
+                throw new RelayConnectionError();
+            }
+        }
+        const challenge = randomBytes(32).toString("hex");
+        const challengeStarted = nowMs();
+        const challengeStartedMonotonic = performance.now();
+        const result = await exchange("/attestation", { version: PRODUCTION_EVIDENCE_VERSION, challenge }, 40 * 1024, false);
+        const verified = policy.development
+            ? verifyAttestation(result.body, new X509Certificate(actualSocket.getPeerCertificate().raw).publicKey, policy.development, now())
+            : await verifyProductionAttestation(result.body, { exportedKeyMaterial, challenge }, trust, now());
+        if (nowMs() < challengeStarted || nowMs() - challengeStarted >= timeoutMs ||
+            performance.now() - challengeStartedMonotonic >= timeoutMs)
+            throw new Error();
+        expires = verified.exp;
+        valid();
+        expiryTimer = setTimeout(close, Math.max(1, (expires - now()) * 1000));
+        expiryTimer.unref();
+        return {
+            get attestedImageDigest() { return verified.imageDigest; },
+            send: createRelayExchange({ development: !!policy.development, valid, close, remainingEvidenceMs: () => Math.max(1, (expires - now()) * 1000),
+                exchange: (path, input, maxBytes, waitMs) => exchange(path, input, maxBytes, true, waitMs) }),
+            close,
+        };
+    }
+    catch {
+        close();
+        throw new RelayConnectionError();
+    }
+}

package/dist/gatekeeper/console.js

@@ -0,0 +1,175 @@
+import { consoleSchemeAllowed } from "../contract/console-url.js";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { CLI_VERSION } from "../contract/cli-version.js";
+import { cliRefusals, FINISH_FAILURE_MESSAGE, RESERVATION_EXPIRED_MESSAGE, RESULTS_TOO_LARGE_MESSAGE, START_FAILURE_MESSAGE } from "../contract/cli-refusals.js";
+import { cliRelayReservationRequestSchema, consoleCreatedSchema, consoleIntakeResultSchema, consoleReservationSchema, consoleStatusSchema, LOCAL_FINDINGS_BODY_LIMIT, localFindingsPayloadSchema, LOCAL_START_BODY_LIMIT, LOCAL_START_EXECUTION_HEADER, localStartRequestSchema, localStartResponseSchema, serializeLocalStartMetadata } from "../contract/console.js";
+const RESPONSE_LIMIT = 64 * 1024;
+const RESERVATION_BODY_LIMIT = 64 * 1024;
+const messages = {
+    ...cliRefusals,
+    invalid_configuration: START_FAILURE_MESSAGE,
+    invalid_request: FINISH_FAILURE_MESSAGE,
+    unavailable: "The results couldn't be saved yet. Run the analysis on the same folder again to save them; you won't be charged again.",
+    unauthorized: "Your sign-in has expired. Run counterfact-labs login, then try again.",
+    not_allowed: "Your account can't run analyses. Ask Counterfact for access.",
+    not_found: "Counterfact couldn't find this analysis. Start a new analysis.",
+    rate_limited: "Counterfact is busy. Try again in a minute.",
+    reservation_closed: "The analysis ended before its results were saved. Start a new analysis.",
+    reservation_closing: "The results are still being saved. Run the analysis on the same folder again in a minute.",
+    delivery_incomplete: "The analysis ended before its results were saved. Start a new analysis.",
+    check_conflict: "Saved results from an earlier run don't match this analysis. Start a new analysis.",
+};
+export class ConsoleError extends Error {
+    code;
+    constructor(code = "unavailable", context) {
+        super(context === "start" && (code === "unavailable" || code === "invalid_request" || code === "not_found") ? START_FAILURE_MESSAGE
+            : context === "intake" && code === "reservation_expired" ? RESERVATION_EXPIRED_MESSAGE
+                // Only saving results can be too large; a rejected status, heartbeat or fail request just could not finish.
+                : context === "intake" && code === "invalid_request" ? RESULTS_TOO_LARGE_MESSAGE : messages[code]);
+        this.name = "ConsoleError";
+        this.code = code;
+    }
+}
+export const isConsoleToken = (token) => /^[\x21-\x7e]{1,4096}$/.test(token);
+/** Only this client may send repository metadata, content-free lifecycle or findings-only intake payloads to the console. */
+export class ConsoleClient {
+    #url;
+    #token;
+    #timeoutMs;
+    constructor(options) {
+        try {
+            const url = new URL(options.url);
+            const timeout = options.timeoutMs ?? 15_000;
+            if (!consoleSchemeAllowed(url)
+                || url.username || url.password || url.pathname !== "/" || url.search || url.hash
+                || !isConsoleToken(options.token)
+                || !Number.isSafeInteger(timeout) || timeout <= 0 || timeout > 120_000)
+                throw new ConsoleError("invalid_configuration");
+            this.#url = url;
+            this.#token = options.token;
+            this.#timeoutMs = timeout;
+        }
+        catch {
+            throw new ConsoleError("invalid_configuration");
+        }
+    }
+    async start(input, metadata) {
+        let headers;
+        try {
+            headers = metadata === undefined ? {} : serializeLocalStartMetadata(metadata);
+        }
+        catch {
+            throw new ConsoleError("invalid_request", "start");
+        }
+        return this.#send("/api/cli/checks", input, localStartRequestSchema, localStartResponseSchema, LOCAL_START_BODY_LIMIT, { statuses: [201], headers: { ...headers, [LOCAL_START_EXECUTION_HEADER.name]: LOCAL_START_EXECUTION_HEADER.value }, context: "start" });
+    }
+    create(input) {
+        return this.#lifecycle({ ...input, action: "create" }, consoleCreatedSchema);
+    }
+    reserve(input) {
+        return this.#lifecycle({ ...input, action: "reserve" }, consoleReservationSchema);
+    }
+    status(reservationId) {
+        return this.#lifecycle({ action: "status", reservationId }, consoleStatusSchema);
+    }
+    heartbeat(reservationId) {
+        return this.#lifecycle({ action: "heartbeat", reservationId }, consoleStatusSchema);
+    }
+    fail(reservationId) {
+        return this.#lifecycle({ action: "fail", reservationId }, consoleStatusSchema);
+    }
+    intake(input) {
+        return this.#send("/api/cli/checks/local", input, localFindingsPayloadSchema, consoleIntakeResultSchema, LOCAL_FINDINGS_BODY_LIMIT, { statuses: [200, 201], context: "intake" });
+    }
+    #lifecycle(input, response) {
+        // Starting work has no saved results to retry; recovery keeps its saving guidance.
+        const context = input.action === "create" || input.action === "reserve" ? "start" : undefined;
+        return this.#send("/api/cli/relay-reservations", input, cliRelayReservationRequestSchema, response, RESERVATION_BODY_LIMIT, { context });
+    }
+    async #send(path, input, schema, responseSchema, limit, options = {}) {
+        let body;
+        const identities = {};
+        try {
+            const parsed = schema.parse(input);
+            for (const field of ["jobId", "checkId", "projectId", "reservationId"]) {
+                const value = parsed[field];
+                if (typeof value === "string" && !(options.context === "intake" && field === "reservationId")) {
+                    identities[field] = value.toLowerCase();
+                }
+            }
+            body = Buffer.from(JSON.stringify(parsed), "utf8");
+            if (body.length > limit)
+                throw new ConsoleError("invalid_request", options.context);
+        }
+        catch {
+            throw new ConsoleError("invalid_request", options.context);
+        }
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (error, result) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (error)
+                    reject(error);
+                else
+                    resolve(result);
+            };
+            const destination = new URL(path, this.#url);
+            const request = (destination.protocol === "https:" ? httpsRequest : httpRequest)(destination, {
+                method: "POST", agent: false, rejectUnauthorized: true, maxHeaderSize: 16 * 1024,
+                headers: { "x-counterfact-cli-version": CLI_VERSION, authorization: `Bearer ${this.#token}`, "content-type": "application/json", accept: "application/json",
+                    "content-length": body.length, "accept-encoding": "identity",
+                    ...options.headers },
+            }, response => {
+                const status = response.statusCode ?? 0;
+                const declared = response.headers["content-length"];
+                const contentType = response.headers["content-type"] ?? "";
+                if (status >= 300 && status < 400 || !/^application\/json(?:\s*;|$)/i.test(contentType)
+                    || response.headers["content-encoding"] && response.headers["content-encoding"] !== "identity"
+                    || declared && (!/^\d+$/.test(declared) || Number(declared) > RESPONSE_LIMIT)) {
+                    finish(new ConsoleError());
+                    response.destroy();
+                    return;
+                }
+                let size = 0;
+                const chunks = [];
+                response.on("data", (chunk) => {
+                    size += chunk.length;
+                    if (size > RESPONSE_LIMIT) {
+                        finish(new ConsoleError());
+                        response.destroy();
+                    }
+                    else
+                        chunks.push(chunk);
+                });
+                response.on("error", () => finish(new ConsoleError()));
+                response.on("aborted", () => finish(new ConsoleError()));
+                response.on("end", () => {
+                    try {
+                        const decoded = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+                        if (!(options.statuses ?? [200]).includes(status)) {
+                            const code = decoded && typeof decoded === "object" && "code" in decoded ? decoded.code : undefined;
+                            throw new ConsoleError(typeof code === "string" && Object.hasOwn(messages, code) ? code : "unavailable");
+                        }
+                        const result = responseSchema.parse(decoded);
+                        for (const [field, expected] of Object.entries(identities)) {
+                            if (result[field] !== expected)
+                                throw new ConsoleError();
+                        }
+                        finish(undefined, result);
+                    }
+                    catch (error) {
+                        finish(error instanceof ConsoleError ? error : new ConsoleError());
+                    }
+                });
+            });
+            // Use one wall-clock deadline: an idle timeout alone lets a trickling response run forever.
+            const timer = setTimeout(() => { finish(new ConsoleError()); request.destroy(); }, this.#timeoutMs);
+            request.on("error", () => finish(new ConsoleError()));
+            request.end(body);
+        }).catch(error => { throw new ConsoleError(error instanceof ConsoleError ? error.code : "unavailable", options.context); });
+    }
+}

package/dist/gatekeeper/loopback.js

@@ -0,0 +1,5 @@
+/** Whether a URL hostname names this machine, so development trust and plain HTTP never leave it. */
+export function isLoopbackHost(hostname) {
+    const host = hostname.replace(/^\[|\]$/g, "");
+    return host === "localhost" || host === "::1" || /^127\.\d+\.\d+\.\d+$/.test(host);
+}