@sanning/proof 0.19.1 → 0.20.0

package/src/agent-proof.ts

@@ -1,264 +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";
-import type { Envelope } from "./types.js";
-
-export const AGENT_PROOF_SPEC_VERSION = "sanning.agent.proof/v1";
-
-export interface AgentProofBundle {
-  spec_version: string;
-  checkpoint_envelope: Envelope;
-  checkpoint_tx_id: string;
-  leaf: Record<string, unknown>;
-  leaf_index: number;
-  audit_path: string[];
-  [k: string]: unknown;
-}
-
-export interface AgentProofResult {
-  status: "verified" | "failed" | "partial" | "malformed";
-  // The checkpoint envelope is authentic (signature + inline payload bind).
-  checkpointOk: boolean;
-  // The leaf's RFC 9162 audit path reconstructs the checkpoint's merkle_root.
-  inclusionOk: boolean;
-  // On-chain re-fetch matched (null when not requested).
-  onChainOk: boolean | null;
-  onChainChecked: boolean;
-  leafIndex: number;
-  leafCount: number | null;
-  checkpointTxId: string | null;
-  errors: string[];
-}
-
-export interface VerifyAgentProofOptions {
-  gateways?: string[];
-  fetchImpl?: typeof fetch;
-}
-
-/** 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: Uint8Array): string {
-  let out = "";
-  for (const x of bytes) out += x.toString(16).padStart(2, "0");
-  return out;
-}
-
-export function isAgentProofSpec(specVersion: unknown): boolean {
-  if (typeof specVersion !== "string") return false;
-  return specVersion === AGENT_PROOF_SPEC_VERSION || specVersion.startsWith(`${AGENT_PROOF_SPEC_VERSION}.`);
-}
-
-export async function verifyAgentProof(
-  bundle: unknown,
-  options: VerifyAgentProofOptions = {},
-): Promise<AgentProofResult> {
-  const fail = (error: string): AgentProofResult => ({
-    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 as AgentProofBundle;
-  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: string[] = [];
-
-  // Step 1: verify the checkpoint envelope (inline payload — no payloadBytes).
-  let checkpointOk = false;
-  let merkleRoot: string | undefined;
-  let leafCount: number | undefined;
-  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 ?? {}) as {
-      merkle_root?: unknown;
-      leaf_count?: unknown;
-    };
-    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: Uint8Array | undefined;
-    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 as number,
-          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: boolean | null = null;
-  let gatewayUnavailable = false;
-  if (onChainChecked) {
-    const fetchImpl = options.fetchImpl ?? (globalThis.fetch as typeof fetch | undefined);
-    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: AgentProofResult["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: Envelope,
-  txId: string,
-  gateways: string[],
-  fetchImpl: typeof fetch,
-): Promise<{ ok: boolean | null; unavailable: boolean; error?: string }> {
-  let expectedHex: string;
-  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/src/run-adapters.ts

@@ -1,44 +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, 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>;
-
-const dynamicImport: Importer = (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: Importer = dynamicImport,
-): Promise<Map<string, EnclaveAdapter>> {
-  const found = new Map<string, EnclaveAdapter>();
-  for (const [provider, name] of Object.entries(ADAPTER_MODULES)) {
-    let module: unknown;
-    try {
-      module = await importer(name);
-    } catch {
-      continue;
-    }
-    const m = module as Partial<EnclaveAdapter> | null;
-    if (
-      m !== null &&
-      typeof m === "object" &&
-      m.provider === provider &&
-      typeof m.check === "function" &&
-      declaredKinds(m) !== null
-    ) {
-      found.set(provider, m as EnclaveAdapter);
-    }
-  }
-  return found;
-}