pazair-verify 1.6.1 → 1.7.0

package/README.md

@@ -4,6 +4,8 @@ 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.
 
 ```sh
 npm install pazair-verify
@@ -35,6 +37,29 @@ const nonce = crypto.randomUUID();
 const r = await checkWordPass(url, { proof, nonce });   // r.checks.holder === true
 ```
 
+## Remember: "Forgets nothing. Holds nothing against you."
+
+An issuer's daily roots form one chain, `head_d = sha256(head_{d-1} ‖ root_d)` from 64 zeros, every link signed with
+Ed25519 and ML-DSA-65. Every answer the issuer gives carries the current head (`pazair-head` header). Recompute the
+whole chain here, from the issuer's published roots, and compare it with what the issuer claims:
+
+```sh
+npx pazair-verify remember https://pazair.kulalabs.ch
+# https://pazair.kulalabs.ch: Remember holds. 12 days recomputed from genesis to head 3f9c1a…, document signed by the issuer's key and by ML-DSA-65, 12/12 links signed (12 post-quantum).
+
+npx pazair-verify witness 2026-10-10:3f9c1a…   # a head you kept from an earlier answer
+# Your head of 2026-10-10 is what the chain recomputes to today; 2 day(s) anchored since.
+```
+
+```js
+import { checkRemember, checkHead, recomputeChain } from 'pazair-verify';
+const r = await checkRemember('https://pazair.kulalabs.ch');   // r.verdict: consistent | inconsistent | unreachable
+const h = await checkHead('2026-10-10:3f9c…');                  // the head you kept, against the chain you recompute
+```
+
+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.
+
 ## Lower level
 
 ```js
@@ -54,10 +79,14 @@ console.log(await verifyReceipt(receipt, { delivery }));
 | Function | Checks |
 |---|---|
 | `checkWordPass(url, { fetch?, keys?, proof?, nonce? })` | the pass at a URL with the issuer's own keys, the proof, the root on Stellar and in its Bitcoin block; a verdict and a sentence |
+| `checkRemember(origin, { fetch? })` | Section 14: the Remember document's two signatures, the chain recomputed from genesis, the document's head against it, every link's two signatures; a verdict and a sentence |
+| `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 |
 | `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` |
 | `verifyPass(anchored, { keys? })` | signature, Merkle proof into the day's root; returns the anchors to check on Bitcoin and Stellar |
 | `verifyProof(leaf, proof, root)` | a Merkle path |

package/bin/cli.js

@@ -1,22 +1,38 @@
 #!/usr/bin/env node
 // npx pazair-verify <word pass url> [--json]: "May I see your Word Pass?", checked from the command line.
-// Exit codes: 0 trusted, 1 invalid (do not rely on it), 2 usage, 3 unreachable (could not check).
+// 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.
+// 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 { checkWordPass } from '../src/index.js';
+import { checkHead, checkRemember, checkWordPass } from '../src/index.js';
 
 const args = process.argv.slice(2);
 if (args.includes('-v') || args.includes('--version')) {
   console.log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url))).version);
   process.exit(0);
 }
-const url = args.find((a) => !a.startsWith('-'));
+const words = args.filter((a) => !a.startsWith('-'));
 const help = args.includes('-h') || args.includes('--help');
-if (!url || help) {
-  (help ? console.log : console.error)('Usage: npx pazair-verify <word pass url> [--json]\nExample: npx pazair-verify https://pazair.kulalabs.ch/v1/agents/ag_xyz/pass');
-  process.exit(help ? 0 : 2);
+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';
+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 };
+
+if (words[0] === 'remember') {
+  const r = await checkRemember(words[1] ?? 'https://pazair.kulalabs.ch');
+  console.log(clean(r.say));
+  if (json) console.log(JSON.stringify(r, null, 2));
+  process.exit(codes[r.verdict] ?? 1);
+}
+if (words[0] === 'witness') {
+  if (!words[1]) { console.error(usage); process.exit(2); }
+  const r = await checkHead(words[1], words[2] ?? 'https://pazair.kulalabs.ch');
+  console.log(clean(r.say));
+  if (json) console.log(JSON.stringify(r, null, 2));
+  process.exit(codes[r.verdict] ?? 1);
 }
-const r = await checkWordPass(url);
-const clean = (s) => s.replace(/[\u0000-\u001f\u007f-\u009f]/g, '?'); // a pass name cannot rewrite your terminal
+const r = await checkWordPass(words[0]);
 console.log(clean(r.say));
