pazair-verify 1.9.0 → 1.11.0

package/README.md

@@ -61,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
@@ -102,11 +122,16 @@ console.log(await verifyReceipt(receipt, { delivery }));
 | `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?, 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 |
+| `verifyLicence(licence, { keys?, pqKeys?, now? })` / `checkLicence(url, { fetch?, now? })` | Section 19, the buyer's licence from an apprenticeship: both signatures, the rules of its level (a signed licence under its pass mark is invalid), whether it is current; `checkLicence` reads a licence URL against the issuer's own keys (`npx pazair-verify licence <url>`) |
 | `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,11 @@
 // 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.
+// npx pazair-verify licence <licence url> [--json]: the buyer's licence from the apprenticeship (SPEC 19), against the issuer's keys.
 // 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, checkLicence, checkRemember, checkWordPass, verifyCredential } from '../src/index.js';
 
 const args = process.argv.slice(2);
 if (args.includes('-v') || args.includes('--version')) {
@@ -14,10 +16,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]\n       npx pazair-verify licence <licence url> [--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\n          npx pazair-verify licence https://pazair.ch/v1/agents/ag_xyz/licence';
 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, expired: 1, none: 1, 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 +34,28 @@ 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));
+}
+if (words[0] === 'licence' || words[0] === 'license') {
+  if (!words[1]) { console.error(usage); process.exit(2); }
+  const r = await checkLicence(words[1]);
+  console.log(clean(r.say));
+  if (json) console.log(JSON.stringify(r, null, 2));
+  process.exit(codes[r.verdict] ?? 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.9.0",
+  "version": "1.11.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",

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

@@ -10,6 +10,8 @@ export function fetchKeysDocument(origin?: string, f?: typeof fetch): Promise<{
 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>;
@@ -19,6 +21,8 @@ export function verifyProof(leaf: string, proof: Step[], root: string): Promise<
 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; 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;
@@ -46,12 +50,12 @@ 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;
@@ -62,3 +66,33 @@ export function fingerprintSvg(codeword: Fingerprint | string, record?: Fingerpr
 // 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>;
+
+// The buyer's licence (SPEC section 19, the apprenticeship).
+export const LICENCE_LEVELS: Record<'basic' | 'professional' | 'critical', { tasks: number; need: number; valid_days: number }>;
+export type LicenceCheck = { valid: boolean; current: boolean; signature_valid: boolean; pq_signed: boolean; ml_dsa_65: boolean | null; rules_hold: boolean; level: string | null; agent: string | null; valid_until: string | null };
+/** Section 19: both signatures and the rules of its level; `current` says whether it has expired. */
+export function verifyLicence(licence: unknown, opts?: { keys?: Jwk[]; pqKeys?: PqKey[]; now?: Date }): Promise<LicenceCheck>;
+/** Section 19: a licence URL checked against the issuer's own keys. */
+export function checkLicence(url: string, opts?: { fetch?: typeof fetch; now?: Date }): Promise<{ verdict: 'valid' | 'expired' | 'none' | 'invalid' | 'unreachable'; agent?: string | null; level?: string; say: string; licences: LicenceCheck[] }>;

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;
@@ -68,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));
 
@@ -84,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);
@@ -184,7 +199,9 @@ export async function verifyPass(anchored, { keys, pqKeys, anchoredBefore } = {}
   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 pq = await verifyPqSignature(pass, pqKeys, { 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 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 && pq.valid !== false && in_root !== false && word_consistent,
     signature_valid,
@@ -323,7 +340,12 @@ export async function verifyHolderProof(proof, { keys, pqKeys, agent, nonce, aud
  * 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.'); }
@@ -353,15 +375,21 @@ 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${checks.ml_dsa_65 ? ' (Ed25519 and ML-DSA-65)' : ''}, ${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).
@@ -371,5 +399,55 @@ export { GENESIS, headOf, recomputeChain, verifyLink, verifyRememberDocument, ch
 export { loadMlDsa, verifyMlDsa, pqKid, verifyPqSignature } from './pq.js';
 import { verifyPqSignature } from './pq.js';
 
-// Fingerprint (SPEC section 15): a print no other agent can carry, provably; the reference drawing.
+// 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';
+
+// The buyer's licence (SPEC section 19, the apprenticeship): an agent passed an exam of buying for someone else.
+/** Section 19: the levels: tasks in the exam, the pass mark, the days a licence is valid. */
+export const LICENCE_LEVELS = { basic: { tasks: 5, need: 4, valid_days: 365 }, professional: { tasks: 8, need: 7, valid_days: 180 }, critical: { tasks: 10, need: 10, valid_days: 90 } };
+
+/**
+ * Section 19: a buyer's licence. Both signatures, and the rules of its level: the score reaches the pass mark, the
+ * tasks match the level, and it is valid no longer than the level allows. A signed licence that breaks its own level's
+ * rules is invalid. `current` says whether it has expired; an expired licence is genuine but no longer shows anything.
+ */
+export async function verifyLicence(licence, { keys, pqKeys, now = new Date() } = {}) {
+  keys ??= await fetchKeys();
+  const l = licence && typeof licence === 'object' ? licence : {}, lv = LICENCE_LEVELS[l.level];
+  const signature_valid = l.kind === 'buyer_licence' && typeof l.issuer === 'string' && (await verifySignature(l, keys));
+  const pq = await verifyPqSignature(l, pqKeys);
+  const [right, of] = String(l.score ?? '').split('/').map(Number);
+  const days = (Date.parse(l.valid_until) - Date.parse(l.issued_at)) / 864e5;
+  const rules_hold = !!lv && of === lv.tasks && right >= lv.need && right <= of && Array.isArray(l.tasks) && l.tasks.length === of && days > 0 && days <= lv.valid_days;
+  const current = typeof l.valid_until === 'string' && l.valid_until > now.toISOString();
+  return { valid: signature_valid && pq.valid !== false && rules_hold, current, signature_valid, pq_signed: pq.signed, ml_dsa_65: pq.valid, rules_hold, level: l.level ?? null, agent: l.agent ?? null, valid_until: l.valid_until ?? null };
+}
+
+/**
+ * Section 19: "Has this agent passed the apprenticeship?", from a licence URL (e.g. <origin>/v1/agents/<id>/licence),
+ * checked against the issuer's own keys. verdict: valid (a current licence), expired, none, invalid or unreachable.
+ */
+export async function checkLicence(url, { fetch: f = fetch, now = new Date() } = {}) {
+  let u; try { u = new URL(url); } catch { return { verdict: 'invalid', say: 'Not a URL.', licences: [] }; }
+  if (u.protocol !== 'https:') return { verdict: 'invalid', say: 'Only https URLs are checked.', licences: [] };
+  let doc, kd;
+  try { const r = await f(u.href, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(8000) }); if (!r.ok) throw new Error(); doc = await r.json(); }
+  catch { return { verdict: 'unreachable', say: `No licence could be read at ${u.host}.`, licences: [] }; }
+  try { kd = await fetchKeysDocument(u.origin, f); } catch { return { verdict: 'unreachable', say: `${u.host} publishes no keys at /.well-known/pazair-receipts.json.`, licences: [] }; }
+  const list = Array.isArray(doc?.licences) ? doc.licences.map((x) => x?.licence ?? x) : doc?.kind === 'buyer_licence' ? [doc] : [];
+  const agent = typeof doc?.agent_id === 'string' ? doc.agent_id : list[0]?.agent ?? null;
+  const licences = await Promise.all(list.map(async (l) => {
+    const v = await verifyLicence(l, { keys: kd.keys, pqKeys: kd.pq_keys, now });
+    // A licence for another agent, served under this one, proves nothing about this one.
+    return agent && l?.agent !== agent ? { ...v, valid: false, rules_hold: false } : v;
+  }));
+  const day = (t) => String(t ?? '').slice(0, 10);
+  if (!licences.length) return { verdict: 'none', agent, say: `${agent ?? 'This agent'} holds no buyer's licence from ${u.host}.`, licences };
+  if (licences.some((v) => !v.valid)) return { verdict: 'invalid', agent, say: `Do not rely on it: a licence from ${u.host} does not verify against the issuer's keys or breaks its level's rules.`, licences };
+  const best = [...licences].reverse().find((v) => v.current);
+  if (!best) return { verdict: 'expired', agent, say: `${agent}: every buyer's licence from ${u.host} has expired (the last on ${day(licences.at(-1).valid_until)}).`, licences };
+  return { verdict: 'valid', agent, level: best.level, say: `${agent}: ${best.level} buyer's licence from ${u.host}, signatures valid${best.ml_dsa_65 ? ' (Ed25519 and ML-DSA-65)' : ''}, current until ${day(best.valid_until)}. It shows the exam was passed that day; it is no regulatory certification.`, licences };
+}

package/src/remember.js

@@ -60,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),
@@ -73,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(); };
 
 /**
@@ -87,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;