pazair-verify 1.8.0 → 1.10.0

package/README.md

@@ -4,8 +4,9 @@ Trust between AI agents, checkable by anyone. Verify PazAIr receipts, Word Passe
 (the [PazAIr Trust Protocol](../SPEC.md)) in a few lines, without trusting PazAIr.
 
 Zero dependencies. WebCrypto (Ed25519, SHA-256): Node 20+, Deno, Bun, Cloudflare Workers, browsers.
-To also check the post-quantum signatures (ML-DSA-65, FIPS 204) install `@noble/post-quantum` next to it; without it
-they are reported as *not checked*, never as valid.
+To also check the post-quantum signatures (ML-DSA-65, FIPS 204, on Remember's links and on twice-signed passes,
+receipts and holder proofs) install `@noble/post-quantum` next to it; without it they are reported as *not checked*,
+never as valid.
 
 ```sh
 npm install pazair-verify
@@ -60,18 +61,38 @@ const h = await checkHead('2026-10-10:3f9c…');                  // the head yo
 Nothing here asks the issuer whether its chain is fine. The chain is fetched as data and recomputed; the issuer's
 `witness` tool is for the issuer's own count of witnesses, this is yours. SPEC section 14 has the formulas.
 
-## Fingerprint: no two passes alike, provably
+## Fingerprint: two prints, 55 of 64 symbols apart
 
 Every pass carries a fingerprint (SPEC section 15): a Reed-Solomon codeword over `sha256(origin, agent, first anchored
-leaf)`. Any two agents differ in at least 55 of 64 symbols, a theorem, not a probability. Draw it, compare it:
+leaf)`. Two different prints differ in at least 55 of 64 symbols, a theorem of the code; that two agents get different
+prints is a probability (the print encodes 80 bits of the hash). Identity is origin, agent id and signature; the print
+is how people and agents recognise a pass. Draw it, compare it:
 
 ```js
 import { fingerprintOf, fingerprintDistance, fingerprintSvg, recordOf } from 'pazair-verify';
 const me = await fingerprintOf({ origin: 'https://pazair.kulalabs.ch', agent: 'ag_xyz', first_leaf: doc.fingerprint.first_leaf });
-fingerprintDistance(me, doc.fingerprint);   // 0: the issuer's print is this agent's
+fingerprintDistance(me, doc.fingerprint);   // 0: the issuer drew the print of this origin, agent and leaf
 const svg = fingerprintSvg(me, recordOf(doc.current));   // the same bytes the issuer serves as fingerprint.svg
 ```
 
