@sanning/proof 0.19.0 → 0.20.0

package/dist/agent-proof.js

@@ -1,226 +0,0 @@
-// Agent inclusion proof verification (`sanning.agent.proof/v1`).
-//
-// The `sanning.agent.proof/v1` bundle is the agent's ~1.4 KB self-contained
-// inclusion proof: a signed checkpoint envelope (sanning.agent/v1, INLINE payload)
-// plus a single leaf object and its RFC 9162 audit path. Verifying it is the
-// inverse of `sanningd proof`. The CLI sniffs `spec_version` and routes here so
-// ONE verifier covers both the agent (this) and the anchor SDK (evidence.ts).
-//
-// Algorithm:
-//   1. Verify the checkpoint envelope (signature + inline payload_hash bind).
-//   2. leaf_hash = SHA-256(0x00 || JCS(leaf)).
-//   3. Walk audit_path with leaf_index + leaf_count (from the checkpoint
-//      payload) to reconstruct the root.
-//   4. Confirm the reconstructed root == checkpoint_envelope.payload.merkle_root.
-//   5. (optional) Re-fetch checkpoint_tx_id from a gateway and byte-compare.
-import { hexToBytes, utf8 } from "./crypto.js";
-import { safeInteger } from "./grading.js";
-import { leafHash, verifyInclusion } from "./merkle.js";
-import { MAX_CANONICAL_DEPTH, exceedsDepth, jcs, jcsParse, verifyEnvelope } from "./verifier.js";
-export const AGENT_PROOF_SPEC_VERSION = "sanning.agent.proof/v1";
-/** The sentence `agent_proof.py` writes when the proof's own fields are not usable. */
-const MALFORMED_PROOF = "merkle_root / audit_path / leaf_index malformed";
-function toHex(bytes) {
-    let out = "";
-    for (const x of bytes)
-        out += x.toString(16).padStart(2, "0");
-    return out;
-}
-export function isAgentProofSpec(specVersion) {
-    if (typeof specVersion !== "string")
-        return false;
-    return specVersion === AGENT_PROOF_SPEC_VERSION || specVersion.startsWith(`${AGENT_PROOF_SPEC_VERSION}.`);
-}
-export async function verifyAgentProof(bundle, options = {}) {
-    const fail = (error) => ({
-        status: "malformed",
-        checkpointOk: false,
-        inclusionOk: false,
-        onChainOk: null,
-        onChainChecked: false,
-        leafIndex: -1,
-        leafCount: null,
-        checkpointTxId: null,
-        errors: [error],
-    });
-    if (bundle === null || typeof bundle !== "object" || Array.isArray(bundle)) {
-        return fail("bundle is not a JSON object");
-    }
-    // Bound nesting before any canonicalization (checkpoint envelope + Merkle
-    // leaves are canonicalized recursively) — a fixed shared limit keeps this a
-    // `malformed` verdict in every kernel. See MAX_CANONICAL_DEPTH.
-    if (exceedsDepth(bundle, MAX_CANONICAL_DEPTH)) {
-        return fail(`bundle nesting exceeds the ${MAX_CANONICAL_DEPTH}-level canonicalization depth bound`);
-    }
-    const b = bundle;
-    if (!isAgentProofSpec(b.spec_version)) {
-        // An absent one reads `null`, as in `agent_proof.py` (`dict.get` gives
-        // None); `JSON.stringify(undefined)` would write the word `undefined`.
-        return fail(`unsupported bundle spec_version: ${JSON.stringify(b.spec_version ?? null)}`);
-    }
-    if (b.checkpoint_envelope === null || typeof b.checkpoint_envelope !== "object") {
-        return fail("bundle missing checkpoint_envelope");
-    }
-    if (b.leaf === null || typeof b.leaf !== "object") {
-        return fail("bundle missing leaf");
-    }
-    if (!Array.isArray(b.audit_path)) {
-        return fail(MALFORMED_PROOF);
-    }
-    const errors = [];
-    // Step 1: verify the checkpoint envelope (inline payload — no payloadBytes).
-    let checkpointOk = false;
-    let merkleRoot;
-    let leafCount;
-    try {
-        const res = await verifyEnvelope(b.checkpoint_envelope);
-        checkpointOk = res.ok && res.payloadHashOk === true;
-        if (!res.signatureOk)
-            errors.push("checkpoint envelope signature failed");
-        if (res.payloadHashOk !== true)
-            errors.push("checkpoint envelope payload binding failed");
-        // A malformed skeleton field (proof#95) fails the envelope with a valid
-        // signature and binding; name it rather than fail with no reason.
-        for (const m of res.errors)
-            if (m.startsWith("malformed "))
-                errors.push(`checkpoint envelope ${m}`);
-        const payload = (b.checkpoint_envelope.payload ?? {});
-        if (typeof payload.merkle_root === "string")
-            merkleRoot = payload.merkle_root;
-        // `leaf_count` and `leaf_index` are read BY VALUE, the rule every
-        // inclusion reader in both kernels follows (evidence-bundle A38): `3.0` is
-        // 3, and a fraction, a value past 2**53 - 1, a string or a boolean is not
-        // an integer. `agent_proof.py` reads them through `_safe_integer`.
-        leafCount = safeInteger(payload.leaf_count) ?? undefined;
-        if (merkleRoot === undefined)
-            errors.push("checkpoint payload missing merkle_root");
-        if (leafCount === undefined)
-            errors.push("checkpoint payload leaf_count is not an integer");
-    }
-    catch {
-        // The sentence `agent_proof.py` writes for the same failure. The thrown
-        // text is the host's, and a public result carries the kernel's words only
-        // (proof#150).
-        errors.push("checkpoint envelope verification failed");
-    }
-    // Steps 2-4: leaf hash, audit-path walk, root match.
-    let inclusionOk = false;
-    if (merkleRoot !== undefined && leafCount !== undefined) {
-        let lh;
-        try {
-            lh = await leafHash(utf8(jcs(b.leaf)));
-        }
-        catch {
-            errors.push("leaf is not JCS-canonicalizable");
-        }
-        const leafIndex = safeInteger(b.leaf_index);
-        if (lh !== undefined && leafIndex === null) {
-            // `agent_proof.py` refuses a leaf_index that is not an integer with this
-            // sentence. Without the check a string, `null` or `1.5` reaches the walk
-            // and reads as a failed inclusion proof instead (proof#150).
-            errors.push(MALFORMED_PROOF);
-        }
-        else if (lh !== undefined) {
-            try {
-                inclusionOk = await verifyInclusion(lh, leafIndex, leafCount, b.audit_path.map((h) => hexToBytes(h)), hexToBytes(merkleRoot));
-                if (!inclusionOk)
-                    errors.push("audit_path does not reconstruct merkle_root");
-            }
-            catch {
-                // `agent_proof.py`'s sentence for the same failure; the thrown text is
-                // the host's (proof#150).
-                errors.push(MALFORMED_PROOF);
-            }
-        }
-    }
-    // Step 5: optional on-chain re-fetch.
-    const gateways = options.gateways ?? [];
-    const onChainChecked = gateways.length > 0;
-    let onChainOk = null;
-    let gatewayUnavailable = false;
-    if (onChainChecked) {
-        const fetchImpl = options.fetchImpl ?? globalThis.fetch;
-        if (typeof fetchImpl !== "function") {
-            gatewayUnavailable = true;
-            errors.push("on-chain re-fetch requested but no fetch implementation is available");
-        }
-        else {
-            const outcome = await refetch(b.checkpoint_envelope, b.checkpoint_tx_id, gateways, fetchImpl);
-            onChainOk = outcome.ok;
-            if (outcome.unavailable)
-                gatewayUnavailable = true;
-            if (outcome.error)
-                errors.push(outcome.error);
-        }
-    }
-    let status;
-    if (!checkpointOk || !inclusionOk || onChainOk === false) {
-        status = "failed";
-    }
-    else if (gatewayUnavailable) {
-        status = "partial";
-    }
-    else {
-        status = "verified";
-    }
-    return {
-        status,
-        checkpointOk,
-        inclusionOk,
-        onChainOk,
-        onChainChecked,
-        // Read by value, as the walk above read it: a `2.5` or `1e+21` index is
-        // reported as no index, never printed beside a verdict that refused it.
-        leafIndex: safeInteger(b.leaf_index) ?? -1,
-        leafCount: leafCount ?? null,
-        checkpointTxId: typeof b.checkpoint_tx_id === "string" ? b.checkpoint_tx_id : null,
-        errors,
-    };
-}
-async function refetch(envelope, txId, gateways, fetchImpl) {
-    let expectedHex;
-    try {
-        expectedHex = toHex(utf8(jcs(envelope)));
-    }
-    catch {
-        return { ok: false, unavailable: false, error: "checkpoint envelope is not JCS-canonicalizable" };
-    }
-    let anyReachable = false;
-    for (const gw of gateways) {
-        const url = `${gw.replace(/\/+$/, "")}/${txId}`;
-        try {
-            const resp = await fetchImpl(url);
-            if (!resp.ok)
-                continue;
-            anyReachable = true;
-            const onChain = new Uint8Array(await resp.arrayBuffer());
-            if (toHex(onChain) === expectedHex)
-                return { ok: true, unavailable: false };
-            try {
-                // `jcsParse`, matching `_probe_gateway` in
-                // `src/sanning_proof/evidence.py`. These bytes arrive from a gateway or
-                // a CDN in front of one, so a lenient decoder is reachable without any
-                // party building a pack: a CDN serving the envelope with a byte-order
-                // mark split this probe from the one in `evidence.ts`, and two honest
-                // readers of ONE transaction disagreed (proof#140 gate 5).
-                const parsed = jcsParse(onChain);
-                if (toHex(utf8(jcs(parsed))) === expectedHex)
-                    return { ok: true, unavailable: false };
-            }
-            catch {
-                // fall through
-            }
-            return {
-                ok: false,
-                unavailable: false,
-                error: `on-chain bytes at ${txId} do not match the checkpoint envelope`,
-            };
-        }
-        catch {
-            // try next gateway
-        }
-    }
-    if (anyReachable)
-        return { ok: false, unavailable: false, error: `checkpoint ${txId} mismatched on every gateway` };
-    return { ok: null, unavailable: true, error: `checkpoint ${txId} unreachable on all gateways` };
-}

