@counterfact-labs/cli 0.1.2 → 0.2.3

package/dist/core/analysis/run-to-end.js

@@ -0,0 +1,55 @@
+import { JobError } from "../../analysis-core/errors.js";
+import { readAnalysisFlags } from "../../analysis-core/analysis/analysis-flags.js";
+import { mapStage, inspectStage, sourceNotesStage, headlinesStage, applyAnalysisDelta, buildAnalysisResult } from "../../analysis-core/index.js";
+import { readFindingQualityConfig } from "./finding-quality/config.js";
+import { buildLocalReport } from "../../adapters/report.js";
+import { runStructures } from "./structural-run.js";
+import { analysisExecution } from "../../adapters/models.js";
+/** Keep the hosted stage order while holding source files and results only in memory. */
+export async function runAnalysisToEnd(input, model, settings = {}, options = {}) {
+    const execution = await analysisExecution(model, options, settings);
+    const { model: llm, requestTools: tools } = execution;
+    const flags = readAnalysisFlags(settings);
+    const qualityConfig = readFindingQualityConfig(settings, tools);
+    if (!Object.keys(input.files).length)
+        throw new JobError("empty_folder", "No admitted source files were found.");
+    let prepared = { repos: [{ key: input.repoKey, kind: "fs", files: input.files, ...(input.root !== undefined ? { root: input.root } : {}) }],
+        warnings: input.warnings ?? [], ...(input.fragment ? { mapped: [input.fragment] } : {}) };
+    const ports = { readers: [], model: llm, instructions: execution.instructions, requestTools: async () => tools, context: {},
+        progress: { checkpoint: async () => { }, assertHeld: () => { }, elapsedMs: () => 0, log: () => { } } };
+    for (;;) {
+        const delta = await mapStage({ phase: "mapping", state: prepared, settings, execution: { scopeConcurrency: 4, forLocal: true,
+                preparation: { capUsd: 20, confirmPrice: false, qualityConfig } } }, ports);
+        prepared = applyAnalysisDelta(prepared, delta);
+        if (delta.next !== "mapping")
+            break;
+    }
+    prepared = { ...prepared, analysisFlags: { ...flags, sourceNotes: !options.findingsOnly && flags.sourceNotes },
+        findingQuality: { config: qualityConfig }, warnings: [...(prepared.warnings ?? []), ...qualityConfig.diagnostics] };
+    let phase = "inspecting";
+    ports.progress.checkpoint = async (fields, part) => {
+        prepared = { ...prepared, ...fields, ...(part ? { passResults: { ...prepared.passResults, [part.index]: part.result } } : {}) };
+    };
+    while (phase !== "structuring") {
+        const step = phase === "inspecting" ? inspectStage : sourceNotesStage;
+        const delta = await step({ phase, state: prepared, settings, execution: { scopeConcurrency: 4, passConcurrency: 4, forLocal: true } }, ports);
+        prepared = applyAnalysisDelta(prepared, delta);
+        phase = delta.next;
+    }
+    const output = () => buildAnalysisResult({ phase: "persisting", state: prepared, settings, execution: { scopeConcurrency: 4 } });
+    // Structural child references index the local display order, including optional ranking.
+    const report = buildLocalReport(input.repoKey, output(), prepared);
+    if (!options.findingsOnly) {
+        const findingsRaw = prepared.findingsRaw;
+        const structural = await runStructures(settings, llm, { repos: prepared.repos,
+            fragments: [{ repoKey: input.repoKey, fragment: prepared.mapped[0] }],
+            graph: report.graph, findings: report.findings, state: prepared }, { execution });
+        // Structural child references keep display order; wording uses the original cleaned order.
+        prepared = { ...structural.state, findingsRaw };
+    }
+    prepared = applyAnalysisDelta(prepared, await headlinesStage({ phase: "persisting", state: prepared, settings,
+        execution: { scopeConcurrency: 4, forLocal: true } }, ports));
+    const result = output();
+    await options.resultSink?.(result);
+    return buildLocalReport(input.repoKey, result, prepared);
+}

package/dist/core/analysis/structural-run.js

