verifyhash 0.1.0

package/docs/PROOFPARCEL.md

@@ -0,0 +1,227 @@
+# ProofParcel — B2B data-delivery receipts
+
+ProofParcel turns a data hand-off between two parties into a **portable, independently-verifiable
+proof-of-delivery receipt**: a tamper-evident manifest that pins **exactly which files (names AND
+bytes) were delivered** for a parcel, plus a signable attestation over that parcel's identity. It is a
+**thin adapter over the same path-bound Merkle + signed-attestation core** as
+[DataLedger](DATALEDGER.md) (`cli/parcel.js` consumes `cli/core/manifest.js` and
+`cli/core/attestation.js`), so every claim it makes is independently re-derivable.
+
+Every ProofParcel command is **offline, needs NO private key, and needs NO network**. You can hand a
+manifest, a verify result, an attestation, or a signed container to the other party and they can
+re-derive the result on an air-gapped machine with only the `vh` CLI — they do not have to trust your
+server, your build machine, or you.
+
+> **Read this first:** the trust posture below is the SAME wording carried in-band in every artifact
+> (`cli/parcel.js` › `TRUST_NOTE` / `PARCEL_TRUST_NOTE`, shared verbatim with DataLedger) and in
+> [`docs/TRUST-BOUNDARIES.md`](TRUST-BOUNDARIES.md). Do not overclaim past it.
+
+---
+
+## Who buys this, and why
+
+**B2B data exchange has an expensive failure mode: a delivery dispute.** "You never sent file X." "The
+file you sent was altered." "That is not the parcel we agreed to." When a contract has a
+delivery-acceptance clause, resolving such a dispute is slow and costly. ProofParcel issues a
+contractual **proof-of-delivery receipt** that makes the dispute re-derivable instead of arguable:
+either party can re-compute the same Merkle root from the files on disk and detect any
+edit/rename/add/remove, and a signed attestation lets a sender **vouch** for exactly which parcel they
+handed over.
+
+Buyers are data vendors, market-data redistributors, ML-data marketplaces, and any contract with a
+delivery-acceptance clause — a **different paying buyer** than DataLedger's data-provenance reviewer,
+with a different budgeted reason to pay.
+
+---
+
+## What ProofParcel PROVES (and what it does NOT)
+
+A parcel manifest commits to a Merkle root over the full set of `(relPath, content)` pairs delivered —
+**file names AND bytes**. From that root and the manifest, anyone can re-derive, offline:
+
+1. **Exactly which files were delivered — names and bytes.** Any edit, rename, add, or remove changes
+   the root. A re-computed root that matches the recorded root means the files on disk are
+   byte-for-byte (and name-for-name) the parcel that was committed to. A hand-edited manifest `root`
+   cannot fake a `MATCH` — `vh parcel verify` re-derives the root from the actual file bytes.
+
+2. **A signable parcel IDENTITY.** `vh parcel attest` emits a deterministic, byte-canonical UNSIGNED
+   payload (root + fileCount + a canonical `manifestDigest` over the delivered file set) that a sender
+   can sign. `vh parcel verify-attest` recovers the signer offline and confirms it.
+
+**It does NOT, by itself, prove:**
+
+- **A trusted delivery TIMESTAMP.** "Delivered ON date T" / "unaltered since date T" rides the
+  **human-owned signing/timestamp trust-root** ([`STRATEGY.md` P-3](../STRATEGY.md), `needs-human`).
+  The loop ships the **FORMAT, the OFFLINE VERIFIER, AND the `vh parcel sign` command** — but `vh parcel
+  sign` only ever reads a key the human PROVISIONED outside the loop (it never generates/persists/logs a
+  key); PROVISIONING the key / standing up a timestamp anchor is the human step. This is the **same honest
+  trust posture as DataLedger** — a receipt binds the file SET and is signable, but a signature is not a
+  timestamp.
+- **That the self-asserted `parcel` metadata is true.** The optional `parcel` block
+  (`parcelId` / `sender` / `recipient`) is **UNTRUSTED, self-asserted metadata**: it is **NOT bound
+  into the Merkle root**, editing it does not change the root, and it is **EXCLUDED** from the
+  attestation `manifestDigest` (a signer commits to the file SET, never the labels). The same applies
+  to the per-file `{source, license}` hints.
+
+---
+
+## Commands
+
+> **Run it, don't just read it.** [`examples/run.js`](../examples/run.js) is the executable companion to
+> the worked example below: `node examples/run.js` drives the ProofParcel pipeline (`parcel build → verify
+> → attest`, alongside the DataLedger side) against tiny committed sample data, offline and with no key,
+> and prints a PASS/FAIL summary — including a caught delivery tamper. It writes only to an OS temp dir,
+> references (does not run) the human-gated sign/timestamp steps, and is test-gated by
+> `test/cli.examples.test.js`. See [`examples/README.md`](../examples/README.md).
+
+| Command | What it produces | Property |
+| --- | --- | --- |
+| `vh parcel build <dir> --out <p>` | a tamper-evident parcel manifest (Merkle root + per-file `{relPath,contentHash,leaf}` + optional untrusted `parcel` block) | offline, no key, no network |
+| `vh parcel verify <dir> --manifest <p>` | re-derives the root from a fresh copy on disk + a precise per-file `ADDED/REMOVED/CHANGED` diff | offline, no key, no network; **CI-gateable exit 0 MATCH / 3 MISMATCH** |
+| `vh parcel attest <manifest> [--out <p>] [--json]` | the deterministic, byte-canonical **UNSIGNED** attestation payload a sender signs (root + fileCount + `manifestDigest`; `signed:false`) | offline, no key, no network |
+| `vh parcel sign <manifest> --key-env <VAR>\|--key-file <p> [--out <p>] [--json]` | signs the UNSIGNED attestation with a key YOU provisioned → the signed container `verify-attest` accepts. Read-only of YOUR key; never generates/persists/logs a key | offline, **caller-supplied key**, no network |
+| `vh parcel verify-attest <signed> [--manifest <m>] [--signer <addr>] [--json]` | recovers the signer, optionally pins the expected sender (`--signer`) and binds the signature to your parcel (`--manifest`) | **offline, no key, no network, CI-gateable exit 0 ACCEPTED / 3 REJECTED** |
+| `vh parcel timestamp-request <manifest> [--out <p>] [--json]` | the SHA-256 digest of the canonical attestation bytes — the exact `messageImprint` you submit to your RFC-3161 TSA | offline, no key, no network |
+| `vh parcel timestamp-wrap <manifest> --token <p> [--out <p>] [--json]` | wraps the TSA's returned RFC-3161 token into a verifiable `verifyhash.parcel-attestation-timestamped` container (binds it to the re-derived SHA-256 digest) | offline, no key, no network |
+| `vh parcel verify-timestamp <container> [--manifest <m>] [--json]` | OFFLINE-verifies a timestamped container: re-derives the digest, confirms the RFC-3161 token binds it, optionally binds to your parcel; ACCEPTED (with genTime / TSA serial / policy OID) or REJECTED | **offline, no key, no network, CI-gateable exit 0 ACCEPTED / 3 REJECTED** |
+
+The signed container uses ProofParcel's own `kind: "verifyhash.parcel-attestation-signed"`, distinct
+from DataLedger's `verifyhash.dataset-attestation-signed`, so a dataset signed-container does **not**
+cross-verify as a parcel one (and vice-versa) — even though the two products' UNSIGNED identity bytes
+can coincide for the same files. The scheme is `eip191-personal-sign` (EIP-191 `personal_sign` over the
+EXACT canonical UNSIGNED bytes).
+
+`vh parcel verify-attest` performs up to three checks, ACCEPTED only when **every requested** one
+passes:
+
+- **signature recovers to the claimed signer** (always): the embedded signature must recover to the
+  address the container claims as `signer`.
+- **`--signer <addr>` pins the expected sender** (optional): the recovered signer must equal a specific
+  address you expected.
+- **`--manifest <m>` binds your parcel** (optional): the canonical UNSIGNED bytes re-computed from YOUR
+  parcel manifest must be byte-identical to the signed payload — proving the signature vouches for the
+  parcel **you** hold.
+
+### `vh parcel sign` — the one-command signing leg (reads a key YOU provisioned)
+
+`vh parcel sign <manifest> --key-env <VAR> | --key-file <path> [--out <p>] [--json]` is the **one command
+that turns "the sender has a key" into a signed container the recipient can verify.** It builds the UNSIGNED
+payload exactly as `vh parcel attest` does (no re-implementation), constructs an in-process ethers `Wallet`
+from the key YOU supply, signs the canonical bytes (`eip191-personal-sign`), and **wraps WITHOUT editing**
+the payload into the `verifyhash.parcel-attestation-signed` container the existing `vh parcel verify-attest`
+accepts.
+
+It performs a **read-only of a key YOU provisioned outside this tool**; it **never generates, never
+persists, and never logs (or echoes) a key**, and it is **OFFLINE — no provider, no network**. The key is
+read from EXACTLY ONE of `--key-env <VAR>` or `--key-file <path>`, used in-process ONLY to sign, then
+discarded. **Neither source, both sources, a missing env var, an unreadable file, or a malformed/all-zero
+key HARD-ERRORS before any signing**, naming only the SOURCE — **never the key material**. On success the
+output prints ONLY the PUBLIC signer address, the output path, and the scheme.
+
+> **Trust posture (inherited verbatim — a signature is NOT a timestamp).** This is the SHARED in-band
+> `SIGN_TRUST_NOTE` (`cli/parcel.js`), the same wording the `sign` command prints and the **SAME honest
+> posture as DataLedger**, so the caveat can never drift from the code:
+>
+> > This signs the parcel IDENTITY (root, fileCount, manifestDigest) with the key YOU supplied. A self-managed key attests "the signer says so" — it is NOT an independent, trusted TIMESTAMP: "delivered/unaltered since a date T" still needs the human-owned signing/timestamp trust-root (needs-human, P-3). The key must be one YOU provisioned OUTSIDE this tool.
+
+---
+
+## Worked example: sender builds a parcel → signs (P-3, ONE command) → recipient verify-attests
+
+```sh
+# --- SENDER ---
+# 1. Build the tamper-evident delivery receipt over the files being delivered.
+vh parcel build ./delivery --out parcel.json \
+    --parcel-id PX-42 --sender "Acme Data" --recipient "Beta Corp"
+#    (parcelId/sender/recipient are UNTRUSTED self-asserted metadata, NOT bound into the root)
+
+# 2. Emit the canonical UNSIGNED attestation payload (the signing-ready bytes).
+vh parcel attest parcel.json --out attest.json
+#    attest.json carries `signed:false` — it is NOT yet a vouch and NOT a timestamp.
+
+# 3. [HUMAN step, STRATEGY.md P-3 — PROVISION ONLY] The sender PROVISIONS a real key OUTSIDE the loop, then
+#    SIGNs with ONE command: `vh parcel sign` reads that key, signs the canonical attest bytes
+#    (eip191-personal-sign), and wraps them into a signed container WITHOUT editing the payload (it stays
+#    signed:false). The loop NEVER generates/persists/logs the key. (In tests this uses an EPHEMERAL
+#    throwaway `Wallet.createRandom()` key — test-only, never a real key.)
+vh parcel sign parcel.json --key-env PARCEL_SIGNING_KEY --out signed.json
+#    signed by 0x<sender's public address>     scheme: eip191-personal-sign
+#    signed parcel attestation written: /abs/path/signed.json
+
+# --- RECIPIENT (offline, no key, no network) ---
+# 4. Verify the signed container binds the parcel actually received, by the expected sender.
+vh parcel verify-attest signed.json --manifest parcel.json --signer 0x<sender-address>
+#    Exit 0 ACCEPTED only if: the signature recovers to the claimed signer, the recovered signer is the
+#    expected sender, AND the signature binds the recipient's own parcel manifest. Exit 3 REJECTED
+#    otherwise — a recipient's CI can gate on this.
+
+# 5. Independently, confirm the delivered bytes still match the receipt.
+vh parcel verify ./received --manifest parcel.json   # exit 0 MATCH / 3 MISMATCH
+```
+
+The wrap step is **wrap-don't-edit**: the signed container embeds the EXACT canonical UNSIGNED bytes as
+a string, and the embedded payload stays strictly `signed:false` — wrapping adds a vouch, it never
+edits the thing vouched for.
+
+---
+
+## The independent delivery timestamp (P-3 Option B): an RFC-3161 TSA proves "existed by date T"
+
+A self-managed signature attests only "the sender **says so**". For the stronger claim that an
+**independent** third party saw this exact parcel identity **by time T**, ProofParcel ships the same P-3
+Option (B) machinery as DataLedger — the `verifyhash.parcel-attestation-timestamped` **FORMAT** and the
+OFFLINE **VERIFIER** `vh parcel verify-timestamp` — proved end-to-end with **self-minted test tokens** (a
+test-only mock TSA with an ephemeral key — **NEVER a real TSA**). Obtaining a real token is a human/network
+step. The flow is **`timestamp-request` → (obtain a token from your TSA) → `timestamp-wrap` →
+`verify-timestamp`**:
+
+```sh
+# 1. REQUEST: emit the SHA-256 digest of the canonical parcel-attestation bytes (the TSA's messageImprint).
+vh parcel timestamp-request parcel.json
+#   sha256 digest (the messageImprint to stamp): 9f12…ab
+
+# 2. [HUMAN, P-3 Option B] Pick a TSA you trust and obtain a token over that digest (network step).
+#    The loop NEVER calls a TSA, holds no token, and generates none.
+
+# 3. WRAP: bind the returned RFC-3161 token to the re-derived digest, WITHOUT editing the payload.
+vh parcel timestamp-wrap parcel.json --token token.der --out parcel.timestamped.json
+
+# 4. The RECIPIENT verifies offline — no key, no network — and (optionally) binds it to THEIR parcel.
+vh parcel verify-timestamp parcel.timestamped.json --manifest parcel.json
+#   verify-timestamp: ACCEPTED
+#   ACCEPTED: an RFC-3161 TSA asserted this parcel identity existed by:
+#     genTime (ISO UTC):  2026-01-01T00:00:00Z   TSA serial: 2a   policy OID: 1.2.3.4.5
+#   (exit 0; exit 3 if a tampered token / mismatched digest / edited payload / different manifest fails)
+```
+
+> **The exact bounded trust claim (never overclaims).** ACCEPTED means **an RFC-3161 TSA asserted this exact
+> parcel identity (the SHA-256 digest of the canonical attestation bytes) existed by `<genTime>`** — and this
+> is **as trustworthy as the TSA whose certificate YOU trust**. `verify-timestamp` does **NOT** validate the
+> TSA's X.509 certificate chain or the token's CMS signature — use a CMS verifier (`openssl ts -verify`) for
+> full PKI validation. It NEVER claims "delivered/unaltered since date T" without that qualification. A
+> tampered token, a mismatched digest, or an edited embedded attestation **REJECTS** — never a false ACCEPT.
+
+P-3 Option (B)'s human handoff collapses to: **(1)** pick a TSA you trust; **(2)** run
+`vh parcel timestamp-request` to get the digest; **(3)** obtain a token from your TSA over that digest;
+**(4)** run `vh parcel timestamp-wrap` — **done**; recipients verify offline with `vh parcel verify-timestamp`.
+
+---
+
+## Trust boundary (the same honest posture as DataLedger)
+
+- The receipt **binds the file SET** to a Merkle root and is **signable** — but it is **NOT by itself a
+  trusted delivery TIMESTAMP**. "Delivered ON date T" rides the human-owned trust-root
+  ([`STRATEGY.md` P-3](../STRATEGY.md), `needs-human`).
+- The `parcel` metadata (`parcelId` / `sender` / `recipient`) and the per-file `{source, license}`
+  hints are **UNTRUSTED, self-asserted**: not bound into the root, excluded from the attestation digest,
+  and proving nothing on their own.
+- A valid signature proves the **holder of `signer`'s key vouched for THIS parcel identity** — not a
+  timestamp, not the truth of the metadata.
+
+See [`docs/TRUST-BOUNDARIES.md`](TRUST-BOUNDARIES.md) and DataLedger's
+[trust posture](DATALEDGER.md) — ProofParcel reuses the SAME in-band `TRUST_NOTE` verbatim so the
+caveats never drift between products.
+
+
+---
+<sub>© 2026 verifyhash.com · Licensed under Apache-2.0 (SPDX-License-Identifier: Apache-2.0) — see the [LICENSE](https://verifyhash.com/LICENSE) and [NOTICE](https://verifyhash.com/NOTICE) served with this file.</sub>

package/docs/PROOFS.md

@@ -0,0 +1,262 @@
+# verifyhash portable proofs — artifact schema, verification steps, worked example
+
+This is the canonical spec for the **portable Merkle-proof artifact** that `cli/proof.js` writes and
+verifies (task **T-9.2**), exported by `vh prove <file> --root <dir> --out <p>` and consumed by the
+read-only `vh verify-proof <p>`. A proof artifact is a versioned, strictly-validated JSON file that
+lets a third party **independently** confirm a single file is part of an anchored repository Merkle
+root — needing **only the artifact + an RPC URL**, never the original repo, no working tree, no key.
+
+That portability is the missing half of the project's core promise ("anyone can later prove that some
+content is byte-for-byte what was anchored, without trusting any server"). `vh prove` already builds a
+genuine proof, but on its own that proof only lives in the prover's terminal. `--out` exports it so it
+can leave the prover's machine; `vh verify-proof` lets the recipient verify it with **no trust in the
+prover** (it re-derives and re-folds everything itself).
+
+> **Trust posture (read this first).** The artifact is an **UNTRUSTED transport container**, in exactly
+> the spirit of [`docs/TRUST-BOUNDARIES.md`](TRUST-BOUNDARIES.md) and the receipt posture in
+> [`docs/RECEIPTS.md`](RECEIPTS.md). `vh verify-proof` **never trusts the file's claims** — it
+> RE-DERIVES the leaf from `contentHash` + `relPath`, RE-FOLDS the `proof` itself, and checks the root
+> the *fold produced* on-chain (not the `root` field the file claims). Every field below is therefore
+> labelled **UNTRUSTED transport — verification re-derives**: tampering with any of them is either
+> caught offline or produces a non-`ACCEPTED` verdict, never a false accept.
+
+> **What an `ACCEPTED` verdict proves: SET-MEMBERSHIP — not authorship, not the `uri`.** It binds the
+> file's path + bytes to an anchored Merkle **root**, exactly the boundary the contract's `verifyLeaf`
+> draws. It says nothing about who anchored that root, what `contributor` means (see the `authorBound`
+> rule in [`docs/TRUST-BOUNDARIES.md`](TRUST-BOUNDARIES.md)), or any `uri`. `vh verify-proof` leads its
+> human-readable output with this caveat verbatim.
+
+---
+
+## Schema
+
+`cli/proof.js` defines the discriminators `kind: "verifyhash.merkle-proof"` and `schemaVersion: 1`
+(distinct from the receipt kinds in [`docs/RECEIPTS.md`](RECEIPTS.md), so a random JSON file, a
+receipt, or a future/foreign artifact is never misread as a current proof). `readProofArtifact`
+validates **strictly** and throws on ANY deviation rather than filling defaults — a malformed/short
+hash or a non-hex `proof` hard-errors, so `vh verify-proof` can never silently accept a structurally
+bogus file. This mirrors the receipt schema's strict-validation posture.
+
+Every field is **UNTRUSTED transport**: verification re-derives, it never relies on a field being
+honest. The columns below name what each field is *for* and how verification *re-checks* it.
+
+| Field | Type | Required | How verification re-checks it (UNTRUSTED transport) |
+|-------|------|----------|------------------------------------------------------|
+| `kind` | string | yes | Must equal `"verifyhash.merkle-proof"` exactly, else rejected as not-a-proof-artifact. A structural discriminator only. |
+| `schemaVersion` | integer | yes | Must be a version this build understands (currently `1`); any other is rejected so a future/foreign file is never misread. |
+| `contentHash` | `0x`+64 hex (32 bytes) | yes | The bare `keccak256` of the file's bytes. The leaf is RE-DERIVED from this + `relPath`; a tampered `contentHash` breaks the re-derived leaf and is REJECTED offline. |
+| `relPath` | non-empty string | yes | The file's repo-relative POSIX path, the value bound into the leaf. The leaf is RE-DERIVED from `contentHash` + `relPath`; changing it changes the re-derived leaf and is REJECTED offline. |
+| `leaf` | `0x`+64 hex (32 bytes) | yes | The path-bound leaf `pathLeaf(relPath, contentHash) = keccak256(DIR_LEAF_DOMAIN ‖ relPath ‖ 0x00 ‖ contentHash)`. Verification RE-DERIVES this from `contentHash`+`relPath` and rejects if the stored `leaf` does not equal the re-derived one — a forged `leaf` alone cannot fool it. |
+| `root` | `0x`+64 hex (32 bytes) | yes | The directory's anchored Merkle root the proof folds to. Verification computes its OWN root by folding `leaf` through `proof`; the `root` field is only confirmed to equal that computed root, and it is the *computed* root that is checked on-chain. |
+| `proof` | array of `0x`+64 hex | yes | The sorted-pair Merkle siblings. RE-FOLDED with the same `nodeHash` convention the contract's `verifyLeaf` uses; a tampered sibling no longer folds to `root` and is REJECTED offline. May be `[]` for a single-file tree (`leaf == root`). |
+| `contractAddress` | `0x`+40 hex (address) | optional | A hint of WHERE the prover expects the root anchored. Recorded when the artifact is built on the on-chain prove path. An explicit `--contract` always overrides it; it is never trusted blindly. |
+| `chainId` | non-negative integer | optional | A hint of WHICH chain the root is anchored on. Informational/self-describing; recorded on the on-chain build path, never required. |
+
+An artifact built with the no-key `--dry-run`/build path legitimately omits `contractAddress`/`chainId`
+(there was no chain context); the verifier then supplies `--contract`/`--rpc`. An artifact built on the
+on-chain prove path records both so `vh verify-proof` can run with **no** `--contract` flag.
+
+### The leaf and fold convention (same as the contract)
+
+The proof artifact reuses the **exact** Merkle machinery `vh hash <dir>` and the contract's
+`verifyLeaf` agree on — there is no second scheme (see [`docs/MERKLE-LEAVES.md`](MERKLE-LEAVES.md)):
+
+- the **path-bound leaf** is `pathLeaf(relPath, contentHash) = keccak256(DIR_LEAF_DOMAIN ‖ relPath ‖ 0x00 ‖ contentHash)`,
+  so the proof is tied to the file's **location**, not just its bytes (renaming or moving the file
+  changes the leaf and the proof no longer folds);
+- the **fold** tags the leaf with `LEAF_TAG`, then walks `proof` applying `NODE_TAG` sorted-pair
+  hashing (`nodeHash`) — byte-identically to the contract's `verifyLeaf`.
+
+`vh verify-proof` reuses `hash.js`'s `pathLeaf` / `leafHash` / `nodeHash` directly (not a
+re-implementation), so the offline fold and the on-chain `verifyLeaf` can never silently diverge.
+
+---
+
+## Verification steps
+
+`vh verify-proof <p>` is **read-only and needs no key, no repo, and no working tree** — just the
+artifact and an RPC URL. It never constructs a signer. It runs two stages, and prints `ACCEPTED`
+**only** when the offline fold **and** both on-chain checks pass:
+
+### 1. Offline fold (no network)
+
+The internal-consistency gate. Purely offline (no network even needed), it:
+
+1. **RE-DERIVES the leaf** from `contentHash` + `relPath`: `derivedLeaf = pathLeaf(relPath, contentHash)`,
+   and checks `leafMatches = (artifact.leaf == derivedLeaf)`. A forged `leaf`, or a tampered
+   `contentHash`/`relPath`, fails here.
+2. **RE-FOLDS the proof**: `computed = leafHash(leaf)`, then for each sibling `s`,
+   `computed = nodeHash(computed, s)`; checks `foldsToRoot = (computed == artifact.root)`. A tampered
+   `proof` sibling (or `root`) fails here.
+
+If either check fails the verdict is **`REJECTED`** immediately, **with no network call** — there is
+nothing meaningful to ask the chain about a proof that does not even fold to its own claimed root.
+The CLI names exactly which check failed.
+
+### 2. On-chain check (one read-only call set)
+
+Only when the offline fold holds, and only if a provider is supplied, `vh verify-proof` makes one
+read-only check set against the root the **offline fold produced** (`computedRoot`, which equals the
+artifact `root` since the fold held — so the file's `root` is never trusted unchecked):
+
+1. `isAnchored(root)` — is the root actually anchored on-chain? If not, the verdict is **`NOT ANCHORED`**
+   (a distinct, non-zero exit), NOT a false accept: the proof is internally valid but there is nothing
+   on-chain to prove it against (it was never anchored, or you are pointed at the wrong contract/chain).
+2. `verifyLeaf(root, leaf, proof)` — the contract's own verdict (defense in depth: even if the offline
+   fold had a bug, the chain decides). `verifyLeaf` tags the supplied `leaf` itself and replays the
+   sorted-pair fold.
+
+The contract address resolves as: explicit `--contract` (or `VH_CONTRACT`) > the artifact's recorded
+`contractAddress`. With no provider at all, `vh verify-proof` reports the offline fold result but does
+**not** claim `ACCEPTED` (acceptance requires the on-chain leg) — a script reading the status never
+mistakes an offline-only pass for a full accept.
+
+### Verdicts
+
+| Verdict | Meaning | Exit |
+|---------|---------|------|
+| `ACCEPTED` | Offline fold held AND root is anchored AND on-chain `verifyLeaf` accepted. The file's path + bytes are a leaf of an anchored root. | 0 |
+| `REJECTED` | An offline or on-chain check failed (tampered `leaf`/`contentHash`/`proof`/`root`, or the chain rejected the proof). Never a false accept. | non-zero |
+| `NOT ANCHORED` | The proof folds offline, but its root was never anchored on-chain. Distinct from a tamper. | non-zero |
+
+---
+
+## Worked end-to-end example (prove → hand over → verify-proof)
+
+The whole point is that the **prover** and the **verifier** can be different people on different
+machines: the only thing that crosses between them is the artifact file.
+
+**Prover** — build and export the artifact (no key needed; works on the `--dry-run` build path):
+
+```
+$ vh prove src/index.js --root ./repo --out proof.json --dry-run
+Wrote portable proof artifact: /work/repo/proof.json
+  repo root dir: /work/repo  (5 files)
+  file:          src/index.js
+  merkle root:   0x9f8c…a1
+  content hash:  0x4b2e…7c
+  leaf (path-bound): 0x77ad…02
+  proof (2 siblings):
+    0x1c3d…9e
+    0xa0f5…44
+```
+
+The exported `proof.json` (every field UNTRUSTED transport — `vh verify-proof` re-derives):
+
+```json
+{
+  "kind": "verifyhash.merkle-proof",
+  "schemaVersion": 1,
+  "root": "0x9f8c00000000000000000000000000000000000000000000000000000000a100",
+  "leaf": "0x77ad00000000000000000000000000000000000000000000000000000000a200",
+  "contentHash": "0x4b2e00000000000000000000000000000000000000000000000000000000a300",
+  "relPath": "src/index.js",
+  "proof": [
+    "0x1c3d00000000000000000000000000000000000000000000000000000000a400",
+    "0xa0f500000000000000000000000000000000000000000000000000000000a500"
+  ],
+  "contractAddress": "0x5FbDB2315678afecb367f032d93F642f64180aa3",
+  "chainId": 31337
+}
+```
+
+> An artifact built on the **on-chain** prove path (with `--contract`/`--rpc`) records
+> `contractAddress` + `chainId`, so the verifier needs no `--contract`. An artifact built with bare
+> `--dry-run` and no chain context omits both; the verifier then passes `--contract`/`--rpc`.
+
+**Hand over** the file (email, attach to a PR, drop in a bucket — it is read-only public-membership
+evidence; it holds **no secret**, unlike a claim receipt). The recipient does **not** need the repo.
+
+**Verifier** — confirm it with only the artifact + an RPC URL, no repo, no key:
+
+```
+$ vh verify-proof proof.json --rpc https://… 
+NOTE: this proves SET-MEMBERSHIP only — that the named file (its path + bytes) is a leaf of an
+anchored repo Merkle root. It does NOT prove authorship, who anchored the root, or anything about
+any `uri`. The artifact is an UNTRUSTED transport container: verify-proof RE-DERIVES the leaf and
+RE-FOLDS the proof itself (it never trusts the file's claims), then confirms the root is anchored
+on-chain. Set-membership in an anchored root is exactly what the contract's verifyLeaf attests.
+
+  proof artifact: proof.json
+  relPath:        src/index.js
+  contentHash:    0x4b2e…7c
+  leaf:           0x77ad…02
+  root:           0x9f8c…a1
+  proof siblings: 2
+
+  offline recompute (no network):
+    leaf re-derived from contentHash+relPath: yes
+    proof folds to the claimed root:          yes
+
+  registry authenticated: REGISTRY_ID ok (v1), chainId 137
+
+  on-chain checks (one read-only call set):
+    root is anchored (isAnchored):            yes
+    contract verifyLeaf accepts the proof:    yes
+
+  result:         ACCEPTED
+```
+
+If the verifier (or anyone in transit) had altered the artifact's `proof`, `leaf`, or `contentHash`,
+the offline fold would not hold and the verdict would be `REJECTED` — caught offline, no network even
+needed. If the `root` was never anchored, the verdict would be `NOT ANCHORED` rather than a false
+accept.
+
+**The on-chain leg authenticates the registry first, on the artifact's recorded chain** (T-11.2).
+Before any on-chain check, verify-proof runs the shared `assertRegistry` preflight: it confirms a
+contract is actually deployed at the address, that it self-identifies as a genuine verifyhash registry
+(`REGISTRY_ID` / `REGISTRY_VERSION`), AND — because the artifact records the `chainId` it was anchored
+on — that the provider is on **that same chain**. An artifact that says "anchored on chainId 137"
+**hard-errors** rather than be "verified" against a different chain that returns fakes. That is the
+portability promise made trustworthy: the consumer no longer trusts the prover's RPC blindly. The
+human verdict prints a `registry authenticated: REGISTRY_ID ok (vN), chainId N` line (above) before
+the on-chain checks; a loud, non-default `--skip-identity-check` bypasses the preflight for a known
+local-dev contract. See the README's
+[authenticated reads](../README.md#authenticated-reads-registry-identity--chainid) section.
+
+`--json` emits the same verdict + per-check booleans (`offline.{leafMatches,foldsToRoot,ok}`,
+`onChain.{checked,rootAnchored,verifyLeaf}`, `accepted`, `status`) plus the trust note, for tooling. It
+also carries a top-level `registry: { id, version, chainId }` block proving the on-chain leg ran
+against an authenticated registry on the artifact's recorded chain (or `{ "skipped": true, "note": … }`
+under `--skip-identity-check`, or `null` when no on-chain leg ran — an offline-only / rejected-early
+verdict).
+
+---
+
+## What this does NOT prove
+
+Consistent with [`docs/TRUST-BOUNDARIES.md`](TRUST-BOUNDARIES.md) and the contract's `verifyLeaf`
+boundary:
+
+- **Not authorship.** `ACCEPTED` says the file is in an anchored root; it says nothing about who
+  anchored it or what `contributor` means (that is the `authorBound` distinction — one-shot `anchor`
+  is front-runnable, only commit-reveal binds an author).
+- **Not the `uri`.** The artifact carries no `uri`; even where one exists on the record, it is an
+  untrusted hint the contract never fetched or validated.
+- **Not "this is the latest/only version."** It proves membership in *the* root in the artifact; a
+  different snapshot has a different root.
+
+> Rule of thumb: **`vh verify-proof` binds a file's path + bytes to an anchored root; that is all.**
+
+---
+
+## Tests
+
+`test/cli.verifyproof.test.js` proves the behaviour this doc describes:
+
+- the offline fold re-derives the leaf and folds to the root with **no network**, and a tampered
+  `proof` / `leaf` / `contentHash` is caught offline (`offlineOk === false`);
+- strict validation hard-errors on a wrong `kind`, an unsupported `schemaVersion`, a short/malformed
+  hash, a non-hex/non-array `proof`, an empty `relPath`, and non-JSON input;
+- end-to-end against a live hardhat node: build `--out` then `vh verify-proof` (artifact + RPC only,
+  **no repo**) `ACCEPTED`s a genuine proof, the on-chain build path records `contractAddress` so
+  verify needs no `--contract`, tampering `proof`/`leaf`/`contentHash` `REJECTED`s, a never-anchored
+  root reports `NOT ANCHORED`, and `--json` round-trips the verdict + per-check booleans.
+
+`test/cli.proofs.docs.test.js` is the docs-rot guard for this file + the README CLI block: it pins the
+schema fields, the `kind`/`schemaVersion`, the verification stages, and the trust caveats to the real
+`cli/proof.js` exports, so the prose cannot silently drift from the code.
+
+
+---
+<sub>© 2026 verifyhash.com · Licensed under Apache-2.0 (SPDX-License-Identifier: Apache-2.0) — see the [LICENSE](https://verifyhash.com/LICENSE) and [NOTICE](https://verifyhash.com/NOTICE) served with this file.</sub>