@ziffer-io/verify 0.1.0 → 0.1.1

package/README.md

@@ -1,121 +1,71 @@
 # @ziffer-io/verify
 
-The **third implementation** of ACP receipt verification. The first two live in the
-engine repository at the pin this workspace's `Cargo.toml` names: the Python reference
-(`reference/src/acp_executor.py`, the readable §9.3 checklist) and Rust
-(`crates/acp-decision`, the production decision path). This package lives in ziffer
-**only because the engine repository is publicly frozen and ziffer CI cannot reach new
-engine commits**; the mirrored corpus in `fixtures/` plus `tools/check-verify-mirror.py`
-is what keeps three copies of one rule honest. Engine-home for this package is revisited
-if the freeze lifts.
+Verify a ZIFFER decision receipt in your own process, against a key you configured yourself.
+
+## Install
 
 ```bash
 npm install @ziffer-io/verify
 ```
 
-Most integrations do not install this directly. `@ziffer-io/client` depends on it and re-exports
-`verifyReceipt`, so there is one verifier in your dependency tree rather than two that can
-disagree. Install it on its own when you verify receipts and never call the API.
+Node 22 or later. If you also call the ZIFFER API, install `@ziffer-io/client` instead. It
+depends on this package and re-exports `verifyReceipt`, so one verifier is in your tree.
 
-## What it does
+## Quickstart
 
 ```ts
-import { verifyReceipt, Refusal } from '@ziffer-io/verify';
-
-const verified = verifyReceipt(receiptJson, proposalBytes, {
-  classical, // Ed25519 verification key, 32 bytes, from the signed bundle (PB-12)
-  pq,        // ML-DSA-65 verification key, 1,952 bytes, same home
-  minSuite: 'hybrid-ed25519-mldsa65', // CR-4 floor, from the signed manifest
-});
-// throws Refusal on any defect; verified.proposalHash is the verifier's OWN hash
+import { readFileSync } from 'node:fs';
+import { verifyReceipt, type TrustAnchor } from '@ziffer-io/verify';
+
+const keys = JSON.parse(readFileSync(process.env.ZIFFER_TRUST_ANCHOR, 'utf8'));
+const anchor: TrustAnchor = {
+  classical: Buffer.from(keys.ed25519_pk_hex, 'hex'),
+  pq: Buffer.from(keys.mldsa65_pk_hex, 'hex'),
+  minSuite: process.env.ZIFFER_SUITE_FLOOR,
+};
+
+const proposalBytes = new TextEncoder().encode(JSON.stringify(proposal));
+const verified = verifyReceipt(receipt, proposalBytes, anchor);
+// It returned, so the receipt holds. verified.proposalHash is this verifier's own hash.
+await bank.transfer(amount, toAccount);   // your line, unchanged
 ```
 