package/dist/run-adapters.d.ts

@@ -1,10 +0,0 @@
-import { type EnclaveAdapter } from "./run.js";
-/** Import a module by name. A parameter so a test can watch what is asked for. */
-export type Importer = (name: string) => Promise<unknown>;
-/**
- * The adapters this environment holds, loaded from `ADAPTER_MODULES` and
- * nothing else. A module counts only when it exports the provider it was
- * loaded for as `provider`, a `check` function, and the failure kinds it
- * declares as `kinds` (`declaredKinds`).
- */
-export declare function loadInstalledAdapters(importer?: Importer): Promise<Map<string, EnclaveAdapter>>;

package/dist/run-adapters.js

@@ -1,35 +0,0 @@
-// Loading the enclave attestation adapters a reader has installed. Kept out of
-// `index.ts` on purpose: it imports packages by name, which a browser bundle
-// cannot resolve, and only the command line needs it. `run.ts` imports nothing.
-//
-// The packages are named by `ADAPTER_MODULES` and by nothing else: a provider
-// id read from a pack is never turned into a module name.
-import { ADAPTER_MODULES, declaredKinds } from "./run.js";
-const dynamicImport = (name) => import(/* @vite-ignore */ name);
-/**
- * The adapters this environment holds, loaded from `ADAPTER_MODULES` and
- * nothing else. A module counts only when it exports the provider it was
- * loaded for as `provider`, a `check` function, and the failure kinds it
- * declares as `kinds` (`declaredKinds`).
- */
-export async function loadInstalledAdapters(importer = dynamicImport) {
-    const found = new Map();
-    for (const [provider, name] of Object.entries(ADAPTER_MODULES)) {
-        let module;
-        try {
-            module = await importer(name);
-        }
-        catch {
-            continue;
-        }
-        const m = module;
-        if (m !== null &&
-            typeof m === "object" &&
-            m.provider === provider &&
-            typeof m.check === "function" &&
-            declaredKinds(m) !== null) {
-            found.set(provider, m);
-        }
-    }
-    return found;
-}

