@sanning/proof 0.17.0 → 0.19.0

package/src/verifier.ts

@@ -9,7 +9,7 @@
 
 import canonicalize from "canonicalize";
 
-import { ed25519Verify, isHexField, sha256Hex, utf8 } from "./crypto.js";
+import { SIGNATURE_FAILED, ed25519Refusal, isHexField, sha256Hex, utf8 } from "./crypto.js";
 import type { ContentRole, Envelope, VerificationResult, VerifyOptions } from "./types.js";
 
 // Fail-closed accepted-profile registry (envelope-spec §2): exactly the
@@ -157,6 +157,18 @@ export function exceedsDepth(value: unknown, max: number): boolean {
   return boundedInput(value, max) === OVER_DEEP;
 }
 
+/**
+ * The bytes an envelope's inline `payload` commits to: `JCS(payload)`. The ONE
+ * place this is spelled: `verifyEnvelope` binds `payload_hash` against these
+ * bytes, and the chain links rule 11 reads (`readChainLinks`) read an inline
+ * record through them, so the binding rule and the linkage rule cannot
+ * disagree about which bytes a record is. Throws where the payload cannot be
+ * canonicalized. The twin is Python's `inline_payload_bytes`.
+ */
+export function inlinePayloadBytes(envelope: { payload: unknown }): Uint8Array {
+  return utf8(jcs(envelope.payload));
+}
+
 // RFC 8785 (JCS) canonicalization. The `canonicalize` package is the reference
 // JS implementation; correctness is pinned by the conformance vectors.
 //
@@ -251,6 +263,87 @@ export function jcsParse(bytes: Uint8Array): unknown {
   return value;
 }
 