+## The W3C way: the pass as a Verifiable Credential
+
+An issuer that implements SPEC section 18 serves every pass a second time, as a W3C Verifiable Credential 2.0 with a
+Data Integrity proof (`eddsa-jcs-2022`) from its did:web. A wallet or framework that speaks VCs can hold it; this
+checks the proof, the pass inside and, from the command line, its anchors. It reproduces the W3C Recommendation's own
+`eddsa-jcs-2022` test vector byte for byte.
+
+```sh
+npx pazair-verify credential https://pazair.ch/v1/agents/ag_xyz/pass.vc
+```
+
+```js
+import { verifyCredential } from 'pazair-verify';
+const vc = await (await fetch('https://pazair.ch/v1/agents/ag_xyz/pass.vc')).json();
+const r = await verifyCredential(vc);   // resolves did:web, checks the proof, the subject's origin and the pass inside
+// { valid: true, trust: 'valid', say: '…', issuer: 'did:web:pazair.ch', subject: '<pass URL>', same_key: true, … }
+```
+
 ## Lower level
 
 ```js
@@ -95,16 +116,21 @@ console.log(await verifyReceipt(receipt, { delivery }));
 | `checkHead("<day>:<head>", origin, { fetch? })` | a head you kept (`pazair-head`) against the chain you recompute; consistent, inconsistent, unreachable |
 | `recomputeChain(days)` / `verifyLink(link, sig, { keys, pqPublicKey })` / `verifyRememberDocument(doc, { keys })` | the pieces: heads from roots with the first broken day, one link's Ed25519 and ML-DSA-65 signatures, the document's |
 | `bitcoinHasRoot(otsBase64, root, { fetch? })` | the .ots proof is for this root and ends in the Merkle root of the block it names (public block explorers) |
-| `verifyReceipt(receipt, { keys?, delivery? })` | Ed25519 signature; optionally that `delivery` is the one signed |
+| `verifyReceipt(receipt, { keys?, pqKeys?, delivery? })` | Ed25519 signature, the second signature when present (section 16), optionally that `delivery` is the one signed |
+| `verifyPqSignature(obj, pqKeys?)` | Section 16: `pq_sig` (ML-DSA-65) with the issuer's `pq_keys`; `{ signed, valid }`, valid null when it cannot be checked here |
 | `verifyReceiptChain(top, { receipts, keys?, maxDepth? })` | Section 3.1: every receipt `top` was built on is present, signed, bought by its seller for that order; returns `{ valid, links, depth, total_minor, broken }` |
 | `verifyMandate(receipt, mandate, { keys?, end? })` | Section 3.2: the receipt was bought within the principal's mandate (agent, currency, cap per order, before its end); returns `{ valid, covers, reasons }` |
 | `verifyAward(receipt, tender, award, { keys?, qa? })` | Section 3.3: the receipt was paid under this award for this tender (buyer, awarded seller, budget, price or milestone, deadline, questions published before the award); returns `{ valid, covers, reasons }` |
 | `receiptHash(receipt)` | The hash a parent receipt lists in `inputs` |
-| `fingerprintOf({ origin, agent, first_leaf })` | Section 15: the seed and the 64-byte codeword of an agent's fingerprint; two agents differ in at least 55 symbols |
+| `fingerprintOf({ origin, agent, first_leaf })` | Section 15: the seed and the 64-byte codeword of an agent's fingerprint; two different prints differ in at least 55 symbols |
 | `fingerprintDistance(a, b)` | How many of the 64 symbols differ: 0 the same agent, below 55 not a fingerprint |
 | `fingerprintSvg(codeword, record?)` | The reference drawing, the same bytes for the same input; `recordOf(pass)` reads the record it grows with |
-| `verifyPass(anchored, { keys? })` | signature, Merkle proof into the day's root; returns the anchors to check on Bitcoin and Stellar |
+| `verifyPass(anchored, { keys?, pqKeys? })` | signature, the second signature when present, Merkle proof into the day's root; returns the anchors to check on Bitcoin and Stellar |
 | `verifyProof(leaf, proof, root)` | a Merkle path |
+| `buyerWordOf(pass)` | Section 4, the buyer's word: `kept_pct` and `pays_99` / `pays_95` from `as_buyer` (paid orders, chargebacks); `checkWordPass` returns it as `buyer_trust` next to the seller's `trust` |
+| `verifyCredential(vc, { fetch?, didDocument?, keysDocument?, now? })` | Section 18: the pass as a W3C Verifiable Credential: VC 2.0, the did:web resolved, the `eddsa-jcs-2022` proof, the subject on the issuer's origin, `validFrom`/`validUntil`, the pass inside; a verdict and a sentence |
+| `verifyDataIntegrity(doc, didDocument)` / `signDataIntegrity(doc, privateKey, verificationMethod, created?)` | any W3C Data Integrity proof with `eddsa-jcs-2022`, checked or made (the W3C Recommendation's vector holds) |
+| `resolveDidWeb(did, fetch?)`, `didWebUrl(did)`, `multikeyOf(x)`, `multikeyToX(multibase)`, `base58btcEncode`/`base58btcDecode` | did:web, Multikey (Ed25519) and base58btc, the pieces of section 18 |
 | `leafOf(pass)`, `canonical(obj)`, `sha256hex(s)` | the building blocks of the spec |
 | `fetchKeys(origin?)` | the issuer's keys from `/.well-known/pazair-receipts.json` |
 

package/bin/cli.js

@@ -2,9 +2,10 @@
 // npx pazair-verify <word pass url> [--json]: "May I see your Word Pass?", checked from the command line.
 // npx pazair-verify remember [origin] [--json]: Remember, the issuer's chain of daily roots, recomputed here.
 // npx pazair-verify witness <day:head> [origin] [--json]: a head you kept, against the chain you recompute.
+// npx pazair-verify credential <credential url or file> [--json]: the Word Pass as a W3C Verifiable Credential (SPEC 18), then its anchors.
 // Exit codes: 0 trusted / consistent, 1 invalid / inconsistent (do not rely on it), 2 usage, 3 unreachable (could not check).
 import { readFileSync } from 'node:fs';
-import { checkHead, checkRemember, checkWordPass } from '../src/index.js';
+import { checkHead, checkRemember, checkWordPass, verifyCredential } from '../src/index.js';
 
 const args = process.argv.slice(2);
 if (args.includes('-v') || args.includes('--version')) {
@@ -14,10 +15,10 @@ if (args.includes('-v') || args.includes('--version')) {
 const words = args.filter((a) => !a.startsWith('-'));
 const help = args.includes('-h') || args.includes('--help');
 const json = args.includes('--json');
-const usage = 'Usage: npx pazair-verify <word pass url> [--json]\n       npx pazair-verify remember [origin] [--json]\n       npx pazair-verify witness <day:head> [origin] [--json]\nExamples: npx pazair-verify https://pazair.kulalabs.ch/v1/agents/ag_xyz/pass\n          npx pazair-verify remember https://pazair.kulalabs.ch\n          npx pazair-verify witness 2026-10-10:3f9c… https://pazair.kulalabs.ch';
+const usage = 'Usage: npx pazair-verify <word pass url> [--json]\n       npx pazair-verify remember [origin] [--json]\n       npx pazair-verify witness <day:head> [origin] [--json]\n       npx pazair-verify credential <credential url or file> [--json]\nExamples: npx pazair-verify https://pazair.kulalabs.ch/v1/agents/ag_xyz/pass\n          npx pazair-verify remember https://pazair.kulalabs.ch\n          npx pazair-verify witness 2026-10-10:3f9c… https://pazair.kulalabs.ch\n          npx pazair-verify credential https://pazair.ch/v1/agents/ag_xyz/pass.vc';
 if (!words.length || help) { (help ? console.log : console.error)(usage); process.exit(help ? 0 : 2); }
 const clean = (s) => String(s).replace(/[\u0000-\u001f\u007f-\u009f]/g, '?'); // nothing from the network rewrites your terminal
-const codes = { consistent: 0, kept_its_word: 0, no_badge_yet: 0, signed_unanchored: 0, inconsistent: 1, invalid: 1, unreachable: 3 };
+const codes = { valid: 0, consistent: 0, kept_its_word: 0, no_badge_yet: 0, signed_unanchored: 0, inconsistent: 1, invalid: 1, unreachable: 3 };
 
 if (words[0] === 'remember') {
   const r = await checkRemember(words[1] ?? 'https://pazair.kulalabs.ch');
@@ -32,6 +33,21 @@ if (words[0] === 'witness') {
   if (json) console.log(JSON.stringify(r, null, 2));
   process.exit(codes[r.verdict] ?? 1);
 }
+if (words[0] === 'credential') {
+  if (!words[1]) { console.error(usage); process.exit(2); }
+  let vc;
+  try {
+    if (/^https:\/\//.test(words[1])) { const res = await fetch(words[1], { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(8000) }); if (!res.ok) throw new Error(); vc = await res.json(); }
+    else vc = JSON.parse(readFileSync(words[1], 'utf8'));
+  } catch { console.log(clean(`No credential could be read at ${words[1]}.`)); process.exit(3); }
+  const r = await verifyCredential(vc);
+  console.log(clean(r.say));
+  // Proof and pass hold: then the day's root on Bitcoin and Stellar, at the pass URL the credential names.
+  const anchors = r.valid ? await checkWordPass(r.subject) : null;
+  if (anchors) console.log(clean(anchors.say));
+  if (json) console.log(JSON.stringify({ ...r, anchors: anchors ? { ...anchors, pass: undefined } : null }, null, 2));
+  process.exit(!r.valid ? (codes[r.trust] ?? 1) : (codes[anchors.trust] ?? 1));
+}
 const r = await checkWordPass(words[0]);
 console.log(clean(r.say));
 if (json) console.log(JSON.stringify({ ...r, pass: undefined }, null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pazair-verify",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "Verify Word Passes, receipts, Merkle proofs and Remember (the chain of daily roots, Ed25519 + ML-DSA-65): checked by anyone, for any issuer, without trusting it. Zero dependencies.",
   "type": "module",
   "main": "./src/index.js",
@@ -30,7 +30,9 @@
     "@noble/post-quantum": ">=0.7.0"
   },
   "peerDependenciesMeta": {
-    "@noble/post-quantum": { "optional": true }
+    "@noble/post-quantum": {
+      "optional": true
+    }
   },
   "keywords": [
     "word-pass",

package/src/credential.js

@@ -0,0 +1,159 @@
+// The Word Pass as a W3C Verifiable Credential 2.0 (SPEC section 18): the issuer as did:web, a Data Integrity proof
+// (cryptosuite eddsa-jcs-2022) around the pass document of section 5. Zero dependencies, WebCrypto Ed25519.
+// A VC verifier checks the proof without knowing Word Pass; this module checks the proof and the pass inside.
+import { canonical, fetchKeysDocument, sayPass, verifyPass } from './index.js';
+
+const enc = new TextEncoder();
+const B58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+const b64u = (b) => btoa(String.fromCharCode(...new Uint8Array(b))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+const unb64u = (s) => Uint8Array.from(atob(s.replace(/-/g, '+').replace(/_/g, '/') + '==='.slice((s.length + 3) % 4)), (c) => c.charCodeAt(0));
+const sha256 = async (s) => new Uint8Array(await crypto.subtle.digest('SHA-256', enc.encode(s)));
+const same = (a, b) => { try { return canonical(a) === canonical(b); } catch { return false; } };
+
+/** Base58 with the Bitcoin alphabet, as multibase "z" writes it. */
+export function base58btcEncode(bytes) {
+  let n = 0n;
+  for (const b of bytes) n = n * 256n + BigInt(b);
+  let s = '';
+  while (n > 0n) { s = B58[Number(n % 58n)] + s; n /= 58n; }
+  for (const b of bytes) { if (b !== 0) break; s = '1' + s; }
+  return s;
+}
+
+export function base58btcDecode(s) {
+  let n = 0n;
+  for (const c of String(s)) { const i = B58.indexOf(c); if (i < 0) throw new Error('not base58btc'); n = n * 58n + BigInt(i); }
+  const out = [];
+  while (n > 0n) { out.unshift(Number(n % 256n)); n /= 256n; }
+  for (const c of String(s)) { if (c !== '1') break; out.unshift(0); }
+  return Uint8Array.from(out);
+}
+
+/** An Ed25519 public key (JWK x) as a Multikey: "z" + base58btc(0xed 0x01 + the 32 key bytes). */
+export function multikeyOf(x) {
+  const raw = unb64u(x), b = new Uint8Array(2 + raw.length);
+  b[0] = 0xed; b[1] = 0x01; b.set(raw, 2);
+  return 'z' + base58btcEncode(b);
+}
+
+/** The Ed25519 key (JWK x) in a Multikey, or null when it is not one. */
+export function multikeyToX(mb) {
+  if (typeof mb !== 'string' || mb[0] !== 'z') return null;
+  let b;
+  try { b = base58btcDecode(mb.slice(1)); } catch { return null; }
+  return b.length === 34 && b[0] === 0xed && b[1] === 0x01 ? b64u(b.slice(2)) : null;
+}
+
+/** did:web:<host>[:path] → the https URL of its DID document (did:web method, read operation). */
+export function didWebUrl(did) {
+  const m = /^did:web:([^:#?/]+)((?::[^:#?/]+)*)$/.exec(String(did));
+  if (!m) throw new Error('not a did:web');
+  const host = decodeURIComponent(m[1]);
+  if (!/^[a-z0-9.-]+(:\d{1,5})?$/i.test(host)) throw new Error('did:web: not a host');
+  const segs = m[2] ? m[2].slice(1).split(':').map(decodeURIComponent) : ['.well-known'];
+  if (segs.some((x) => !x || x === '.' || x === '..' || /[/\\?#]/.test(x))) throw new Error('did:web: not a path');
+  return `https://${host}/${segs.join('/')}/did.json`;
+}
+
+/** Fetch a did:web document; it must name the DID it was fetched for. */
+export async function resolveDidWeb(did, f = fetch) {
+  const r = await f(didWebUrl(did), { headers: { accept: 'application/did+json, application/json' }, signal: AbortSignal.timeout(8000) });
+  if (!r.ok) throw new Error(`did: HTTP ${r.status}`);
+  const doc = await r.json();
+  if (doc?.id !== did) throw new Error('did: the document is for another DID');
+  return doc;
+}
+
+/** The Ed25519 key (JWK x) a DID document lists for assertions under this id, or null. */
+function assertionKey(didDocument, vmId) {
+  const listed = (didDocument?.assertionMethod ?? []).map((m) => (typeof m === 'string' ? m : m?.id));
+  if (!listed.includes(vmId)) return null;
+  const vm = [...(didDocument.verificationMethod ?? []), ...(didDocument.assertionMethod ?? []).filter((m) => typeof m === 'object')].find((m) => m?.id === vmId);
+  if (!vm || (vm.controller !== undefined && vm.controller !== didDocument.id)) return null;
+  if (vm.publicKeyMultibase) return multikeyToX(vm.publicKeyMultibase);
+  const j = vm.publicKeyJwk;
+  return j?.kty === 'OKP' && j.crv === 'Ed25519' && typeof j.x === 'string' && !j.d ? j.x : null;
+}
+
+/**
+ * A Data Integrity proof with cryptosuite eddsa-jcs-2022 (W3C Recommendation), checked against a DID document:
+ * Ed25519 over sha256(JCS(proof without proofValue)) || sha256(JCS(document without proof)). The canonical JSON of
+ * section 1 is JCS for these documents. Returns { valid, reason, verificationMethod }.
+ */
+export async function verifyDataIntegrity(doc, didDocument) {
+  const no = (reason) => ({ valid: false, reason, verificationMethod: doc?.proof?.verificationMethod ?? null });
+  const proof = doc?.proof;
+  if (!proof || typeof proof !== 'object' || Array.isArray(proof)) return no('no proof (one Data Integrity proof is expected)');
+  const { proofValue, ...config } = proof;
+  if (config.type !== 'DataIntegrityProof' || config.cryptosuite !== 'eddsa-jcs-2022') return no('not an eddsa-jcs-2022 Data Integrity proof');
+  if (config.proofPurpose !== 'assertionMethod') return no('the proof is not for assertionMethod');
+  if (config.created !== undefined && !(Date.parse(config.created) > 0)) return no('created is not a date');
+  if (typeof proofValue !== 'string' || proofValue[0] !== 'z') return no('proofValue is not multibase base58btc');
+  const { proof: _proof, ...unsecured } = doc;
+  if (config['@context'] !== undefined) {
+    // The proof's context must be where the document's context starts, in the same order; it then stands for it.
+    const dc = [].concat(unsecured['@context'] ?? []), pc = [].concat(config['@context']);
+    if (pc.length > dc.length || pc.some((c, i) => !same(c, dc[i]))) return no('the proof @context is not the document @context');
+    unsecured['@context'] = config['@context'];
+  }
+  const vmId = String(config.verificationMethod ?? '');
+  if (!didDocument?.id || !vmId.startsWith(`${didDocument.id}#`)) return no('the key is not one of the DID document');
+  const x = assertionKey(didDocument, vmId);
+  if (!x) return no('the DID document lists no Ed25519 assertion key under that id');
+  let sig;
+  try { sig = base58btcDecode(proofValue.slice(1)); } catch { return no('proofValue is not base58btc'); }
+  if (sig.length !== 64) return no('proofValue is not an Ed25519 signature');
+  try {
+    const data = new Uint8Array(64);
+    data.set(await sha256(canonical(config)), 0);
+    data.set(await sha256(canonical(unsecured)), 32);
+    const key = await crypto.subtle.importKey('jwk', { kty: 'OKP', crv: 'Ed25519', x }, { name: 'Ed25519' }, false, ['verify']);
+    const ok = await crypto.subtle.verify({ name: 'Ed25519' }, key, sig, data);
+    return ok ? { valid: true, reason: 'ok', verificationMethod: vmId } : no('the signature does not match the key');
+  } catch {
+    return no('the document cannot be checked (not canonical JSON)');
+  }
+}
+
+/**
+ * A Word Pass credential (SPEC 18): the Data Integrity proof against the issuer's did:web document, the subject a
+ * pass URL on the issuer's own origin, and the pass inside checked as section 5 says (signature, Merkle proof,
+ * word), with the keys document of the same origin. The anchors on Bitcoin and Stellar are checkWordPass's job:
+ * call it with `subject`. Returns { valid, trust, say, issuer, subject, proof, pass, same_key }.
+ */
+export async function verifyCredential(vc, { fetch: f = fetch, didDocument, keysDocument, now = Date.now() } = {}) {
+  const out = (trust, say, extra = {}) => ({ valid: trust === 'valid', trust, say, issuer: typeof vc?.issuer === 'string' ? vc.issuer : null, subject: vc?.credentialSubject?.id ?? null, proof: null, pass: null, same_key: null, ...extra });
+  if (!vc || typeof vc !== 'object' || [].concat(vc['@context'] ?? [])[0] !== 'https://www.w3.org/ns/credentials/v2') return out('invalid', 'This is not a Verifiable Credential 2.0.');
+  if (!Array.isArray(vc.type) || !vc.type.includes('VerifiableCredential') || !vc.type.includes('WordPassCredential')) return out('invalid', 'This credential is not a Word Pass credential.');
+  const issuer = vc.issuer;
+  let origin;
+  try { origin = new URL(didWebUrl(issuer)).origin; } catch { return out('invalid', 'The issuer of a Word Pass credential is a did:web.'); }
+  let dd = didDocument, kd = keysDocument;
+  try { dd ??= await resolveDidWeb(issuer, f); } catch { return out('unreachable', `The DID document of ${issuer} could not be read.`); }
+  const proof = await verifyDataIntegrity(vc, dd);
+  if (!proof.valid) return out('invalid', `Do not rely on this credential: ${proof.reason}.`, { proof });
+  const { id: subject, wordPass } = vc.credentialSubject ?? {};
+  const pass = wordPass?.pass;
+  let u;
+  try { u = new URL(subject); } catch { u = null; }
+  if (!u || u.protocol !== 'https:' || u.origin !== origin) return out('invalid', `Do not rely on this credential: its subject is not a pass URL on ${origin}.`, { proof });
+  if (pass?.kind !== 'word_pass') return out('invalid', 'Do not rely on this credential: it carries no Word Pass.', { proof });
+  if (vc.validUntil !== undefined && !(Date.parse(vc.validUntil) >= now)) return out('invalid', 'Do not rely on this credential: it has expired (validUntil).', { proof });
+  if (vc.validFrom !== undefined && !(Date.parse(vc.validFrom) <= now + 300_000)) return out('invalid', 'Do not rely on this credential: it is not valid yet (validFrom).', { proof });
+  try { kd ??= await fetchKeysDocument(origin, f); } catch { return out('unreachable', `${u.host} publishes no keys at /.well-known/pazair-receipts.json.`, { proof }); }
+  const v = await verifyPass(wordPass, { keys: kd.keys ?? [], pqKeys: kd.pq_keys });
+  const passKey = (kd.keys ?? []).find((k) => k.kid === pass.kid);
+  const same_key = !!passKey && passKey.x === assertionKey(dd, proof.verificationMethod);
+  if (!v.valid) return out('invalid', `Do not rely on this credential: the Word Pass inside does not verify (${!v.signature_valid ? 'signature' : v.ml_dsa_65 === false ? 'second signature' : v.in_root === false ? 'Merkle proof' : 'badge'}).`, { proof, pass: v, same_key });
+  const where = v.in_root ? `in the Merkle root of ${v.anchors.day}` : 'signed today, not anchored yet';
+  return out('valid', `${sayPass(pass, u.host)} Credential by ${issuer}: proof eddsa-jcs-2022 valid, pass signature valid${v.ml_dsa_65 ? ' (Ed25519 and ML-DSA-65)' : ''}, ${where}. Anchors on Bitcoin and Stellar: checkWordPass(${subject}).`, { proof, pass: v, same_key });
+}
+
+/** For issuers (and the test vector): sign a document with eddsa-jcs-2022. `priv` is an Ed25519 CryptoKey. */
+export async function signDataIntegrity(doc, priv, verificationMethod, created = new Date()) {
+  const proof = { ...(doc['@context'] !== undefined ? { '@context': doc['@context'] } : {}), type: 'DataIntegrityProof', cryptosuite: 'eddsa-jcs-2022', created: created.toISOString().replace(/\.\d{3}Z$/, 'Z'), verificationMethod, proofPurpose: 'assertionMethod' };
+  const data = new Uint8Array(64);
+  data.set(await sha256(canonical(proof)), 0);
+  data.set(await sha256(canonical(doc)), 32);
+  return { ...doc, proof: { ...proof, proofValue: 'z' + base58btcEncode(new Uint8Array(await crypto.subtle.sign({ name: 'Ed25519' }, priv, data))) } };
+}