package/dist/run.d.ts

@@ -1,209 +0,0 @@
-import { type SideContentMap } from "./side-content.js";
-export declare const ATTESTATION_VERSION = "sanning.enclave-attestation/v1";
-export declare const BINDING_VERSION = "sanning.run-binding/v1";
-export declare const POLICY_VERSION = "sanning.enclave-policy/v1";
-export declare const MANIFEST_VERSION = "sanning.run-manifest/v1";
-export declare const RUN_OPENED = "runner.run_opened";
-export declare const RUN_CLOSED = "runner.run_closed";
-export declare const PROVIDER_GCP = "gcp-confidential-space";
-export declare const PROVIDER_FLARE = "flare-fcc";
-/**
- * The fixed table: provider id to the package that answers for it. A provider
- * id read from a pack is looked up HERE and nowhere else, so a pack naming `os`
- * or `../x` loads nothing.
- */
-export declare const ADAPTER_MODULES: Readonly<Record<string, string>>;
-/** Printed after an enclave line whose token was checked. Never a state. */
-export declare const REVOCATION_SENTENCE: string;
-export declare const ENCLAVE_STATES: readonly ["confirmed", "differs", "not_checked"];
-export declare const RUN_ACCOUNT_STATES: readonly ["closed", "differs", "not_closed"];
-/** Why an enclave line reads `not_checked`. */
-export declare const ENCLAVE_NOT_CHECKED_KINDS: readonly ["no_adapter", "no_attestation", "unknown_version", "no_policy", "policy_unreadable", "adapter_failed", "no_opening_record"];
-/** The provider-neutral checks that make a line `differs`, in line order. */
-export declare const ENCLAVE_DIFFERS_KINDS: readonly ["attestation_malformed", "subject_key_not_signer", "manifest_not_content", "binding_other_run", "binding_other_manifest", "binding_other_keys", "signed_at_outside_tolerance", "manifest_content_mismatch", "manifest_unreadable", "case_hash_differs", "agent_record_under_runner_key"];
-/** The kinds an adapter may answer with; any other reads `adapter_failed`. */
-export declare const ENCLAVE_NOTE_KINDS: readonly ["no_issue_time", "manifest_withheld", "stamp_unwitnessed"];
-/**
- * Every kind and note the kernel itself names. An adapter declares its own
- * failure kinds (its `kinds`, section 9); none of them may be one of these, so
- * an adapter can never speak for a neutral check.
- */
-export declare const NEUTRAL_KINDS: ReadonlySet<string>;
-export declare const ACCOUNT_FINDING_KINDS: readonly ["record_not_listed", "listed_record_absent", "more_than_one_closing_record", "closing_malformed"];
-/**
- * Why the online line (`flare-fcc` only, section 8) reads `not_checked`:
- * nothing was decided. `adapter_failed` is the kernel's.
- */
-export declare const ONLINE_NOT_CHECKED_KINDS: readonly ["adapter_failed", "evidence_not_confirmed", "no_contracts", "manifest_withheld", "manifest_unreadable", "chain_unavailable", "not_final"];
-/** Why the online line reads `differs`: the chain answered, and it does not match. */
-export declare const ONLINE_DIFFERS_KINDS: readonly ["instruction_count", "instruction_other_extension", "instruction_other_machine", "instruction_other_operation", "instruction_other_message", "transaction_failed", "log_malformed", "run_opened_differs", "run_opened_count", "machine_not_production", "machine_other_extension", "code_not_supported", "call_reverted"];
-export declare const ACCOUNT_NOTE_KINDS: readonly ["agent_key_unknown", "runner_record_under_agent_key", "runner_record_bytes_withheld", "payload_hashes_absent", "unacknowledged_record_absent"];
-/**
- * Whether `s`, the text between a host's brackets, is an IPv6 address as the
- * WHATWG URL Standard's IPv6 parser accepts one (RFC 4291 text form), in
- * lowercase. A step for step port of the parser, the twin of Python's
- * `is_ipv6_text` and the runner's `run.IsPlaneOrigin`.
- */
-export declare function isIpv6Text(s: string): boolean;
-/** The object does not read under the one spelling. The message is the reason. */
-export declare class AttestationRefused extends Error {
-}
-/** `attestation_version` is a string this reader does not know. */
-export declare class UnknownAttestationVersion extends AttestationRefused {
-}
-/** `sanning.run-binding/v1`, read strictly from the evidence. */
-export interface Binding {
-    runId: string;
-    manifestHash: string;
-    runnerPublicKey: string;
-    agentPublicKey: string;
-    credentialPublicKey: string;
-    caseHash: string;
-    /**
-     * The plane's origin the runner claimed the run from (section 4). Carried,
-     * not compared: the plane refuses a claim whose binding names another plane.
-     */
-    plane: string;
-    request: Readonly<Record<string, unknown>>;
-}
-/** `sanning.enclave-attestation/v1`, read strictly. */
-export interface Attestation {
-    runnerPublicKey: string;
-    agentPublicKey: string;
-    manifestHash: string;
-    runId: string;
-    provider: string;
-    evidence: Readonly<Record<string, unknown>>;
-    /** The binding the evidence carries, for a registered provider; else null. */
-    binding: Binding | null;
-}
-/**
- * Read the `enclave_attestation` member of an opening record strictly. Throws
- * `UnknownAttestationVersion` for a version string this reader does not know,
- * and `AttestationRefused` for anything else that is not the one spelling.
- */
-export declare function readAttestation(value: unknown): Attestation;
-/** `readAttestation` over bytes that must be `JCS(object)`. */
-export declare function readAttestationJson(raw: Uint8Array): Attestation;
-/**
- * What an adapter answers (checks 2 to 6 and 8). `binding` is the binding the
- * adapter verified its evidence commits to: `confirmed` without one is outside
- * the contract and reads `adapter_failed`, because the kernel runs checks 7
- * and 11 on that binding. Each kind is one the adapter declares in `kinds`.
- */
-export interface AdapterResult {
-    state: (typeof ENCLAVE_STATES)[number];
-    kinds?: readonly string[];
-    /** The verified token's issue time, seconds since the epoch, or null. */
-    issuedAt?: number | null;
-    imageId?: string | null;
-    hwModel?: string | null;
-    tokenChecked?: boolean;
-    binding?: Binding | null;
-}
-/**
- * An adapter: the provider it answers for, the failure kinds it declares, its
- * check, and optionally the online line.
- */
-export interface EnclaveAdapter {
-    provider: string;
-    kinds: readonly string[];
-    check(attestation: Attestation, options: {
-        policy: Readonly<Record<string, unknown>>;
-        at: string | null;
-    }): AdapterResult | Promise<AdapterResult>;
-    online?(attestation: Attestation, options: {
-        policy: Readonly<Record<string, unknown>>;
-        at: string | null;
-        manifest: Uint8Array | null;
-        rpc: string;
-    }): OnlineLine | Promise<OnlineLine>;
-}
-/**
- * The online line (section 8): what the chain says of a `flare-fcc` opening,
- * read by the adapter at the offline line's evaluation time. `confirmed`
- * carries no kind; `not_checked` and `differs` carry one. It moves nothing.
- */
-export interface OnlineLine {
-    state: (typeof ENCLAVE_STATES)[number];
-    kinds: string[];
-}
-export interface EnclaveLine {
-    state: (typeof ENCLAVE_STATES)[number];
-    kinds: string[];
-    notes: string[];
-    reason: string | null;
-    provider: string | null;
-    evaluatedAt: string | null;
-    evaluation: "stamp" | "token_issue_time" | null;
-    tokenChecked: boolean;
-}
-export interface AccountEntry {
-    kind: string;
-    eventId: string | null;
-}
-export interface RunAccountLine {
-    state: (typeof RUN_ACCOUNT_STATES)[number];
-    findings: AccountEntry[];
-    notes: AccountEntry[];
-    closingEventId: string | null;
-    reason: string | null;
-}
-export interface RunReading {
-    /** The pack by the reader's name for it; two packs can share one (A43). */
-    packRef: string;
-    /** The pack's position among the packs read, as the case reading's `pack_index`. */
-    packIndex: number;
-    eventId: string;
-    runnerPublicKey: string;
-    agentPublicKey: string | null;
-    enclave: EnclaveLine;
-    account: RunAccountLine;
-    /** The online line, where the reader asked for one and the adapter reads the chain; else null. */
-    online: OnlineLine | null;
-}
-export interface RunsReading {
-    runs: RunReading[];
-}
-/** One pack, as `readCase` takes it. */
-export interface RunPack {
-    ref: string;
-    bundle: unknown;
-    content?: SideContentMap | null;
-}
-/**
- * The time the token is evaluated at (7): the interval end of a stamp that
- * holds the opening record and whose witness the reader's lookup confirmed;
- * otherwise null, the token's own issue time.
- */
-/**
- * @internal For the kernel's own tests: the enclave line of one opening record,
- * verified as the caller says, under a provider table the caller names. It is
- * how a test reaches a provider outside `ADAPTER_MODULES`; `readRuns` always
- * reads under `ADAPTER_MODULES`.
- */
-export declare function enclaveLineForTest(record: Record<string, unknown>, publicKey: string, content: Uint8Array | null, policy: unknown, adapters: ReadonlyMap<string, EnclaveAdapter>, table: Readonly<Record<string, string>>): Promise<EnclaveLine>;
-/**
- * The failure kinds an adapter declares as its `kinds`: an array of snake_case
- * strings, at least one, none of them a kind or note the kernel names
- * (`NEUTRAL_KINDS`). `null` where the declaration is not of that form, an
- * empty one included, and then the adapter is not loaded.
- */
-export declare function declaredKinds(adapter: unknown): ReadonlySet<string> | null;
-export declare function readRuns(packs: readonly RunPack[], options?: {
-    policy?: unknown;
-    adapters?: ReadonlyMap<string, EnclaveAdapter> | null;
-    /** A chain endpoint for the online line, handed to an adapter that reads one. */
-    rpc?: string | null;
-    /**
-     * For each pack by position, the `stamp_ref` of every stamp whose witness
-     * the caller looked up and the public record confirmed (the on-chain
-     * half's `confirm`). A token is evaluated at a stamp's interval end only
-     * there, and at its own issue time otherwise. Absent: no lookup.
-     */
-    witnessed?: readonly (readonly string[] | null | undefined)[] | null;
-}): Promise<RunsReading>;
-/** The enclave line, the revocation sentence where a token was checked, and the online line. */
-export declare function renderEnclaveLines(r: RunReading): string[];
-/** The run-account line (specs/run-records.md). */
-export declare function renderAccountLine(r: RunReading): string;