@sanning/proof 0.17.0 → 0.19.0

package/src/environment.ts

@@ -0,0 +1,145 @@
+// The environment marker: is this sandbox evidence?
+//
+// `environment` is an OPTIONAL skeleton field inside every envelope's signed
+// scope, `"dev"` or `"production"` (envelope-spec §2, A1 and A9). The spec
+// says a verifier MAY surface the value as `environment_marker` in its result
+// and a profile MAY refuse to count dev-marked envelopes toward production
+// evidence. Both commands now do the first, and print a pack or case that
+// holds a `dev` envelope as sandbox evidence rather than as `VERIFIED`.
+//
+// The marker is read from the signed envelopes the pack holds, never from a
+// wrapper field, a pack name or anything else the holder could write without a
+// key. It never moves the verdict word: a sandbox pack that verifies is still
+// `verified`, and the commands map that to the headline `SANDBOX` and exit 5
+// (`sandboxExit` in `./exit-codes.ts`). The Python twin is
+// `src/sanning_proof/environment.py`.
+
+import { isAgentProofSpec } from "./agent-proof.js";
+import {
+  ANCHOR_TRACE_BODY_TYPE,
+  EXPORT_BODY_TYPE,
+  type EvidenceBundleResult,
+  SIMULATED_WITNESS_KIND,
+  STAMP_EVIDENCE_BODY_TYPE,
+} from "./evidence.js";
+
+/** `"dev"` when every envelope is signed `dev`, `"mixed"` when only some are. */
+export type EnvironmentMarker = "dev" | "mixed";
+
+/** The headline `verify` prints for sandbox evidence in place of `VERIFIED`. */
+export const SANDBOX_HEADLINE = "SANDBOX";
+
+/** The title `case` prints for sandbox evidence in place of `Verified` (case titles are title case). */
+export const SANDBOX_TITLE = "Sandbox";
+
+/** The one line printed with it, and with any other headline, wherever the marker is present. */
+export const SANDBOX_LINE = "Sandbox evidence (environment dev): not production evidence";
+
+// The same bound `resolveTraceEvents` puts on unwrapping export wrappers.
+const MAX_EXPORT_UNWRAP = 4;
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function own(o: Record<string, unknown>, key: string): unknown {
+  return Object.prototype.hasOwnProperty.call(o, key) ? o[key] : undefined;
+}
+
+function entryEnvelopes(list: unknown, out: Record<string, unknown>[]): void {
+  if (!Array.isArray(list)) return;
+  for (const entry of list) {
+    if (!isObject(entry)) continue;
+    const env = own(entry, "envelope");
+    if (isObject(env)) out.push(env);
+  }
+}
+
+/**
+ * The signed envelopes a pack holds: every checkpoint and event envelope of an
+ * anchor-trace body, every event envelope of a stamp-evidence body, the same
+ * inside an export's inline source bundle, and an agent proof's checkpoint
+ * envelope. A stamp-trace body holds none. A value that is not an object is
+ * not an envelope and is not counted.
+ */
+export function packEnvelopes(bundle: unknown): Record<string, unknown>[] {
+  const out: Record<string, unknown>[] = [];
+  if (isObject(bundle) && isAgentProofSpec(own(bundle, "spec_version"))) {
+    const env = own(bundle, "checkpoint_envelope");
+    if (isObject(env)) out.push(env);
+    return out;
+  }
+  let cur: unknown = bundle;
+  for (let depth = 0; depth < MAX_EXPORT_UNWRAP; depth++) {
+    if (!isObject(cur)) return out;
+    const bodyType = own(cur, "body_type");
+    const body = own(cur, "body");
+    if (!isObject(body)) return out;
+    if (bodyType === ANCHOR_TRACE_BODY_TYPE) {
+      entryEnvelopes(own(body, "checkpoints"), out);
+      entryEnvelopes(own(body, "events"), out);
+      return out;
+    }
+    if (bodyType === STAMP_EVIDENCE_BODY_TYPE) {
+      entryEnvelopes(own(body, "events"), out);
+      return out;
+    }
+    if (bodyType !== EXPORT_BODY_TYPE) return out;
+    cur = own(body, "source_bundle");
+  }
+  return out;
+}
+
+/**
+ * The environment marker over one or more packs: `"dev"` where every envelope
+ * they hold is signed `environment: "dev"`, `"mixed"` where some are and some
+ * are not (`production`, or no `environment` at all), and `null` where none
+ * is, which is every production pack and every pack that holds no envelope.
+ */
+export function environmentMarker(bundles: readonly unknown[]): EnvironmentMarker | null {
+  let total = 0;
+  let dev = 0;
+  for (const bundle of bundles) {
+    for (const env of packEnvelopes(bundle)) {
+      total++;
+      if (own(env, "environment") === "dev") dev++;
+    }
+  }
+  if (dev === 0) return null;
+  return dev === total ? "dev" : "mixed";
+}
+
+/**
+ * Whether a body's only unsettled witnesses are simulated: the body has events
+ * and witnesses (checkpoints, stamps or both), every witness is named, at
+ * least one is simulated, and every other one a gateway confirmed. Then the
+ * one thing that keeps the bundle from `verified` is a simulated witness
+ * nobody can look up: no mismatch, no unreachable gateway, no witness of
+ * another kind, no checkpoint or stamp witnessed by nobody.
+ */
+export function onlySimulatedUnsettled(result: EvidenceBundleResult): boolean {
+  const witnesses = [...result.checkpoints, ...(result.stamps ?? [])];
+  if (witnesses.length === 0 || result.events.length === 0) return false;
+  let simulated = 0;
+  for (const w of witnesses) {
+    if (w.anchorRef === null) return false;
+    if (w.anchorRef.kind === SIMULATED_WITNESS_KIND) simulated++;
+    else if (w.onChain?.rollup !== "confirm") return false;
+  }
+  return simulated > 0;
+}
+
+/**
+ * Whether a run with gateways counted only simulated witnesses, so nothing
+ * was looked up on a chain: gateways were passed, the run is not counted as
+ * checked on a chain, and it holds a simulated witness. A run that stopped
+ * before its witnesses were read (a bad wrapper signature or `body_hash`, an
+ * unknown `body_type`, an export whose source is not inline) holds none, so it
+ * is not one, and prints what it printed before simulated witnesses existed.
+ */
+export function simulatedOnlyRun(result: EvidenceBundleResult, gateways: readonly string[]): boolean {
+  if (gateways.length === 0 || result.onChainChecked) return false;
+  return [...result.checkpoints, ...(result.stamps ?? [])].some(
+    (w) => w.anchorRef?.kind === SIMULATED_WITNESS_KIND,
+  );
+}

