@sanning/proof 0.7.0 → 0.8.1

package/src/index.ts

@@ -66,6 +66,7 @@ export {
   EXPORT_BODY_TYPE,
   STAMP_BODY_VERSION,
   STAMP_TRACE_BODY_TYPE,
+  STAMP_EVIDENCE_BODY_TYPE,
   disclosedContent,
   recomputeExportVerdict,
   verifyEvidenceBundle,
@@ -98,6 +99,9 @@ export type {
   StampSubtree,
   StampSubtreeResult,
   StampTraceBody,
+  StampEvidenceBody,
+  StampEvidenceEvent,
+  StampEvidenceInclusion,
   TraceCheckpoint,
   TraceCheckpointV1,
   TraceEvent,

package/vectors/README.md

@@ -8,6 +8,24 @@ That distinction is the whole point. A rule that consumers must agree with needs
 a statement they can *fetch*, not one they have to be trusted to have copied
 correctly.
 
+## `stamp-on-chain.json`
+
+The rule that decides what re-fetching a **stamp's witness** from a gateway does
+and does not settle — the optional, online half of `sanning.stamp.trace/v1` and
+`sanning.stamp.evidence/v1` (`evidence-bundle.md` §5.2.4 / §5.3.4). Implemented
+by [`../src/evidence.ts`](../src/evidence.ts) and asserted against this table by
+[`../test/stamp-on-chain-vectors.test.ts`](../test/stamp-on-chain-vectors.test.ts)
+— **and by the Python kernel against the same bytes**, in
+`tests/test_stamp_on_chain_vectors.py`, so neither kernel can pass by agreeing
+with the other.
+
+**The one thing a consumer must not do with it: collapse the four states into a
+boolean.** `not checked` · `confirm` · `mismatch` · `unreachable`. A reader that
+cannot tell the first from the last will report that no gateway could be reached
+on a run that contacted none — a false accusation manufactured by a missing
+state, and the defect this table was written after. Vendoring rules are the same
+three steps as below, against `vectors/stamp-on-chain.json`.
+
 ## `pack-grading.json`
 
 The rule that decides whether a **pack** — a signed bundle plus whatever

package/vectors/stamp-on-chain.json

@@ -0,0 +1,229 @@
+{
+  "rule": "stamp-on-chain",
+  "ruleVersion": 1,
+  "statement": "What re-fetching a stamp's witness from a gateway DOES and DOES NOT settle. A stamp body carries no producer signature and no inclusion proof of its own, so the witness is the entire independent part of it (evidence-bundle.md §5.2.4): confirming that a gateway holds the exact bytes named by anchor_ref is the only check that turns Sanning's own assertion into evidence. It is an ONLINE act and always optional — an offline verdict is unchanged by it and never claims it happened. Four states, never three: not-checked (no gateway was asked, or the stamp names no witness), confirm (a gateway returned the witnessed bytes), mismatch (a gateway returned DIFFERENT bytes — the only outcome that fails anything), unreachable (we asked and nobody answered — an availability gap, never an accusation). The expected bytes are stamps[].stamp_bytes VERBATIM, because §5.2.2 defines that field as the exact bytes handed to the witness; re-canonicalizing them would compare the chain against bytes nobody signed.",
+  "home": "@sanning/proof — ts/vectors/stamp-on-chain.json. This file is the RULE, not a test fixture of one implementation. The TypeScript kernel implements it in ts/src/evidence.ts (refetchStamps / refetchStamp / probeGateway / rollupOnChain) and is held to it by ts/test/stamp-on-chain-vectors.test.ts; the Python kernel implements it in src/sanning_proof/evidence.py (_refetch_stamps / _refetch_stamp / _probe_gateway / _rollup_on_chain) and is held to the SAME file by tests/test_stamp_on_chain_vectors.py. Neither kernel can pass by agreeing with the other.",
+  "consumers": "A surface that re-fetches a stamp witness SHOULD call the kernel's verifyEvidenceBundle with `gateways` rather than derive the rule again. A surface that cannot yet (an older pinned kernel, another language) vendors this file byte-for-byte, asserts its own derivation against it, and runs a drift check against the copy shipped in the @sanning/proof tarball at vectors/stamp-on-chain.json — failing when it cannot find a copy to compare against. A vendored copy that is not byte-identical to this one is a defect, not a variant. In particular: a surface MUST NOT collapse the four states into a boolean. A reader that cannot distinguish not-checked from unreachable will report that no gateway could be reached when none was tried, which is a false accusation manufactured by a missing state, and is the defect this table was written after.",
+  "howToUse": "Each case describes one sanning.stamp.evidence/v1 pack and one set of scripted gateway responses. Build the pack from `packScaffold`: for each entry of `stamps` (index i, 0-based) sign ONE sanning.events/v1 envelope over the record {\"event\":{\"content_hash\":\"<64×a>\"},\"i\":i} with event_id `ev-<i>` and the fixed seed, take its leaf under RFC 9162 (SHA-256(0x00 ‖ JCS(envelope))), make a one-leaf tree, and build the stamp body from `stampBodyScaffold` with merkle_root = that root, leaf_count = 1 and one sub-tree covering [0,1). stamp_bytes is JCS(stamp body) hex-encoded; stamp_ref is SHA-256 of the DECODED bytes. When the entry's `witnessed` is true attach anchor_ref = {kind: \"arweave\", id: `<anchorIdPrefix><i>`}, otherwise omit anchor_ref entirely. Give each stamp one event whose inclusion is {stamp_ref, leaf_index: 0, leaf_count: 1, leaf_hash, audit_path: []}. Wrap the body per `wrapperScaffold`, set body_hash = SHA-256(JCS(body)) and sign the wrapper (minus `signature`) with the same seed. Then call the kernel with the case's `gateways` and a fetch seam that answers `{gateway}/{anchor id}` per the `returns` entry for that stamp at that gateway's index, and assert `expect`. A case with an empty `gateways` list is called with no gateway list at all — that is the not-checked state and it must be reachable without a fetch seam.",
+  "responseKinds": {
+    "witnessed": "The exact decoded stamp_bytes. The honest chain.",
+    "altered": "JCS of the same stamp body with interval_end changed to 2026-09-09T13:00:00.000Z — a well-formed, canonical, semantically different stamp. This is the forgery shape that matters: a pack built on it is fully self-consistent OFFLINE and lies only about what was witnessed.",
+    "reserialized": "The same JSON object re-serialized with 2-space indentation. Semantically identical, byte-different. MUST confirm: a gateway that pretty-prints is a delivery quirk, not a finding.",
+    "notJson": "The bytes `not json at all`. Neither byte-equal nor parseable, so there is nothing to compare structurally — a mismatch.",
+    "unreachable": "The fetch fails: a network error, a timeout, a non-ok response, or no such transaction. Never a mismatch."
+  },
+  "alsoAppliesTo": "sanning.stamp.trace/v1 — the same case, with body_type changed and events[] dropped. Every case's `expect` holds UNCHANGED for that body, and a grader MUST run all of them twice. §5.2 and §5.3 carry the same stamps[] array under the same §5.2.2 definition, so they must give the same on-chain answer: a stamp that can be re-fetched inside one wrapper and not the other forces every consumer to know which wrapper it is holding before it can read `onChain: null`, and that is the kind of per-body exception a reader eventually gets wrong. The one case-level difference is outside this rule: a §5.2 body with no stamps at all is `partial` for carrying nothing, which no case here exercises.",
+  "anchorIdPrefix": "stampOnChainFixtureAnchorId0000000000-",
+  "packScaffold": {
+    "seedHex": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+    "eventIdPrefix": "ev-",
+    "contentHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "signedAt": "2026-09-09T12:00:00Z",
+    "environment": "production"
+  },
+  "stampBodyScaffold": {
+    "stamp_version": "sanning.stamp/v1",
+    "org_ref": "9999999999999999999999999999999999999999999999999999999999999999",
+    "interval_start": "2026-09-09T12:00:00.000Z",
+    "interval_end": "2026-09-09T12:10:00.000Z",
+    "subtreeRef": "1111111111111111111111111111111111111111111111111111111111111111"
+  },
+  "wrapperScaffold": {
+    "spec_version": "sanning.evidence/v1",
+    "body_type": "sanning.stamp.evidence/v1",
+    "issuer": { "kind": "sanning" },
+    "generated_at": "2026-09-09T12:20:00.000Z",
+    "gateway": null,
+    "previous_hash": "GENESIS",
+    "signature_alg": "ed25519"
+  },
+  "cases": [
+    {
+      "id": "not-checked-when-no-gateways",
+      "why": "The default, and the state the other three are defined against. No gateway list means no gateway was asked, so onChain is null — NOT an unreachable result over an empty list. An implementation that reported unreachable here would tell every offline auditor that the chain could not be reached, on a run that never intended to touch it.",
+      "gateways": [],
+      "stamps": [{ "witnessed": true, "returns": [] }],
+      "expect": {
+        "onChainChecked": false,
+        "status": "verified",
+        "exit": 0,
+        "stamps": [{ "rollup": null, "onChainOk": null, "ok": true }],
+        "bundleErrorsContain": []
+      }
+    },
+    {
+      "id": "confirm-single-gateway",
+      "why": "The gateway holds exactly the bytes the bundle says were witnessed. This is the only case in which a stamp bundle has been shown to be more than Sanning's own assertion, and it must still read `verified` — confirming a witness adds evidence, it does not change a verdict that was already sound offline.",
+      "gateways": ["https://g1.example"],
+      "stamps": [{ "witnessed": true, "returns": ["witnessed"] }],
+      "expect": {
+        "onChainChecked": true,
+        "status": "verified",
+        "exit": 0,
+        "stamps": [
+          { "rollup": "confirm", "onChainOk": true, "ok": true, "perGateway": ["confirm"] }
+        ],
+        "bundleErrorsContain": []
+      }
+    },
+    {
+      "id": "mismatch-fails-the-stamp",
+      "why": "THE case this capability exists for. The pack is internally perfect — wrapper signed, stamp_ref derived from its own bytes, those bytes JCS-canonical, the event's RFC 9162 path reconstructing the committed root — and verifies `verified` offline. The chain holds different bytes. Only a re-fetch can tell, and it must fail the stamp rather than note it: a stamp whose witness contradicts it is not partially witnessed, it is contradicted. An implementation whose byte comparison cannot fail passes every other case in this table and this one alone.",
+      "gateways": ["https://g1.example"],
+      "stamps": [{ "witnessed": true, "returns": ["altered"] }],
+      "expect": {
+        "onChainChecked": true,
+        "status": "failed",
+        "exit": 1,
+        "stamps": [
+          {
+            "rollup": "mismatch",
+            "onChainOk": false,
+            "ok": false,
+            "perGateway": ["mismatch"],
+            "errorContains": "do not match the stamp's witnessed bytes"
+          }
+        ],
+        "bundleErrorsContain": []
+      }
+    },
+    {
+      "id": "unreachable-is-undetermined-not-failed",
+      "why": "A gateway that does not answer has told us NOTHING about the evidence, and a verifier that turns silence into an accusation is the exact failure the anchor_ref vocabulary was designed around. Undetermined: the offline-sound stamp stays ok, the run drops to `partial`, and the exit code is 3 — a retry, not a finding.",
+      "gateways": ["https://g1.example"],
+      "stamps": [{ "witnessed": true, "returns": ["unreachable"] }],
+      "expect": {
+        "onChainChecked": true,
+        "status": "partial",
+        "exit": 3,
+        "stamps": [
+          {
+            "rollup": "unreachable",
+            "onChainOk": null,
+            "ok": true,
+            "perGateway": ["unreachable"],
+            "errorContains": "unreachable on all gateways"
+          }
+        ],
+        "bundleErrorsContain": ["could not be re-fetched from the supplied gateways"]
+      }
+    },
+    {
+      "id": "mismatch-beats-confirm",
+      "why": "Worst-finding-wins. One gateway serving the right bytes does not answer the other one serving different bytes — a disagreement between gateways about a permanent record is itself the finding, and the honest reading is the accusing one. The per-gateway array is retained so a reader can see WHICH gateway disagreed rather than only that one did.",
+      "gateways": ["https://g1.example", "https://g2.example"],
+      "stamps": [{ "witnessed": true, "returns": ["altered", "witnessed"] }],
+      "expect": {
+        "onChainChecked": true,
+        "status": "failed",
+        "exit": 1,
+        "stamps": [
+          {
+            "rollup": "mismatch",
+            "onChainOk": false,
+            "ok": false,
+            "perGateway": ["mismatch", "confirm"]
+          }
+        ],
+        "bundleErrorsContain": []
+      }
+    },
+    {
+      "id": "confirm-beats-unreachable",
+      "why": "Best-evidence, once nothing has contradicted anything. One gateway being down is an availability fact about that gateway; another gateway returning the witnessed bytes is a fact about the record. The record wins, and the run is not downgraded for the outage — otherwise every auditor with one stale gateway in their list would read `partial` on fully witnessed evidence.",
+      "gateways": ["https://g1.example", "https://g2.example"],
+      "stamps": [{ "witnessed": true, "returns": ["unreachable", "witnessed"] }],
+      "expect": {
+        "onChainChecked": true,
+        "status": "verified",
+        "exit": 0,
+        "stamps": [
+          {
+            "rollup": "confirm",
+            "onChainOk": true,
+            "ok": true,
+            "perGateway": ["unreachable", "confirm"]
+          }
+        ],
+        "bundleErrorsContain": []
+      }
+    },
+    {
+      "id": "unwitnessed-stamp-is-not-checked-never-unreachable",
+      "why": "A stamp with no anchor_ref names no witness, so there is nothing to ask any gateway for. onChain stays null — not-checked — even though gateways were supplied and every one of them is reachable. Reporting all-unreachable here would invent a network event that did not occur, and would move this pack's exit code from 0 to 3 purely because the caller passed a gateway list. The bundle is already `partial` for the right reason, said in the right words, by §5.2.4.",
+      "gateways": ["https://g1.example"],
+      "stamps": [{ "witnessed": false, "returns": ["witnessed"] }],
+      "expect": {
+        "onChainChecked": true,
+        "status": "partial",
+        "exit": 0,
+        "stamps": [{ "rollup": null, "onChainOk": null, "ok": true }],
+        "bundleErrorsContain": ["sealed by Sanning, witnessed by nobody"]
+      }
+    },
+    {
+      "id": "reserialized-body-still-confirms",
+      "why": "A gateway that re-serializes JSON on the way out has changed the delivery, not the record. The byte compare fails and the structural compare — JCS of what came back against the witnessed bytes — succeeds, so this is a confirm. Without the structural fallback every pretty-printing gateway would read as a tampered record, which is a false accusation with an operational cause.",
+      "gateways": ["https://g1.example"],
+      "stamps": [{ "witnessed": true, "returns": ["reserialized"] }],
+      "expect": {
+        "onChainChecked": true,
+        "status": "verified",
+        "exit": 0,
+        "stamps": [
+          { "rollup": "confirm", "onChainOk": true, "ok": true, "perGateway": ["confirm"] }
+        ],
+        "bundleErrorsContain": []
+      }
+    },
+    {
+      "id": "not-json-is-mismatch-not-unreachable",
+      "why": "The gateway answered — so this is not an availability gap — and what it returned is neither the witnessed bytes nor anything that canonicalizes to them. The structural fallback must not swallow the failure to parse into a shrug: a witness id that resolves to something which is not this stamp is a finding, and filing it as unreachable would let a substituted record read as a temporary outage.",
+      "gateways": ["https://g1.example"],
+      "stamps": [{ "witnessed": true, "returns": ["notJson"] }],
+      "expect": {
+        "onChainChecked": true,
+        "status": "failed",
+        "exit": 1,
+        "stamps": [
+          {
+            "rollup": "mismatch",
+            "onChainOk": false,
+            "ok": false,
+            "perGateway": ["mismatch"],
+            "errorContains": "do not match the stamp's witnessed bytes"
+          }
+        ],
+        "bundleErrorsContain": []
+      }
+    },
+    {
+      "id": "two-gaps-are-two-notes",
+      "why": "One stamp witnessed but unreachable, one stamp never witnessed. Both hold the bundle at `partial` and both get SAID. They have different causes and different fixes — one waits for the network, the other for the interval to close — and an auditor told only about the gateway would read the unwitnessed stamp as fine. The per-stamp results keep them apart too: the first carries an unreachable rollup, the second carries null.",
+      "gateways": ["https://g1.example"],
+      "stamps": [
+        { "witnessed": true, "returns": ["unreachable"] },
+        { "witnessed": false, "returns": ["witnessed"] }
+      ],
+      "expect": {
+        "onChainChecked": true,
+        "status": "partial",
+        "exit": 3,
+        "stamps": [
+          {
+            "rollup": "unreachable",
+            "onChainOk": null,
+            "ok": true,
+            "perGateway": ["unreachable"],
+            "errorContains": "unreachable on all gateways"
+          },
+          { "rollup": null, "onChainOk": null, "ok": true }
+        ],
+        "bundleErrorsContain": [
+          "could not be re-fetched from the supplied gateways",
+          "sealed by Sanning, witnessed by nobody"
+        ]
+      }
+    }
+  ]
+}