@@ -0,0 +1,16 @@
+import { structureStage, applyAnalysisDelta } from "../../analysis-core/index.js";
+import { analysisExecution } from "../../adapters/models.js";
+/** The local product supplies its in-memory allowance; the shared stage owns every transition. */
+export async function runStructures(settings, model, input, options = {}) {
+    const execution = await analysisExecution(model, options, settings);
+    let state = { ...input.state, repos: input.repos, mapped: input.fragments.map(({ fragment }) => fragment),
+        findingsRaw: input.findings, warnings: input.state?.warnings ?? [], splitCheckPriced: true, splitFindingsPriced: true };
+    const ports = { readers: [], model: execution.model, instructions: execution.instructions, requestTools: async () => execution.requestTools, context: {},
+        progress: { checkpoint: async () => { }, assertHeld: () => { }, elapsedMs: () => 0, log: () => { } } };
+    for (;;) {
+        const delta = await structureStage({ phase: "structuring", state, settings, execution: { scopeConcurrency: 4, forLocal: true } }, ports);
+        state = applyAnalysisDelta(state, delta);
+        if (delta.next === "persisting")
+            return { state, structures: (state.structuresRaw ?? []), warnings: state.warnings ?? [] };
+    }
+}

package/dist/gatekeeper/attestation.js

@@ -0,0 +1,67 @@
+import { createHash, verify } from "node:crypto";
+import { z } from "zod";
+import { MAX_ATTESTATION_BYTES, attestationClaims } from "../contract/messages.js";
+import { decodeBase64url } from "../transport/base64url.js";
+export function attestationPolicy(settings, trust) {
+    return { ...trust, allowDevelopment: settings.CF_RELAY_DEV === "1" };
+}
+export class AttestationError extends Error {
+    name = "AttestationError";
+}
+const tokenHeader = z.object({
+    alg: z.literal("EdDSA"), kid: z.string().min(1).optional(), typ: z.literal("JWT").optional(),
+}).strict();
+/** Local signatures never establish a production identity, even if an old RSA issuer policy is supplied. */
+export function verifyAttestation(token, channelPublicKey, policy, now = Math.floor(Date.now() / 1000)) {
+    if (!policy.allowDevelopment)
+        throw new AttestationError("Relay development issuer is disabled");
+    let payload;
+    try {
+        if (token.length > MAX_ATTESTATION_BYTES)
+            throw new Error();
+        const parts = token.split(".");
+        if (parts.length !== 3)
+            throw new Error();
+        const [header, body, signature] = parts;
+        const parsed = tokenHeader.parse(JSON.parse(decodeBase64url(header).toString("utf8")));
+        payload = decodeBase64url(body);
+        const issuer = policy.developmentIssuer;
+        const key = issuer?.keys.find(item => parsed.kid === undefined || item.kid === parsed.kid)?.publicKey;
+        if (!key || key.type !== "public" || key.asymmetricKeyType !== "ed25519" ||
+            !verify(null, Buffer.from(`${header}.${body}`), key, decodeBase64url(signature))) {
+            throw new AttestationError("Invalid relay attestation signature");
+        }
+    }
+    catch (error) {
+        if (error instanceof AttestationError)
+            throw error;
+        throw new AttestationError("Malformed relay attestation token");
+    }
+    const result = attestationClaims.safeParse((() => {
+        try {
+            return JSON.parse(payload.toString("utf8"));
+        }
+        catch {
+            return undefined;
+        }
+    })());
+    if (!result.success)
+        throw new AttestationError("Invalid relay attestation claims");
+    const claims = result.data;
+    if (claims.iss !== policy.developmentIssuer?.issuer)
+        throw new AttestationError("Untrusted relay attestation issuer");
+    if (!policy.imageDigests.includes(claims.imageDigest))
+        throw new AttestationError("Untrusted relay image digest");
+    if (!Number.isSafeInteger(now))
+        throw new AttestationError("Invalid attestation clock");
+    if (claims.exp <= now)
+        throw new AttestationError("Relay attestation has expired");
+    if (claims.iat > now || claims.exp <= claims.iat)
+        throw new AttestationError("Invalid relay attestation lifetime");
+    if (channelPublicKey.type !== "public")
+        throw new AttestationError("Invalid relay channel key");
+    const hash = createHash("sha256").update(channelPublicKey.export({ format: "der", type: "spki" })).digest("hex");
+    if (claims.channelKeyHash !== hash)
+        throw new AttestationError("Relay attestation channel key mismatch");
+    return claims;
+}