+/**
+ * Whether the bytes nest arrays and objects deeper than `max`, read from the
+ * bytes before any parser sees them: the greatest number of `[` and `{` open
+ * at once outside strings. A `"` opens a string and the next `"` no `\`
+ * escapes closes it; a `]` or `}` outside a string closes one open level, if
+ * one is open. Defined for every byte string, JSON or not. The Python twin is
+ * `exceeds_text_depth` in `canonicalize.py`.
+ *
+ * On the bytes because a parser's own limit is its host's: CPython 3.10
+ * stops near 1,000 levels, `JSON.parse` and CPython 3.13 read far deeper, Go's
+ * decoder stops at 10,000 (enclave-attestation section 2.1).
+ */
+export function exceedsTextDepth(bytes: Uint8Array, max: number): boolean {
+  let brackets = 0;
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i]!;
+    if (b === 0x5b || b === 0x7b) brackets++;
+  }
+  if (brackets <= max) return false; // it cannot open more levels than it has brackets
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i]!;
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (b === 0x5c) escaped = true;
+      else if (b === 0x22) inString = false;
+    } else if (b === 0x22) {
+      inString = true;
+    } else if (b === 0x5b || b === 0x7b) {
+      if (++depth > max) return true;
+    } else if ((b === 0x5d || b === 0x7d) && depth > 0) {
+      depth--;
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether a parsed value holds a number no IEEE 754 double holds, at any
+ * depth. `JSON.parse` reads `1e400`, and an integer of 400 digits, as
+ * `Infinity`. Iterative: the value is a producer's. The Python twin is
+ * `has_non_finite_number`.
+ */
+export function hasNonFiniteNumber(value: unknown): boolean {
+  const stack: unknown[] = [value];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (typeof node === "number") {
+      if (!Number.isFinite(node)) return true;
+    } else if (Array.isArray(node)) {
+      for (const child of node) stack.push(child);
+    } else if (typeof node === "object" && node !== null) {
+      for (const child of Object.values(node)) stack.push(child);
+    }
+  }
+  return false;
+}
+
+/**
+ * The deepest a JSON text an enclave reader parses may nest, and the depth
+ * every kernel canonicalizes to (`MAX_CANONICAL_DEPTH`).
+ */
+export const MAX_READ_DEPTH = MAX_CANONICAL_DEPTH;
+
+/**
+ * `jcsParse`, within the reader limits of enclave-attestation section 2.1:
+ * the bytes nest at most `MAX_READ_DEPTH` levels, checked on the bytes first,
+ * and every number in the value is a finite double. Throws past either limit,
+ * and wherever `jcsParse` throws. The Python twin is `jcs_loads_within_limits`.
+ */
+export function jcsParseWithinLimits(bytes: Uint8Array): unknown {
+  if (exceedsTextDepth(bytes, MAX_READ_DEPTH)) {
+    throw new Error(`jcsParseWithinLimits: nests deeper than ${MAX_READ_DEPTH} levels`);
+  }
+  const value = jcsParse(bytes);
+  if (hasNonFiniteNumber(value)) throw new Error("jcsParseWithinLimits: holds a number no double holds");
+  return value;
+}
+
 /**
  * A JSON object that names one member twice (I-JSON, RFC 7493 section 2.3).
  * The Python twin is `DuplicateKey` in `canonicalize.py`, and the message is
@@ -809,7 +902,7 @@ async function verifyEnvelopeChecked(
     const checks: boolean[] = [];
     if ("payload" in env && env.payload !== undefined) {
       try {
-        const recomputed = await sha256Hex(utf8(jcs(env.payload)));
+        const recomputed = await sha256Hex(inlinePayloadBytes(env as { payload: unknown }));
         checks.push(recomputed === env.payload_hash);
       } catch {
         checks.push(false);
@@ -835,16 +928,20 @@ async function verifyEnvelopeChecked(
   // invalidating the primary signature; the field is reserved/default-absent.
   // The corpus has no co-signed vectors, so this strip is pinned by an explicit
   // unit test rather than by conformance.
+  // The refusal names the clause of the Ed25519 rule a signature breaks
+  // (envelope-spec §7, A44), so a forged shape reads differently from a
+  // corrupted byte; an equation that does not hold reads the bare sentence.
   let signatureOk = false;
   try {
     const { signature: _signature, co_signatures: _coSignatures, ...envelopeForSig } = env;
-    signatureOk = await ed25519Verify(utf8(jcs(envelopeForSig)), env.signature, env.public_key);
-    if (!signatureOk) errors.push("Ed25519 signature verification failed");
+    const refusal = await ed25519Refusal(utf8(jcs(envelopeForSig)), env.signature, env.public_key);
+    signatureOk = refusal === null;
+    if (refusal !== null) errors.push(refusal);
   } catch {
     // The sentence the Python kernel writes for the same failure. What was
     // thrown is the host's wording (`jcs: input nesting exceeds ...`), and a
     // public result carries the kernel's own words only (proof#150).
-    errors.push("Ed25519 signature verification failed");
+    errors.push(SIGNATURE_FAILED);
   }
 
   // Check 3 (optional) — Content Bind: the user's bytes match a hash this

package/src/witness-lookup.ts

@@ -20,7 +20,7 @@
 // `witness-cache.json` read as part of the pack rather than as a side file a
 // caller must remember to also pass in.
 
-import { verifyEvidenceBundle } from "./evidence.js";
+import { SIMULATED_WITNESS_KIND, verifyEvidenceBundle } from "./evidence.js";
 import type { WitnessLine, WitnessState } from "./case.js";
 import { WITNESS_NOT_LOOKED_UP, renderWitnessLine } from "./case.js";
 import {
@@ -44,6 +44,12 @@ export interface OnChainRow {
   mismatched: number;
   unreachable: number;
   not_checked: number;
+  /**
+   * How many of the `not_checked` witnesses are simulated: a sandbox plane's
+   * stand-in for a chain, never looked up. Present only where there
+   * is one, so a production pack's row is unchanged.
+   */
+  simulated?: number;
   /** Present only where the pack caches a witness time (5.6.6, v1.25, A30). */
   witness_times?: WitnessTimeRow[];
 }
