@appforge-ci/core 0.2.3 → 0.3.1

package/dist/vpn-attestation.d.ts

@@ -0,0 +1,1015 @@
+import { z } from "zod";
+import type { AttestationSignature } from "./attestation-signing.js";
+import type { VpnEgressPolicy, VpnJobConfig } from "./types.js";
+/**
+ * Per-build signed attestation (regulated-VPN program, PR-M): what the document says, how it is
+ * derived, and the evidence bundle and printable page an auditor verifies offline with
+ * `scripts/appforge-verify.mjs`. Pure and runtime-neutral (WebCrypto only), so the Worker that
+ * assembles it (apps/admin-api through `@appforge/db`), the Worker that exports it (apps/api), the
+ * agent that reports the raw evidence, and the tests that feed the real verifier all share one
+ * definition.
+ *
+ * Who says what. Three parties contribute facts, and the document records which:
+ *   - the SERVER (control plane): what it leased (the egress policy it sent, the tunnel's public
+ *     configuration), the build row, the VpnEvent timeline, the audit chain head, and everything it
+ *     can RECOMPUTE from raw data it holds (the connection log's digest, per-destination summary,
+ *     totals and completeness);
+ *   - the AGENT: what ran on the Mac (helper identity, sandbox profile hashes and the self-test
+ *     matrix, hygiene), reported in one JSON document plus the raw connection log;
+ *   - the HELPER: the connection log itself (metadata only), written by a process on the build host.
+ * Every value the agent claims that the server can also derive is compared, and a mismatch is
+ * recorded as a failing control test (the verifier exits 2 on those). Nothing is silently trusted,
+ * and nothing is ever dropped silently either: what could not be checked is listed in `crossChecks`
+ * and `gaps`.
+ *
+ * What it is not: macOS offers no remote attestation, so this proves what the server verified and
+ * what the Mac reported, not that the Mac told the truth. docs/attestation.md lists the limits.
+ */
+export declare const ATTESTATION_DOC_TYPE = "appforge.vpn.build-attestation";
+export declare const ATTESTATION_DOC_VERSION = 1;
+export declare const EVIDENCE_BUNDLE_FORMAT = "appforge-evidence-bundle";
+/** The rule that turns the helper's raw log lines into the `records` a bundle carries. Part of the signed document. */
+export declare const CONNECTION_RECORDS_NORMALIZATION = "appforge-conn-records-v1";
+/**
+ * The largest connection log the control plane will hold and process (the agent keeps up to 50 MiB; a log
+ * past this is reported as not retained and the attestation says so). 8 MiB is about 27,000 records, an order
+ * of magnitude above a real build, and keeps one Worker request well inside its CPU and memory limits.
+ */
+export declare const ATTESTATION_LOG_MAX_BYTES: number;
+/** Largest `POST /agents/vpn/attestation` body. */
+export declare const ATTESTATION_EVIDENCE_MAX_BYTES: number;
+/**
+ * How long after the control plane first sees a strict/regulated build finished the agent may still report its
+ * evidence. After it, the cron issues a `server_observed_only` attestation and a late report is refused.
+ */
+export declare const ATTESTATION_AGENT_GRACE_SECONDS: number;
+/** Distinct (destination, route, decision) groups a document lists; beyond it the summary is cut and the document says so. */
+export declare const ATTESTATION_MAX_DESTINATIONS = 1000;
+/** Chain entries one evidence bundle carries at most (one page of the audit export). */
+export declare const ATTESTATION_BUNDLE_MAX_CHAIN_ENTRIES = 1000;
+export declare const ATTESTATION_ID_PREFIX = "att_";
+export declare const attestationIdForBuild: (buildId: string) => string;
+/** A build id as the control plane makes them (UUIDs) and as the agent's evidence directory and the helper accept them. */
+export declare const ATTESTATION_BUILD_ID_RE: RegExp;
+/** Where a build's raw connection log lives in the artifacts bucket. */
+export declare function connectionLogKey(orgId: string, buildId: string): string;
+/** Release manifests, published next to the artifacts by scripts/r2-release.mjs. */
+export declare function releaseManifestKey(prefix: "agent-releases" | "vpn-releases", version: string): string;
+/** Why a document is unsigned, in the words the API and the dashboard use. */
+export declare const ATTESTATION_UNSIGNED_NOTE = "This attestation is NOT signed: the platform's signing key was not available when it was issued. It is registered in the audit chain, but nothing authenticates it, and it cannot be verified offline.";
+declare const selfTestResultSchema: z.ZodObject<{
+    id: z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodString>;
+    area: z.ZodEffects<z.ZodString, string, string>;
+    title: z.ZodEffects<z.ZodString, string, string>;
+    tier: z.ZodEnum<["core", "internet", "optional"]>;
+    expect: z.ZodEnum<["blocked", "allowed", "known_gap"]>;
+    status: z.ZodEnum<["pass", "fail", "inconclusive", "na", "known_gap_open", "known_gap_closed"]>;
+    detail: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+}, "strip", z.ZodTypeAny, {
+    status: "fail" | "pass" | "inconclusive" | "na" | "known_gap_open" | "known_gap_closed";
+    id: string;
+    title: string;
+    expect: "blocked" | "allowed" | "known_gap";
+    area: string;
+    tier: "core" | "internet" | "optional";
+    detail?: string | undefined;
+}, {
+    status: "fail" | "pass" | "inconclusive" | "na" | "known_gap_open" | "known_gap_closed";
+    id: string;
+    title: string;
+    expect: "blocked" | "allowed" | "known_gap";
+    area: string;
+    tier: "core" | "internet" | "optional";
+    detail?: string | undefined;
+}>;
+export type AgentSelfTestResult = z.infer<typeof selfTestResultSchema>;
+declare const sandboxEvidenceSchema: z.ZodObject<{
+    profileVersion: z.ZodEffects<z.ZodNumber, number, number>;
+    templateSha256: z.ZodString;
+    renderedSha256: z.ZodString;
+    paramsSha256: z.ZodString;
+    loopbackDenyPorts: z.ZodArray<z.ZodEffects<z.ZodNumber, number, number>, "many">;
+    orgId: z.ZodEffects<z.ZodString, string, string>;
+    selfTest: z.ZodObject<{
+        verdict: z.ZodEnum<["pass", "fail", "inconclusive"]>;
+        counts: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodNumber, number, number>>, Record<string, number>, Record<string, number>>;
+        startedAt: z.ZodEffects<z.ZodString, string, string>;
+        durationMs: z.ZodEffects<z.ZodNumber, number, number>;
+        results: z.ZodArray<z.ZodObject<{
+            id: z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodString>;
+            area: z.ZodEffects<z.ZodString, string, string>;
+            title: z.ZodEffects<z.ZodString, string, string>;
+            tier: z.ZodEnum<["core", "internet", "optional"]>;
+            expect: z.ZodEnum<["blocked", "allowed", "known_gap"]>;
+            status: z.ZodEnum<["pass", "fail", "inconclusive", "na", "known_gap_open", "known_gap_closed"]>;
+            detail: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        }, "strip", z.ZodTypeAny, {
+            status: "fail" | "pass" | "inconclusive" | "na" | "known_gap_open" | "known_gap_closed";
+            id: string;
+            title: string;
+            expect: "blocked" | "allowed" | "known_gap";
+            area: string;
+            tier: "core" | "internet" | "optional";
+            detail?: string | undefined;
+        }, {
+            status: "fail" | "pass" | "inconclusive" | "na" | "known_gap_open" | "known_gap_closed";
+            id: string;
+            title: string;
+            expect: "blocked" | "allowed" | "known_gap";
+            area: string;
+            tier: "core" | "internet" | "optional";
+            detail?: string | undefined;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        counts: Record<string, number>;
+        verdict: "fail" | "pass" | "inconclusive";
+        startedAt: string;
+        durationMs: number;
+        results: {
+            status: "fail" | "pass" | "inconclusive" | "na" | "known_gap_open" | "known_gap_closed";
+            id: string;
+            title: string;
+            expect: "blocked" | "allowed" | "known_gap";
+            area: string;
+            tier: "core" | "internet" | "optional";
+            detail?: string | undefined;
+        }[];
+    }, {
+        counts: Record<string, number>;
+        verdict: "fail" | "pass" | "inconclusive";
+        startedAt: string;
+        durationMs: number;
+        results: {
+            status: "fail" | "pass" | "inconclusive" | "na" | "known_gap_open" | "known_gap_closed";
+            id: string;
+            title: string;
+            expect: "blocked" | "allowed" | "known_gap";
+            area: string;
+            tier: "core" | "internet" | "optional";
+            detail?: string | undefined;
+        }[];
+    }>;
+    scope: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+}, "strip", z.ZodTypeAny, {
+    orgId: string;
+    profileVersion: number;
+    templateSha256: string;
+    renderedSha256: string;
+    paramsSha256: string;
+    loopbackDenyPorts: number[];
+    selfTest: {
+        counts: Record<string, number>;
+        verdict: "fail" | "pass" | "inconclusive";
+        startedAt: string;
+        durationMs: number;
+        results: {
+            status: "fail" | "pass" | "inconclusive" | "na" | "known_gap_open" | "known_gap_closed";
+            id: string;
+            title: string;
+            expect: "blocked" | "allowed" | "known_gap";
+            area: string;
+            tier: "core" | "internet" | "optional";
+            detail?: string | undefined;
+        }[];
+    };
+    scope?: string | undefined;
+}, {
+    orgId: string;
+    profileVersion: number;
+    templateSha256: string;
+    renderedSha256: string;
+    paramsSha256: string;
+    loopbackDenyPorts: number[];
+    selfTest: {
+        counts: Record<string, number>;
+        verdict: "fail" | "pass" | "inconclusive";
+        startedAt: string;
+        durationMs: number;
+        results: {
+            status: "fail" | "pass" | "inconclusive" | "na" | "known_gap_open" | "known_gap_closed";
+            id: string;
+            title: string;
+            expect: "blocked" | "allowed" | "known_gap";
+            area: string;
+            tier: "core" | "internet" | "optional";
+            detail?: string | undefined;
+        }[];
+    };
+    scope?: string | undefined;
+}>;
+export type AgentSandboxEvidence = z.infer<typeof sandboxEvidenceSchema>;
+/**
+ * What an agent sends to `POST /agents/vpn/attestation` after a strict-egress or regulated build ends. Unknown
+ * top-level fields are dropped (a newer agent may send more), `hygiene` is kept as an opaque, size-bounded object
+ * because its shape is owned by a change that has not shipped everywhere.
+ */
+export declare const agentVpnEvidenceSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    buildId: z.ZodString;
+    agent: z.ZodObject<{
+        version: z.ZodEffects<z.ZodString, string, string>;
+        os: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        arch: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    }, "strip", z.ZodTypeAny, {
+        version: string;
+        os?: string | undefined;
+        arch?: string | undefined;
+    }, {
+        version: string;
+        os?: string | undefined;
+        arch?: string | undefined;
+    }>;
+    /** What the agent believes happened; the control plane's own build row is what the document records. */
+    outcome: z.ZodObject<{
+        status: z.ZodEnum<["succeeded", "failed"]>;
+        failureKind: z.ZodOptional<z.ZodEnum<["user", "infra"]>>;
+    }, "strip", z.ZodTypeAny, {
+        status: "succeeded" | "failed";
+        failureKind?: "user" | "infra" | undefined;
+    }, {
+        status: "succeeded" | "failed";
+        failureKind?: "user" | "infra" | undefined;
+    }>;
+    helper: z.ZodObject<{
+        version: z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>;
+        sha256: z.ZodNullable<z.ZodString>;
+        arch: z.ZodNullable<z.ZodEnum<["arm64", "amd64"]>>;
+    }, "strip", z.ZodTypeAny, {
+        sha256: string | null;
+        version: string | null;
+        arch: "arm64" | "amd64" | null;
+    }, {
+        sha256: string | null;
+        version: string | null;
+        arch: "arm64" | "amd64" | null;
+    }>;
+    egress: z.ZodObject<{
+        mode: z.ZodNullable<z.ZodEnum<["standard", "strict"]>>;
+        policyHash: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "standard" | "strict" | null;
+        policyHash: string | null;
+    }, {
+        mode: "standard" | "strict" | null;
+        policyHash: string | null;
+    }>;
+    tunnel: z.ZodObject<{
+        configDigest: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        configDigest: string | null;
+    }, {
+        configDigest: string | null;
+    }>;
+    sandbox: z.ZodNullable<z.ZodObject<{
+        profileVersion: z.ZodEffects<z.ZodNumber, number, number>;
+        templateSha256: z.ZodString;
+        renderedSha256: z.ZodString;
+        paramsSha256: z.ZodString;
+        loopbackDenyPorts: z.ZodArray<z.ZodEffects<z.ZodNumber, number, number>, "many">;
+        orgId: z.ZodEffects<z.ZodString, string, string>;
+        selfTest: z.ZodObject<{
+            verdict: z.ZodEnum<["pass", "fail", "inconclusive"]>;
+            counts: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodNumber, number, number>>, Record<string, number>, Record<string, number>>;
+            startedAt: z.ZodEffects<z.ZodString, string, string>;
+            durationMs: z.ZodEffects<z.ZodNumber, number, number>;
+            results: z.ZodArray<z.ZodObject<{
+                id: z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodString>;
+                area: z.ZodEffects<z.ZodString, string, string>;
+                title: z.ZodEffects<z.ZodString, string, string>;
+                tier: z.ZodEnum<["core", "internet", "optional"]>;
+                expect: z.ZodEnum<["blocked", "allowed", "known_gap"]>;
+                status: z.ZodEnum<["pass", "fail", "inconclusive", "na", "known_gap_open", "known_gap_closed"]>;
+                detail: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+            }, "strip", z.ZodTypeAny, {
+                status: "fail" | "pass" | "inconclusive" | "na" | "known_gap_open" | "known_gap_closed";
+                id: string;
+                title: string;
+                expect: "blocked" | "allowed" | "known_gap";
+                area: string;
+                tier: "core" | "internet" | "optional";
+                detail?: string | undefined;
+            }, {
+                status: "fail" | "pass" | "inconclusive" | "na" | "known_gap_open" | "known_gap_closed";
+                id: string;
+                title: string;
+                expect: "blocked" | "allowed" | "known_gap";
+                area: string;
+                tier: "core" | "internet" | "optional";
+                detail?: string | undefined;
+            }>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            counts: Record<string, number>;
+            verdict: "fail" | "pass" | "inconclusive";
+            startedAt: string;
+            durationMs: number;
+            results: {
+                status: "fail" | "pass" | "inconclusive" | "na" | "known_gap_open" | "known_gap_closed";
+                id: string;
+                title: string;
+                expect: "blocked" | "allowed" | "known_gap";
+                area: string;
+                tier: "core" | "internet" | "optional";
+                detail?: string | undefined;
+            }[];
+        }, {
+            counts: Record<string, number>;
+            verdict: "fail" | "pass" | "inconclusive";
+            startedAt: string;
+            durationMs: number;
+            results: {
+                status: "fail" | "pass" | "inconclusive" | "na" | "known_gap_open" | "known_gap_closed";
+                id: string;
+                title: string;
+                expect: "blocked" | "allowed" | "known_gap";
+                area: string;
+                tier: "core" | "internet" | "optional";
+                detail?: string | undefined;
+            }[];
+        }>;
+        scope: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    }, "strip", z.ZodTypeAny, {
+        orgId: string;
+        profileVersion: number;
+        templateSha256: string;
+        renderedSha256: string;
+        paramsSha256: string;
+        loopbackDenyPorts: number[];
+        selfTest: {
+            counts: Record<string, number>;
+            verdict: "fail" | "pass" | "inconclusive";
+            startedAt: string;
+            durationMs: number;
+            results: {
+                status: "fail" | "pass" | "inconclusive" | "na" | "known_gap_open" | "known_gap_closed";
+                id: string;
+                title: string;
+                expect: "blocked" | "allowed" | "known_gap";
+                area: string;
+                tier: "core" | "internet" | "optional";
+                detail?: string | undefined;
+            }[];
+        };
+        scope?: string | undefined;
+    }, {
+        orgId: string;
+        profileVersion: number;
+        templateSha256: string;
+        renderedSha256: string;
+        paramsSha256: string;
+        loopbackDenyPorts: number[];
+        selfTest: {
+            counts: Record<string, number>;
+            verdict: "fail" | "pass" | "inconclusive";
+            startedAt: string;
+            durationMs: number;
+            results: {
+                status: "fail" | "pass" | "inconclusive" | "na" | "known_gap_open" | "known_gap_closed";
+                id: string;
+                title: string;
+                expect: "blocked" | "allowed" | "known_gap";
+                area: string;
+                tier: "core" | "internet" | "optional";
+                detail?: string | undefined;
+            }[];
+        };
+        scope?: string | undefined;
+    }>>;
+    hygiene: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    connectionLog: z.ZodNullable<z.ZodObject<{
+        /** The raw file reached the control plane (`PUT /agents/vpn/evidence/:buildId/conn-log`). */
+        uploaded: z.ZodBoolean;
+        omitted: z.ZodOptional<z.ZodEnum<["too_large", "not_kept", "upload_failed", "unreadable"]>>;
+        /** sha256 of the file's exact bytes, as the agent computed it. */
+        sha256: z.ZodNullable<z.ZodString>;
+        bytes: z.ZodEffects<z.ZodNumber, number, number>;
+        lines: z.ZodEffects<z.ZodNumber, number, number>;
+        complete: z.ZodBoolean;
+        incompleteReasons: z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">;
+        /** The agent's own summary, compared with what the control plane recomputes from the file. */
+        summary: z.ZodNullable<z.ZodObject<{
+            total: z.ZodEffects<z.ZodNumber, number, number>;
+            allowed: z.ZodEffects<z.ZodNumber, number, number>;
+            denied: z.ZodEffects<z.ZodNumber, number, number>;
+            connected: z.ZodEffects<z.ZodNumber, number, number>;
+            failed: z.ZodEffects<z.ZodNumber, number, number>;
+            bytesUp: z.ZodEffects<z.ZodNumber, number, number>;
+            bytesDown: z.ZodEffects<z.ZodNumber, number, number>;
+        }, "strip", z.ZodTypeAny, {
+            failed: number;
+            connected: number;
+            denied: number;
+            allowed: number;
+            total: number;
+            bytesUp: number;
+            bytesDown: number;
+        }, {
+            failed: number;
+            connected: number;
+            denied: number;
+            allowed: number;
+            total: number;
+            bytesUp: number;
+            bytesDown: number;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        lines: number;
+        complete: boolean;
+        sha256: string | null;
+        uploaded: boolean;
+        bytes: number;
+        incompleteReasons: string[];
+        summary: {
+            failed: number;
+            connected: number;
+            denied: number;
+            allowed: number;
+            total: number;
+            bytesUp: number;
+            bytesDown: number;
+        } | null;
+        omitted?: "too_large" | "not_kept" | "upload_failed" | "unreadable" | undefined;
+    }, {
+        lines: number;
+        complete: boolean;
+        sha256: string | null;
+        uploaded: boolean;
+        bytes: number;
+        incompleteReasons: string[];
+        summary: {
+            failed: number;
+            connected: number;
+            denied: number;
+            allowed: number;
+            total: number;
+            bytesUp: number;
+            bytesDown: number;
+        } | null;
+        omitted?: "too_large" | "not_kept" | "upload_failed" | "unreadable" | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    sandbox: {
+        orgId: string;
+        profileVersion: number;
+        templateSha256: string;
+        renderedSha256: string;
+        paramsSha256: string;
+        loopbackDenyPorts: number[];
+        selfTest: {
+            counts: Record<string, number>;
+            verdict: "fail" | "pass" | "inconclusive";
+            startedAt: string;
+            durationMs: number;
+            results: {
+                status: "fail" | "pass" | "inconclusive" | "na" | "known_gap_open" | "known_gap_closed";
+                id: string;
+                title: string;
+                expect: "blocked" | "allowed" | "known_gap";
+                area: string;
+                tier: "core" | "internet" | "optional";
+                detail?: string | undefined;
+            }[];
+        };
+        scope?: string | undefined;
+    } | null;
+    buildId: string;
+    v: 1;
+    agent: {
+        version: string;
+        os?: string | undefined;
+        arch?: string | undefined;
+    };
+    tunnel: {
+        configDigest: string | null;
+    };
+    outcome: {
+        status: "succeeded" | "failed";
+        failureKind?: "user" | "infra" | undefined;
+    };
+    helper: {
+        sha256: string | null;
+        version: string | null;
+        arch: "arm64" | "amd64" | null;
+    };
+    egress: {
+        mode: "standard" | "strict" | null;
+        policyHash: string | null;
+    };
+    connectionLog: {
+        lines: number;
+        complete: boolean;
+        sha256: string | null;
+        uploaded: boolean;
+        bytes: number;
+        incompleteReasons: string[];
+        summary: {
+            failed: number;
+            connected: number;
+            denied: number;
+            allowed: number;
+            total: number;
+            bytesUp: number;
+            bytesDown: number;
+        } | null;
+        omitted?: "too_large" | "not_kept" | "upload_failed" | "unreadable" | undefined;
+    } | null;
+    hygiene?: Record<string, unknown> | undefined;
+}, {
+    sandbox: {
+        orgId: string;
+        profileVersion: number;
+        templateSha256: string;
+        renderedSha256: string;
+        paramsSha256: string;
+        loopbackDenyPorts: number[];
+        selfTest: {
+            counts: Record<string, number>;
+            verdict: "fail" | "pass" | "inconclusive";
+            startedAt: string;
+            durationMs: number;
+            results: {
+                status: "fail" | "pass" | "inconclusive" | "na" | "known_gap_open" | "known_gap_closed";
+                id: string;
+                title: string;
+                expect: "blocked" | "allowed" | "known_gap";
+                area: string;
+                tier: "core" | "internet" | "optional";
+                detail?: string | undefined;
+            }[];
+        };
+        scope?: string | undefined;
+    } | null;
+    buildId: string;
+    v: 1;
+    agent: {
+        version: string;
+        os?: string | undefined;
+        arch?: string | undefined;
+    };
+    tunnel: {
+        configDigest: string | null;
+    };
+    outcome: {
+        status: "succeeded" | "failed";
+        failureKind?: "user" | "infra" | undefined;
+    };
+    helper: {
+        sha256: string | null;
+        version: string | null;
+        arch: "arm64" | "amd64" | null;
+    };
+    egress: {
+        mode: "standard" | "strict" | null;
+        policyHash: string | null;
+    };
+    connectionLog: {
+        lines: number;
+        complete: boolean;
+        sha256: string | null;
+        uploaded: boolean;
+        bytes: number;
+        incompleteReasons: string[];
+        summary: {
+            failed: number;
+            connected: number;
+            denied: number;
+            allowed: number;
+            total: number;
+            bytesUp: number;
+            bytesDown: number;
+        } | null;
+        omitted?: "too_large" | "not_kept" | "upload_failed" | "unreadable" | undefined;
+    } | null;
+    hygiene?: Record<string, unknown> | undefined;
+}>;
+export type AgentVpnEvidence = z.infer<typeof agentVpnEvidenceSchema>;
+export interface ConnectionRecord {
+    /** 1-based position among this build's attributed records in the file. */
+    n: number;
+    /** The helper's own per-build record number (a gap in these is a lost record). */
+    bseq: number;
+    ts: string;
+    /** `host:port`, `[v6]:port` for an IPv6 literal. */
+    dest: string;
+    host: string;
+    port: number;
+    proto: string;
+    route: string;
+    decision: "allow" | "deny";
+    reason: string;
+    connected: boolean;
+    bytesUp: number;
+    bytesDown: number;
+    durationMs: number;
+    class?: string;
+    failure?: string;
+}
+export interface DestinationSummary {
+    dest: string;
+    route: string;
+    decision: string;
+    conns: number;
+    bytesUp: number;
+    bytesDown: number;
+}
+/**
+ * Per-(destination, route, decision) totals, sorted by `dest + route + decision` in UTF-16 code unit order.
+ * `scripts/appforge-verify.mjs` recomputes exactly this from a bundle's raw records, so the two must agree to
+ * the byte; the order is deliberately locale-independent (a collation order differs between ICU locales and
+ * would make one verifier disagree with another about the same evidence).
+ */
+export declare function summariseConnections(records: readonly {
+    dest: string;
+    route: string;
+    decision: string;
+    bytesUp?: number;
+    bytesDown?: number;
+}[]): DestinationSummary[];
+/** The digest the document's `connections.logSha256` holds: sha256 over the canonical records, one per line, newline-terminated. */
+export declare function connectionRecordsDigest(records: readonly ConnectionRecord[]): Promise<string>;
+/** The helper's own tally of a build (its `summary` line). */
+export interface HelperTally {
+    reason: string;
+    conns: number;
+    allowed: number;
+    denied: number;
+    connected: number;
+    failed: number;
+    bytesUp: number;
+    bytesDown: number;
+    dropped: number;
+    forcedClosed: number;
+    stream: boolean;
+}
+export interface ConnectionLogAnalysis {
+    records: ConnectionRecord[];
+    destinations: DestinationSummary[];
+    /** Groups beyond ATTESTATION_MAX_DESTINATIONS (0 = the list is complete). */
+    destinationsOmitted: number;
+    /** `errors` counts allowed requests whose dial failed. */
+    totals: {
+        allowed: number;
+        denied: number;
+        errors: number;
+        bytesUp: number;
+        bytesDown: number;
+    };
+    connected: number;
+    logRecords: number;
+    /** See `connectionRecordsDigest`. */
+    logSha256: string;
+    rawLines: number;
+    complete: boolean;
+    incompleteReasons: string[];
+    authFailures: number;
+    sessionCredentialRequests: number;
+    droppedRecords: number;
+    helperTally: HelperTally | null;
+    helperTallyAgrees: boolean | null;
+}
+/**
+ * Re-derives everything a document says about the connection log from the raw file, so the control plane
+ * never relies on the agent's summary. The completeness rules mirror the agent's own aggregator
+ * (packages/agent/src/lib/evidence.ts) so that, for a log nothing went wrong with, both say "complete"; a
+ * test runs the two on the same files. Trusts nothing in a line: malformed lines are counted, strings are
+ * reduced to printable ASCII and clipped, a record of another build is excluded and makes the log incomplete.
+ *
+ * `raw` is the file's text (UTF-8); callers bound its size (`ATTESTATION_LOG_MAX_BYTES`).
+ */
+export declare function analyzeConnectionLog(raw: string, buildId: string): Promise<ConnectionLogAnalysis>;
+/**
+ * The tunnel configuration both sides can describe without any key material: the control plane from the lease
+ * it built, the agent from the job it received. A key-free digest on purpose: the agent's own session
+ * fingerprint (vpn-session.ts) is over the whole job, private key included, and must never be published.
+ */
+export type TunnelDigestInput = Pick<VpnJobConfig, "tunnelId" | "keyVersion" | "gatewayEndpoint" | "gatewayPublicKey" | "tunnelCidr" | "localAddress" | "gatewayAddress" | "lanCidrs" | "dnsServer" | "allowedDomains" | "allowPrivateEndpoint" | "egress">;
+export declare function vpnPublicConfigDigest(job: TunnelDigestInput): Promise<string>;
+/** What a document says about the tunnel: public configuration only, captured when the build was leased. */
+export interface TunnelFacts {
+    id: string;
+    name: string | null;
+    keyVersion: number;
+    gatewayEndpoint: string;
+    lanCidrs: string[];
+    tunnelCidr: string;
+    dnsServer: string | null;
+    allowedDomains: string[];
+    /** First 32 hex characters of sha256(raw 32-byte WireGuard public key), so a customer can match AppForge's side of their gateway config. */
+    appforgePublicKeyFp: string | null;
+    gatewayPublicKeyFp: string | null;
+    configDigest: string;
+}
+export declare function buildTunnelFacts(job: TunnelDigestInput & {
+    tunnelName?: string;
+}, appforgePublicKey: string | null): Promise<TunnelFacts>;
+/** The egress policy as it is recorded: the helper's canonical expansion (one entry per host, explicit sorted ports). */
+export interface AttestedEgressPolicy {
+    v: number;
+    allow: {
+        host: string;
+        ports: number[];
+    }[];
+}
+/**
+ * The policy exactly as the helper enforces it, in the form a document inlines, with the helper's own hash of it.
+ * Throws on an invalid policy (callers validated it when they built the lease).
+ */
+export declare function expandLeasedPolicy(policy: VpnEgressPolicy): Promise<{
+    policy: AttestedEgressPolicy;
+    helperHash: string;
+}>;
+/**
+ * What `scripts/r2-release.mjs` publishes next to a release's artifacts (`<prefix>/<version>/manifest.json`):
+ * the sha256 of every artifact and a few release-level facts. The control plane compares what an agent reports
+ * (the helper binary it ran, the sandbox template it rendered) with these. A release cut before manifests existed
+ * has none, which is recorded as "not checked", never as a match.
+ */
+export declare const releaseManifestSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    prefix: z.ZodString;
+    version: z.ZodString;
+    publishedAt: z.ZodString;
+    artifacts: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        sha256: z.ZodString;
+        bytes: z.ZodEffects<z.ZodNumber, number, number>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        sha256: string;
+        bytes: number;
+    }, {
+        name: string;
+        sha256: string;
+        bytes: number;
+    }>, "many">;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    v: 1;
+    artifacts: {
+        name: string;
+        sha256: string;
+        bytes: number;
+    }[];
+    prefix: string;
+    version: string;
+    publishedAt: string;
+    meta?: Record<string, string> | undefined;
+}, {
+    v: 1;
+    artifacts: {
+        name: string;
+        sha256: string;
+        bytes: number;
+    }[];
+    prefix: string;
+    version: string;
+    publishedAt: string;
+    meta?: Record<string, string> | undefined;
+}>;
+export type ReleaseManifest = z.infer<typeof releaseManifestSchema>;
+export declare function parseReleaseManifest(textBody: string): ReleaseManifest | null;
+/** The helper artifact name `scripts/r2-release.mjs` publishes for an architecture. */
+export declare const helperArtifactName: (arch: "arm64" | "amd64") => string;
+export type AttestationCompleteness = "full" | "partial" | "server_observed_only";
+export type ControlsVerdict = "all_enforced" | "violations_detected" | "not_evaluated" | "network_policy_checked";
+export type CrossCheckStatus = "match" | "mismatch" | "not_checked";
+export interface ControlTestResult {
+    id: string;
+    area: string;
+    title: string;
+    expect: string;
+    verdict: "pass" | "fail" | "inconclusive";
+    reason: string;
+    /** Who produced the result: the on-host matrix the agent ran, or a comparison the control plane made. */
+    source: "agent-selftest" | "server-crosscheck";
+}
+export interface CrossCheck {
+    id: string;
+    status: CrossCheckStatus;
+    detail: string;
+}
+/** Everything the control plane knows about a build without asking the agent. Times are ISO-8601 UTC, whole seconds. */
+export interface AttestationServerFacts {
+    orgId: string;
+    appId: string;
+    buildId: string;
+    workflow: string;
+    branch: string;
+    commitSha: string | null;
+    tunnelId: string | null;
+    /** 1 = strict egress, 2 = regulated (Build.vpnClass at lease time). */
+    vpnClass: 1 | 2;
+    build: {
+        status: string;
+        failureKind: string | null;
+        queuedAt: string | null;
+        startedAt: string | null;
+        finishedAt: string | null;
+    };
+    /** The Mac that leased the build, as the control plane has it (from its own agent row). */
+    agent: {
+        id: string | null;
+        version: string | null;
+        os: string | null;
+    };
+    /** What the lease carried, recorded when the build was leased. Null when there is no such record. */
+    lease: {
+        leasedAt: string | null;
+        /** The expanded egress policy exactly as sent to the helper (helper canonical form). */
+        policy: AttestedEgressPolicy | null;
+        /** The helper's canonical-form hash of `policy`. */
+        policyHash: string | null;
+        tunnel: TunnelFacts | null;
+    } | null;
+    /** The build's VpnEvent rows, oldest first. */
+    events: {
+        type: string;
+        at: string;
+    }[];
+    chain: {
+        headSeq: number;
+        headHash: string;
+        firstEventSeq: number | null;
+    };
+    issuedAt: string;
+    manifests: {
+        vpnRelease: ReleaseManifest | null;
+        agentRelease: ReleaseManifest | null;
+    };
+}
+export interface BuiltAttestation {
+    doc: AttestationDocument;
+    completeness: AttestationCompleteness;
+    controlsVerdict: ControlsVerdict;
+    /** Failing control-test results, agent-side and server-side. */
+    violations: number;
+    gaps: string[];
+}
+export interface AttestationDocument {
+    type: typeof ATTESTATION_DOC_TYPE;
+    version: number;
+    id: string;
+    issuedAt: string;
+    completeness: AttestationCompleteness;
+    subject: {
+        orgId: string;
+        appId: string;
+        buildId: string;
+        workflow: string;
+        branch: string;
+        commitSha: string | null;
+        tunnelId: string | null;
+    };
+    host: {
+        agentId: string | null;
+        agentVersion: string | null;
+        os: string | null;
+        arch: string | null;
+    };
+    helper: Record<string, unknown>;
+    tunnel: Record<string, unknown> | null;
+    policy: {
+        mode: string;
+        egressPolicy?: AttestedEgressPolicy;
+        egressPolicySha256?: string;
+        helperPolicyHash: string | null;
+        enforcement: Record<string, unknown> | null;
+    };
+    timing: Record<string, string | number | null>;
+    isolation: Record<string, unknown>;
+    connections: Record<string, unknown> & {
+        destinations?: DestinationSummary[];
+        logSha256?: string;
+    };
+    controlTests?: {
+        packVersion: string;
+        phase: string;
+        results: ControlTestResult[];
+        summary: {
+            pass: number;
+            fail: number;
+            inconclusive: number;
+        };
+        resultsSha256: string;
+        [k: string]: unknown;
+    };
+    crossChecks: CrossCheck[];
+    gaps: string[];
+    scope: {
+        statement: string;
+        limits: string[];
+    };
+    provenance: Record<string, string[]>;
+    auditChain: {
+        headSeq: number;
+        headHash: string;
+        firstEventSeq: number | null;
+    };
+    result: {
+        buildStatus: string;
+        failureKind: string | null;
+        agentReportedStatus: string | null;
+        controlsVerdict: ControlsVerdict;
+        violations: number;
+    };
+    [k: string]: unknown;
+}
+/** The statements every document carries, so a reader never has to guess what it does not claim. */
+export declare const ATTESTATION_LIMITS: readonly string[];
+export declare const ATTESTATION_PROVENANCE: Readonly<Record<string, string[]>>;
+export declare function summariseControls(results: readonly {
+    verdict: string;
+}[]): {
+    pass: number;
+    fail: number;
+    inconclusive: number;
+};
+/**
+ * A canonical-JSON-safe copy of an object whose shape this module does not own (the agent's hygiene evidence), or null when it is
+ * too large or too deep to carry. Numbers that are not safe integers are rounded and lone surrogates replaced (`normalized` says
+ * so): the evidence is kept, not dropped, because it cannot be hashed identically everywhere as sent.
+ */
+export declare function sanitizeOpaque(value: unknown, maxBytes: number): {
+    value: Record<string, unknown>;
+    normalized: boolean;
+} | null;
+export interface BuildAttestationInput {
+    facts: AttestationServerFacts;
+    /** The agent's report; null when none arrived (the degraded, server-observed document). */
+    evidence: AgentVpnEvidence | null;
+    /** The control plane's own analysis of the raw log it holds; null when it holds none. */
+    log: ConnectionLogAnalysis | null;
+    /** The raw object the control plane holds: its digest (verified by the bucket at upload) and size. */
+    rawLog: {
+        sha256: string;
+        bytes: number;
+    } | null;
+    /** Why this is a degraded document (no agent evidence), in words. */
+    degradedReason?: string;
+}
+/**
+ * Assembles the attestation document for a build, in exactly the shape `scripts/appforge-verify.mjs` reads, and
+ * decides its completeness and verdict. Every comparison between a thing the agent claims and a thing the
+ * control plane knows becomes a `crossChecks` entry; a mismatch is also a failing control-test result, which
+ * makes the verifier exit 2. Throws only on a programming error (a value canonical JSON cannot represent).
+ */
+export declare function buildAttestationDocument(input: BuildAttestationInput): Promise<BuiltAttestation>;
+export interface BundleChainEntry {
+    seq: number;
+    prevHash: string;
+    hash: string;
+    kind: string;
+    refId: string | null;
+    payload: unknown;
+}
+export interface BundleCheckpoint {
+    orgId: string;
+    seq: number;
+    hash: string;
+    issuedAt: string;
+    keyId: string;
+    signature: string;
+}
+export interface EvidenceBundle {
+    format: typeof EVIDENCE_BUNDLE_FORMAT;
+    version: 1;
+    attestation: {
+        doc: AttestationDocument;
+        signatures: AttestationSignature[];
+    };
+    auditChain: {
+        orgId: string;
+        anchor: {
+            seq: number;
+            hash: string;
+        } | null;
+        entries: BundleChainEntry[];
+        checkpoints: BundleCheckpoint[];
+    };
+    connectionLog?: {
+        encoding: "records";
+        normalization: string;
+        records: ConnectionRecord[];
+    };
+}
+/** sha256 of the canonical document: what the chain's registration entry holds as `docSha256`. */
+export declare function attestationDocumentSha256(doc: unknown): Promise<string>;
+/**
+ * The printable page for a bundle. A TWIN of `renderEvidenceHtml` in scripts/appforge-verify.mjs, which cannot
+ * be imported here (it is a zero-dependency single file built on node:crypto, and these Workers do not enable
+ * Node compatibility): `--render-check` re-renders the visible page from its embedded JSON with that function
+ * and requires a byte-for-byte match, so this one must produce identical output, and packages/core's tests
+ * require it on many bundles. Only the JSON embedded in the page is authenticated; the visible text is a
+ * rendering of it.
+ */
+export declare function renderEvidenceHtml(bundle: EvidenceBundle, { docSha256 }: {
+    docSha256: string;
+}): string;
+/**
+ * The bundle and, when asked, its printable page, from an attestation's stored parts. The page is rendered from a
+ * JSON round trip of the bundle, so the bytes the verifier re-renders from the embedded JSON are the bytes written
+ * here (JS reorders integer-like object keys on a parse, and the round trip applies that once, up front).
+ */
+export declare function renderEvidencePage(bundle: EvidenceBundle): Promise<string>;
+export declare function isoNowSeconds(now?: Date): string;
+export {};
+//# sourceMappingURL=vpn-attestation.d.ts.map