twzrd-receipt-verifier 1.0.9 → 1.2.0

package/README.md

@@ -1,20 +1,23 @@
 # TWZRD Receipt Verifier (standalone)
 
-Verify a TWZRD **AO-Receipt (V5 or V6)** offline, trusting **nothing from TWZRD's
-servers or codebase** - only the receipt, TWZRD's published public key, and two
-widely-audited crypto libraries. The verifier reads the domain the receipt
-carries and applies the matching V5 or V6 leaf rules (V6 binds the
-`reputation_*` provenance fields into the signed leaf; V5 left them unsigned).
+Verify a TWZRD receipt offline, trusting **nothing from TWZRD's servers or
+codebase** - only the receipt, TWZRD's published public key, and two
+widely-audited crypto libraries. The verifier **auto-detects** two receipt
+families:
 
-A TWZRD trust receipt has two layers:
+| Family | What it is | Scheme | Signing key |
+|--------|-----------|--------|-------------|
+| **AO-Receipt V5/V6** | trust-API receipts from `intel.twzrd.xyz` | `keccak256` leaf over a packed preimage, Ed25519 over the leaf bytes | `9V6Pn19...` (fetched/pinned) |
+| **cNFT Receipt** | the 95k genesis compressed-NFT receipts | Ed25519 **directly** over a compact-JSON payload (no leaf), hex sig | `2ELSDx...` (built-in) |
 
-1. **Tamper-evidence** - a `keccak256` leaf over the receipt's preimage fields.
-2. **Authenticity** - an **Ed25519 signature** over the leaf bytes, made with
-   TWZRD's dedicated receipt-signing key.
+For V5/V6 the verifier reads the domain the receipt carries and applies the
+matching leaf rules (V6 binds the `reputation_*` provenance fields into the signed
+leaf; V5 left them unsigned). For cNFT receipts there is no leaf - tamper-evidence
+**is** the signature: any change to a signed field (including the wallet)
+invalidates it.
 
-This tool recomputes the leaf **and** checks the signature against the published
-key. If it says `VALID`, the receipt was authored by TWZRD and was not altered.
-Unsigned, wrong-key, or tampered receipts fail.
+If it says `VALID`, the receipt was authored by TWZRD and was not altered.
+Unsigned, wrong-key, wrong-wallet, or tampered receipts fail.
 
 ## Where this fits: the agent trust loop
 
@@ -50,10 +53,79 @@ Also published, machine-readable, at:
 > **Most paranoid mode:** pin the key out-of-band with `--pubkey` instead of
 > fetching it, so you never trust the live endpoint to tell you which key to trust.
 