package/src/evidence.ts

@@ -1662,6 +1662,10 @@ async function verifyAnchorTrace(
   let gatewayUnavailable = false;
   let uncheckedKind = false;
   let uncheckedId = false;
+  // Simulated witnesses against witnesses of any other kind, counted over the
+  // checkpoints that name one, as `refetchStamps` counts stamps.
+  let simulated = 0;
+  let onChainKinds = 0;
   if (onChainChecked) {
     if (typeof fetchImpl !== "function") {
       gatewayUnavailable = true;
@@ -1701,6 +1705,8 @@ async function verifyAnchorTrace(
           cpr.errors.push("checkpoint has no anchor_ref -- not yet witnessed, nothing to re-fetch");
           continue;
         }
+        if (cpr.anchorRef.kind === SIMULATED_WITNESS_KIND) simulated++;
+        else onChainKinds++;
         const outcome = await refetchCheckpoint(cp, cpr.anchorRef, gateways, fetchImpl);
         cpr.onChain = outcome.onChain;
         cpr.onChainOk = outcome.onChain?.onChainOk ?? null;
@@ -1764,7 +1770,10 @@ async function verifyAnchorTrace(
     bodyHashOk: true,
     signatureOk: true,
     bodyType,
-    onChainChecked,
+    // A run whose only witnessed checkpoints are simulated looked nothing up
+    // on a chain, so it is not counted as checked on one (the stamp rule in
+    // `refetchStamps`). The checkpoints stay not checked and the run partial.
+    onChainChecked: onChainChecked && !(simulated > 0 && onChainKinds === 0),
     checkpoints: checkpointResults,
     events: eventResults,
     assertedStatus,
@@ -2679,12 +2688,16 @@ async function refetchStamps(
   let gatewayUnavailable = false;
   let uncheckedKind = false;
   let uncheckedId = false;
+  let simulated = 0;
+  let onChainKinds = 0;
   for (let i = 0; i < stamps.length; i++) {
     const st = stamps[i]!;
     const witnessedHex = witnessed[i];
     // No witness named, or bytes we could not read: nothing to re-fetch, and
     // nothing a gateway could confirm or deny. Left as `onChain: null`.
     if (st.anchorRef === null || witnessedHex === undefined) continue;
+    if (st.anchorRef.kind === SIMULATED_WITNESS_KIND) simulated++;
+    else onChainKinds++;
 
     const outcome = await refetchStamp(witnessedHex, st.anchorRef, gateways, fetchImpl);
     st.onChain = outcome.onChain;
@@ -2704,9 +2717,24 @@ async function refetchStamps(
     // unreachable note would fail a stamp for a gateway being down.
     st.ok = st.ok && st.onChainOk !== false;
   }
+  // A simulated witness is a sandbox plane's stand-in for a chain: there is no
+  // chain to look it up on, so it is never counted as checked on one.
+  // It stays not checked like any kind this verifier has no adapter for, and
+  // the run stays undetermined; what changes is that a run whose only
+  // witnesses are simulated no longer says it checked anything on a chain.
+  if (simulated > 0 && onChainKinds === 0) {
+    return { onChainChecked: false, gatewayUnavailable, uncheckedKind, uncheckedId };
+  }
   return { onChainChecked, gatewayUnavailable, uncheckedKind, uncheckedId };
 }
 
+/**
+ * The `anchor_ref.kind` a sandbox plane writes for a witness it simulated
+ * (chain id `sanning-sandbox`). Never looked up and never counted as checked
+ * on a chain.
+ */
+export const SIMULATED_WITNESS_KIND = "simulated";
+
 interface StampRefetchSummary {
   onChainChecked: boolean;
   gatewayUnavailable: boolean;

package/src/exit-codes.ts

@@ -16,6 +16,14 @@ export const EXIT_FAILED = 1;
 export const EXIT_MALFORMED = 2;
 export const EXIT_UNDETERMINED = 3;
 export const EXIT_MIXED = 4;
+/**
+ * Sandbox evidence (envelope-spec §2): a run that would exit 0 over a pack or
+ * case holding a record signed `environment: "dev"`, or a run over records
+ * that are ALL signed `dev` whose only unsettled witnesses are simulated.
+ * Not a verdict word: the verdict stays what the checks established
+ * (`sandboxExit`). No flag turns 5 into 0.
+ */
+export const EXIT_SANDBOX = 5;
 
 /**
  * The exit code of each of the eight verdict words (`evidence-bundle.md` §3).
@@ -40,6 +48,7 @@ export const EXIT_CODES_HELP = [
   "  2  usage or malformed",
   "  3  undetermined: partial, pending, incomplete or not_found",
   "  4  mixed: more than one outcome, none failed; read the exceptions",
+  "  5  sandbox: a record is signed environment dev; would be 0, or only a simulated witness is unchecked",
 ].join("\n");
 
 /**
@@ -52,3 +61,22 @@ export function exitCodeFor(verdict: unknown): number {
   }
   return EXIT_MALFORMED;
 }
+
+/**
+ * The code a verb exits with once the environment marker is read. 5 where the
+ * run would otherwise exit 0 and the pack or case holds a record signed `dev`;
+ * 5 where the run is undetermined only because a simulated witness could not
+ * be looked up (`onlySimulatedUnsettled`, which the caller works out) and
+ * EVERY record is signed `dev`, so a production or mixed pack carrying a
+ * simulated witness keeps 3; the code unchanged everywhere else. A failure
+ * stays 1, malformed 2 and mixed 4.
+ */
+export function sandboxExit(
+  code: number,
+  environmentMarker: string | null,
+  onlySimulatedUnsettled = false,
+): number {
+  if (code === EXIT_VERIFIED && environmentMarker !== null) return EXIT_SANDBOX;
+  if (code === EXIT_UNDETERMINED && environmentMarker === "dev" && onlySimulatedUnsettled) return EXIT_SANDBOX;
+  return code;
+}

package/src/index.ts

@@ -25,9 +25,19 @@ export {
   specVersionSupported,
   verifyEnvelope,
 } from "./verifier.js";
+// The strict reader of bytes that claim to be JCS, the twin of Python's public
+// `canonicalize.jcs_loads`. The enclave attestation adapters read a token's
+// JSON through it, so they refuse what the kernel refuses. Additive.
+export { jcsParse } from "./verifier.js";
+// The same reader within the enclave readers' limits (enclave-attestation
+// section 2.1): depth checked on the bytes first, every number finite. The
+// adapters read a token's header and claims and the manifest through it.
+// Additive.
+export { exceedsTextDepth, hasNonFiniteNumber, jcsParseWithinLimits, MAX_READ_DEPTH } from "./verifier.js";
 export {
   bytesToHex,
   deriveOperatorAddress,
+  ed25519Refusal,
   ed25519Verify,
   hexToBytes,
   sha256Bytes,
@@ -174,6 +184,7 @@ export {
   DECLARATION_VERDICTS,
   DECLARATION_VERSION,
   DECLARATION_VERSION_V2,
+  DECLARATION_VERSION_V3,
   DECLARATION_VERSIONS,
   checkDeclaration,
   declarationClaims,
@@ -352,7 +363,10 @@ export type {
 // `vectors/chain-reading.json` beside the pack-grading table for the same
 // reason: a rule consumers must agree with needs a statement they can fetch.
 //
-// It returns FINDINGS, never a verdict, and it feeds no status. Chain links are
+// It returns FINDINGS, never a verdict, and it feeds no status on its own: a
+// pack's signed v3 declaration can claim a chain complete and in order, and
+// `checkDeclaration` holds that claim to the links `readChainLinks` reads
+// (evidence-bundle.md 5.4.2 rule 11). Chain links are
 // deletion/reorder-evidence for the events present and NOT a completeness proof
 // (`anchor/docs/profile-sanning.events-v2.md` §5), drop the last N events of a
 // chain and nothing dangles. `CHAIN_READING_SCOPE` is that sentence, exported so
@@ -361,12 +375,14 @@ export type {
 export {
   ADAPTER_CHAIN_NAMESPACES,
   CHAIN_READING_SCOPE,
+  readChainLinks,
   readChains,
   renderChainFinding,
 } from "./chain.js";
 export type {
   ChainFinding,
   ChainFindingKind,
+  ChainLink,
   ChainReading,
   ChainSource,
   ChainSummary,
@@ -384,10 +400,24 @@ export {
   EXIT_FAILED,
   EXIT_MALFORMED,
   EXIT_MIXED,
+  EXIT_SANDBOX,
   EXIT_UNDETERMINED,
   EXIT_VERIFIED,
   exitCodeFor,
+  sandboxExit,
 } from "./exit-codes.js";
+// Sandbox evidence: the environment marker over the envelopes a pack or case
+// holds (envelope-spec §2, the `environment_marker` MAY), and the headline and
+// line both commands print for it. Additive.
+export {
+  SANDBOX_HEADLINE,
+  SANDBOX_LINE,
+  SANDBOX_TITLE,
+  environmentMarker,
+  onlySimulatedUnsettled,
+  packEnvelopes,
+} from "./environment.js";
+export type { EnvironmentMarker } from "./environment.js";
 export { attestationSignatureToHex, composeExport } from "./compose.js";
 export type { ComposeExportOptions, ComposeExportResult, ExporterKey } from "./compose.js";
 

package/src/run-adapters.ts

@@ -0,0 +1,44 @@
+// 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;
+}