diff --git a/README.md b/README.md index 4f09dd2..ea35439 100644 --- a/README.md +++ b/README.md @@ -7,14 +7,35 @@ > Verify CertifiedData.io certificates from the command line. Audit-friendly, zero crypto dependencies. -## Install + verify in three lines +## Verify something real, right now + +No install, no account, nothing of ours on your machine: + +```bash +npx --package @certifieddata/verify cd-verify d6da041f-a70c-4945-93b7-dff1e42a00d0 --type certificate +# → ✓ VALID certification_id d6da041f-a70c-4945-93b7-dff1e42a00d0 +# signed by ed25519-prod-2025-02 (Certified Data LLC) + +npx --package @certifieddata/verify cd-verify 2492a060-8fbc-40ae-beab-7258aefb0608 --type receipt +# → ✓ VALID receipt 2492a060-8fbc-40ae-beab-7258aefb0608 +# settlement succeeded_live +``` + +Both ids are real production artifacts, and both verdicts are computed locally +against the issuer's published key — not read back from our API. If our servers +disagreed with the maths, this tool would side with the maths. + +## Install ```bash npm install -g @certifieddata/verify -certifieddata-verify ce_01HXYZ123abc... --dataset path/to/data.csv -# → ✓ VALID certification_id ce_01HXYZ123abc... +cd-verify --dataset path/to/data.csv ``` +> **On Windows use `cd-verify`, not `verify`.** `verify` is a built-in cmd.exe +> command and shadows the bin, which fails silently with exit 1. The +> `cd-verify` and `certifieddata-verify` aliases work everywhere. + ## What this verifies - **The signature.** An Ed25519 signature over the RFC 8785 JCS canonicalization of the certificate payload. We re-canonicalize, re-verify, and refuse to claim a cert is valid unless the signature checks out. @@ -141,9 +162,12 @@ Receipts are a different artifact from certificates, with a different trust root (`/.well-known/certifieddata-public-key.pem` rather than the keys document). ```bash -npx --package github:certifieddata/verify cd-verify --type receipt +npx --package @certifieddata/verify cd-verify 2492a060-8fbc-40ae-beab-7258aefb0608 --type receipt ``` +That id is a real production receipt for a live 99-cent settlement, so the +command above works as written rather than needing a placeholder substituted. + The canonicalization, the exact bytes that are signed, and the test vectors are specified normatively in **[RECEIPT-VERIFICATION.md](./RECEIPT-VERIFICATION.md)**. It is RFC 8785 (JCS) — not `json-stable-stringify`; the two produce different diff --git a/RECEIPT-VERIFICATION.md b/RECEIPT-VERIFICATION.md index c056da9..8352e4a 100644 --- a/RECEIPT-VERIFICATION.md +++ b/RECEIPT-VERIFICATION.md @@ -119,11 +119,11 @@ Note the key id: **`ed25519-prod-2025-02`**. Some older documentation shows ### Reproduce it ```bash -npx --package github:certifieddata/verify cd-verify 2492a060-8fbc-40ae-beab-7258aefb0608 --type receipt +npx --package @certifieddata/verify cd-verify 2492a060-8fbc-40ae-beab-7258aefb0608 --type receipt ``` > **Windows note:** invoke the `cd-verify` bin explicitly, as above. The short -> form `npx github:certifieddata/verify …` selects the bin named `verify`, and +> form `npx @certifieddata/verify …` selects the bin named `verify`, and > `verify` is a **cmd.exe built-in command** — cmd intercepts the bare name > before PATH is consulted, so on Windows the built-in swallows the invocation > (exit 1, no output). POSIX shells have no such built-in, so the short form @@ -155,15 +155,15 @@ In `fixtures/`: With the repo checked out: ```bash -npx -p github:certifieddata/verify cd-verify fixtures/valid-receipt.json --type receipt # VALID -npx -p github:certifieddata/verify cd-verify fixtures/tampered-receipt.json --type receipt # INVALID +npx -p @certifieddata/verify cd-verify fixtures/valid-receipt.json --type receipt # VALID +npx -p @certifieddata/verify cd-verify fixtures/tampered-receipt.json --type receipt # INVALID ``` Without checking anything out — pipe the fixture in on stdin: ```bash curl -s https://raw.githubusercontent.com/certifieddata/verify/main/fixtures/tampered-receipt.json \ - | npx -p github:certifieddata/verify cd-verify - --type receipt + | npx -p @certifieddata/verify cd-verify - --type receipt # → ✗ INVALID ed25519 signature does not verify against the RFC 8785 canonical payload ```