+## cNFT Receipts (the 95k genesis receipts)
+
+Every genesis receipt is a compressed NFT on Solana mainnet (tree
+`8QFdTqBkSeyuvp47dXdpwfWzXTuYSbAC64oT4soPGnXS`, verified creator `2ELSDx...`). Its
+at-mint snapshot is published as a signed `anchor` block in the cNFT metadata,
+served at `https://twzrd.xyz/r/<wallet>.json`:
+
+```json
+{
+  "anchor": {
+    "tier_at_mint": "Platinum",
+    "score_at_mint": 255,
+    "verified_tx": "<solana settlement signature>",
+    "behavior_proof": "<sha256 hex>",
+    "minted_at": 1782415336,
+    "signature": "<128-hex Ed25519 sig>",
+    "verify_pubkey": "2ELSDxLkb7dYrN6EUG69tNtULAq4Fo7WPvXyrZPmuFif"
+  },
+  "live": { "...": "current decayed reputation (NOT signed)" }
+}
+```
+
+The signed payload is the compact JSON `{wallet, tier_at_mint, score_at_mint,
+verified_tx, behavior_proof, minted_at}` (exact key order). The `wallet` is the
+first signed field but is **not** stored in the anchor - it is the `<wallet>.json`
+filename / the cNFT leaf owner - so pass `--wallet` or keep the filename. The
+signing key (`2ELSDx...`) is **built in** to the verifier (pinned in the audited
+package); override with `--pubkey`, or fetch the published copy with `--fetch-key`.
+
+```bash
+# fetch a receipt and verify it (wallet inferred from the filename, key built-in)
+W=zoz7neLHXoaLwNBuckSqNqaMsacpqJsphtFuNNpQyt3
+curl -s https://twzrd.xyz/r/$W.json -o $W.json
+npx twzrd-receipt-verifier $W.json --self-test
+
+# or pass the wallet explicitly (e.g. when piping from stdin)
+npx twzrd-receipt-verifier anchor.json --wallet $W
+
+# fetch the key from the published descriptor instead of the built-in copy
+# (cross-check, or pin to whatever the live domain publishes)
+npx twzrd-receipt-verifier $W.json --fetch-key
+```
+
+The key is published, machine-readable, at `https://api.twzrd.xyz/v1/receipts/pubkey`
+(and `https://twzrd.xyz/.well-known/twzrd-receipt-pubkey`) with the full signing spec
+(`public_key`, `signed_fields`, `scheme`, `tree`). It must equal the built-in key **and**
+the on-chain verified creator of every cNFT in the tree - three independent sources.
+
+```
+mode             : cNFT (Bubblegum anchor)
+trusted pubkey   : 2ELSDxLkb7dYrN6EUG69tNtULAq4Fo7WPvXyrZPmuFif  [source: built-in genesis authority]
+wallet           : zoz7neLHXoaLwNBuckSqNqaMsacpqJsphtFuNNpQyt3  [source: filename]
+signature_valid  : true
+RESULT           : VALID (TWZRD-authored, untampered)
+```
+
+Only the `anchor` block is signed. The `live` block (current decayed reputation)
+is informational and intentionally NOT covered by the signature. For full on-chain
+binding, confirm the cNFT exists in the genesis tree with verified creator
+`2ELSDx` via any DAS provider (`getAsset` / `getAssetProof`); the signature alone
+already proves `2ELSDx` authorship of the at-mint snapshot.
+
 ## Get a receipt to verify
 