package/dist/gatekeeper/certificate-algorithms.js

@@ -0,0 +1,18 @@
+export const RSA_PSS_SIGNATURE_ALGORITHM = "1.2.840.113549.1.1.10";
+const curves = new Set(["prime256v1", "secp384r1", "secp521r1"]);
+const signatures = new Set([
+    "1.2.840.113549.1.1.11", "1.2.840.113549.1.1.12", "1.2.840.113549.1.1.13",
+    "1.2.840.10045.4.3.2", "1.2.840.10045.4.3.3", "1.2.840.10045.4.3.4",
+    "1.3.101.112", "1.3.101.113",
+]);
+const pssHashes = new Set(["2.16.840.1.101.3.4.2.1", "2.16.840.1.101.3.4.2.2", "2.16.840.1.101.3.4.2.3"]);
+/** WebCrypto can verify obsolete algorithms; accepting a signature also requires a local strength policy. */
+export function hasStrongCertificateAlgorithms(algorithms) {
+    const { keyType, modulusLength, namedCurve, signatureAlgorithm, pssHashAlgorithm } = algorithms;
+    const strongKey = keyType === "rsa" || keyType === "rsa-pss" ? (modulusLength ?? 0) >= 2048
+        : keyType === "ec" ? curves.has(namedCurve ?? "") : keyType === "ed25519" || keyType === "ed448";
+    if (!strongKey)
+        return false;
+    return signatureAlgorithm === RSA_PSS_SIGNATURE_ALGORITHM
+        ? pssHashes.has(pssHashAlgorithm ?? "") : signatures.has(signatureAlgorithm);
+}

package/dist/gatekeeper/certificate-path.js

