From ac9fd935e979976e4bd249ae355bddc64a0ad9b4 Mon Sep 17 00:00:00 2001 From: SDS <209957663+dkitchell@users.noreply.github.com> Date: Mon, 14 Sep 2026 19:38:24 -0600 Subject: [PATCH] docs: point install instructions at the published package, and make the hero command actually run MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 0.1.0 is on npm now, so the docs no longer need the pre-publish workaround. Every install instruction pointed at `github:certifieddata/verify` — five in RECEIPT-VERIFICATION.md and the receipt example in the README. That form still works, but it clones and builds rather than fetching 35 kB from the registry, and it is not the command anyone would paste into a terminal on a call. The bigger problem was the hero. It read: npm install -g @certifieddata/verify certifieddata-verify ce_01HXYZ123abc... --dataset path/to/data.csv `ce_01HXYZ123abc...` is not a certificate. Anyone following the README literally — which is the stated bar for this repo — got a failure on the first command they ran, after installing globally to get there. The hero now leads with the zero-install path and two REAL production artifacts, both confirmed working against the published package before being written down: npx --package @certifieddata/verify cd-verify d6da041f-… --type certificate → VALID, signed by ed25519-prod-2025-02 npx --package @certifieddata/verify cd-verify 2492a060-… --type receipt → VALID, settlement succeeded_live Global install is kept, demoted below it, and now shows `cd-verify` with an explicit Windows warning: `verify` is a cmd.exe built-in that shadows the bin and fails silently with exit 1. That is the same trap #7 fixed for the npx form, and the global-install line still had it. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 32 ++++++++++++++++++++++++++++---- RECEIPT-VERIFICATION.md | 10 +++++----- 2 files changed, 33 insertions(+), 9 deletions(-) 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 ```