-Any TWZRD V5 receipt works. To mint a fresh one, pay the trust endpoint (x402,
-0.05 USDC on Solana mainnet) - e.g. via AgentCash:
+Any TWZRD V5/v6 receipt works. To mint a fresh one, pay the trust endpoint
+(x402, 0.05 USDC on Solana mainnet) with an x402 client that preserves TWZRD's
+sponsored fee-payer slot semantics.
+
+Current caveat (2026-06-23): `npx agentcash@latest fetch ...` is not a green
+TWZRD paid-trust repro. It failed closed with `payment_invalid` /
+`fee_payer_slot_already_signed`, and AgentCash balance stayed unchanged.
+
+Known-bad compatibility command:
 
 ```bash
 npx agentcash@latest fetch https://intel.twzrd.xyz/v1/intel/trust/<PUBKEY> > resp.json

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "twzrd-receipt-verifier",
-  "version": "1.0.9",
-  "description": "Standalone offline verifier for TWZRD AO-Receipt V5 and V6 (Ed25519-signed keccak256 leaf). No trust in TWZRD servers or code.",
+  "version": "1.2.0",
+  "description": "Standalone offline verifier for TWZRD receipts: AO-Receipt V5/V6 (keccak256 leaf) and genesis cNFT receipts (Ed25519 over compact JSON). No trust in TWZRD servers or code.",
   "keywords": [
     "twzrd",
     "x402",
@@ -11,7 +11,10 @@
     "receipt",
     "verifier",
     "agent",
-    "attestation"
+    "attestation",
+    "cnft",
+    "bubblegum",
+    "compressed-nft"
   ],
   "homepage": "https://intel.twzrd.xyz",
   "bugs": {

package/verify_twzrd_receipt.js

@@ -1,21 +1,30 @@
 #!/usr/bin/env node
 /*
- * Standalone offline verifier for TWZRD AO-Receipt V5 (Node).
+ * Standalone offline verifier for TWZRD receipts (Node). Two receipt families,
+ * auto-detected:
  *
- * Verifies, with NO trust in TWZRD's servers or codebase, that a receipt was
- * authored by TWZRD's published Ed25519 key and was not tampered with:
- *   1. TAMPER-EVIDENCE - recompute the keccak256 leaf from the preimage,
- *      confirm it equals receipt.leaf.
- *   2. AUTHENTICITY    - verify the Ed25519 signature over the leaf bytes
- *      against TWZRD's PUBLISHED public key (you supply / fetch it).
+ *   A. AO-Receipt V5/V6 (trust-API)  - keccak256 leaf over a packed preimage,
+ *      Ed25519-signed over the leaf bytes by the receipt key (9V6Pn19...).
+ *      Shape: { preimage, leaf, signature, signing_pubkey }.
+ *   B. cNFT Receipt (Bubblegum anchor) - the genesis compressed-NFT receipts.
+ *      Ed25519 signed DIRECTLY over a compact-JSON payload (no keccak leaf) by
+ *      the airship genesis authority (2ELSDx...), signature hex-encoded.
+ *      Shape: { anchor: { tier_at_mint, score_at_mint, verified_tx,
+ *      behavior_proof, minted_at, signature, verify_pubkey }, ... }.
  *
- * Crypto comes from audited libs (tweetnacl = ref Ed25519, js-sha3 = Keccak),
- * not from this script. base58 + the TWZRD byte layout are the only logic here.
+ * Verifies, with NO trust in TWZRD's servers or codebase, that a receipt was
+ * authored by TWZRD's published Ed25519 key and was not tampered with. Crypto
+ * comes from audited libs (tweetnacl = ref Ed25519, js-sha3 = Keccak), not from
+ * this script. base58 + the TWZRD byte layout are the only logic here.
  *
  *   npm install tweetnacl js-sha3 bs58
  *
- *   node verify_twzrd_receipt.js receipt.json
+ *   # trust-API receipt (A)
  *   node verify_twzrd_receipt.js receipt.json --pubkey 9V6Pn19kiUA5Rn6JpQfNduanvGt2aXGwsarosNfa2Ldf
+ *   # cNFT receipt (B) - wallet is part of the signed payload but not in the
+ *   #   anchor block, so pass it or name the file <wallet>.json
+ *   node verify_twzrd_receipt.js zoz7...json            # wallet inferred from filename
+ *   node verify_twzrd_receipt.js anchor.json --wallet zoz7neLHXoaLwNBuckSqNqaMsacpqJsphtFuNNpQyt3
  *   cat receipt.json | node verify_twzrd_receipt.js -            # stdin
  *   node verify_twzrd_receipt.js receipt.json --self-test        # tamper must fail
  *
@@ -24,6 +33,7 @@
 'use strict';
 
 const fs = require('fs');
+const path = require('path');
 const crypto = require('crypto');
 const https = require('https');
 const nacl = require('tweetnacl');
@@ -32,6 +42,14 @@ const bs58 = require('bs58');
 
 const DEFAULT_BASE_URL = 'https://intel.twzrd.xyz';
 const KECCAK_EMPTY = 'c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470';
+// Genesis cNFT receipt authority (airship). Baked in as the most paranoid form of
+// out-of-band pinning: the key ships in this audited package, never fetched live.
+// Override with --pubkey, or fetch the published copy with --fetch-key (cross-check).
+// Matches `verify_pubkey` in every genesis anchor and the verified creator on every
+// cNFT in tree 8QFdTqBkSeyuvp47dXdpwfWzXTuYSbAC64oT4soPGnXS.
+const DEFAULT_CNFT_PUBKEY = '2ELSDxLkb7dYrN6EUG69tNtULAq4Fo7WPvXyrZPmuFif';
+// Where --fetch-key looks for the published cNFT key descriptor.
+const DEFAULT_CNFT_BASE_URL = 'https://api.twzrd.xyz';
 
 function b58decode(s) { return Buffer.from(bs58.decode(s)); }
 
@@ -131,6 +149,32 @@ function fetchPublishedPubkey(baseUrl) {
   return fetchPath(0);
 }
 
+// Fetch the published cNFT signing key descriptor (for --fetch-key). Returns the
+// base58 pubkey. This trades package-trust for domain/TLS-trust; the built-in key is
+// the default precisely because it needs no network. Use this to CROSS-CHECK the
+// built-in, or to pin to whatever the live domain currently publishes.
+function fetchCnftPubkey(baseUrl) {
+  const base = baseUrl.replace(/\/+$/, '');
+  const paths = ['/v1/receipts/pubkey', '/.well-known/twzrd-receipt-pubkey'];
+  const headers = { 'User-Agent': 'twzrd-receipt-verifier/cnft' };
+  function fetchPath(i) {
+    if (i >= paths.length) return Promise.reject(new Error('no cNFT pubkey endpoint responded'));
+    return new Promise((resolve, reject) => {
+      https.get(base + paths[i], { headers }, (res) => {
+        let body = '';
+        res.on('data', (c) => (body += c));
+        res.on('end', () => {
+          try {
+            const pk = JSON.parse(body).public_key;
+            if (pk) resolve(pk); else throw new Error('no public_key field');
+          } catch (e) { fetchPath(i + 1).then(resolve, reject); }
+        });
+      }).on('error', () => fetchPath(i + 1).then(resolve, reject));
+    });
+  }
+  return fetchPath(0);
+}
+
 function verify(receipt, trustedPubkey) {
   const out = { leaf_valid: false, signature_valid: false, errors: [] };
   const pre = receipt.preimage || {};
@@ -166,31 +210,124 @@ function verify(receipt, trustedPubkey) {
   return out;
 }
 
+// ── cNFT (Bubblegum anchor) receipt ───────────────────────────────────────
+// The genesis compressed-NFT receipts are NOT keccak-leaf receipts. Each is an
+// Ed25519 signature made DIRECTLY over the UTF-8 bytes of a compact JSON object,
+// in this EXACT key order (JSON.stringify defaults: no spaces). Do not reorder.
+const CNFT_SIGNED_FIELDS = ['wallet', 'tier_at_mint', 'score_at_mint', 'verified_tx', 'behavior_proof', 'minted_at'];
+
+// A cNFT receipt is the metadata JSON served at /r/<wallet>.json: it carries an
+// `anchor` block (at-mint snapshot + signature) instead of a keccak `leaf`.
+function isCnftReceipt(receipt) {
+  const a = receipt && receipt.anchor;
+  return !!(a && typeof a === 'object' && a.signature &&
+    (a.tier_at_mint !== undefined || a.score_at_mint !== undefined));
+}
+
+// Reconstruct the exact bytes the issuer signed (airship.ts). `wallet` is the
+// first signed field but is NOT stored in the anchor block (it is the leaf owner /
+// the <wallet>.json filename), so it must be supplied by the caller.
+function cnftSignedPayload(anchor, wallet) {
+  return Buffer.from(JSON.stringify({
+    wallet,
+    tier_at_mint: anchor.tier_at_mint,
+    score_at_mint: anchor.score_at_mint,
+    verified_tx: anchor.verified_tx,
+    behavior_proof: anchor.behavior_proof,
+    minted_at: anchor.minted_at,
+  }), 'utf8');
+}
+
+// Resolve the wallet from (in priority): explicit --wallet, the receipt body (if a
+// future format embeds it), or the <wallet>.json filename. Only accepts a filename
+// stem that base58-decodes to a 32-byte pubkey, so a stray filename can't be passed
+// off as the signed wallet.
+function resolveWallet({ explicitWallet, receipt, receiptPath } = {}) {
+  if (explicitWallet) return { wallet: explicitWallet, src: '--wallet' };
+  if (receipt && typeof receipt.wallet === 'string') return { wallet: receipt.wallet, src: 'receipt.wallet' };
+  if (receipt && receipt.anchor && typeof receipt.anchor.wallet === 'string') return { wallet: receipt.anchor.wallet, src: 'anchor.wallet' };
+  if (receiptPath && receiptPath !== '-') {
+    const stem = path.basename(receiptPath).replace(/\.json$/i, '');
+    try { if (Buffer.from(bs58.decode(stem)).length === 32) return { wallet: stem, src: 'filename' }; } catch (_) {}
+  }
+  return { wallet: undefined, src: 'none' };
+}
+
+// Authenticity for a cNFT receipt: Ed25519-verify the hex signature over the
+// reconstructed compact-JSON payload against the trusted key. There is no keccak
+// leaf to recompute - tamper-evidence is the signature itself: any change to a
+// signed field (incl. wallet) invalidates it.
+function verifyCnft(receipt, trustedPubkey, wallet) {
+  const out = { mode: 'cnft', signature_valid: false, errors: [] };
+  const a = (receipt && receipt.anchor) || {};
+  out.wallet = wallet;
+  if (!wallet) {
+    out.errors.push('cNFT receipt: wallet unknown - it is part of the signed payload but not in the anchor block. Pass --wallet <addr> or name the file <wallet>.json.');
+    return out;
+  }
+  const embedded = a.verify_pubkey;
+  if (embedded && embedded !== trustedPubkey) {
+    out.errors.push(`anchor.verify_pubkey ${embedded} != trusted key ${trustedPubkey}`);
+    return out;
+  }
+  const sigHex = String(a.signature || '').toLowerCase().replace(/^0x/, '');
+  if (!sigHex) { out.errors.push('missing anchor.signature'); return out; }
+  if (!/^[0-9a-f]+$/.test(sigHex) || sigHex.length !== 128) {
+    out.errors.push(`anchor.signature must be 64 hex bytes (got ${sigHex.length / 2 | 0})`);
+    return out;
+  }
+  const sig = Buffer.from(sigHex, 'hex');
+  const msg = cnftSignedPayload(a, wallet);
+  out.signed_payload = msg.toString('utf8');
+  let pk;
+  try { pk = b58decode(trustedPubkey); }
+  catch (e) { out.errors.push('trusted pubkey not base58: ' + e.message); return out; }
+  try {
+    out.signature_valid = nacl.sign.detached.verify(
+      new Uint8Array(msg), new Uint8Array(sig), new Uint8Array(pk));
+  } catch (e) { out.errors.push('signature check error: ' + e.message); return out; }
+  if (!out.signature_valid) {
+    out.errors.push('signature not valid for the trusted key (payload tampered, or wrong --wallet / --pubkey)');
+  }
+  out.valid = out.signature_valid && out.errors.length === 0;
+  out.trusted_pubkey = trustedPubkey;
+  return out;
+}
+
 async function main() {
   const args = process.argv.slice(2);
-  const HELP = `twzrd-receipt-verifier -- offline verifier for TWZRD AO-Receipt V5 (Ed25519-signed keccak256 leaf)
+  const HELP = `twzrd-receipt-verifier -- offline verifier for TWZRD receipts (Ed25519)
 
 Verifies, with NO trust in TWZRD's servers or code, that a receipt was authored by
-TWZRD's published Ed25519 key and was not tampered with.
+TWZRD's published Ed25519 key and was not tampered with. Auto-detects two families:
+  - AO-Receipt V5/V6 (trust-API): keccak256 leaf, signed by ${'9V6Pn19...'} (default fetch)
+  - cNFT Receipt (genesis anchor): compact-JSON payload, signed by ${DEFAULT_CNFT_PUBKEY.slice(0, 7)}... (built-in)
 
 usage:
-  twzrd-receipt-verifier <receipt.json|-> [--pubkey KEY] [--base-url URL] [--max-age SECS] [--self-test]
+  twzrd-receipt-verifier <receipt.json|-> [--pubkey KEY] [--fetch-key] [--wallet ADDR] [--base-url URL] [--max-age SECS] [--self-test]
 
 arguments:
   <receipt.json>   path to the receipt JSON, or "-" to read from stdin
-  --pubkey KEY     trust this base58 Ed25519 pubkey (out-of-band) instead of fetching it
-  --base-url URL   where to fetch the published key (default: ${DEFAULT_BASE_URL})
-  --max-age SECS   replay-resistance policy: reject if preimage.timestamp_unix is older than
-                   SECS, OR if the receipt carries no valid timestamp. Crypto (leaf+sig) is
-                   time-independent; this is opt-in relying-party policy.
+  --pubkey KEY     trust this base58 Ed25519 pubkey (out-of-band) instead of fetching/built-in
+  --fetch-key      (cNFT only) fetch the signing key from the published well-known descriptor
+                   (--base-url or ${DEFAULT_CNFT_BASE_URL}) instead of the built-in copy. Trades
+                   package-trust for domain/TLS-trust; default stays built-in (no network).
+  --wallet ADDR    (cNFT only) the leaf-owner wallet, which is part of the signed payload but
+                   not stored in the anchor block. Inferred from a <wallet>.json filename if omitted.
+  --base-url URL   where to fetch the key: trust-API default ${DEFAULT_BASE_URL}; cNFT (--fetch-key)
+                   default ${DEFAULT_CNFT_BASE_URL}
+  --max-age SECS   replay-resistance policy: reject if the receipt's timestamp (preimage.timestamp_unix
+                   for trust-API, anchor.minted_at for cNFT) is older than SECS, OR is missing.
+                   Crypto is time-independent; this is opt-in relying-party policy.
   --self-test      additionally confirm a tampered copy FAILS (proves the check works)
   -h, --help       show this help
 
 exit code: 0 = VALID, 1 = INVALID / error
-key source: ${DEFAULT_BASE_URL}/.well-known/x402`;
+trust-API key source: ${DEFAULT_BASE_URL}/.well-known/x402
+cNFT key source:      ${DEFAULT_CNFT_BASE_URL}/v1/receipts/pubkey`;
   if (args.includes('-h') || args.includes('--help')) { console.log(HELP); process.exit(0); }
   if (args.length === 0) {
-    console.error('usage: twzrd-receipt-verifier <receipt.json|-> [--pubkey KEY] [--base-url URL] [--max-age SECS] [--self-test]');
+    console.error('usage: twzrd-receipt-verifier <receipt.json|-> [--pubkey KEY] [--fetch-key] [--wallet ADDR] [--base-url URL] [--max-age SECS] [--self-test]');
     console.error('       twzrd-receipt-verifier --help');
     process.exit(1);
   }
@@ -201,16 +338,71 @@ key source: ${DEFAULT_BASE_URL}/.well-known/x402`;
   const maxAgeArg = getOpt('--max-age');
   const maxAge = maxAgeArg ? parseInt(maxAgeArg, 10) : 0;  // 0 = freshness check off (opt-in policy)
 
