verifyhash 0.1.0 → 0.1.2

package/docs/ANCHORING.md

@@ -43,11 +43,12 @@ logged), and a chainId outside the known local/testnet set refuses without `--i-
 Exit contract: `0` anchored / `3` named reject (an invalid artifact, or the registry's own revert
 such as `AlreadyAnchored`) / `2` usage / `1` IO-network-key.
 
-`verify-anchored` is **OFFLINE by default** — no key, no network (but it runs through the producer
-`cli/` stack, which loads `ethers`; "OFFLINE" here means **no key and no network**, NOT "no producer
-stack" — the standalone `verifier/` tree does not yet verify anchored receipts, see **Independent
-verification** below): it validates the receipt strictly and **recomputes** the artifact's digest
-through the same closed table; any deviation is a specific named reject (`digest-mismatch` /
+`verify-anchored` is **OFFLINE by default** — no key, no network. The same offline binding leg also
+runs with **zero producer stack**: the standalone `verifier/` tree recognizes `vh-anchored-receipt@1`
+(`verify-vh <receipt> --anchored-artifact <sealed-file>`, see **Independent verification** below), so
+"verify without installing the producer's stack" now covers the receipt too. Either way the check is
+the same: the receipt is validated strictly and the artifact's digest is **recomputed** through the
+same closed table; any deviation is a specific named reject (`digest-mismatch` /
 `kind-mismatch` / `how-mismatch` / `bad-receipt` / the artifact's own named reject). With **both** `--rpc` and `--contract` it additionally authenticates the registry
 (the standing identity probe — no record is believed until the contract self-identifies) and
 re-checks every chain fact the receipt claims. Exit `0` ACCEPTED / `3` REJECTED / `2` / `1` — the
@@ -86,31 +87,51 @@ Spelled out:
   `timestamp-request`/`timestamp-wrap`/`verify-timestamp`) is a third party's *existed-by-genTime*
   attestation. An on-chain anchor (C) complements them; it does not replace them.
 
-## Independent verification — the one axis this does NOT yet cover
+## Independent verification — the anchored receipt verifies standalone too (T-70.4)
 
 The verifyhash family's headline is that a counterparty can verify a sealed artifact **OFFLINE,
 without installing the producer's stack**: the standalone `verifier/` bundle
 ([`../verifier/dist/verify-vh-standalone.js`](../verifier/dist/verify-vh-standalone.js)) is a single,
 dependency-free file — **no `ethers`, no `npm install`** — that re-derives an evidence packet's or
-agent packet's digest by itself. That promise **DOES** cover the **sealed artifact underneath** an
+agent packet's digest by itself. That promise DOES cover the **sealed artifact underneath** an
 anchored receipt: hand a counterparty the `*.vhevidence.json` (or any closed-table artifact) and they
 verify it standalone, exactly as before, with no producer code.
 
-It does **NOT yet extend to the anchored receipt itself.** `vh verify-anchored` — including its
-OFFLINE binding leg — runs **only through the producer `cli/` stack, which loads `ethers` at module
-load** (`cli/anchor-artifact.js` → `cli/core/attestation.js`); and `vh-anchored-receipt@1` is **NOT a
-recognized kind** in the standalone `verifier/verify-vh.js` tree, which scopes itself to sealed
-artifacts and explicitly puts on-chain anchoring out of scope. So the family's zero-install
-"verify without the producer's stack" promise **does not YET reach the anchored-receipt binding
-leg**: a counterparty who wants to check the receipt's binding today must run the producer cli
-(`node cli/vh.js verify-anchored`).
-
-This is a **packaging gap, not a proof gap.** (1) The binding check is pure hashing — the standalone
-verifier already re-derives evidence-seal and agent-packet digests with no `ethers` — so
-`vh-anchored-receipt@1` can be added to the standalone tree to actually close it (tracked as
-**T-70.4**). (2) The `--rpc` chain re-check needs the chain anyway, so the offline binding leg's
-standalone value is limited until then. Until T-70.4 lands: verify the **sealed artifact** standalone
-(zero-install, independent), and verify the **anchor** via the producer cli.
+Since **T-70.4** it also covers the **anchored receipt's OFFLINE binding leg itself**:
+`vh-anchored-receipt@1` **IS a recognized kind in the standalone `verifier/verify-vh.js` tree**. A
+counterparty handed a receipt plus the sealed artifact it anchors checks the binding with zero
+producer code — from this repo, or from the single-file bundle:
+
+```bash
+node verifier/verify-vh.js examples/anchoring/anchored-receipt.local.json \
+  --anchored-artifact examples/anchoring/sample-seal.vhevidence.json
+# zero-install, same command: node verify-vh-standalone.js <receipt> --anchored-artifact <sealed-file>
+```
+
+The standalone validates the receipt strictly (an edited in-band trust note is the named
+`bad-receipt`) and **recomputes** the artifact's digest through the SAME closed kind table the
+producer core uses — each leg re-validating the artifact through a strict, `ethers`-free port of its
+shipped validator, over the verifier's own dependency-free keccak/sha256. The verdicts match the
+producer cli's on the same inputs: ACCEPTED exit `0`, or the specific named reject
+(`digest-mismatch` / `kind-mismatch` / `how-mismatch` / `bad-receipt` / the artifact's own named
+reject) exit `3` — the packaging gap disclosed here before T-70.4 is **closed**.
+
+**Chain-class guidance (so a local-dev receipt is never mistaken for a public proof).** On ACCEPT the
+standalone also classifies the chain the receipt *claims* and surfaces it as a stable, machine-gateable
+part of the `--json` contract — `chainClass` (`local-dev` / `public-testnet` / `unknown`) plus a
+`publiclyMeaningful` boolean (and a leading human-readable `WARNING`/`ADVISORY` line). The offline leg
+cannot (by definition) confirm the digest is actually on-chain, but it *can* tell a counterparty that a
+receipt from a **local dev chain** proves mechanism only and is worth nothing publicly (STRATEGY.md
+**P-2**) — the committed `chainId 31337` fixture is flagged exactly that way. The classification never
+changes the accept/reject decision; it is additive trust context the counterparty's own tooling can
+gate on. The id sets mirror the producer's `cli/anchor.js` known-testnet set (pinned by a drift guard).
+
+**The honest remaining boundary.** The standalone checks the OFFLINE **binding leg only**: the
+receipt's `chain` facts remain the **anchorer's claim** until re-checked against the chain, and that
+re-check needs a chain endpoint by definition — it stays with the producer cli
+(`vh verify-anchored --rpc <url> --contract <addr>`, whose `cli/` stack loads `ethers` at module
+load: `cli/anchor-artifact.js` → `cli/core/attestation.js`). What a receipt proves — and does NOT
+prove — is unchanged either way (see the trust note above).
 
 ## The free line
 

package/docs/PUBLISH-VERIFY-VH.md

@@ -0,0 +1,45 @@
+# Publish `verify-vh` — the HUMAN checklist (one page)
+
+**Publishing stays human.** The build loop only builds and tests locally — it never runs
+`npm publish`, never deploys, never holds registry credentials (STRATEGY.md hard guardrails).
+This page is what the human follows when they decide to publish the standalone verifier package.
+
+**Why publish at all.** The front-door line in [docs/ADOPT.md](ADOPT.md) —
+`npx --yes verify-vh demo` — **404s until `verify-vh` is published to npm**. Everything else about
+that line is already true and machine-tested from the repo; publish is the single missing (human) step.
+
+**The gate that must be green first.** `test/verify-vh.pack.test.js` runs `npm pack` on `verifier/`
+(offline), extracts the tarball OUTSIDE the repo, proves the bare tree *cannot* fall back to the
+repo's modules, provisions ONLY the one declared dependency (`js-sha3`), and then proves `demo` and
+the real `--vendor` verify path work from the extracted tree alone — so a file missing from
+`verifier/package.json` `files` fails that suite, not the first stranger's `npx` run.
+
+## Checklist
+
+1. **Gate** (repo root): `npx hardhat test test/verify-vh.pack.test.js` → must be green.
+2. **Inspect the shipment** (from `verifier/`): `cd verifier && npm pack --dry-run` — expect
+   `verify-vh.js`, `lib/*.js`, `README.md`, `package.json`, and nothing else.
+3. **Log in as the human npm account**: `npm whoami` (then `npm login` if needed). The loop holds no
+   npm credentials and must never be given any.
+4. **Publish from `verifier/` — NOT the repo root** (the root package is `verifyhash`, a different
+   surface): `cd verifier && npm publish`. Re-publishing later requires a version bump in
+   `verifier/package.json` first (npm rejects a reused version).
+5. **Post-publish smoke**, from any directory OUTSIDE this repo (a clean machine is even better):
+
+   ```bash
+   npx --yes verify-vh demo
+   ```
+
+   Expect exit `0`; the transcript must ACCEPT the genuine packet naming signer
+   `0x70997970c51812dc3a010c7d01b50e0d17dc79c8` (the fixed TEST-ONLY hardhat #1 key — never a real
+   key), then REJECT the one-byte-tampered copy naming `model-card.md`.
+6. **Hands-on smoke** (optional): `npx --yes verify-vh demo ./vh-demo`, then run the verify / tamper /
+   restore commands it prints.
+7. **If the smoke fails**: `npm deprecate verify-vh@<version> "broken — do not use"`, fix, bump, and
+   re-run this checklist from step 1. Never leave a broken version as `latest`.
+
+## The honest boundary (say no more than this, anywhere the package is announced)
+
+The demo proves tamper-evidence + signer-pin, NOT a trusted timestamp, NOT a legal opinion.
+A verified packet means: the bytes you hold match what the named signer sealed — nothing about
+*when* it was sealed, and nothing about whether the content is true, licensed, or lawful.

package/examples/README.md

@@ -0,0 +1,185 @@
+# verifyhash — runnable examples
+
+Two committed, self-checking, fully-offline examples. Zero setup, one command each.
+
+## `sdk-verify.js` — embed the SDK exactly as an external developer would
+
+```bash
+node examples/sdk-verify.js
+```
+
+This is the **consumer** example: it imports the package **only** through its single public entrypoint,
+`require("verifyhash")` (plus `ethers`, verifyhash's **own** declared dependency, used only to mint an
+**ephemeral throwaway** signing key that stands in for a real, out-of-band vendor key) — **no** deep
+`cli/core/...` reach-in, no network, no third-party non-core dependency, no real key. It runs **two acts**:
+the free-tier tamper-evidence path, and the paid, revenue-relevant **signed + vendor-pinned verify gate**.
+
+**Act 1 — UNSIGNED tamper-evidence (free tier):**
+
+1. **`buildSeal`** — seal an in-memory `{ relPath, bytes }` file set (no directory, no disk).
+2. **`verifySeal`** (untouched bytes) → **ACCEPTED** — the root is re-derived from the bytes you hold.
+3. **`verifySeal`** (one byte flipped) → **REJECTED** — and it prints the per-file **diff** the verdict is
+   built from (which `relPath` changed, expected vs. actual hash).
+4. **`serializeSeal` / `readSeal`** — the canonical, byte-deterministic packet a counterparty can re-read.
+
+**Act 2 — SIGNED + vendor-PINNED verify gate (the paid embed).** This is the integration a downstream
+service pays for: **verify in-process that a packet was signed by _our_ published vendor address**, with
+**no** shell-out to the `vh` binary (STRATEGY.md **P-9** / EPIC-58 — "verified by verifyhash, signed &
+pinned, inside _your_ product").
+
+5. **`signSealWith`** — a publisher signs the seal (ephemeral key here; a real out-of-band key in prod).
+6. **`verifySignedSeal`** pinned to **our** vendor address → **ACCEPTED**.
+7. **`verifySignedSeal`** pinned to a **different** vendor → **REJECTED** — the signature is *genuine*; only
+   the **pin** fails. "Signed by someone, but not by us" must reject; that is the security property a paying
+   integrator's gate enforces (it is **not** tamper-evidence — the bytes are fine).
+8. **`verifySignedSeal`** on a one-byte-tampered signature → **REJECTED** (recovered signer ≠ claimed).
+
+It leads with the standing **trust note** (a seal proves *tamper-evidence*; a valid **signature** proves
+*who vouched* — the pinned address's key-holder — for those bytes; **neither** proves a trusted timestamp
+and **neither** is a legal opinion — timestamping rides the human-owned trust-root, `needs-human`, P-3 in
+[`STRATEGY.md`](../STRATEGY.md)), prints a clear **PASS** summary naming both acts, and exits 0. The only
+key it ever uses is an **ephemeral, in-memory throwaway** (never persisted, funded, or logged). It is
+test-gated by [`test/sdk.example.test.js`](../test/sdk.example.test.js) on every `npx hardhat test` — a grep
+there asserts the example uses **only** the public surface (`require("verifyhash")` + `ethers`, no deep
+`cli/*` import), so the "public API stands alone" claim can never silently rot.
+
+## `verify-service-client.js` — call the `vh serve-verify` HTTP endpoint as a drop-in dependency
+
+```bash
+node examples/verify-service-client.js
+```
+
+The **verify-service client** example: it boots the `vh serve-verify` HTTP endpoint (the *"CI plugin that
+imports rather than shells out"*), then treats it as a drop-in dependency. It **builds** a seal with
+`require("verifyhash")`, **POSTs** a clean seal to the booted service (HTTP **200 ACCEPTED** → prints
+`ACCEPT`), then **POSTs** the same seal with **one byte flipped** (HTTP **422 REJECTED** → prints `REJECT`),
+tears the service down, and exits 0. It imports **only** `require("verifyhash")`, the `vh` **command**
+(spawned from the package's own `bin.vh`), and Node built-ins (`http`, `child_process`, `path`) — **no**
+deep `cli/*` reach-in and **no** third-party dependency. See
+[`docs/VERIFY-SERVICE.md`](../docs/VERIFY-SERVICE.md) for the request/response schema, the status mapping,
+and the trust boundary. It is test-gated by
+[`test/verify-service.example.test.js`](../test/verify-service.example.test.js) on every `npx hardhat test`,
+so it can never silently rot.
+
+## `journal-ci.js` — continuous-integrity CI step (the `vh journal` integrity journal)
+
+```bash
+node examples/journal-ci.js
+```
+
+The **continuous-integrity** example: it treats the `vh journal` **append-only, hash-chained integrity
+journal** as a drop-in CI step. It **builds** a seal with `require("verifyhash")`, writes the sealed bytes +
+packet to a throwaway workdir, then shells out to `vh journal append` **twice** (recording two hash-chained
+verdicts, strictly additively), runs `vh journal verify` (reporting an **unbroken chain**, exit 0), and exits
+0. It imports **only** `require("verifyhash")`, the `vh` **command** (spawned from the package's own `bin.vh`),
+and Node built-ins (`fs`, `os`, `path`, `child_process`) — **no** deep `cli/*` reach-in (not even the pure
+journal core) and **no** third-party dependency. The `ts` on each entry is **self-asserted**, **not** a
+trusted timestamp — the journal never claims *"unaltered since date T"* on its own (STRATEGY.md **P-3**). See
+[`docs/INTEGRITY-JOURNAL.md`](../docs/INTEGRITY-JOURNAL.md) for the schema, the chain guarantee, the 0/3
+contract, and the honesty boundary. It is test-gated by
+[`test/journal.example.test.js`](../test/journal.example.test.js) on every `npx hardhat test`, so it can
+never silently rot.
+
+## `sdk-verify-signed.js` — the SIGNED + vendor-PINNED verify gate, in-process
+
+```bash
+node examples/sdk-verify-signed.js
+```
+
+This is the **buyer's** signed-verify example: it plays a downstream service that **receives** a signed,
+vendor-address-pinned deliverable (a model, a dataset, a build artifact) and clears the **two gates that
+gate a real purchase** — **(a)** *"was this signed by our published vendor address?"* and **(b)** *"are the
+exact files I received **on disk** the ones that vendor signed?"* — **in-process**, with **no** shell-out to
+the `vh` binary. It is the SIGNED twin of `vh evidence verify-signed` (including its `--signer` pin and
+`--dir` binding), byte-identical because it **is** the same code (`index.js` is a thin identity re-export;
+see [`../docs/SDK.md`](../docs/SDK.md)). This is the paid, revenue-relevant embed (STRATEGY.md **P-9** /
+EPIC-58 — "verified by verifyhash, signed & pinned, inside _your_ product").
+
+The verify example imports **only** `require("verifyhash")` and **relative** example files — nothing else,
+**no** `child_process`, **no** built-in (`fs`/`os`/`path`), **no** network, **no** deep `cli/*` reach-in.
+Because a buyer **never signs** and does not do its own disk plumbing, both the publisher-side key handling
+(minting an **ephemeral throwaway** key that stands in for the publisher's real out-of-band key) **and** the
+"receive the deliverable to a throwaway temp dir / corrupt one received file / clean up" plumbing are
+quarantined in [`lib/ephemeral-publisher.js`](./lib/ephemeral-publisher.js) — the only place `ethers`
+(verifyhash's own dependency) and Node built-ins are touched. It runs one **ACCEPT** then **four** REJECT/
+ACCEPT steps that **escalate in value**:
+
+1. **`verifySignedSeal`** pinned to **our** vendor address → **ACCEPTED**.
+2. **`verifySignedSeal`** pinned to a **different** vendor → **REJECTED** — a **wrong-signer** reject: the
+   signature is *genuine* and the bytes are fine; it just recovers to a signer we do **not** pin. "Signed by
+   someone, but not by us" must reject; that is the security property a paying integrator's gate enforces.
+3. **`verifySignedSeal`** on a one-byte-**tampered** signature → **REJECTED** — the recovered signer no
+   longer matches the claimed one, so it rejects even under the correct vendor pin.
+4. **`verifySignedSealAttestation`** — the **strict, on-disk BINDING gate** a paying integrator actually
+   buys — pinned to **our** vendor address **and bound to the actual files received on disk**:
+   - **[4a]** the **untouched** received deliverable → **ACCEPTED** — both gates pass: our vendor signed it
+     **and** the bytes on disk are byte-identical to what was signed (`manifestBindsAttestation=true`).
+   - **[4b]** the received deliverable with **one file corrupted on disk** → **REJECTED** — the vendor
+     signature over the **original** bytes is **still genuine** and the pin **still** matches; only the
+     on-disk bytes drifted, so `manifestBindsAttestation=false`. This is the **real fraud** the buyer cares
+     about — a **genuine our-vendor signature attached to a substituted download** — and it is the case the
+     signature-only path (1–3) **cannot** catch. The on-disk binding does.
+
+It leads with the standing **trust note** (a valid **signature** proves *who vouched* — the pinned address's
+key-holder — for those exact sealed bytes; it does **not** prove a trusted timestamp and is **not** a legal
+opinion — timestamping rides the human-owned trust-root, `needs-human`, P-3 in
+[`../STRATEGY.md`](../STRATEGY.md)), prints a clear **PASS** summary, and exits 0. The received deliverable
+is written to a **throwaway OS temp dir** (never the repo tree) and cleaned up in a `finally`. Verification
+is **offline and key-free**: it recovers a **public** address from the signature, holds no private key, and
+contacts nothing. It is test-gated by [`test/sdk.example.signed.test.js`](../test/sdk.example.signed.test.js)
+on every `npx hardhat test` — a grep there asserts the example imports **only** `require("verifyhash")` +
+relative files, with **no** deep `cli/*` import, **no** `child_process`, **no** built-in, and **no** network,
+and a snapshot check asserts it leaves no temp dir in the repo — so the "in-process public verify stands
+alone" claim can never silently rot.
+
+## `run.js` — the end-to-end DataLedger + ProofParcel buyer pipeline
+
+One command, zero setup, fully offline:
+
+```bash
+node examples/run.js
+```
+
+This drives the **real** DataLedger + ProofParcel buyer pipeline against the tiny committed sample data
+in this directory, using the **same module entrypoints the `vh` CLI dispatches to** (`cli/dataset.js`,
+`cli/parcel.js`) — it is not a brittle shell pipeline of string parsing. It prints a clear **PASS/FAIL**
+summary with the produced artifact paths.
+
+## What it runs
+
+- **DataLedger:** `dataset build` → `check --policy` (a PASS against a lenient policy **and** a FAIL
+  against a strict one) → `verify` (a MATCH against the untouched sample **and** a MISMATCH after a
+  one-byte tamper) → `report` (one filed evidence document) → `attest` (the canonical UNSIGNED bytes).
+- **ProofParcel:** `parcel build` → `verify` (MATCH **and** a tamper MISMATCH) → `attest`.
+
+The sample contains **deliberate** problems so the gates have something real to catch:
+
+- `vendored/gpl-snippet.txt` carries a `GPL-3.0` license hint → flagged by `denyLicenses`.
+- `data/unlabeled.txt` carries no license hint → flagged by `requireLicense`.
+
+## Where it writes
+
+The committed sample under `examples/` is **read-only** to the script. Everything it produces (manifests,
+the report, the unsigned attestation bytes, and the working copies it deliberately tampers) goes to a
+fresh **OS temp dir**. Override the location with `VH_EXAMPLE_OUT=/some/path`; keep the artifacts for
+inspection with `VH_EXAMPLE_KEEP=1`. **Nothing is ever scattered into the repo working tree.**
+
+## Trust posture (read this — the script will not let you forget it)
+
+The example proves **tamper-evidence** (any edit, rename, add, or remove flips the Merkle root) and emits
+the canonical **UNSIGNED** attestation bytes a trust-root would sign. It does **not**, and cannot, prove
+*"unaltered since date T"*: that standing claim rides the **human-owned** signing / timestamp / anchor
+trust-root (`needs-human`, P-3 in [`STRATEGY.md`](../STRATEGY.md)). The script **references but never
+executes** those `sign` / `timestamp` / anchor steps, and says exactly where the human handoff is. See
+[`docs/TRUST-BOUNDARIES.md`](../docs/TRUST-BOUNDARIES.md), [`docs/DATALEDGER.md`](../docs/DATALEDGER.md),
+and [`docs/PROOFPARCEL.md`](../docs/PROOFPARCEL.md).
+
+## It cannot rot
+
+`test/cli.examples.test.js` runs this example end-to-end against the committed sample on every
+`npx hardhat test`, asserting the pipeline completes, the policy violation is flagged, the tamper is
+caught, and the run leaves the working tree clean.
+
+
+---
+<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/examples/policy.lenient.json

@@ -0,0 +1,5 @@
+{
+  "kind": "verifyhash.dataset-policy",
+  "schemaVersion": 1,
+  "denyLicenses": ["AGPL-3.0"]
+}

package/examples/policy.strict.json

@@ -0,0 +1,6 @@
+{
+  "kind": "verifyhash.dataset-policy",
+  "schemaVersion": 1,
+  "denyLicenses": ["GPL-3.0", "AGPL-3.0"],
+  "requireLicense": true
+}