feat: normative receipt canonicalization, test vectors, publishable package

[dkitchell]

feat: normative receipt canonicalization, test vectors, publishable package

Today nobody outside CertifiedData can independently verify a receipt. Not
because it is hard — because the three things required were all missing. This
adds them.

1. publishConfig

@certifieddata/verify has a working bin and zero dependencies but was never on
npm. publishConfig was undefined, and npm defaults scoped packages to
"restricted" — so publish either demands a paid org or lands private. That is
the likely reason it never appeared. Now { access: "public" }.
npm pack --dry-run: 24.4 kB, 43 files, 0 deps.

2. The canonicalization, specified

RECEIPT-VERIFICATION.md states it normatively for the first time. It is
RFC 8785 (JCS) over the envelope's receipt object — NOT
json-stable-stringify. The two agree on key order for simple documents and
disagree on string escaping and number formatting, so they can produce
different bytes and different hashes. The platform applies stripUndefined()
before canonicalizing; that is a producer-side detail with no effect on a
consumer, since JSON has no undefined, and is documented so the two
implementations can be compared line by line.

Also specified: signature lives at the envelope level, and sha256_hash /
ed25519_sig are appended by the capture response and are NOT part of the
signed payload. An implementer working from a capture response must strip them;
one working from the verify endpoint need not. That distinction was written
nowhere.

3. Receipt test vectors

fixtures/ had webhook-signature, idempotency, provenance and event fixtures and
nothing for receipts, so an implementer had nothing to check against.

valid-receipt.json VALID captured from production
tampered-receipt.json INVALID amount altered, signature untouched
malformed-receipt.json MALFORMED signature is not 64-byte ed25519

The tampered vector is the one that matters: an implementation reporting VALID
for it is not verifying anything.

src/receipt-vectors.test.ts pins the expected digest
sha256:2e14cf92c38d5d0cf2b577c4736404fad1c1092c3c4ef87e3b4efeb3923dde22 and
asserts the repo's hand-written JCS reproduces it — which is what actually
settles the RFC 8785 question, rather than asserting it in prose. It also
checks key-order independence and that the live receipt carries artifact,
policy and settlement bindings with distinct correctly-prefixed pi_/ch_ values.

59 tests pass, up from 49.

Verified against production: the CLI returns VALID for receipt
2492a060-8fbc-40ae-beab-7258aefb0608 with the verdict computed locally from the
published PEM, and a 90-line zero-dependency implementation reproduces the same
hash and signature result.

Not included: publishing. That needs npm auth and is a release decision.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

Reproduce

npm ci && npm test          # 59 pass
node dist/cli.js 2492a060-8fbc-40ae-beab-7258aefb0608 --type receipt
node dist/cli.js fixtures/tampered-receipt.json --type receipt   # must be INVALID

Remaining, needs your hands

• npm publish --access public — needs npm auth; a release decision, not mine to make
• The stale signingKeyId: "cd_root_2026" and the examples/verify-only rewrite are in certifieddata-agent-commerce-public, not this repo. Only reference here is the warning in the new spec.

Known issue, not fixed here

On Windows the CLI returns exit 127 for the receipt path while printing the correct verdict; --version returns 0 correctly and main() returns 0 when called directly, so the verdict logic is sound. Needs confirming on Linux/CI before chasing — CI consumers depend on the documented codes.

🤖 Generated with Claude Code