@@ -0,0 +1,99 @@
+import { X509Certificate, webcrypto } from "node:crypto";
+import { BitString, fromBER } from "asn1js";
+import { BasicConstraints, Certificate, CertificateChainValidationEngine, CryptoEngine, ExtensionValueFactory, RSASSAPSSParams } from "pkijs";
+import { AttestationError } from "./attestation.js";
+import { hasStrongCertificateAlgorithms, RSA_PSS_SIGNATURE_ALGORITHM } from "./certificate-algorithms.js";
+const crypto = new CryptoEngine({ name: "node", crypto: webcrypto,
+    subtle: webcrypto.subtle });
+function parseCertificate(cert) {
+    const bytes = Uint8Array.from(cert.raw);
+    const decoded = fromBER(bytes.buffer);
+    if (decoded.offset !== bytes.length)
+        throw new Error();
+    return new Certificate({ schema: decoded.result });
+}
+function checkPathConstraints(path) {
+    let intermediateCount = 0;
+    for (const [index, cert] of path.entries()) {
+        for (const extension of cert.extensions ?? []) {
+            if (!extension.critical)
+                continue;
+            // PKIjs also parses unknown extensions as generic ASN.1; parsing alone does not establish recognition.
+            // Subject key identifier, key usage and inhibit-any-policy use primitive ASN.1 rather than registered classes.
+            const recognized = ExtensionValueFactory.find(extension.extnID) || ["2.5.29.14", "2.5.29.15", "2.5.29.54"].includes(extension.extnID);
+            const value = extension.parsedValue;
+            if (!recognized || !value || "parsingError" in value)
+                throw new Error();
+        }
+        // PKIjs does not enforce pathLenConstraint. Count only non-self-issued CAs below each issuer, never the leaf.
+        const constraints = cert.extensions?.find(extension => extension.extnID === "2.5.29.19")?.parsedValue;
+        if (constraints instanceof BasicConstraints && constraints.pathLenConstraint !== undefined) {
+            const limit = constraints.pathLenConstraint;
+            if (intermediateCount > (typeof limit === "number" ? limit : limit.toBigInt()))
+                throw new Error();
+        }
+        if (index > 0 && !cert.subject.isEqual(cert.issuer))
+            intermediateCount++;
+    }
+}
+/** PKIjs owns path validation; only shipped roots are trusted, with no network or system CA discovery. */
+export async function validateCertificatePath(chain, roots, now) {
+    try {
+        if (!Number.isSafeInteger(now) || chain.length < 1 || chain.length > 5 || !roots.length || roots.length > 8)
+            throw new Error();
+        // Reviewed root rotations can overlap; an unused expired anchor must not invalidate a different valid path.
+        const current = (cert) => now * 1000 >= Date.parse(cert.validFrom) && now * 1000 < Date.parse(cert.validTo);
+        const anchors = roots.map(root => new X509Certificate(root)).filter(root => root.ca && current(root));
+        if (!anchors.length || chain.some(cert => !current(cert)))
+            throw new Error();
+        const [leaf] = chain;
+        if (leaf.ca || leaf.publicKey.asymmetricKeyType !== "rsa")
+            throw new Error();
+        // Path builders may discard extraneous certificates; the wire format requires one ordered, connected path.
+        if (new Set(chain.map(cert => cert.fingerprint256)).size !== chain.length)
+            throw new Error();
+        for (let index = 1; index < chain.length; index++) {
+            if (!chain[index].ca || !chain[index - 1].checkIssued(chain[index]))
+                throw new Error();
+        }
+        const isAnchor = (cert) => anchors.some(root => root.fingerprint256 === cert.fingerprint256);
+        const last = chain.at(-1);
+        if (last.checkIssued(last) && !isAnchor(last))
+            throw new Error();
+        const supplied = chain.map(cert => ({ cert, parsed: parseCertificate(cert) }));
+        const trusted = anchors.map(cert => ({ cert, parsed: parseCertificate(cert) }));
+        for (const { cert, parsed } of [...supplied, ...trusted]) {
+            const key = cert.publicKey;
+            const signature = parsed.signatureAlgorithm;
+            const pssHashAlgorithm = signature.algorithmId === RSA_PSS_SIGNATURE_ALGORITHM && signature.algorithmParams
+                ? new RSASSAPSSParams({ schema: signature.algorithmParams }).hashAlgorithm.algorithmId : undefined;
+            if (!hasStrongCertificateAlgorithms({ keyType: key.asymmetricKeyType,
+                modulusLength: key.asymmetricKeyDetails?.modulusLength, namedCurve: key.asymmetricKeyDetails?.namedCurve,
+                signatureAlgorithm: signature.algorithmId, pssHashAlgorithm }))
+                throw new Error();
+        }
+        // RFC 5280: a leaf without a key usage extension is unrestricted, and Google's Confidential Space leaves omit it.
+        // When the extension is present it must still allow digital signatures.
+        const usageExtension = supplied[0].parsed.extensions?.find((extension) => extension.extnID === "2.5.29.15");
+        if (usageExtension) {
+            const usage = usageExtension.parsedValue;
+            if (!(usage instanceof BitString) || !(usage.valueBlock.valueHexView[0] & 0x80))
+                throw new Error();
+        }
+        const validator = new CertificateChainValidationEngine({
+            trustedCerts: trusted.map(({ parsed }) => parsed),
+            // PKIjs takes the target certificate last, independently of the wire's leaf-first order.
+            certs: supplied.filter(({ cert }) => !isAnchor(cert)).reverse().map(({ parsed }) => parsed),
+            checkDate: new Date(now * 1000),
+        });
+        const result = await validator.verify({}, crypto);
+        if (!result.result || !result.certificatePath)
+            throw new Error();
+        checkPathConstraints(result.certificatePath);
+        return leaf.publicKey;
+    }
+    catch {
+        // Certificate and dependency diagnostics can contain token material; retain only the fixed category.
+        throw new AttestationError("Invalid production attestation certificate path");
+    }
+}

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,60 @@
+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 frame = options.development ? { answer: relayAnswer.parse(response.body), 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;
+    };
+}