twzrd-receipt-verifier 1.1.0 → 1.2.1

package/README.md

@@ -80,7 +80,7 @@ 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`.
+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)
@@ -90,8 +90,17 @@ 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]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twzrd-receipt-verifier",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "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",

package/verify_twzrd_receipt.js

@@ -44,9 +44,12 @@ 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. Matches `verify_pubkey` in every genesis anchor and the
-// verified creator on every cNFT in tree 8QFdTqBkSeyuvp47dXdpwfWzXTuYSbAC64oT4soPGnXS.
+// 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)); }
 
@@ -146,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 || {};
@@ -275,14 +304,18 @@ TWZRD's published Ed25519 key and was not tampered with. Auto-detects two famili
   - 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] [--wallet ADDR] [--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/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   (trust-API only) where to fetch the published key (default: ${DEFAULT_BASE_URL})
+  --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.
@@ -290,10 +323,11 @@ arguments:
   -h, --help       show this help
 
 exit code: 0 = VALID, 1 = INVALID / error
-trust-API 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] [--wallet ADDR] [--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);
   }
@@ -310,8 +344,16 @@ trust-API key source: ${DEFAULT_BASE_URL}/.well-known/x402`;
   // ── 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 { trusted = DEFAULT_CNFT_PUBKEY; keySrc = 'built-in genesis authority'; }
+    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,
     });
@@ -339,6 +381,7 @@ trust-API key source: ${DEFAULT_BASE_URL}/.well-known/x402`;
     res.errors.forEach((e) => console.log('  - ' + e));
     let ok = !!res.valid;
     console.log(`RESULT           : ${ok ? 'VALID (TWZRD-authored, untampered)' : 'INVALID'}`);
+    if (ok) console.log('                   verified with the same library TWZRD uses internally (npm: twzrd-receipt-verifier)');
 
     if (selfTest) {
       const tampered = JSON.parse(raw);
@@ -387,6 +430,7 @@ trust-API key source: ${DEFAULT_BASE_URL}/.well-known/x402`;
   res.errors.forEach((e) => console.log('  - ' + e));
   let ok = !!res.valid;
   console.log(`RESULT           : ${ok ? 'VALID (TWZRD-authored, untampered)' : 'INVALID'}`);
+  if (ok) console.log('                   verified with the same library TWZRD uses internally (npm: twzrd-receipt-verifier)');
 
   if (selfTest) {
     const tampered = JSON.parse(raw);
@@ -406,7 +450,8 @@ trust-API key source: ${DEFAULT_BASE_URL}/.well-known/x402`;
 module.exports = {
   verify, recomputeLeaf,
   verifyCnft, cnftSignedPayload, isCnftReceipt, resolveWallet,
-  DEFAULT_CNFT_PUBKEY, CNFT_SIGNED_FIELDS,
+  fetchCnftPubkey,
+  DEFAULT_CNFT_PUBKEY, DEFAULT_CNFT_BASE_URL, CNFT_SIGNED_FIELDS,
 };
 
 if (require.main === module) {