@sanning/proof
v0.20.3
Published
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.events/v2. Conformance-gated byte-
Readme
@sanning/proof
Verify Sanning evidence-plane provenance records, with no Sanning code or service in the trust path.
This is the TypeScript verification kernel for the Verifiable Event Envelope family: the signed JSON records that Sanning's SDKs anchor permanently to Arweave. Given an envelope (fetched from any AR.IO gateway: a gateway that serves Arweave data over HTTP; any gateway that serves the transaction works), this package answers: is it authentic, and does it commit to the bytes I'm holding?
- RFC 8785 (JCS) canonicalization
- SHA-256 payload binding (WebCrypto)
- Ed25519 signature verification (
@noble/ed25519) - RFC 9162 binary Merkle inclusion proofs (checkpoint leaves)
- Zero config, two small dependencies, ESM, browser + Node ≥ 20
Install
npm install @sanning/proofVerify an envelope
Fetch the raw transaction from any AR.IO gateway and verify it client-side:
import { verifyEnvelope } from "@sanning/proof";
const env = await (await fetch("https://gateway.example/raw/<tx_id>")).json();
const result = await verifyEnvelope(env);
result.ok; // spec_version + payload_hash + Ed25519 all passed
result.signatureOk; // Ed25519 over the signed scope, against env.public_key
result.payloadHashOk; // SHA-256(JCS(payload)) === env.payload_hash
result.errors; // [] when ok: machine-readable reasons otherwiseverifyEnvelope never throws on hostile input: a malformed envelope (or a lying gateway) yields ok: false with reasons, not an exception.
Bind an envelope to bytes you hold (reverse provenance)
The check that defeats a lying gateway: Arweave tags are unsigned search hints, so after finding a candidate envelope, confirm it actually commits to your artifact's hash:
import { sha256Hex, verifyEnvelope, contentHashes } from "@sanning/proof";
const myHash = await sha256Hex(fileBytes); // 64-char lowercase hex
const result = await verifyEnvelope(env, { expectedContentHash: myHash });
result.contentHashOk; // true ⇔ the envelope commits to exactly these bytes
result.contentRole; // how it commits: e.g. the registered baseline,
// an observed (tampered) hash, …
contentHashes(env); // all content hashes an envelope commits to, by event typeVerify a whole trace bundle: one command
npm install -g @sanning/proof puts sanning-proof on your path, the same name pip install sanning-proof does. npx @sanning/proof <command> runs it without installing.
The @sanning/anchor SDK hands a producer a set of InclusionReceipts and can serialize them into one portable, self-verifying sanning.evidence/v1 bundle (body_type: sanning.anchor.trace/v3). Verify the entire bundle (every event's signature + payload binding + Merkle inclusion, all offline) with the bundled CLI:
npx @sanning/proof verify trace-bundle.json
# also re-fetch each checkpoint on-chain to confirm it's anchored:
npx @sanning/proof verify trace-bundle.json --gateways https://gateway-a.example,https://gateway-b.exampleIt prints the person layer first (a verdict of Verified, Failed or Incomplete, one line per claim that is disproven or not proven, the next action, the notes, the sandbox line and the witness line), then the detail, and exits by the one table every verb uses: 0 verified · 1 failed (a claim is disproven: a bad signature, a tamper, a broken inclusion, a record that does not follow its vocabulary) · 2 incomplete (nothing is disproven and a claim is not proven: a stamp no witness published, a record nobody hashed, or a pack the grading rule calls incomplete) · 3 sandbox: the verdict is verified and a record is signed environment: "dev" · 4 could not run (a bad flag, a missing file, or an input that is not a pack or a case at all). A failed verdict carries a reason kind in --json: nonconforming where an agent record is signed and intact and breaks its vocabulary and no other claim is disproven (a producer's error, nothing proven altered), changed otherwise; both exit 1. Sandbox is a label, never a verdict: a pack holding a record signed dev keeps its verdict word, the line Sandbox: these records are sandbox records, not production evidence. is printed, --json carries environment_marker (dev or mixed), and a run that would exit 0 exits 3; a failure is still 1 and an incomplete run 2. For a production pack environment_marker is absent and no sandbox line prints. The headline is the pack verdict, the same one gradePack gives the browser verify page: a record nobody hashed leaves the pack incomplete even when the signed bundle itself is verified, and both verdicts are printed when they differ. Only arweave witnesses are re-fetched: a checkpoint or stamp whose anchor_ref.kind is anything else is not looked up, the witness line says so, and the verdict and the exit code do not move (only a lookup that finds other bytes or another time moves one, to 1). A sandbox plane's simulated witness is never fetched and never counted as checked on a chain: where it is the only witness, the report says nothing was looked up and --json writes "on_chain_checked": false. A bundle carries no verdict: the verdict is always recomputed from the body, and a wrapper verdict member, where an older producer wrote one, is never read.
The command is
npx @sanning/proof verify <bundle> [--gateways <url,url>], andverifyEvidenceBundleis the programmatic API.
Programmatically:
import { verifyEvidenceBundle } from "@sanning/proof";
const bundle = JSON.parse(await fs.readFile("trace-bundle.json", "utf8"));
const result = await verifyEvidenceBundle(bundle, { gateways: ["https://gateway.example"] });
result.status; // "verified" | "failed" | "incomplete" (recomputed)
result.signatureOk; // wrapper Ed25519 signature
result.bodyHashOk; // body_hash === SHA-256(JCS(body))
result.checkpoints; // per-checkpoint envelope / merkle-root / on-chain results
result.events; // per-event signature / payload-binding / inclusion resultsA withheld event_bytes (external commitment, record not disclosed) leaves that event's payload binding not proven, surfaced, never failed (the bundle stays cryptographically sound).
…including the raw logs, when the holder discloses them
The checks above prove the stamps. To also confirm a holder's raw logs are the bytes whose hash was anchored, the verifier closes the final rawLog → content_hash link: SHA-256(disclosed bytes) must equal the content_hash the event's record committed to.
A bundle a producer built with disclosure carries the bytes in the signed body (events[].content), so they're checked automatically: no flag, and the disclosure is itself covered by the wrapper signature:
npx @sanning/proof verify trace-bundle.json # in-body content verified inlineIf the logs travel alongside a minimal bundle instead, pass them with --logs. It takes either shape below, and which one you passed is determined by stat, never by the extension.
A materialized pack: a DIRECTORY. materializeBundle (in @sanning/anchor) writes bundle.json + logs/<event_id>.json, and each file's raw bytes are the disclosure. Point --logs at that directory and the pack verifies with nothing of ours in the path:
npx @sanning/proof verify pack/bundle.json --logs pack/logsNothing is decoded, re-parsed or re-serialised on the way in: the bytes on disk are the bytes hashed against the committed content_hash: the same bytes a verify page hashes from the same files. That is the whole point of the directory form. The alternative (reading the directory and hex-encoding it into a map yourself) is a step that has been got wrong twice in shipped code, once by writing the hex text into the log files, so SHA-256(file) was the hash of the encoding rather than of the bytes and genuine, untampered evidence failed.
A side input: a JSON FILE mapping event_id → bytes, where an even-length hex value, in either case, is read as hex and anything else as UTF-8 text:
npx @sanning/proof verify trace-bundle.json --logs logs.jsonEmit hex, not text, into that map: a UTF-8 decode is lossy for a non-text payload, and a log line that happens to look like hex would be decoded into something the producer never wrote. logsSideInput in @sanning/anchor builds the map correctly.
The directory form's edge cases, none of which is a verification failure, an absent disclosure is not evidence of tampering:
| Situation | What happens |
|---|---|
| A record with no file | That event's content is not proven (~) and reported as undisclosed. Exit code unchanged. |
| An empty directory | Valid. Discloses nothing and says so. The exit code is whatever the pack reads with no --logs at all, which for a pack holding any undisclosed record is 2, not 0. |
| A file whose name is no event id | Read, binds to nothing, and is named in a note: a typo'd filename is otherwise indistinguishable from minimal disclosure. |
| A subdirectory | Skipped, never recursed: the layout is flat. Noted. |
| Anything not named <event_id>.json, or not a regular file | Skipped, noted. |
| A file we selected but cannot read | Exit 4. We were pointed at it, so a permissions or broken-link problem must not read as minimal disclosure. |
Either way each event gains a contentOk: true match · false mismatch (the event and the rollup fail, exit 1) · null not proven, nothing disclosed, or no committed content_hash (a withheld record); never a failure, mirroring the payload-binding rule. The CLI prints a logs ✓/✗/~ mark per event and a logs: N/M record(s) content-verified line, where M is the records in the PACK and not the records that happened to disclose bytes: a pack disclosing two of three reads 2/3, not the full score 2/2.
Programmatically the same side input is content, keyed by event_id: a Uint8Array is used as-is, a string is hex. Prefer a Map:
const result = await verifyEvidenceBundle(bundle, {
content: new Map([[eventId, rawLogBytes]]), // Uint8Array, or a hex string
});
result.events[0].contentOk; // true | false | nullA plain object still works and is fully guarded on the way in. But an event_id is producer-chosen, and on a plain object the names that live on Object.prototype are not free: content["__proto__"] = bytes does not store anything: it replaces the object's prototype, and the bytes you meant to disclose are lost before the verifier ever sees them. If you are building the map from names you did not choose (a directory listing, a JSON key, an id off the wire) use a Map (or Object.create(null)). It is also what disclosedContent hands back, so its output feeds straight back in.
In-body events[].content (signed) takes precedence over the side input; if both are present for an event and disagree, the event fails.
…and get those raw logs back out (ingest)
events[].content rides as lowercase hex, JSON cannot carry arbitrary bytes. To materialize a received bundle's logs (serve them, write pack files, hand them on), use disclosedContent rather than decoding that field yourself:
import { disclosedContent } from "@sanning/proof";
const result = await disclosedContent(bundle); // verifies, then decodes
for (const [eventId, bytes] of result.content) {
await writeFile(`logs/${eventId}.json`, bytes); // Uint8Array: write it as-is
}Verify-then-return: disclosedContent runs the full verifyEvidenceBundle (same options) and hands back bytes only for events whose chain verified and whose disclosed bytes hash to the committed content_hash. There is no path through it that yields bytes that are not the committed ones, and result.verification carries the whole EvidenceBundleResult, so you verify once and render the verdict from the same call.
Every event also appears in result.events, in body order, with a status that never lets "nothing was disclosed" pass for "empty":
| status | bytes | Meaning |
|---|---|---|
| verified | the bytes | Decoded and bound to the committed content_hash: safe to write as-is. May be zero-length: an empty payload is real, verifiable content. |
| not_disclosed | null | Minimal disclosure: the hash was committed, the bytes were not shared. Nothing to write, and not an error. |
| undetermined | null | Bytes were disclosed but there is nothing to bind them to (withheld record, or no committed content_hash). Withheld rather than returned. |
| failed | null | The event's own proof chain failed, or the disclosure did not bind or did not decode. errors says which. |
Bytes come back as Uint8Array, never a string: the spec commits to raw bytes, and a UTF-8 decode is lossy for any payload that is not valid UTF-8, re-encoding such a string would change the bytes and break the hash. Decode to text yourself if you know your payload is text.
Check the files that came with a pack
A pack proves what its records signed. To ask whether it vouches for the files
you were handed beside it, such as a screenshot, a report or an export, name
them after --files. Each file is hashed with SHA-256 and looked up among what
the pack's signed records commit to. A folder stands for every regular file
inside it, so one argument covers a whole download on any operating system,
the Windows command prompt and PowerShell included (they do not expand a
wildcard such as evidence/*, and this command does not either):
npx @sanning/proof verify pack/bundle.json --logs pack/logs --files evidence/The report lists the files the pack vouches for, the files that match no record and the commitments no file was offered for. A match is by hash alone: file and folder names are never compared, and the verdict and the exit code never move.
- A folder is read recursively, and hidden files count. Its files are listed as
<folder>/<path inside>in UTF-16 code unit order of that path, so both kernels print one list in one order. Files and folders can be mixed in one command. - A symbolic link inside a folder is never followed. It is listed as skipped, with the reason, as is anything that is not a regular file (a pipe, a socket) and a file or folder the command cannot read. Nothing is dropped without being named, and a skipped file is not a verdict about it.
- Two files with one hash are both listed, each under its own name. An empty
file is an ordinary file with the empty digest. A file is read in
pieces and hashed, so it is never held in memory. A file you name yourself is
read at any size; the files found inside folders share 1 GiB per run, the cap
the
.zipreader uses, and one that would push past it is listed as skipped (too_large) and not read, so a sparse file of a terabyte cannot hold the command.casebounds its other reads of files on disk as well; the section oncaselists them. - A folder nested more than 32 levels deep, one holding more than 50,000 files
and folders, or one with a name that is not valid UTF-8, exits 4, as
casedoes. A path that is not a readable file or folder exits 4.
Read several packs together: a case reading
When a case spans more than one pack (two agents, two organizations, one hand-off between them), check the packs together. This is readCase from a terminal, with no page in the way:
npx @sanning/proof case audit-file.zip # a whole download, one command
npx @sanning/proof case assessor-pack/ challenger-pack/
npx @sanning/proof case case/ --json # the full reading, for a scriptEach argument is a folder, or a case file named as a .zip. A folder is one pack (bundle.json plus logs/), or a folder that holds several packs, such as an unzipped folder of packs. A .zip is read as the folder unzip <name>.zip -d <name> would make, so the archive and its unpacked folder give one reading, with no unzip step and on any operating system. A .zip inside a folder is a file like any other: it is hashed, never unzipped. Packs are found by the verify page's splitting rule, so the page and this command apply the same rule to the same unpacked tree: every bundle.json is a pack, a file belongs to the deepest pack whose bundle.json or logs/ it sits in, and every other file is listed as outside every pack and is never read as part of a pack. Several folders are read as one folder holding them, each under its own name. Each bundle.json is read with verify's own reader (readBundleBytes), so the two commands classify one bundle the same way.
The files outside every pack are checked too, with no flag. A download usually holds more than packs: a screenshot, a report, an export. case hashes each file that sits outside every pack, with SHA-256 over its exact bytes, and looks the digest up among what every pack's signed records commit to, the same check verify --files makes. The report lists each as vouched for, naming the record and its pack, or as matching no record:
npx @sanning/proof case audit-file.zipThis is information beside the case reading and never inside it: the verdict, the exit code and the summary are the same whether a file matches or not, and a changed file reads as no match, nothing more. A match is by hash alone, so no name or folder is compared. Files after --files are offered as well. Each file that cannot be hashed, such as a link, a pipe, a zip entry the reader refused (with the reader's own words) or a file that cannot be read, is listed as skipped with the reason, so every file outside a pack is matched, unmatched or skipped. Two files with one hash are both listed; an empty file is an ordinary file; a file is read in pieces. The files share 1 GiB in all, the cap the .zip reader uses: one that would push past it is listed as skipped (too_large) and not read, so a sparse file of a terabyte in a download cannot hold case at that step. Every other read case makes of a file on disk is bounded too, so a sparse file of a terabyte can neither stall case nor exhaust its memory. The index comparison hashes every file under packs/ and report/ in pieces, within its own 1 GiB, the files the index lists first, and a listed file it has no room left for is reported as case_index_file_too_large, never as a match and never as absent. A pack's own files (bundle.json, logs/), contents.json and witness-cache.json are read whole within one 1 GiB total across the run: a pack's own file with no room left exits 4 at once, naming the file (the words say the run's total is used up, not that the file is itself over 1 GiB), a contents.json with no room left reads as an unreadable index (case_index_unreadable), and a witness-cache.json with no room left reads as no cache, with a note line saying so. A .zip larger than 1.25 GiB on disk exits 4 before it is read. A file outside every pack, contents.json and witness-cache.json included, therefore never keeps case from its verdict, and one a pack owns, or an archive that large, is refused promptly instead. Without --files the report lists each file read and then one line, N recorded commitment(s) matched no loose file and no log in their own pack, with no line for each record; --files and --json list every commitment no file matched, those the count leaves out included. The section is printed when a file sits outside every pack or --files is given, so a case with neither prints what it printed before, and the files member of --json follows the same rule.
The walk is bounded and follows no link. A symbolic link is never followed: it is listed as outside every pack and not read, even under a pack's logs/, and a link named on the command line exits 2. A folder nested more than 32 levels deep, more than 50,000 files and folders in all, or a name that is not valid UTF-8 exits 2; a bad name is refused rather than escaped, because two different names would then read as one. A bundle.json nested more than 512 levels deep exits 2, from case and from verify alike. The rules are pinned for both kernels by vectors/case-split.json, shipped in this tarball, as directory trees.
Known differences from the verify page: the page opens a dropped .zip; the page drops a leading byte-order mark from bundle.json, which verify's reader refuses; the page reads whatever the browser hands it for a link, a bad name or a very deep tree; and the page loses a record named __proto__, which this command keeps.
The first lines are the person layer, which opens with the case verdict, then come the kernel's summary and every exception through renderException, then the packs, the files outside them, and the on-chain half. A case reads its worst pack: failed, then incomplete, then verified. Exit codes: 0 verified · 1 failed (either reason kind; a proven failure keeps the headline) · 2 incomplete · 3 sandbox (the verdict is verified and a pack holds a record signed environment: "dev") · 4 could not run (a bad flag, a missing file, an input that cannot be read as a case, or an unexpected error in the command). This is the one table every verb uses (EXIT_CODES, exported from the package root).
A case reading establishes that every pack verified offline, that every record every pack supplied was read in one pile under envelope-spec section 4.1's hand-off rules, and that a hand-off record with no counterpart is always named. It does not establish that the case is complete, that a party which presented no pack under the named key recorded nothing, that two organizations are independent, or that any witness was re-fetched on chain: the witness line reads Not checked unless you pass --gateways <url,url>. With gateways, each pack's witnesses are re-fetched pack by pack and reported beside the reading, which they never change; a witness that does not match exits 1, and a lookup that could not be settled moves nothing.
The Python kernel ships the same command as sanning-proof case, and cross-kernel/run_case_cli.sh requires the two to print the same bytes, the same --json and the same exit code over every case/ corpus vector and every tree in vectors/case-split.json.
Compose an attested export
An attested export (sanning.evidence.export/v2) carries operator attestations over a source bundle, signed with your own Ed25519 key. composeExport is the programmatic API:
npx @sanning/proof export source.json --attestations attestations.json --key exporter.key --out export.json
npx @sanning/proof verify export.jsonexport exits 0 when it wrote the export, 1 when the recomputed export is failed (it still writes it, so you can inspect it), and 4 on a bad flag or an input that is not a bundle at all. The Python kernel ships the same command as sanning-proof export.
Verify a Merkle inclusion proof
Agents close daily checkpoints over per-cycle leaves (RFC 9162, section 2.1 domain separation, not the Bitcoin duplicate-leaf variant). Verify a leaf's inclusion against an anchored root:
import { leafHash, verifyInclusion, hexToBytes } from "@sanning/proof";
const ok = await verifyInclusion(
await leafHash(leafBytes), // Uint8Array leaf hash
leafIndex, // 0-based position
totalLeaves,
auditPath.map(hexToBytes), // sibling hashes, leaf → root
hexToBytes(expectedRootHex),
);API
| Export | What it does |
|---|---|
| verifyEnvelope(env, options?) | The three load-bearing checks (spec-version registry, payload-hash recompute, Ed25519 over the signed scope) + optional content bind. Pass { payloadBytes } for external-commitment envelopes, { expectedContentHash } for the content bind (a bare string is refused), and { acceptedSpecMajors } to narrow the accept-set for one call. Returns VerificationResult, whose fault says why ok is false (ENVELOPE_FAULTS: not_an_envelope, key_unreadable, signature_failed, payload_unbound, spec_version_unknown, nonconforming); ENVELOPE_FAULT_KINDS maps each to the kind, claim and state a pack reads (envelope-spec section 2). |
| verifyEvidenceBundle(bundle, { gateways?, fetchImpl? }) | Verify a signed sanning.evidence/v1 bundle (sanning.anchor.trace/v3, sanning.stamp.trace/v1, sanning.stamp.evidence/v2 or sanning.evidence.export/v2): wrapper signature + body_hash + every checkpoint + every event's inclusion, offline (optional on-chain re-fetch). Returns EvidenceBundleResult. Powers the npx @sanning/proof verify CLI. |
| disclosedContent(bundle, { gateways?, content?, fetchImpl? }) | Ingest: verify a bundle, then hand back the DECODED raw bytes (Uint8Array) of every event whose disclosure bound to its committed content_hash, so materializing a received pack never means re-implementing the hex convention. Returns DisclosedContentResult (content map + per-event verified / not_disclosed / undetermined / failed, plus the full verification). |
| gradePack(result, account, notes) + accountDisclosure(bundle, content) / completenessNotes(bundle) / renderCause(cause) | Pack grading: what a SURFACE may claim about a pack: the bundle plus whatever disclosed bytes travelled with it. verified only when every record's own bytes bound to its own commitment, nothing is missing, unreadable, surplus or omitted, and every agent record reads verified; failed where a claim is disproven (a proven mismatch, or an agent record that breaks its vocabulary, which carries the reason kind nonconforming where nothing else is disproven); incomplete where a claim is not proven. Absent evidence is not proven, never an accusation. Pure: no I/O; transport stays yours. Conformance table: vectors/pack-grading.json, shipped in this tarball. |
| readAgentRecord(record) / readAgentRecordWithHeld(subject, held) | Read one agent.* event record (agent-events.md section 10 of the pinned sanning-io/specs release): steps 1 to 6 alone, or steps 1 to 7 with the records you hold beside it. The schemas ship inside the package (AGENT_SCHEMA_VERSIONS, pinned by AGENT_SCHEMA_PIN); nothing is read from disk or fetched. Returns { verdict, reason?, at?, reasons?, findings }: verified; failed or incomplete with every reason and its JSON Pointer in step order (reasons; reason and at are the first), incomplete for a vocabulary version this build does not know or a listed record not held (never verified); or null for a record outside the vocabulary (which reads failed, bad_value, at /context/salt where its salt is not 32 lowercase hex characters). AGENT_EVENT_TYPES is the closed type set per version. Conformance table: vectors/agent-record.json. |
| readAgentRecords(items) / renderAgentReading(reading) | The reading verify, case and verifyEvidenceBundle wire in, over every sanning.events/v2 record. readAgentRecords reads each item of a pile through steps 1 to 7 with every item held beside it: a type outside the closed set reads failed, and null is the reading of one of the seven types outside the vocabulary with no event_schema and no context.salt in the wrong form. The bundle verifier puts each reading on EventResult.agent, over the pack; readCase reads every pack of the case as one pile and puts it on records[].agent. gradePack (rule version 9, vectors/pack-grading.json) turns each reason of an agent record that is not verified into a cause: agent_record_nonconforming for a reason that reads failed (the pack is failed, reason kind nonconforming) and agent_record_incomplete for one that reads incomplete; a finding never moves the verdict. A hand-off record that reads failed makes the record it pairs with read counterpart_nonconforming. |
| contentHashes(env) | The content hash(es) an envelope commits to, by event type: the reverse-provenance join keys. |
| specVersionSupported(v) | Fail-closed accept-check: sanning.events/v2 and additive minors (sanning.events/v2.<n>). Unknown majors and profiles, the retired sanning.agent/v1 among them, are rejected. |
| jcs(value) | RFC 8785 canonical JSON bytes. |
| sha256Hex(bytes) / sha256Bytes(bytes) | SHA-256 via WebCrypto. |
| ed25519Verify(message, signatureHex, publicKeyHex) | Raw Ed25519 verification, strict RFC 8032 (zip215: false). The message comes first, as in the Python ed25519_verify. |
| leafHash / nodeHash / merkleRoot / auditPath / verifyInclusion / EMPTY_TREE_ROOT_HEX | RFC 9162 binary Merkle tree primitives. |
| utf8 / bytesToHex / hexToBytes | Encoding helpers. |
| Envelope / VerificationResult / ContentRole / Subject | Types. |
Signed scope
The primary signature covers JCS(envelope minus signature minus co_signatures) (specs/envelope-spec.md sections 2 and 7.1, in the source repository). The reserved co_signatures carve-out lets countersignatures be added later without invalidating the primary signature.
Why you can trust it (without trusting us)
Two independent implementations of this kernel exist: this package and the Python sanning-proof (PyPI). They are conformance-gated byte-for-byte in CI against one shared corpus, pinned per file by SHA-256 at the newest cut tag, test-vectors-v5.1, named in test-vectors/CORPUS-v5.md, and a cross-kernel agreement gate re-runs the corpus plus adversarial negatives through both, asserting identical verdicts on identical bytes.
That mutual gate is the point: anyone can verify these provenance records with no Sanning code in the trust path, write your own verifier against the specs in the source repository, and the corpus will tell you if it is conformant.
What this package deliberately does NOT do
- No I/O, ever. Including in
gradePack: it takes an account of what was disclosed, it does not go and read a directory. How a pack reached you is yours. - Single-envelope scope. Chain walking (
previous_hash), checkpoint reconciliation, and gateway/transport logic are consumer-layer concerns composed above the kernel. - Provenance is history, not endorsement. A verified envelope proves these bytes have this signed, anchored history, never "safe," "approved," or "currently in production."
- Key identity is out-of-band. The kernel proves the signature matches
env.public_key; binding that key to a real-world identity is yours to establish.
Requirements
ESM-only. Needs WebCrypto (globalThis.crypto.subtle): any modern browser, Node.js ≥ 20 (≥ 19 works), Deno, Bun, workers.
License
MIT, verification must be open.