-  // keccak self-test: refuse to run with a broken hash backend
-  if (keccak256('') !== KECCAK_EMPTY) { console.error('FATAL: keccak256 backend is wrong'); process.exit(1); }
-
   const raw = receiptArg === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(receiptArg, 'utf8');
   const receipt = JSON.parse(raw);
 
+  // ── cNFT (Bubblegum anchor) receipt: Ed25519 over compact JSON, no keccak leaf ──
+  if (isCnftReceipt(receipt)) {
+    let trusted = getOpt('--pubkey'), keySrc;
+    if (trusted) {
+      keySrc = '--pubkey (out-of-band)';
+    } else if (args.includes('--fetch-key')) {
+      const fetchBase = getOpt('--base-url') || DEFAULT_CNFT_BASE_URL;
+      trusted = await fetchCnftPubkey(fetchBase);
+      keySrc = `fetched from ${fetchBase}`;
+    } else {
+      trusted = DEFAULT_CNFT_PUBKEY;
+      keySrc = 'built-in genesis authority';
+    }
+    const { wallet, src: walletSrc } = resolveWallet({
+      explicitWallet: getOpt('--wallet'), receipt, receiptPath: receiptArg,
+    });
+    console.log(`mode             : cNFT (Bubblegum anchor)`);
+    console.log(`trusted pubkey   : ${trusted}  [source: ${keySrc}]`);
+    console.log(`wallet           : ${wallet || '(unknown)'}  [source: ${walletSrc}]`);
+
+    const res = verifyCnft(receipt, trusted, wallet);
+    res.errors = res.errors || [];
+
+    // Opt-in freshness gate (anchor.minted_at). cNFT receipts are long-lived by
+    // design, so this is rarely useful, but kept for parity with the trust-API path.
+    if (maxAge > 0) {
+      const ts = receipt.anchor ? Number(receipt.anchor.minted_at) : NaN;
+      if (!Number.isFinite(ts) || ts <= 0) {
+        res.errors.push(`--max-age ${maxAge}s set but anchor has no valid minted_at`);
+        res.valid = false;
+      } else {
+        const age = Math.abs(Math.floor(Date.now() / 1000) - ts);
+        if (age > maxAge) { res.errors.push(`receipt too old (age ${age}s > --max-age ${maxAge}s)`); res.valid = false; }
+      }
+    }
+
+    console.log(`signature_valid  : ${res.signature_valid}`);
+    res.errors.forEach((e) => console.log('  - ' + e));
+    let ok = !!res.valid;
+    console.log(`RESULT           : ${ok ? 'VALID (TWZRD-authored, untampered)' : 'INVALID'}`);
+
+    if (selfTest) {
+      const tampered = JSON.parse(raw);
+      tampered.anchor = tampered.anchor || {};
+      tampered.anchor.score_at_mint = (Number(tampered.anchor.score_at_mint) || 0) + 1;
+      const t = verifyCnft(tampered, trusted, wallet);
+      const passed = !t.valid;
+      console.log(`self-test (tampered score must FAIL): ${passed ? 'PASS' : 'BROKEN'}`);
+      ok = ok && passed;
+    }
+    process.exit(ok ? 0 : 1);
+  }
+
+  // ── trust-API receipt (V5/V6): keccak256 leaf, signed over the leaf bytes ──
+  // keccak self-test: refuse to run with a broken hash backend
+  if (keccak256('') !== KECCAK_EMPTY) { console.error('FATAL: keccak256 backend is wrong'); process.exit(1); }
+
   let trusted = getOpt('--pubkey'), src;
   if (trusted) { src = '--pubkey (out-of-band)'; }
   else { trusted = await fetchPublishedPubkey(baseUrl); src = baseUrl + '/.well-known/x402'; }
-  console.log(`trusted pubkey: ${trusted}  [source: ${src}]`);
+  console.log(`mode             : AO-Receipt (trust-API)`);
+  console.log(`trusted pubkey   : ${trusted}  [source: ${src}]`);
 
   const res = verify(receipt, trusted);
 
@@ -251,4 +443,15 @@ key source: ${DEFAULT_BASE_URL}/.well-known/x402`;
   process.exit(ok ? 0 : 1);
 }
 
-main().catch((e) => { console.error('error:', e.message); process.exit(1); });
+// Export the pure verifiers for tests / programmatic use. Only run the CLI when
+// invoked directly (so `require()` from the test suite does not trigger main()).
+module.exports = {
+  verify, recomputeLeaf,
+  verifyCnft, cnftSignedPayload, isCnftReceipt, resolveWallet,
+  fetchCnftPubkey,
+  DEFAULT_CNFT_PUBKEY, DEFAULT_CNFT_BASE_URL, CNFT_SIGNED_FIELDS,
+};
+
+if (require.main === module) {
+  main().catch((e) => { console.error('error:', e.message); process.exit(1); });
+}