-`verifyReceipt` runs exactly the **stateless** portion of the §9.3 checklist — the part
-answerable with only receipt + proposal + identity: AB-0 (receipt version 3 only),
-AB-5/AB-6 (signed-body exclusion and byte cap), CR-1/CR-4/CR-3 (suite known, floor by
-containment, hybrid **conjunctive** — every primitive must verify), 9.3-2 (decision
-domain), 9.3-3 (proposal hash **recomputed** from the caller's own bytes, never read
-from the message — RES-8), 9.3-5/L-14 (temporal position and window ceiling, over
-strictly parsed RFC 3339 UTC instants), WE-4/L-17 (nonce type and size).
-
-A pass means "the stateless set found nothing", never "the receipt may be consumed":
-steps 4 (policy basis), 6's CL-2 claim, 7 (grading recomputation), 7b (the quorum),
-8 (tenant scoping) and 9–10 need the signed bundle, the attester registry, a ledger and
-a context store, and are deliberately absent rather than approximated. The module doc in
-`src/verify.ts` carries the full table and the R/B/T classification.
-
-Every refusal is a thrown `Refusal` whose `clause` is spelled **exactly as the engine's
-Rust clause constants** spell it (`AB-0`, `AB-6`, `CR-1`, `CR-4`, `AT-8a`, `9.3-1`,
-`9.3-2`, `9.3-3`, `9.3-5`, `L-14`, `WE-4`, `L-17`) — the clause is what the three
-implementations are compared on.
-
-## What it does not do
-
-- **It is not a receipt gate.** A pass is "the stateless set found nothing", not "this receipt may
-  be consumed" — the paragraph above lists the six §9.3 steps that need a signed bundle, an
-  attester registry, a ledger and a context store, and are absent rather than approximated.
-- **It fetches nothing and trusts nothing you did not hand it.** The identity keys and the CR-4
-  suite floor are arguments. It will not read them from the receipt, because a verifier that takes
-  a derived security value from the party it is verifying is the defect class this specification
-  has published five corrections for (RES-8).
-- **It does not hash your proposal for you.** You pass the bytes your own code passes to the API,
-  and the verifier recomputes the hash from them. Handing it the hash would verify nothing.
-- **It has no `approve`, and no test mode that mints a receipt.** Signing lives behind keys this
-  package never holds.
-
-## Strict Ed25519, written out
-
-`@noble/curves`' `verify` with `{ zip215: false }` enforces canonical encodings but —
-like OpenSSL — does **not** refuse small-order points. The ACP-106 rule (a small-order
-public key or a small-order `R` makes the verification equation stop mentioning the
-message) is therefore written out in `src/ed25519.ts`, exactly as the Python reference
-writes it in `verify_prim` and Rust gets from `verify_strict`. The mirrored
-`fixtures/refused_ed25519.json` is the executable statement: every vector is accepted by
-RFC 8032 as OpenSSL implements it and refused by all three implementations. Deleting the
-guard here was observed to accept the corpus's `r_is_the_identity_point` vector.
-
-## Canonicalization, proven not transcribed
-
-`src/canon.ts` reproduces the engine canon (sorted keys at every depth by **code
-point** — not JS's UTF-16 unit order — no whitespace, raw UTF-8). The proof is a
-triangle: `fixtures/canon_vectors.json` was generated by importing and executing the
-engine's own `acp_executor.canon` (`fixtures/gen_canon_vectors.py`), the TS tests assert
-byte-identity with the fixture on every case, and `tools/check-verify-mirror.py`
-re-derives every case against the engine at the pin.
-
-**Disclosed divergence (fail-closed):** the engine accepts a float *nested* in a signed
-structure (the ACP-75 bug-for-bug agreement between Python and Rust). This
-implementation refuses any non-integer number at any depth under `AT-8a`, because
-`JSON.parse` collapses `1000.0` and `1000` into one value and reproducing the engine's
-bytes would be a guess about bytes it never saw. Integers beyond `2^53−1` are refused
-for the same reason (the ACP-54 integer-domain family reached from the JS side). No
-conforming wire receipt carries either — every temporal field is an RFC 3339 string
-since v1.3.28 (ACP-167). Both refusals are pinned by tests so the divergence cannot
-vanish silently.
-
-## Fixtures
-
-Byte-identical mirrors of engine files, each with a `.provenance.json` sidecar (source
-path, rev, sha256 — a header *inside* the JSON would change the bytes the identity claim
-is about): `refused_ed25519.json`, `python_signatures.json` (the reference's signatures,
-which this side must accept — the TS leg of `tests/python_interop.rs`' claim; its seeds
-also pin the test-key derivation mirror in `src/testkeys.ts`), and
-`instant-type-vectors.json` (this package is the shared instant corpus's fourth
-consumer). Plus the derived `canon_vectors.json` above. Re-mirror at a pin bump;
-`tools/check-verify-mirror.py` refuses a mirror whose provenance rev is not the
-workspace pin.
-
-## Running
-
-```sh
-pnpm --filter @ziffer-io/verify test        # tsc -b && node --test (27 tests)
-python3 tools/check-verify-mirror.py  # from the repo root; needs ACP_REPO_PATH at the pin
-```
+It reaches no network and trusts nothing it was not handed. The keys and the suite floor are
+arguments you pass in. The proposal hash is recomputed from your bytes, never read from the
+receipt.
+Key order and spacing do not matter, because the verifier canonicalises your bytes itself.
+
+`verifyReceipt` checks the answer. Your own `if` is what stops the action.
+
+## Configuration
+
+| Variable | What it is | Where the value comes from |
+| --- | --- | --- |
+| `ZIFFER_TRUST_ANCHOR` | Path to the public key file your receipts are signed under. | We give you the file. Take it from us, never from the API you are checking. |
+| `ZIFFER_SUITE_FLOOR` | The weakest signature suite you will accept. | You choose it. There is no default. |
+
+## When a request is refused
+
+Every refusal is a thrown `Refusal` whose `clause` names the rule that fired; the table of every
+clause, what it means and what to do is at https://ziffer.io/docs/refusals. Narrow with
+`instanceof Refusal`, record the clause, and do not retry it.
+
+## Documentation
+
+- Quickstart: https://ziffer.io/docs/quickstart
+- Integrating the SDK: https://ziffer.io/docs/developers/sdk
+- Every refusal: https://ziffer.io/docs/refusals
+- The specification: https://ziffer.io/docs/specification
+- Glossary: https://ziffer.io/docs/glossary
+
+## Support
+
+Write to hello@ziffer.io. Your trust anchor file and your suite floor come from us. So does an
+answer about a refusal you cannot explain.
 
-## Licence
+## License
 
-Proprietary. Copyright (c) 2026 code75 SASU, Paris, France. ZIFFER is a registered trademark of code75
-SASU. This package is **not open source**: it is licensed for use with the ZIFFER service under
-your agreement with code75, on the terms in `LICENSE` beside this file. The third-party
-open-source components it redistributes are listed in `THIRD-PARTY-NOTICES` and are governed by
-their own licences.
+Proprietary. Copyright (c) 2026 code75 SASU, Paris, France. ZIFFER is a registered trademark of
+code75 SASU. This package is not open source. Its use is governed by your agreement with code75
+and by `LICENSE` beside this file. The open-source components it redistributes are listed in
+`THIRD-PARTY-NOTICES`, under their own licences.

package/package.json

@@ -1,14 +1,20 @@
 {
   "name": "@ziffer-io/verify",
-  "version": "0.1.0",
-  "description": "ZIFFER receipt verification: the stateless half of the ACP 9.3 checklist, refusals named by clause.",
+  "version": "0.1.1",
+  "description": "Verify a ZIFFER decision receipt in your own process, against a key you configured.",
+  "keywords": [
+    "ziffer",
+    "agent",
+    "ai-agent",
+    "guardrail",
+    "approval",
+    "receipt"
+  ],
   "author": "code75 SASU",
   "license": "SEE LICENSE IN LICENSE",
-  "comment-license": "The SDK is proprietary (code75 SASU). \"license\" is the SPDX escape hatch for exactly this case: there is no SPDX identifier for these terms, so the field points at the file that states them, and LICENSE ships in the tarball beside THIRD-PARTY-NOTICES. Do not put an OSI identifier here -- Apache-2.0 stood in these four files until ACP-214 and was wrong the whole time.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "comment-exports": "The `./dist/*` entry is not laziness and removing it breaks a caller. `exports` is a gate as well as a map: declaring only `.` makes every other path unreachable, and packages/mcp/src/tools.test.ts imports `@ziffer-io/verify/dist/testkeys.js` ON PURPOSE -- testkeys is deliberately absent from index.ts so it cannot be reached by accident, and the deep import is how the MCP package's tests get a signing key without a second definition of one identity. That import resolves today because there is no exports map; adding a `.`-only one would break it at publish time, which is the class of defect an exports map introduces rather than prevents. So the dist is declared addressable, and the reason is here rather than in a reviewer's memory.",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -34,12 +40,9 @@
   "publishConfig": {
     "access": "public"
   },
-  "comment-no-provenance": "There is deliberately no \"provenance\": true here, and it was removed rather than never added. npm generates a provenance attestation only from a recognised CI runner, and its documentation states plainly that provenance is NOT SUPPORTED for private repositories (docs.npmjs.com/trusted-publishers, read 2026-09-03) -- ziffer-hq/ziffer is private (`gh api` says so). Setting the flag does not degrade to a warning: npm attempts the attestation and the publish FAILS, so the field would have broken the operator's very first publish from a laptop and every CI publish after it. tools/release-npm.sh asserts the field stays absent, and that assertion is the thing to delete on the day this repository becomes public -- at which point trusted publishing generates provenance on its own, with no flag at all.",
   "ziffer": {
-    "enginePin": "fed43d10b427e0a4435a8f04e474334d88a5aa6e"
+    "enginePin": "8ae262196dbe75210a975a456785df5d9f0524a3"
   },
-  "comment-enginePin": "The engine commit whose clause spellings, canon and mirrored corpus this implementation is bound to. A COPY of the rev in Cargo.toml, which is the one authority tools/guard.sh reads; tools/release-npm.sh refuses to release when the two differ, by name. tools/bump-pin.sh does not move this field -- see packages/types/package.json for why and what closing it costs.",
-  "comment-deps": "Exactly the two signature primitives, at the versions services/approval already pins -- the DR-2 permitted common set minus the wire types, which this package does not consume: it verifies raw parsed JSON, and typing the wire is the client's (@ziffer-io/client) business. Adding anything else needs written justification (ACP-197 runbook section 5).",
   "dependencies": {
     "@noble/curves": "2.3.0",
     "@noble/post-quantum": "0.7.0"
@@ -51,7 +54,7 @@
   "scripts": {
     "build": "tsc -b",
     "typecheck": "tsc -b",
-    "pretest": "tsc -b && if ! find dist -name '*.test.js' -print -quit | grep -q .; then echo 'ACP-248: no compiled test file under dist/ -- node --test reports 0 tests and exits 0, so this package would go green having run nothing' >&2; exit 1; fi",
+    "pretest": "tsc -b && if ! find dist -name '*.test.js' -print -quit | grep -q .; then echo 'no compiled test file under dist/ -- node --test reports 0 tests and exits 0, so this package would go green having run nothing' >&2; exit 1; fi",
     "test": "tsc -b && node --test \"dist/**/*.test.js\""
   }
 }