@@ -97,6 +103,12 @@ export async function onChainHalf(
   packs: readonly (readonly [string, unknown, readonly CachedWitnessTime[]])[],
   gateways: readonly string[],
   options: WitnessLookupOptions = {},
+  /**
+   * Where given, receives for each pack the `stamp_ref` of every stamp whose
+   * witness this lookup confirmed: the run reading evaluates an enclave token
+   * at a stamp's interval end only there.
+   */
+  witnessed?: string[][],
 ): Promise<OnChainHalf> {
   if (gateways.length === 0) return { checked: false, gateways: [], packs: [], verdict: "not_checked" };
   const fetchImpl = options.fetchImpl ?? fetch;
@@ -113,6 +125,9 @@ export async function onChainHalf(
       unreachable: 0,
       not_checked: 0,
     };
+    witnessed?.push(
+      (result.stamps ?? []).filter((st) => st.ok && st.onChain?.rollup === "confirm").map((st) => st.stampRef),
+    );
     for (const w of witnesses) {
       const rollup = w.onChain?.rollup ?? null;
       if (rollup === "confirm") row.confirmed++;
@@ -120,6 +135,8 @@ export async function onChainHalf(
       else if (rollup === "unreachable") row.unreachable++;
       else row.not_checked++;
     }
+    const simulated = witnesses.filter((w) => w.anchorRef?.kind === SIMULATED_WITNESS_KIND).length;
+    if (simulated > 0) row.simulated = simulated;
     // The witness times the pack's witness-cache.json gives, looked up where
     // it gives any (5.6.6, v1.25, A30). A pack with no cache gets no key and
     // no request.

package/vectors/README.md

@@ -214,3 +214,40 @@ tree. One splitting row disagrees with the page on purpose: `record-file-names`
 a record named `__proto__`, which the page's `assemble` loses because it keys
 disclosed content by a plain object. A page that vendors this table fails that
 row until it keys content by a `Map`.
+
+## `sandbox-evidence.json`
+
+What both commands print and exit for a pack whose records are signed
+`environment: "dev"` (envelope-spec §2, where a verifier MAY surface the value
+as `environment_marker`), and what they may claim about a witness a sandbox
+plane simulated. Implemented by [`../src/environment.ts`](../src/environment.ts),
+the `sandboxExit` of [`../src/exit-codes.ts`](../src/exit-codes.ts) and the two
+commands in [`../src/cli.ts`](../src/cli.ts), and asserted against this table by
+[`../test/sandbox-evidence.test.ts`](../test/sandbox-evidence.test.ts) **and by
+the Python kernel against the same bytes**, in `tests/test_sandbox_evidence.py`,
+and through both commands as child processes by `cross-kernel/run_sandbox.sh`.
+Every expectation is written by hand in
+`tools/gen-vectors/gen_sandbox_evidence_table.py`, which writes this file. Two
+of the cases are the real sandbox pack in
+[`../test/fixtures/sandbox/`](../test/fixtures/sandbox/), with its provenance.
+
+**The one thing a consumer must not do with it: print a `dev` pack as
+verified.** The verdict word stays what the checks established; the `verify`
+headline is `SANDBOX` and the `case` title `Sandbox`, the line
+`Sandbox evidence (environment dev): not production evidence` is printed
+wherever the marker is present, and the exit code is 5 where it would be 0, or
+where every record is `dev` and only simulated witnesses are unchecked. A
+failure is still 1, and a production or mixed pack with a simulated witness is
+still 3. And a `simulated` witness, a stamp's or a checkpoint's, is never
+fetched and never counted as checked on a chain. Each case's
+`simulatedSentence` says whether `verify` says "a simulated witness is not on a
+chain, so nothing was looked up": only a run with `--gateways` that counted a
+simulated witness and was not checked on a chain. Both tests assert the
+TypeScript verdict line and the Python `Gateways` line exactly.
+
+Two more members: `stoppedEarly` holds packs whose verification stops before
+any witness is read, each of which must print and write the same with
+`--gateways`, reachable or not, as offline (the Python `Gateways` line names
+the gateways passed); `agentProof` holds an agent proof signed `dev`, which the
+TypeScript `verify` prints as `SANDBOX` with exit 5 and the Python one, which
+implements no agent-proof verifier, refuses with exit 2.