package/src/fingerprint.js

@@ -1,7 +1,9 @@
-// Fingerprint (SPEC section 15): a print no other agent can carry, provably.
+// Fingerprint (SPEC section 15): two different prints differ in at least 55 of 64 symbols, provably.
 // seed = sha256(origin "\n" agent "\n" first_leaf); the first 10 bytes are the message of a Reed-Solomon code over
-// GF(256) with n = 64, k = 10, so any two prints differ in at least d = n - k + 1 = 55 of 64 symbols. Each symbol is
-// one sector of the drawing. The record is drawn over it and never changes the identity.
+// GF(256) with n = 64, k = 10, so any two prints of different messages differ in at least d = n - k + 1 = 55 of 64
+// symbols. Seeds that share their first 10 bytes share the print: that two agents get different messages is a
+// probability (80 bits of a hash), not part of the theorem. Each symbol is one sector of the drawing. The record is
+// drawn over it and never changes the identity.
 import { sha256hex } from './index.js';
 
 const N = 64, K = 10, POLY = 0x11d;
@@ -33,7 +35,7 @@ export async function fingerprintOf({ origin, agent, first_leaf }) {
   return { seed, codeword: hex(rsEncode(unhex(seed))) };
 }
 
-/** How many of the 64 symbols differ. For two different seeds this is never below 55. */
+/** How many of the 64 symbols differ: 0 for the same message, never 1 to 54 for two fingerprints of section 15. */
 export function fingerprintDistance(a, b) {
   const x = unhex(a.codeword ?? a), y = unhex(b.codeword ?? b);
   if (x.length !== N || y.length !== N) throw new TypeError('fingerprintDistance: a codeword has 64 bytes');

package/src/index.d.ts

@@ -1,24 +1,30 @@
 export type Jwk = { kid: string; kty?: string; crv?: string; x: string; revoked_at?: string };
+/** Section 16: an ML-DSA-65 public key as the keys document lists it under pq_keys. */
+export type PqKey = { pq_kid: string; alg?: 'ML-DSA-65'; public_key_b64url: string; revoked_at?: string };
 export type Step = { side: 'L' | 'R'; hash: string };
 export function canonical(v: unknown): string;
 export function sha256hex(s: string): Promise<string>;
 export function fetchKeys(origin?: string, f?: typeof fetch): Promise<Jwk[]>;
 export function verifySignature(obj: { sig?: string; kid?: string } & Record<string, unknown>, keys: Jwk[], opts?: { anchoredBefore?: string }): Promise<boolean>;
-export function fetchKeysDocument(origin?: string, f?: typeof fetch): Promise<{ keys: Jwk[]; anchors?: { stellar?: { account: string; network: string } } }>;
-export function verifyHolderProof(proof: unknown, opts: { keys?: Jwk[]; agent: string; nonce: string; aud?: string; now?: number }): Promise<{ ok: boolean; reason: string }>;
-export function verifyReceipt(receipt: Record<string, unknown>, opts?: { keys?: Jwk[]; delivery?: unknown }): Promise<{ valid: boolean; signature_valid: boolean; delivery_matches: boolean | null }>;
+export function fetchKeysDocument(origin?: string, f?: typeof fetch): Promise<{ keys: Jwk[]; pq_keys?: PqKey[]; anchors?: { stellar?: { account: string; network: string } } }>;
+export function verifyHolderProof(proof: unknown, opts: { keys?: Jwk[]; pqKeys?: PqKey[]; agent: string; nonce: string; aud?: string; now?: number }): Promise<{ ok: boolean; reason: string }>;
+export function verifyReceipt(receipt: Record<string, unknown>, opts?: { keys?: Jwk[]; pqKeys?: PqKey[]; delivery?: unknown }): Promise<{ valid: boolean; signature_valid: boolean; pq_signed: boolean; ml_dsa_65: boolean | null; delivery_matches: boolean | null }>;
 export function wordOf(pass: Record<string, unknown>): { kept_pct: number | null; badge: 'word_kept_99' | 'word_kept_95' | null };
+/** SPEC section 4, the buyer's word: from as_buyer (paid orders, chargebacks); pays_99 / pays_95 from 10 paid orders and 5 sellers. */
+export function buyerWordOf(pass: Record<string, unknown>): { kept_pct: number | null; badge: 'pays_99' | 'pays_95' | null };
 export function verifyMandate(receipt: Record<string, unknown>, mandate: Record<string, unknown>, opts?: { keys?: Jwk[]; end?: Record<string, unknown> }): Promise<{ valid: boolean; covers: string[]; reasons: string[] }>;
 export function verifyAward(receipt: Record<string, unknown>, tender: Record<string, unknown>, award: Record<string, unknown>, opts?: { keys?: Jwk[]; qa?: Record<string, unknown>[] }): Promise<{ valid: boolean; covers: string[]; reasons: string[] }>;
 export function receiptHash(receipt: Record<string, unknown>): Promise<string>;
 export function verifyReceiptChain(top: Record<string, unknown>, opts?: { receipts?: Record<string, unknown>[]; keys?: Jwk[]; maxDepth?: number }): Promise<{ valid: boolean; links: number; depth: number; total_minor: Record<string, number>; broken: string | null }>;
 export function leafOf(pass: Record<string, unknown>): Promise<string>;
 export function verifyProof(leaf: string, proof: Step[], root: string): Promise<boolean>;
-export function verifyPass(anchored: Record<string, unknown>, opts?: { keys?: Jwk[]; anchoredBefore?: string }): Promise<{ valid: boolean; signature_valid: boolean; word_consistent: boolean; in_root: boolean | null; word: unknown; anchors: { root: string; day: string; bitcoin_ots: string | null; stellar_tx: string | null } | null }>;
+export function verifyPass(anchored: Record<string, unknown>, opts?: { keys?: Jwk[]; pqKeys?: PqKey[]; anchoredBefore?: string }): Promise<{ valid: boolean; signature_valid: boolean; pq_signed: boolean; ml_dsa_65: boolean | null; word_consistent: boolean; in_root: boolean | null; word: unknown; anchors: { root: string; day: string; bitcoin_ots: string | null; stellar_tx: string | null } | null }>;
 export type PassCheck = {
   trust: 'kept_its_word' | 'signed_unanchored' | 'no_badge_yet' | 'invalid' | 'unreachable';
+  /** The buyer's word (SPEC 4), for whoever sells to this agent; absent when the pass is invalid or unreachable. */
+  buyer_trust?: 'pays_its_way' | 'signed_unanchored' | 'no_buyer_badge_yet';
   say: string; issuer: string | null;
-  checks: { signature: boolean; in_root: boolean | null; day: string | null; stellar: boolean | null; stellar_account_bound: boolean; bitcoin_ots: boolean; bitcoin: boolean | null; bitcoin_block?: BitcoinBlock; holder: boolean | null; word: boolean } | null;
+  checks: { signature: boolean; ml_dsa_65: boolean | null; in_root: boolean | null; day: string | null; stellar: boolean | null; stellar_account_bound: boolean; bitcoin_ots: boolean; bitcoin: boolean | null; bitcoin_block?: BitcoinBlock; holder: boolean | null; word: boolean } | null;
   pass: Record<string, unknown> | null;
 };
 export type BitcoinBlock = { height: number; hash: string; time: string };
@@ -44,15 +50,41 @@ export type RememberCheck = { verdict: 'consistent' | 'inconsistent' | 'unreacha
 export function checkRemember(origin?: string, opts?: { fetch?: typeof fetch }): Promise<RememberCheck>;
 export function checkHead(kept: string, origin?: string, opts?: { fetch?: typeof fetch }): Promise<{ verdict: 'consistent' | 'inconsistent' | 'unreachable'; day?: string; kept?: string; recomputed?: string | null; published?: string | null; days_since?: number; say: string }>;
 
-// Fingerprint (SPEC section 15): a print no other agent can carry, provably.
+// Fingerprint (SPEC section 15): two different prints differ in at least 55 of 64 symbols, provably.
 export const FINGERPRINT: { n: 64; k: 10; d: 55; field: string; generator: string };
 export function rsEncode(msg: Uint8Array): Uint8Array;
 export type Fingerprint = { seed: string; codeword: string };
 export function fingerprintOf(input: { origin: string; agent: string; first_leaf: string }): Promise<Fingerprint>;
-/** Symbols that differ, 0 … 64; never below 55 for two different seeds. */
+/** Symbols that differ, 0 … 64: 0 for the same message (the first 10 bytes of the seed), otherwise at least 55. */
 export function fingerprintDistance(a: Fingerprint | string, b: Fingerprint | string): number;
 export type FingerprintRecord = { delivered: number; buyers: number; badge: string | null; disputes_lost: number };
 export function recordOf(pass: Record<string, unknown>): FingerprintRecord;
 export function ridgesOf(delivered: number): number;
 /** The reference drawing, the same bytes for the same input. */
 export function fingerprintSvg(codeword: Fingerprint | string, record?: FingerprintRecord, opts?: { size?: number; ink?: string; gold?: string; background?: string }): string;
+
+// The second signature (SPEC section 16).
+/** { signed: false } without pq_sig; valid true / false, or null when it cannot be checked here (library missing, key not published). */
+export function verifyPqSignature(obj: Record<string, unknown>, pqKeys?: PqKey[], opts?: { anchoredBefore?: string }): Promise<{ signed: boolean; valid: boolean | null }>;
+
+// The Word Pass as a W3C Verifiable Credential 2.0 (SPEC section 18).
+export type DidDocument = { id: string; verificationMethod?: Record<string, unknown>[]; assertionMethod?: (string | Record<string, unknown>)[]; [k: string]: unknown };
+export function base58btcEncode(bytes: Uint8Array): string;
+export function base58btcDecode(s: string): Uint8Array;
+/** An Ed25519 public key (JWK x) as a Multikey ("z6Mk…"). */
+export function multikeyOf(x: string): string;
+/** The Ed25519 key (JWK x) in a Multikey, or null. */
+export function multikeyToX(multibase: string): string | null;
+/** did:web → the https URL of its DID document; throws for anything that is not a did:web or leaves its host. */
+export function didWebUrl(did: string): string;
+export function resolveDidWeb(did: string, f?: typeof fetch): Promise<DidDocument>;
+/** A Data Integrity proof with cryptosuite eddsa-jcs-2022, against a DID document. */
+export function verifyDataIntegrity(doc: Record<string, unknown>, didDocument: DidDocument): Promise<{ valid: boolean; reason: string; verificationMethod: string | null }>;
+/** Sign a document with eddsa-jcs-2022 (the proof carries the document's @context). */
+export function signDataIntegrity<T extends Record<string, unknown>>(doc: T, privateKey: CryptoKey, verificationMethod: string, created?: Date): Promise<T & { proof: Record<string, unknown> }>;
+export type CredentialCheck = {
+  valid: boolean; trust: 'valid' | 'invalid' | 'unreachable'; say: string; issuer: string | null; subject: string | null;
+  proof: { valid: boolean; reason: string; verificationMethod: string | null } | null;
+  pass: Awaited<ReturnType<typeof verifyPass>> | null; same_key: boolean | null;
+};
+export function verifyCredential(vc: unknown, opts?: { fetch?: typeof fetch; didDocument?: DidDocument; keysDocument?: { keys: Jwk[]; pq_keys?: PqKey[] }; now?: number }): Promise<CredentialCheck>;

package/src/index.js

@@ -9,6 +9,8 @@ const enc = new TextEncoder();
 export function canonical(v) {
   if (Array.isArray(v)) return `[${v.map(canonical).join(',')}]`;
   if (v && typeof v === 'object') return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`).join(',')}}`;
+  // 1e400 parses to Infinity, which JSON.stringify writes as null: a signed null must never read back as a number.
+  if (typeof v === 'number' && !Number.isFinite(v)) throw new TypeError('canonical: number out of range');
   return JSON.stringify(v);
 }
 
@@ -37,7 +39,7 @@ export async function fetchKeys(origin = 'https://pazair.kulalabs.ch', f = fetch
  */
 export async function verifySignature(obj, keys, { anchoredBefore } = {}) {
   if (!obj || typeof obj.sig !== 'string' || typeof obj.kid !== 'string') return false;
-  const jwk = keys.find((k) => k.kid === obj.kid);
+  const jwk = Array.isArray(keys) ? keys.find((k) => k && typeof k === 'object' && k.kid === obj.kid) : undefined;
   if (!jwk || typeof jwk.x !== 'string') return false;
   if ((await sha256hex(jwk.x)).slice(0, 16) !== jwk.kid) return false; // SPEC §1: kid = sha256(x)[0:16]
   if (jwk.revoked_at && !(anchoredBefore && anchoredBefore < String(jwk.revoked_at).slice(0, 10))) return false;
@@ -51,11 +53,12 @@ export async function verifySignature(obj, keys, { anchoredBefore } = {}) {
 }
 
 /** A delivery receipt: signed by the issuer; optionally, the delivery you hold is the one that was signed. */
-export async function verifyReceipt(receipt, { keys, delivery } = {}) {
+export async function verifyReceipt(receipt, { keys, pqKeys, delivery } = {}) {
   keys ??= await fetchKeys();
   const signature_valid = typeof receipt?.issuer === 'string' && (await verifySignature(receipt, keys));
+  const pq = await verifyPqSignature(receipt, pqKeys);
   const delivery_matches = delivery === undefined ? null : (await sha256hex(typeof delivery === 'string' ? delivery : JSON.stringify(delivery))) === receipt?.delivery_sha256;
-  return { valid: signature_valid && delivery_matches !== false, signature_valid, delivery_matches };
+  return { valid: signature_valid && pq.valid !== false && delivery_matches !== false, signature_valid, pq_signed: pq.signed, ml_dsa_65: pq.valid, delivery_matches };
 }
 
 /** SPEC section 4: kept_pct and badge as they follow from the pass's own counts. */
@@ -67,6 +70,17 @@ export function wordOf(pass) {
   return { kept_pct: kept, badge: enough && kept >= 99 ? 'word_kept_99' : enough && kept >= 95 ? 'word_kept_95' : null };
 }
 
+/**
+ * SPEC section 4, the buyer's word: paid for what was delivered. Broken only by a chargeback on a delivered order;
+ * pays_99 / pays_95 from 10 paid orders and 5 different sellers, as they follow from as_buyer.
+ */
+export function buyerWordOf(pass) {
+  const b = pass?.as_buyer ?? {}, paid = Number(b.paid_orders ?? 0), closed = paid + Number(b.chargebacks ?? 0);
+  if (!closed) return { kept_pct: null, badge: null };
+  const kept = Math.floor((paid / closed) * 1000) / 10, enough = paid >= 10 && Number(b.sellers ?? 0) >= 5;
+  return { kept_pct: kept, badge: enough && kept >= 99 ? 'pays_99' : enough && kept >= 95 ? 'pays_95' : null };
+}
+
 /** Section 3.1: the hash a parent receipt names in `inputs`, the child receipt with its signature. */
 export const receiptHash = (receipt) => sha256hex(canonical(receipt));
 
@@ -83,6 +97,8 @@ export async function verifyReceiptChain(top, { receipts = [], keys, maxDepth =
     if (!(await verifySignature(p, keys))) return `${p?.order}: signature`;
     if (p.inputs === undefined) return null;
     if (!Array.isArray(p.inputs)) return `${p.order}: inputs`;
+    // Each bought input counts once: a repeated hash would inflate the total (and the walk) without another purchase.
+    if (new Set(p.inputs).size !== p.inputs.length) return `${p.order}: an input is named twice`;
     if (p.inputs.length && d >= maxDepth) return `${p.order}: deeper than ${maxDepth}`;
     for (const h of p.inputs) {
       const c = byHash.get(h);
@@ -177,15 +193,20 @@ export async function verifyProof(leaf, proof, root) {
  * A revoked key counts only with { anchoredBefore }: a day you proved yourself (a Bitcoin block time), never the
  * root.day the document claims, which whoever holds the stolen key can write.
  */
-export async function verifyPass(anchored, { keys, anchoredBefore } = {}) {
+export async function verifyPass(anchored, { keys, pqKeys, anchoredBefore } = {}) {
   keys ??= await fetchKeys();
   const pass = anchored?.pass ?? anchored;
   const in_root = anchored?.proof && anchored?.root?.root ? await verifyProof(await leafOf(pass), anchored.proof, anchored.root.root) : null;
   const signature_valid = pass?.kind === 'word_pass' && (await verifySignature(pass, keys, { anchoredBefore: in_root ? anchoredBefore : undefined }));
-  const w = wordOf(pass), word_consistent = pass?.word == null || ((pass.word.kept_pct ?? null) === w.kept_pct && (pass.word.badge ?? null) === w.badge); // no word, no claim
+  const pq = await verifyPqSignature(pass, pqKeys, { anchoredBefore: in_root ? anchoredBefore : undefined });
+  const w = wordOf(pass), bw = buyerWordOf(pass);
+  const word_consistent = (pass?.word == null || ((pass.word.kept_pct ?? null) === w.kept_pct && (pass.word.badge ?? null) === w.badge)) // no word, no claim
+    && (pass?.buyer_word == null || ((pass.buyer_word.kept_pct ?? null) === bw.kept_pct && (pass.buyer_word.badge ?? null) === bw.badge));
   return {
-    valid: signature_valid && in_root !== false && word_consistent,
+    valid: signature_valid && pq.valid !== false && in_root !== false && word_consistent,
     signature_valid,
+    pq_signed: pq.signed,
+    ml_dsa_65: pq.valid,
     word_consistent,
     in_root,
     word: pass?.word ?? null,
@@ -301,10 +322,11 @@ export async function bitcoinHasRoot(otsBase64, root, { fetch: f = fetch, explor
  * A holder proof (section 9): the issuer signed { agent, nonce } for the agent showing the pass. Proves the pass
  * is theirs and not a copied URL. Check it against the nonce you gave and the pass's agent.
  */
-export async function verifyHolderProof(proof, { keys, agent, nonce, aud, now = Date.now() } = {}) {
+export async function verifyHolderProof(proof, { keys, pqKeys, agent, nonce, aud, now = Date.now() } = {}) {
   keys ??= await fetchKeys();
   if (proof?.kind !== 'word_pass_proof') return { ok: false, reason: 'not a holder proof' };
   if (!(await verifySignature(proof, keys))) return { ok: false, reason: "signature does not match the issuer's key" };
+  if ((await verifyPqSignature(proof, pqKeys)).valid === false) return { ok: false, reason: "second signature (ML-DSA-65) does not match the issuer's key" };
   if (proof.agent !== agent) return { ok: false, reason: 'the proof is for another agent' };
   if (typeof nonce !== 'string' || nonce.length < 8 || proof.nonce !== nonce) return { ok: false, reason: 'the proof is not for the nonce you gave' };
   if (aud != null && proof.aud !== aud) return { ok: false, reason: 'the proof was made for another checker' };
@@ -318,7 +340,12 @@ export async function verifyHolderProof(proof, { keys, agent, nonce, aud, now =
  * the root on Stellar from the issuer's anchor account, the root in its Bitcoin block and, given { proof, nonce }, that the pass is theirs.
  * Returns a verdict and one sentence to act on.
  */
-export async function checkWordPass(url, { fetch: f = fetch, keys, proof, nonce, aud } = {}) {
+export async function checkWordPass(url, opts = {}) {
+  // A hostile issuer (keys that are not a list, a pass nested thousands deep) gets a verdict, never a crash.
+  try { return await checkWordPassUnsafe(url, opts); }
+  catch { return { trust: 'unreachable', say: 'The Word Pass or its keys could not be read as a valid document.', issuer: null, checks: null, pass: null }; }
+}
+async function checkWordPassUnsafe(url, { fetch: f = fetch, keys, proof, nonce, aud } = {}) {
   const none = (say) => ({ trust: 'unreachable', say, issuer: null, checks: null, pass: null });
   let u;
   try { u = new URL(url); } catch { return none('That is not a URL.'); }
@@ -329,16 +356,17 @@ export async function checkWordPass(url, { fetch: f = fetch, keys, proof, nonce,
   const pass = anchored?.pass ?? (doc?.current?.kind === 'word_pass' ? doc.current : doc?.kind === 'word_pass' ? doc : null);
   if (!pass) return none(`The document at ${u.href} is not a Word Pass.`);
   try { kd = keys ? { keys } : await fetchKeysDocument(u.origin, f); } catch { return none(`${u.host} publishes no keys at /.well-known/pazair-receipts.json.`); }
-  let v = await verifyPass(anchored ?? pass, { keys: kd.keys });
+  let v = await verifyPass(anchored ?? pass, { keys: kd.keys, pqKeys: kd.pq_keys });
   const a = kd.anchors?.stellar, account = a?.network === 'mainnet' && typeof a.account === 'string' ? a.account : undefined;
   const stellar = v.in_root && anchored.root.stellar_tx && account ? await stellarHasRoot(anchored.root.stellar_tx, anchored.root.root, { fetch: f, account }) : null;
   const btc = v.in_root && anchored.root.bitcoin_ots ? await bitcoinHasRoot(anchored.root.bitcoin_ots, anchored.root.root, { fetch: f }) : null;
   // Revoked key: only a Bitcoin block older than the revocation proves the pass was signed before the theft.
-  if (!v.signature_valid && btc?.ok && btc.block?.time) v = await verifyPass(anchored, { keys: kd.keys, anchoredBefore: btc.block.time.slice(0, 10) });
-  const held = proof != null ? await verifyHolderProof(proof, { keys: kd.keys, agent: pass.agent, nonce, aud }) : null;
-  const checks = { signature: v.signature_valid, in_root: v.in_root, day: v.anchors?.day ?? null, stellar, stellar_account_bound: !!(stellar && account), bitcoin_ots: !!(v.in_root && anchored.root.bitcoin_ots), bitcoin: btc ? btc.ok : null, ...(btc?.block ? { bitcoin_block: btc.block } : {}), holder: held ? held.ok : null, word: v.word_consistent };
+  if ((!v.signature_valid || v.ml_dsa_65 === false) && btc?.ok && btc.block?.time) v = await verifyPass(anchored, { keys: kd.keys, pqKeys: kd.pq_keys, anchoredBefore: btc.block.time.slice(0, 10) });
+  const held = proof != null ? await verifyHolderProof(proof, { keys: kd.keys, pqKeys: kd.pq_keys, agent: pass.agent, nonce, aud }) : null;
+  const checks = { signature: v.signature_valid, ml_dsa_65: v.pq_signed ? v.ml_dsa_65 : null, in_root: v.in_root, day: v.anchors?.day ?? null, stellar, stellar_account_bound: !!(stellar && account), bitcoin_ots: !!(v.in_root && anchored.root.bitcoin_ots), bitcoin: btc ? btc.ok : null, ...(btc?.block ? { bitcoin_block: btc.block } : {}), holder: held ? held.ok : null, word: v.word_consistent };
   const issuer = u.host;
   if (!checks.signature) return { trust: 'invalid', issuer, checks, pass, say: `Do not rely on this pass: its signature does not match ${issuer}'s published key.` };
+  if (checks.ml_dsa_65 === false) return { trust: 'invalid', issuer, checks, pass, say: `Do not rely on this pass: its second signature (ML-DSA-65) does not match ${issuer}'s published key.` };
   if (checks.in_root === false) return { trust: 'invalid', issuer, checks, pass, say: `Do not rely on this pass: its Merkle proof does not lead to the root of ${checks.day}.` };
   if (stellar === false) return { trust: 'invalid', issuer, checks, pass, say: `Do not rely on this pass: the Stellar transaction it names does not carry the root of ${checks.day} from ${issuer}'s anchor account.` };
   if (btc?.ok === false) return { trust: 'invalid', issuer, checks, pass, say: `Do not rely on this pass: the Bitcoin proof it names for the root of ${checks.day} is not for that root or not in the block it claims.` };
@@ -347,19 +375,32 @@ export async function checkWordPass(url, { fetch: f = fetch, keys, proof, nonce,
   const where = checks.in_root ? `in the Merkle root of ${checks.day}${stellar ? (account ? ", found on Stellar from the issuer's anchor account" : ', found on Stellar') : ''}${btc?.block ? `, confirmed in Bitcoin block ${btc.block.height} (${btc.block.time.slice(0, 10)})` : checks.bitcoin_ots ? ', stamped in Bitcoin (block confirmation pending)' : ''}` : 'not anchored yet';
   const whose = held?.ok ? ' The agent showing it proved it is this agent.' : ' To be sure it is theirs, give them a fresh nonce and ask for a holder proof (prove_word_pass).';
   const anchored_ok = stellar === true || btc?.ok === true;
-  return { trust: !pass.word?.badge ? 'no_badge_yet' : anchored_ok ? 'kept_its_word' : 'signed_unanchored', issuer, checks, pass, say: `${sayPass(pass, issuer)} Checked: signature of ${issuer} valid, ${where}.${whose}` };
+  // trust is the seller's verdict, as it always was; buyer_trust is the buyer's word (SPEC 4), for whoever sells to it.
+  const buyer_trust = !pass.buyer_word?.badge ? 'no_buyer_badge_yet' : anchored_ok ? 'pays_its_way' : 'signed_unanchored';
+  return { trust: !pass.word?.badge ? 'no_badge_yet' : anchored_ok ? 'kept_its_word' : 'signed_unanchored', buyer_trust, issuer, checks, pass, say: `${sayPass(pass, issuer)} Checked: signature of ${issuer} valid${checks.ml_dsa_65 ? ' (Ed25519 and ML-DSA-65)' : ''}, ${where}.${whose}` };
 }
 
 /** One plain sentence about a pass. */
 export function sayPass(p, by = p.issuer) {
   const s = p.as_seller ?? {}, w = p.word ?? {}, n = (x, one, many = one + 's') => `${x} ${x === 1 ? one : many}`;
   const record = s.delivered ? `${n(s.delivered, 'paid order')} delivered to ${n(s.buyers, 'buyer')}, ${n(p.disputes_lost ?? 0, 'dispute')} lost` : `no sales yet, ${n(p.as_buyer?.paid_orders ?? 0, 'paid purchase')}`;
-  const head = w.badge === 'word_kept_99' ? 'kept its word on 99 % or more' : w.badge === 'word_kept_95' ? 'kept its word on 95 % or more' : w.kept_pct != null ? `kept its word on ${w.kept_pct} % (no badge yet)` : 'new, no record yet';
-  return `${p.name} (Word Pass by ${by}): ${head}; ${record}.`;
+  const head = w.badge === 'word_kept_99' ? 'kept its word on 99 % or more' : w.badge === 'word_kept_95' ? 'kept its word on 95 % or more' : w.kept_pct != null ? `kept its word on ${w.kept_pct} % (no badge yet)` : p.as_buyer?.paid_orders || p.as_buyer?.chargebacks ? 'no record as a seller yet' : 'new, no record yet';
+  const bw = p.buyer_word, b = p.as_buyer ?? {}, cb = Number(b.chargebacks ?? 0);
+  const buyer = bw && bw.kept_pct != null
+    ? ` As a buyer: ${bw.badge === 'pays_99' ? 'paid for 99 % or more' : bw.badge === 'pays_95' ? 'paid for 95 % or more' : `paid for ${bw.kept_pct} % (no buyer's badge yet)`} of ${n(Number(b.paid_orders ?? 0) + cb, 'delivered order')} from ${n(Number(b.sellers ?? 0), 'seller')}, ${n(cb, 'chargeback')}.`
+    : '';
+  return `${p.name} (Word Pass by ${by}): ${head}; ${record}.${buyer}`;
 }
 
 // Remember: the chain of daily roots, checked without the issuer (SPEC section 14).
-export { GENESIS, headOf, recomputeChain, verifyLink, verifyRememberDocument, checkRemember, checkHead, loadMlDsa, verifyMlDsa, pqKid } from './remember.js';
+export { GENESIS, headOf, recomputeChain, verifyLink, verifyRememberDocument, checkRemember, checkHead } from './remember.js';
 
-// Fingerprint (SPEC section 15): a print no other agent can carry, provably; the reference drawing.
+// The second signature (SPEC section 16): ML-DSA-65 on passes, receipts and holder proofs; checked when @noble/post-quantum is installed.
+export { loadMlDsa, verifyMlDsa, pqKid, verifyPqSignature } from './pq.js';
+import { verifyPqSignature } from './pq.js';
+
+// Fingerprint (SPEC section 15): two different prints differ in at least 55 of 64 symbols; the reference drawing.
 export { FINGERPRINT, rsEncode, fingerprintOf, fingerprintDistance, fingerprintSvg, recordOf, ridgesOf } from './fingerprint.js';
+
+// The Word Pass as a W3C Verifiable Credential 2.0 (SPEC section 18): did:web, Multikey, Data Integrity eddsa-jcs-2022.
+export { base58btcEncode, base58btcDecode, multikeyOf, multikeyToX, didWebUrl, resolveDidWeb, verifyDataIntegrity, verifyCredential, signDataIntegrity } from './credential.js';

package/src/pq.js

@@ -0,0 +1,42 @@
+// ML-DSA-65 (FIPS 204), the second signature. Checked when the optional package @noble/post-quantum is installed
+// next to pazair-verify; otherwise reported as not checked (null), never as valid. Used by Remember (section 14)
+// and by the second signature on passes, receipts and holder proofs (section 16).
+import { canonical, sha256hex } from './index.js';
+
+const enc = new TextEncoder();
+const unb64u = (s) => Uint8Array.from(atob(s.replace(/-/g, '+').replace(/_/g, '/') + '==='.slice((s.length + 3) % 4)), (c) => c.charCodeAt(0));
+const hex = (b) => [...b].map((x) => x.toString(16).padStart(2, '0')).join('');
+
+let mlDsa; // the optional ML-DSA-65 implementation, loaded once
+/** ML-DSA-65 when @noble/post-quantum is installed; null otherwise. */
+export async function loadMlDsa() {
+  if (mlDsa !== undefined) return mlDsa;
+  try { mlDsa = (await import('@noble/post-quantum/ml-dsa.js')).ml_dsa65 ?? null; } catch { mlDsa = null; }
+  return mlDsa;
+}
+
+/** true / false, or null when ML-DSA-65 cannot be checked here. */
+export async function verifyMlDsa(sigB64u, msgBytes, publicKeyB64u) {
+  const m = await loadMlDsa(); if (!m) return null;
+  try { return m.verify(unb64u(sigB64u), msgBytes, unb64u(publicKeyB64u)); } catch { return false; }
+}
+
+/** kid of an ML-DSA key: sha256hex(hex(public key))[0:16], like the Ed25519 kid is built from x. */
+export const pqKid = async (publicKeyB64u) => (await sha256hex(hex(unb64u(publicKeyB64u)))).slice(0, 16);
+
+/**
+ * Section 16: the second signature of an object. `pq_sig` is ML-DSA-65 over canonical(object without "sig" and
+ * "pq_sig") with the issuer's key named by `pq_kid` (`pq_keys` in the keys document). Returns
+ * { signed, valid }: signed false when the object carries no pq_sig; valid true / false, or null when it cannot be
+ * checked here (no library, or the key is not published). A revoked pq key signs nothing valid.
+ */
+export async function verifyPqSignature(obj, pqKeys = [], { anchoredBefore } = {}) {
+  if (!obj || typeof obj.pq_sig !== 'string') return { signed: false, valid: null };
+  if (typeof obj.pq_kid !== 'string') return { signed: true, valid: false };
+  const key = (pqKeys ?? []).find((k) => k?.pq_kid === obj.pq_kid);
+  if (!key || typeof key.public_key_b64url !== 'string') return { signed: true, valid: null };
+  if ((await pqKid(key.public_key_b64url)) !== key.pq_kid) return { signed: true, valid: false };
+  if (key.revoked_at && !(anchoredBefore && anchoredBefore < String(key.revoked_at).slice(0, 10))) return { signed: true, valid: false };
+  const { sig, pq_sig, ...body } = obj;
+  return { signed: true, valid: await verifyMlDsa(pq_sig, enc.encode(canonical(body)), key.public_key_b64url) };
+}

package/src/remember.js

@@ -8,7 +8,6 @@ import { canonical, fetchKeysDocument, sha256hex, verifySignature } from './inde
 export const GENESIS = '0'.repeat(64);
 const enc = new TextEncoder();
 const unb64u = (s) => Uint8Array.from(atob(s.replace(/-/g, '+').replace(/_/g, '/') + '==='.slice((s.length + 3) % 4)), (c) => c.charCodeAt(0));
-const hex = (b) => [...b].map((x) => x.toString(16).padStart(2, '0')).join('');
 
 /** One link of the chain. */
 export const headOf = (prev, root) => sha256hex(prev + root);
@@ -30,22 +29,8 @@ export async function recomputeChain(days) {
   return { head, days: sorted.length, last_day: sorted.length ? sorted[sorted.length - 1].day : null, broken_at, heads };
 }
 
-let mlDsa; // the optional ML-DSA-65 implementation, loaded once
-/** ML-DSA-65 when @noble/post-quantum is installed; null otherwise. */
-export async function loadMlDsa() {
-  if (mlDsa !== undefined) return mlDsa;
-  try { mlDsa = (await import('@noble/post-quantum/ml-dsa.js')).ml_dsa65 ?? null; } catch { mlDsa = null; }
-  return mlDsa;
-}
-
-/** true / false, or null when ML-DSA-65 cannot be checked here. */
-export async function verifyMlDsa(sigB64u, msgBytes, publicKeyB64u) {
-  const m = await loadMlDsa(); if (!m) return null;
-  try { return m.verify(unb64u(sigB64u), msgBytes, unb64u(publicKeyB64u)); } catch { return false; }
-}
-
-/** kid of an ML-DSA key: sha256hex(hex(public key))[0:16], like the Ed25519 kid is built from x. */
-export const pqKid = async (publicKeyB64u) => (await sha256hex(hex(unb64u(publicKeyB64u)))).slice(0, 16);
+export { loadMlDsa, verifyMlDsa, pqKid } from './pq.js';
+import { loadMlDsa, verifyMlDsa, pqKid } from './pq.js';
 
 async function ed25519(jwk, sigB64u, msgBytes) {
   if (!jwk || typeof jwk.x !== 'string') return false;
@@ -75,11 +60,14 @@ export async function verifyLink(link, sig, { keys = [], pqPublicKey } = {}) {
  * The public document (/.well-known/pazair-remember.json): `sig` is Ed25519 over the canonical JSON without "sig" and
  * "pq_sig"; `pq_sig` is ML-DSA-65 over the same bytes with the key the document itself carries, whose kid must be `pq_kid`.
  */
-export async function verifyRememberDocument(doc, { keys = [] } = {}) {
+export async function verifyRememberDocument(doc, { keys = [], pqKeys } = {}) {
   if (!doc || typeof doc !== 'object') return { ed25519: false, ml_dsa_65: false, pq_kid_matches: false };
   const { pq_sig, ...rest } = doc;
   const { sig, ...body } = rest;
-  const pub = doc.keys?.ml_dsa_65?.public_key_b64url;
+  // When the issuer publishes its ML-DSA keys (pq_keys), only that key counts: one the document brings itself proves
+  // nothing against someone who could forge the Ed25519 signature, which is what the second signature is for.
+  const published = publishedPq(pqKeys, doc.pq_kid);
+  const pub = published !== undefined ? published : doc.keys?.ml_dsa_65?.public_key_b64url;
   const kidOk = typeof pub === 'string' && (await pqKid(pub)) === doc.pq_kid;
   return {
     ed25519: await verifySignature({ ...body, sig }, keys),
@@ -88,6 +76,13 @@ export async function verifyRememberDocument(doc, { keys = [] } = {}) {
   };
 }
 
+/** The issuer's published ML-DSA key for a kid: undefined when it publishes none, null when it publishes others. */
+const publishedPq = (pqKeys, kid) => {
+  if (!Array.isArray(pqKeys) || !pqKeys.length) return undefined;
+  const k = pqKeys.find((x) => x && typeof x === 'object' && x.pq_kid === kid && !x.revoked_at);
+  return typeof k?.public_key_b64url === 'string' ? k.public_key_b64url : null;
+};
+
 const get = async (f, url) => { const r = await f(url, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(10000) }); if (!r.ok) throw new Error(`HTTP ${r.status}`); return r.json(); };
 
 /**
@@ -102,9 +97,10 @@ export async function checkRemember(origin = 'https://pazair.kulalabs.ch', { fet
   try { doc = await get(f, `${o}/.well-known/pazair-remember.json`); } catch (e) { return none(`No Remember document at ${o}/.well-known/pazair-remember.json (${e.message}).`); }
   try { kd = await fetchKeysDocument(o, f); } catch { return none(`${o} publishes no keys at /.well-known/pazair-receipts.json.`); }
   try { chain = await get(f, `${o}/v1/remember/chain`); } catch (e) { return none(`No chain at ${o}/v1/remember/chain (${e.message}).`); }
-  const docSig = await verifyRememberDocument(doc, { keys: kd.keys });
+  const docSig = await verifyRememberDocument(doc, { keys: kd.keys, pqKeys: kd.pq_keys });
   const re = await recomputeChain(chain.chain ?? []);
-  const pub = chain.keys?.ml_dsa_65_public_key_b64url ?? doc.keys?.ml_dsa_65?.public_key_b64url;
+  const published = publishedPq(kd.pq_keys, doc.pq_kid);
+  const pub = published !== undefined ? published : chain.keys?.ml_dsa_65_public_key_b64url ?? doc.keys?.ml_dsa_65?.public_key_b64url;
   let linksEd = 0, linksPq = 0, linksChecked = 0, linkFailures = [];
   for (const d of chain.chain ?? []) {
     if (!d.head_sig) continue;