@sanning/proof 0.18.0 → 0.19.0

package/dist/verifier.d.ts

@@ -2,6 +2,17 @@ import type { ContentRole, Envelope, VerificationResult, VerifyOptions } from ".
 export declare const ACCEPTED_SPEC_MAJORS: readonly string[];
 export declare const MAX_CANONICAL_DEPTH = 128;
 export declare function exceedsDepth(value: unknown, max: number): boolean;
+/**
+ * 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 declare function inlinePayloadBytes(envelope: {
+    payload: unknown;
+}): Uint8Array;
 export declare function jcs(value: unknown): string;
 /**
  * Read bytes that claim to be `jcs(value)` (RFC 8785), strictly. The Python
@@ -48,6 +59,38 @@ export declare function jcs(value: unknown): string;
  */
 export declare function utf8Strict(bytes: Uint8Array): string;
 export declare function jcsParse(bytes: Uint8Array): unknown;
+/**
+ * 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 declare function exceedsTextDepth(bytes: Uint8Array, max: number): boolean;
+/**
+ * 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 declare function hasNonFiniteNumber(value: unknown): boolean;
+/**
+ * The deepest a JSON text an enclave reader parses may nest, and the depth
+ * every kernel canonicalizes to (`MAX_CANONICAL_DEPTH`).
+ */
+export declare const MAX_READ_DEPTH = 128;
+/**
+ * `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 declare function jcsParseWithinLimits(bytes: Uint8Array): unknown;
 /**
  * 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

package/dist/verifier.js

@@ -147,6 +147,17 @@ function boundedInput(value, max) {
 export function exceedsDepth(value, max) {
     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) {
+    return utf8(jcs(envelope.payload));
+}
 // RFC 8785 (JCS) canonicalization. The `canonicalize` package is the reference
 // JS implementation; correctness is pinned by the conformance vectors.
 //
@@ -236,6 +247,98 @@ export function jcsParse(bytes) {
     rejectUnpairedSurrogates(value);
     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, max) {
+    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) {
+    const stack = [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) {
+    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
@@ -782,7 +885,7 @@ async function verifyEnvelopeChecked(env, opts) {
         const checks = [];
         if ("payload" in env && env.payload !== undefined) {
             try {
-                const recomputed = await sha256Hex(utf8(jcs(env.payload)));
+                const recomputed = await sha256Hex(inlinePayloadBytes(env));
                 checks.push(recomputed === env.payload_hash);
             }
             catch {

package/dist/witness-lookup.d.ts

@@ -11,6 +11,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[];
 }
@@ -46,7 +52,13 @@ export interface OnChainHalf {
  * instead of a `Cli` stream (`io.fetchImpl ?? fetch`, the same fallback the
  * CLI already applied at its own call site).
  */
-export declare function onChainHalf(packs: readonly (readonly [string, unknown, readonly CachedWitnessTime[]])[], gateways: readonly string[], options?: WitnessLookupOptions): Promise<OnChainHalf>;
+export declare 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>;
 /**
  * `cached` is every witness time the packs cache (5.6.6, v1.25, A30). Where no
  * lookup ran, each is printed labelled not checked. Where one ran, each time

package/dist/witness-lookup.js

@@ -19,7 +19,7 @@
 // one pack (or several) in, one four-state result out, with a pack's
 // `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 { WITNESS_NOT_LOOKED_UP, renderWitnessLine } from "./case.js";
 import { checkWitnessCache, readWitnessCache, renderWitnessTime, } from "./witness-cache.js";
 function witnessTimeRow(t) {
@@ -45,7 +45,13 @@ function witnessTimeRow(t) {
  * instead of a `Cli` stream (`io.fetchImpl ?? fetch`, the same fallback the
  * CLI already applied at its own call site).
  */