-if (args.includes('--json')) console.log(JSON.stringify({ ...r, pass: undefined }, null, 2));
-process.exit({ kept_its_word: 0, no_badge_yet: 0, signed_unanchored: 0, invalid: 1, unreachable: 3 }[r.trust] ?? 1);
+if (json) console.log(JSON.stringify({ ...r, pass: undefined }, null, 2));
+process.exit(codes[r.trust] ?? 1);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pazair-verify",
-  "version": "1.6.1",
-  "description": "Verify Word Passes, receipts and Merkle proofs: \"May I see your Word Pass?\", checked by anyone, for any issuer. Zero dependencies.",
+  "version": "1.7.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",
   "types": "./src/index.d.ts",
@@ -23,8 +23,20 @@
   "scripts": {
     "test": "node --test test/*.test.js"
   },
+  "devDependencies": {
+    "@noble/post-quantum": "^0.7.1"
+  },
+  "peerDependencies": {
+    "@noble/post-quantum": ">=0.7.0"
+  },
+  "peerDependenciesMeta": {
+    "@noble/post-quantum": { "optional": true }
+  },
   "keywords": [
     "word-pass",
+    "remember",
+    "post-quantum",
+    "ml-dsa",
     "ai-agents",
     "agent-trust",
     "a2a",

package/src/index.d.ts

@@ -9,6 +9,7 @@ export function verifyHolderProof(proof: unknown, opts: { keys?: Jwk[]; agent: s
 export function verifyReceipt(receipt: Record<string, unknown>, opts?: { keys?: Jwk[]; delivery?: unknown }): Promise<{ valid: boolean; signature_valid: boolean; delivery_matches: boolean | null }>;
 export function wordOf(pass: Record<string, unknown>): { kept_pct: number | null; badge: 'word_kept_99' | 'word_kept_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>;
@@ -26,3 +27,19 @@ export function bitcoinHasRoot(otsBase64: string, root: string, opts?: { fetch?:
 export function stellarHasRoot(tx: string, root: string, opts?: { fetch?: typeof fetch; horizon?: string; account?: string }): Promise<boolean | null>;
 export function checkWordPass(url: string, opts?: { fetch?: typeof fetch; keys?: Jwk[]; proof?: unknown; nonce?: string; aud?: string }): Promise<PassCheck>;
 export function sayPass(pass: Record<string, unknown>, by?: string): string;
+
+// Remember (SPEC section 14): the chain of daily roots and its two signatures, checked without the issuer.
+export const GENESIS: string;
+export function headOf(prev: string, root: string): Promise<string>;
+export type ChainHead = { day: string; root: string; prev: string; head: string; published_head: string | null; published_matches: boolean | null };
+export function recomputeChain(days: { day: string; root: string; head?: string | null }[]): Promise<{ head: string; days: number; last_day: string | null; broken_at: string | null; heads: ChainHead[] }>;
+export type HeadSig = { kid: string; ed25519: string; pq_kid: string; ml_dsa_65: string; over?: string };
+/** ml_dsa_65 is null when @noble/post-quantum is not installed next to pazair-verify: not checked, never trusted. */
+export function verifyLink(link: { day: string; prev: string; root: string; head: string }, sig: HeadSig | null, opts?: { keys?: Jwk[]; pqPublicKey?: string }): Promise<{ ed25519: boolean; ml_dsa_65: boolean | null; pq_kid_matches: boolean }>;
+export function verifyRememberDocument(doc: Record<string, unknown>, opts?: { keys?: Jwk[] }): Promise<{ ed25519: boolean; ml_dsa_65: boolean | null; pq_kid_matches: boolean }>;
+export function loadMlDsa(): Promise<unknown | null>;
+export function verifyMlDsa(sigB64u: string, msg: Uint8Array, publicKeyB64u: string): Promise<boolean | null>;
+export function pqKid(publicKeyB64u: string): Promise<string>;
+export type RememberCheck = { verdict: 'consistent' | 'inconsistent' | 'unreachable'; origin: string; say: string; checks: { document: { ed25519: boolean; ml_dsa_65: boolean | null; pq_kid_matches: boolean; kid_in_issuer_keys: boolean }; chain: { days: number; recomputed_head: string; document_head: string | null; head_matches: boolean; broken_at: string | null; published_heads_match: boolean }; links: { with_signature: number; ed25519_valid: number; ml_dsa_65_valid: number | null; failures: string[] }; ml_dsa_65_checked: boolean } | null };
+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 }>;

package/src/index.js

@@ -1,5 +1,6 @@
 // pazair-verify: check PazAIr receipts, Word Passes and Merkle proofs without trusting PazAIr.
 // Zero dependencies. WebCrypto Ed25519 + SHA-256: Node 20+, Deno, Bun, Cloudflare Workers, modern browsers.
+// Remember (SPEC section 14: the chain of daily roots, two signatures) lives in ./remember.js and is exported below.
 // Specification: https://github.com/Kula-Labs/pazair/blob/main/SPEC.md
 
 const enc = new TextEncoder();
@@ -123,6 +124,42 @@ export async function verifyMandate(receipt, mandate, { keys, end } = {}) {
   return { valid: reasons.length === 0, covers, reasons };
 }
 
+/**
+ * Section 3.3: was this receipt paid under this award, for this tender? `qa` are the signed questions, if held.
+ * Returns { valid, covers, reasons }: covers lists what held, reasons what did not.
+ */
+export async function verifyAward(receipt, tender, award, { keys, qa } = {}) {
+  keys ??= await fetchKeys();
+  const reasons = [], covers = [];
+  const ok = (cond, yes, no) => (cond ? covers.push(yes) : reasons.push(no));
+  const tenderHash = await receiptHash(tender);
+  ok(tender?.kind === 'tender' && (await verifySignature(tender, keys)), 'tender signed', 'tender signature');
+  ok(award?.kind === 'award' && (await verifySignature(award, keys)), 'award signed', 'award signature');
+  ok(await verifySignature(receipt, keys), 'receipt signed', 'receipt signature');
+  ok(award?.tender === tenderHash, 'award names this tender', 'award names another tender');
+  ok(receipt?.award === (await receiptHash(award)), 'receipt names this award', 'receipt names another award');
+  ok(receipt?.buyer === tender?.buyer, 'paid by the tendering agent', `paid by ${receipt?.buyer}, not by ${tender?.buyer}`);
+  ok(receipt?.seller === award?.seller && award?.seller !== tender?.buyer, 'delivered by the awarded seller', `delivered by ${receipt?.seller}, awarded to ${award?.seller}`);
+  ok(receipt?.currency === tender?.currency, 'currency of the tender', `currency ${receipt?.currency}, tender ${tender?.currency}`);
+  ok(Number.isInteger(award?.price_minor) && award.price_minor <= tender?.budget_max_minor, 'price within the budget', `price ${award?.price_minor} over the budget ${tender?.budget_max_minor}`);
+  const ms = receipt?.milestone === undefined ? null : tender?.milestones?.[receipt.milestone];
+  const cap = receipt?.milestone === undefined ? award?.price_minor : ms?.max_minor;
+  ok(Number.isInteger(receipt?.amount_minor) && Number.isInteger(cap) && receipt.amount_minor <= cap,
+    ms ? `amount within milestone ${receipt.milestone}` : 'amount within the price', `amount ${receipt?.amount_minor} over ${cap}`);
+  ok(String(tender?.issued_at) <= String(award?.at) && String(award?.at) <= String(receipt?.delivered_at), 'tender, award, delivery in order', 'out of order in time');
+  if (tender?.deadline != null) ok(String(receipt?.delivered_at) <= String(tender.deadline), 'delivered by the deadline', 'delivered after the deadline');
+  if (qa !== undefined) {
+    const held = new Map();
+    for (const q of qa) held.set(await receiptHash(q), q);
+    for (const h of award?.qa ?? []) {
+      const q = held.get(h);
+      ok(q?.kind === 'tender_qa' && q.tender === tenderHash && String(q.at) <= String(award.at) && (await verifySignature(q, keys)),
+        `question ${h.slice(0, 8)} published before the award`, `question ${h.slice(0, 8)} missing or invalid`);
+    }
+  }
+  return { valid: reasons.length === 0, covers, reasons };
+}
+
 /** The Merkle leaf of a Word Pass: sha256 of its canonical JSON, signature included. */
 export const leafOf = (pass) => sha256hex(canonical(pass));
 
@@ -320,3 +357,6 @@ export function sayPass(p, by = p.issuer) {
   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}.`;
 }
+
+// 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';

package/src/remember.js

@@ -0,0 +1,151 @@
+// pazair-verify/remember: Remember ("Forgets nothing. Holds nothing against you."), checked without the issuer.
+// SPEC section 14. The daily roots form one chain: head_d = sha256hex(head_{d-1} + root_d), head_0 = 64 zeros.
+// Every link and the public document carry two signatures: Ed25519 (the receipt key) and ML-DSA-65 (FIPS 204).
+// Ed25519 and SHA-256 come from WebCrypto (zero dependencies). ML-DSA-65 is checked when the optional package
+// @noble/post-quantum is installed next to this one; otherwise it is reported as not checked, never as valid.
+import { canonical, fetchKeysDocument, sha256hex, verifySignature } from './index.js';
+
+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);
+
+/**
+ * Recompute the chain from the days as the issuer publishes them (`/v1/remember/chain`, or any list of
+ * { day, root, head? }). Returns the head, and the first day whose published head disagrees with the recomputation.
+ */
+export async function recomputeChain(days) {
+  const sorted = [...days].filter((d) => d && typeof d.day === 'string' && /^[0-9a-f]{64}$/.test(String(d.root))).sort((a, b) => a.day.localeCompare(b.day));
+  let head = GENESIS, broken_at = null;
+  const heads = [];
+  for (const d of sorted) {
+    const prev = head; head = await headOf(prev, d.root);
+    const published = typeof d.head === 'string' ? d.head : null, ok = published == null ? null : published === head;
+    if (ok === false && !broken_at) broken_at = d.day;
+    heads.push({ day: d.day, root: d.root, prev, head, published_head: published, published_matches: ok });
+  }
+  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);
+
+async function ed25519(jwk, sigB64u, msgBytes) {
+  if (!jwk || typeof jwk.x !== 'string') return false;
+  if ((await sha256hex(jwk.x)).slice(0, 16) !== jwk.kid) return false;
+  try {
+    const pub = await crypto.subtle.importKey('jwk', { kty: 'OKP', crv: 'Ed25519', x: jwk.x }, { name: 'Ed25519' }, false, ['verify']);
+    return await crypto.subtle.verify({ name: 'Ed25519' }, pub, unb64u(sigB64u), msgBytes);
+  } catch { return false; }
+}
+
+/**
+ * Both signatures of one link { day, prev, root, head } (`head_sig`): Ed25519 with the issuer's published key named
+ * by `kid`, ML-DSA-65 with the public key the issuer publishes next to the chain (`pqPublicKey`, base64url).
+ */
+export async function verifyLink(link, sig, { keys = [], pqPublicKey } = {}) {
+  if (!sig || typeof sig !== 'object') return { ed25519: false, ml_dsa_65: false, pq_kid_matches: false };
+  const msg = enc.encode(canonical({ day: link.day, prev: link.prev, root: link.root, head: link.head }));
+  const kidOk = pqPublicKey ? (await pqKid(pqPublicKey)) === sig.pq_kid : false;
+  return {
+    ed25519: typeof sig.ed25519 === 'string' ? await ed25519(keys.find((k) => k.kid === sig.kid), sig.ed25519, msg) : false,
+    ml_dsa_65: kidOk && typeof sig.ml_dsa_65 === 'string' ? await verifyMlDsa(sig.ml_dsa_65, msg, pqPublicKey) : false,
+    pq_kid_matches: kidOk,
+  };
+}
+
+/**
+ * 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 = [] } = {}) {
+  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;
+  const kidOk = typeof pub === 'string' && (await pqKid(pub)) === doc.pq_kid;
+  return {
+    ed25519: await verifySignature({ ...body, sig }, keys),
+    ml_dsa_65: kidOk && typeof pq_sig === 'string' ? await verifyMlDsa(pq_sig, enc.encode(canonical(body)), pub) : false,
+    pq_kid_matches: kidOk,
+  };
+}
+
+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(); };
+
+/**
+ * The whole check, without trusting the issuer: the document's two signatures against the issuer's published keys,
+ * the chain recomputed from genesis, the document's head against the recomputation, every link's two signatures.
+ * Verdicts: consistent, inconsistent, unreachable.
+ */
+export async function checkRemember(origin = 'https://pazair.kulalabs.ch', { fetch: f = fetch } = {}) {
+  const o = origin.replace(/\/+$/, '');
+  const none = (say) => ({ verdict: 'unreachable', origin: o, say, checks: null });
+  let doc, chain, kd;
+  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 re = await recomputeChain(chain.chain ?? []);
+  const pub = 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;
+    linksChecked++;
+    const r = await verifyLink({ day: d.day, prev: d.prev, root: d.root, head: d.head }, d.head_sig, { keys: kd.keys, pqPublicKey: pub });
+    if (r.ed25519) linksEd++; else linkFailures.push(`${d.day}: Ed25519`);
+    if (r.ml_dsa_65 === true) linksPq++; else if (r.ml_dsa_65 === false && await loadMlDsa()) linkFailures.push(`${d.day}: ML-DSA-65`);
+  }
+  const pqAvailable = !!(await loadMlDsa());
+  const headMatches = re.days === 0 ? (doc.head?.head === GENESIS || doc.head?.day == null) : doc.head?.head === re.head;
+  const checks = {
+    document: { ed25519: docSig.ed25519, ml_dsa_65: pqAvailable ? docSig.ml_dsa_65 : null, pq_kid_matches: docSig.pq_kid_matches, kid_in_issuer_keys: kd.keys.some((k) => k.kid === doc.kid) },
+    chain: { days: re.days, recomputed_head: re.head, document_head: doc.head?.head ?? null, head_matches: headMatches, broken_at: re.broken_at, published_heads_match: re.heads.every((h) => h.published_matches !== false) },
+    links: { with_signature: linksChecked, ed25519_valid: linksEd, ml_dsa_65_valid: pqAvailable ? linksPq : null, failures: linkFailures },
+    ml_dsa_65_checked: pqAvailable,
+  };
+  const bad = [];
+  if (!checks.document.ed25519) bad.push('the document\'s Ed25519 signature does not match the issuer\'s published key');
+  if (pqAvailable && !docSig.ml_dsa_65) bad.push('the document\'s ML-DSA-65 signature does not verify');
+  if (!headMatches) bad.push(`the document names head ${String(doc.head?.head).slice(0, 12)}… but the chain recomputes to ${re.head.slice(0, 12)}…`);
+  if (re.broken_at) bad.push(`published heads disagree with the recomputed chain from ${re.broken_at} on`);
+  if (linkFailures.length) bad.push(`link signatures fail: ${linkFailures.join(', ')}`);
+  const pqNote = pqAvailable ? '' : ' ML-DSA-65 not checked here (npm install @noble/post-quantum to check it too).';
+  if (bad.length) return { verdict: 'inconsistent', origin: o, checks, say: `Do not rely on ${o}'s memory: ${bad.join('; ')}.${pqNote}` };
+  return { verdict: 'consistent', origin: o, checks, say: `${o}: Remember holds. ${re.days} day${re.days === 1 ? '' : 's'} recomputed from genesis to head ${re.head.slice(0, 16)}…, document signed by the issuer's key${pqAvailable ? ' and by ML-DSA-65' : ''}, ${linksEd}/${linksChecked} links signed${pqAvailable ? ` (${linksPq} post-quantum)` : ''}.${pqNote}` };
+}
+
+/**
+ * A head you kept ("<day>:<head>", the pazair-head header of an earlier answer), checked against the chain you
+ * recompute yourself, not against the issuer's witness tool.
+ */
+export async function checkHead(kept, origin = 'https://pazair.kulalabs.ch', { fetch: f = fetch } = {}) {
+  const o = origin.replace(/\/+$/, '');
+  const m = /^(\d{4}-\d{2}-\d{2}):([0-9a-f]{64})$/.exec(String(kept).trim().toLowerCase());
+  if (!m) return { verdict: 'unreachable', say: 'A kept head looks like <day>:<64 hex>, e.g. the pazair-head header of an earlier answer.' };
+  const [, day, head] = m;
+  let chain;
+  try { chain = await get(f, `${o}/v1/remember/chain`); } catch (e) { return { verdict: 'unreachable', say: `No chain at ${o}/v1/remember/chain (${e.message}).` }; }
+  const re = await recomputeChain(chain.chain ?? []);
+  const d = re.heads.find((h) => h.day === day);
+  if (!d) return { verdict: 'inconsistent', day, kept: head, recomputed: null, say: `The chain at ${o} has no day ${day}. Your head is evidence that this day was published and is now gone.` };
+  const ok = d.head === head;
+  return { verdict: ok ? 'consistent' : 'inconsistent', day, kept: head, recomputed: d.head, published: d.published_head, days_since: re.heads.length - 1 - re.heads.indexOf(d), say: ok ? `Your head of ${day} is what the chain recomputes to today; ${re.heads.length - 1 - re.heads.indexOf(d)} day(s) anchored since.` : `The chain at ${o} recomputes ${day} to ${d.head.slice(0, 8)}…${d.head.slice(-8)}, not to your ${head.slice(0, 8)}…${head.slice(-8)}: the past was changed, or you were served by someone else. Keep your copy; it is evidence.` };
+}