-export async function onChainHalf(packs, gateways, options = {}) {
+export async function onChainHalf(packs, gateways, options = {}, 
+/**
+ * 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) {
     if (gateways.length === 0)
         return { checked: false, gateways: [], packs: [], verdict: "not_checked" };
     const fetchImpl = options.fetchImpl ?? fetch;
@@ -62,6 +68,7 @@ export async function onChainHalf(packs, gateways, options = {}) {
             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")
@@ -73,6 +80,9 @@ export async function onChainHalf(packs, gateways, options = {}) {
             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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanning/proof",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "TypeScript kernel of the Sanning verification stack: RFC 8785 (JCS) canonicalization, SHA-256, and Ed25519 verification for Verifiable Event Envelopes. Full-family verifier (inline + external commitment); accepts sanning.agent/v1 and sanning.events/v2. Conformance-gated byte-for-byte against the test-vectors corpus.",
   "license": "MIT",
   "type": "module",

package/src/case-file.ts

@@ -95,7 +95,8 @@ export function howToVerifyText(name: string): string {
     `  sanning-proof case ${name}\n` +
     "\n" +
     "Exit codes: 0 verified, 1 failed, 2 not readable or a usage error,\n" +
-    "3 could not be settled (partial, pending, incomplete, not found), 4 mixed.\n" +
+    "3 could not be settled (partial, pending, incomplete, not found), 4 mixed,\n" +
+    "5 sandbox (records signed environment dev, not production evidence).\n" +
     "\n" +
     "To also look each witness up on the public record, add --gateways <url,url>.\n" +
     "The lookup is reported on its own line and never changes the verdict word.\n" +

package/src/case.ts

@@ -247,12 +247,13 @@ import {
   type DeclarationClaims,
   type DeclarationRole,
   DECLARATION_VERSION,
-  DECLARATION_VERSION_V2,
+  DECLARATION_VERSIONS,
   type PackRecord,
   checkDeclaration,
   declarationClaims,
   packRecords,
 } from "./declaration.js";
+import { readChainLinks } from "./chain.js";
 import {
   type HandoffReading,
   type HeldRecord,
@@ -1516,14 +1517,18 @@ export async function readCase(
     } else if (ungraded) {
       grade = signed.status === "verified" ? "malformed" : (signed.status as PackVerdict);
     } else {
-      check = checkDeclaration(pack.bundle, pack.content);
+      // Rule 11 reads the chain links of the same pack, and the reader reads
+      // only the signed body, so the bare check below takes the same reading
+      // (evidence-bundle.md 5.4.2 v1.36, A45).
+      const chainLinks = await readChainLinks(pack.bundle);
+      check = checkDeclaration(pack.bundle, pack.content, chainLinks);
       const completeness = completenessNotes(pack.bundle);
       full = gradePack(verified, accountDisclosure(pack.bundle, pack.content ?? {}), completeness, check);
       const bareGrade = gradePack(
         signed,
         accountDisclosure(pack.bundle, {}),
         completeness,
-        checkDeclaration(pack.bundle, null),
+        checkDeclaration(pack.bundle, null, chainLinks),
       );
       // NO `failed` HERE RESTS ON BYTES NOBODY SIGNED. The signed grade decides
       // where it is `failed` or `malformed`; a failure only the side map
@@ -2008,7 +2013,9 @@ function declarationVersionOf(bundle: unknown): string | null {
     return null;
   }
   const version = (declaration as Record<string, unknown>)["declaration_version"];
-  return version === DECLARATION_VERSION || version === DECLARATION_VERSION_V2 ? version : null;
+  return typeof version === "string" && (DECLARATION_VERSIONS as readonly string[]).includes(version)
+    ? version
+    : null;
 }
 
 // ---- Presentation (optional) ------------------------------------------------

package/src/chain.ts

@@ -49,13 +49,14 @@
 //
 // (2) is a transitional accommodation, not the design. `metadata` is
 // caller-owned and the profile says a verifier MUST NOT read it for
-// verification — which is exactly why nothing here feeds a verdict. The fix is
+// verification — which is exactly why nothing read through it feeds a
+// verdict, a claimed chain included (rule 11 reads linkage (1) only). The fix is
 // for every adapter to set the record's own `previous_hash` (filed separately
 // against `anchor`); when it lands, the namespace table below stops mattering
 // and can go.
 
 import { hexToBytes, sha256Hex } from "./crypto.js";
-import { jcsParse } from "./verifier.js";
+import { inlinePayloadBytes, jcsParse } from "./verifier.js";
 import { resolveTraceEvents } from "./evidence.js";
 
 /**
@@ -280,7 +281,31 @@ function adapterLinkage(
  * nothing and means a relabelled record DANGLES instead of quietly resolving.
  * That is why this function is async.
  */
-async function groupChains(bundle: unknown): Promise<Group[]> {
+/**
+ * The record an envelope binds, for rule 11's links: `event_bytes` where the
+ * entry carries them, else the inline `payload` read through
+ * `inlinePayloadBytes`, the bytes `payload_hash` binds. Its identity is the
+ * SHA-256 of whichever bytes it is read from. Python's `_bound_record`.
+ */
+function boundRecord(
+  entry: { event_bytes?: unknown; envelope?: unknown } | undefined,
+): { record: EventRecord; bytes: Uint8Array } | null {
+  const eventBytes = entry?.event_bytes;
+  if (typeof eventBytes === "string" && eventBytes.length > 0) return decodeRecord(eventBytes);
+  const envelope = entry?.envelope;
+  if (typeof envelope !== "object" || envelope === null || Array.isArray(envelope)) return null;
+  if (!("payload" in envelope)) return null;
+  try {
+    const bytes = inlinePayloadBytes(envelope as { payload: unknown });
+    const record = jcsParse(bytes) as EventRecord;
+    if (record === null || typeof record !== "object" || Array.isArray(record)) return null;
+    return { record, bytes };
+  } catch {
+    return null;
+  }
+}
+
+async function groupChains(bundle: unknown, inline = false): Promise<Group[]> {
   const groups = new Map<string, Group>();
   const events = eventsOf(bundle);
 
@@ -292,7 +317,11 @@ async function groupChains(bundle: unknown): Promise<Group[]> {
     // event id an adapter pointer has nothing to resolve against.
     if (eventId === null || publicKey === null) continue;
 
-    const decoded = decodeRecord(entry?.event_bytes);
+    // `inline` (rule 11's links only): a record carried as the envelope's
+    // inline `payload` with no `event_bytes` is read too. The chain reading
+    // itself keeps reading `event_bytes` alone, so its findings and its rule
+    // table do not move.
+    const decoded = inline ? boundRecord(entry) : decodeRecord(entry?.event_bytes);
     if (decoded === null) continue;
     const { record, bytes } = decoded;
 
@@ -448,6 +477,54 @@ function findingsFor(group: Group): ChainFinding[] {
   return findings;
 }
 
+/**
+ * One record's place in a chain, as the reader grouped it, for a check that
+ * needs the links themselves rather than the findings: rule 11 of
+ * evidence-bundle.md 5.4.2, which holds a claimed chain to every link. The
+ * twin of Python's `ChainLink`.
+ */
+export interface ChainLink {
+  eventId: string;
+  publicKey: string;
+  chainKey: string;
+  source: ChainSource;
+  namespace?: string;
+  /** The SHA-256 of the record's committed bytes, or its event id for an adapter chain. */
+  selfId: string;
+  /** The pointer the record carries, or `null` where it begins a chain. */
+  prev: string | null;
+  seq: number | null;
+  /** Position in `body.events`. */
+  order: number;
+}
+
+/**
+ * Every record the chain reader places in a chain, in bundle order, with the
+ * identity and pointer it read: the grouping `readChains` reads, over every
+ * record an envelope binds, `event_bytes` or the inline `payload` where no
+ * `event_bytes` travel, with the identity the SHA-256 of those bytes, exactly
+ * as the envelope verifier binds `payload_hash`.
+ */
+export async function readChainLinks(bundle: unknown): Promise<ChainLink[]> {
+  const links: ChainLink[] = [];
+  for (const g of await groupChains(bundle, true)) {
+    for (const m of g.members) {
+      links.push({
+        eventId: m.eventId,
+        publicKey: g.publicKey,
+        chainKey: g.chainKey,
+        source: g.source,
+        ...(g.namespace !== undefined ? { namespace: g.namespace } : {}),
+        selfId: m.selfId,
+        prev: m.prev,
+        seq: m.seq,
+        order: m.order,
+      });
+    }
+  }
+  return links.sort((a, b) => a.order - b.order);
+}
+
 /**
  * Follow every chain the bundle's records describe, and report the links that
  * do not resolve within it.