twzrd-receipt-verifier 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TWZRD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# TWZRD Receipt Verifier (standalone)
+
+Verify a TWZRD **AO-Receipt V5** offline, trusting **nothing from TWZRD's servers
+or codebase** - only the receipt, TWZRD's published public key, and two
+widely-audited crypto libraries.
+
+A TWZRD trust receipt has two layers:
+
+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.
+
+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.
+
+## The published signing key
+
+| field | value |
+|-------|-------|
+| algorithm | `ed25519` |
+| key_id | `twzrd-receipt-ed25519-v1` |
+| public key (base58) | `9V6Pn19kiUA5Rn6JpQfNduanvGt2aXGwsarosNfa2Ldf` |
+
+Also published, machine-readable, at:
+- `https://intel.twzrd.xyz/.well-known/x402` → `receipt.signature.public_key`
+- `https://intel.twzrd.xyz/openapi.json` → `x402.receipt.signature.public_key`
+- the MCP card `agent-intel-mcp-card.json` → `receipt_signing.public_key`
+
+> **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.
+
+## 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:
+
+```bash
+npx agentcash@latest fetch https://intel.twzrd.xyz/v1/intel/trust/<PUBKEY> > resp.json
+# the receipt is the `twzrd_receipt` object in the response
+```
+
+The receipt object looks like:
+
+```json
+{
+  "version": "v5",
+  "leaf": "0x...",
+  "preimage": { "domain": "TWZRD:AO_REPUTATION_RECEIPT_V5", "agent_id": "...", "score": 15, "...": "..." },
+  "signature": "base58 ed25519 sig",
+  "signing_pubkey": "9V6Pn19kiUA5Rn6JpQfNduanvGt2aXGwsarosNfa2Ldf",
+  "key_id": "twzrd-receipt-ed25519-v1",
+  "signing_alg": "ed25519"
+}
+```
+
+## Python
+
+```bash
+pip install pynacl pycryptodome     # libsodium Ed25519 + original Keccak-256
+
+# fetch the published key and verify:
+python verify_twzrd_receipt.py receipt.json
+
+# pin the key out-of-band (recommended):
+python verify_twzrd_receipt.py receipt.json --pubkey 9V6Pn19kiUA5Rn6JpQfNduanvGt2aXGwsarosNfa2Ldf
+
+# also confirm a tampered copy FAILS:
+python verify_twzrd_receipt.py receipt.json --self-test
+
+# from stdin:
+cat receipt.json | python verify_twzrd_receipt.py -
+```
+
+## Node
+
+```bash
+npm install                          # tweetnacl + js-sha3 + bs58
+
+node verify_twzrd_receipt.js receipt.json
+node verify_twzrd_receipt.js receipt.json --pubkey 9V6Pn19kiUA5Rn6JpQfNduanvGt2aXGwsarosNfa2Ldf --self-test
+cat receipt.json | node verify_twzrd_receipt.js -
+```
+
+Both exit `0` on `VALID`, `1` on `INVALID`.
+
+## What it checks (and the exact layout)
+
+The keccak256 leaf preimage is a strict little-endian, length-prefixed concat
+(reproducible in any language):
+
+```
+domain            = "TWZRD:AO_REPUTATION_RECEIPT_V5"   (or ...ATTENTION... for attention receipts)
+agent_id          = u16_le(len(utf8)) || utf8 bytes
+score             = u16_le
+confidence_bps    = u16_le
+timestamp_unix    = u64_le
+payer             = 32 bytes  (base58-decoded pubkey, or sha256(marker) for synthetic payers)
+settlement_anchor = 32 bytes  (last 32 bytes of the utf-8 settlement_tx string, or 32 zero bytes)
+
+leaf      = keccak256(domain || agent_id || score || confidence_bps || timestamp_unix || payer || settlement_anchor)
+signature = Ed25519_sign(receipt_signing_key, leaf_bytes)
+```
+
+The verifier:
+1. recomputes `leaf` from the preimage and compares it to `receipt.leaf`,
+2. confirms `receipt.signing_pubkey` (if present) equals the trusted key,
+3. verifies the Ed25519 `signature` over the 32 leaf bytes against the trusted key.
+
+`VALID` requires all three. The `settlement_tx` in the preimage is an on-chain
+Solana signature you can independently check for ground truth.
+
+## Trust assumptions
+
+You trust: the receipt you were given, the published public key (ideally pinned),
+and the crypto libraries (`PyNaCl`/libsodium, `pycryptodome`; `tweetnacl`,
+`js-sha3`). You do **not** trust TWZRD's API, database, or this repository's other
+code. Swap the libraries for your own if you prefer - the byte layout above is the
+whole spec.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "twzrd-receipt-verifier",
+  "version": "1.0.0",
+  "description": "Standalone offline verifier for TWZRD AO-Receipt V5 (Ed25519-signed keccak256 leaf). No trust in TWZRD servers or code.",
+  "keywords": ["twzrd", "x402", "solana", "ed25519", "keccak256", "receipt", "verifier", "agent", "attestation"],
+  "homepage": "https://intel.twzrd.xyz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/twzrd-sol/wzrd-final.git",
+    "directory": "packages/twzrd-agent-intel/verifier"
+  },
+  "license": "MIT",
+  "author": "TWZRD",
+  "bin": {
+    "verify-twzrd-receipt": "./verify_twzrd_receipt.js"
+  },
+  "files": [
+    "verify_twzrd_receipt.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "verify": "node verify_twzrd_receipt.js"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "dependencies": {
+    "bs58": "^4.0.1",
+    "js-sha3": "^0.8.0",
+    "tweetnacl": "^1.0.3"
+  }
+}

package/verify_twzrd_receipt.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+/*
+ * Standalone offline verifier for TWZRD AO-Receipt V5 (Node).
+ *
+ * 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).
+ *
+ * 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
+ *   node verify_twzrd_receipt.js receipt.json --pubkey 9V6Pn19kiUA5Rn6JpQfNduanvGt2aXGwsarosNfa2Ldf
+ *   cat receipt.json | node verify_twzrd_receipt.js -            # stdin
+ *   node verify_twzrd_receipt.js receipt.json --self-test        # tamper must fail
+ *
+ * Exit code 0 = VALID, 1 = INVALID / error.
+ */
+'use strict';
+
+const fs = require('fs');
+const crypto = require('crypto');
+const https = require('https');
+const nacl = require('tweetnacl');
+const { keccak256 } = require('js-sha3');
+const bs58 = require('bs58');
+
+const DEFAULT_BASE_URL = 'https://intel.twzrd.xyz';
+const KECCAK_EMPTY = 'c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470';
+
+function b58decode(s) { return Buffer.from(bs58.decode(s)); }
+
+function u16le(n) { const b = Buffer.alloc(2); b.writeUInt16LE(n & 0xffff, 0); return b; }
+function u64le(n) { const b = Buffer.alloc(8); b.writeBigUInt64LE(BigInt(n), 0); return b; }
+
+function payer32(payer) {
+  try { const raw = b58decode(payer); if (raw.length === 32) return raw; } catch (_) {}
+  return crypto.createHash('sha256').update(payer, 'utf8').digest();
+}
+
+function anchor32(tx) {
+  if (!tx) return Buffer.alloc(32);
+  const raw = Buffer.from(tx, 'utf8');
+  if (raw.length >= 32) return raw.subarray(raw.length - 32);
+  return Buffer.concat([Buffer.alloc(32 - raw.length), raw]);
+}
+
+function recomputeLeaf(pre) {
+  const dom = String(pre.domain || '').toUpperCase();
+  const isAttention = dom.includes('ATTENTION');
+  const domain = Buffer.from(isAttention ? 'TWZRD:AO_ATTENTION_RECEIPT_V5' : 'TWZRD:AO_REPUTATION_RECEIPT_V5', 'ascii');
+  const score = isAttention ? (pre.attention_score || 0) : (pre.score || 0);
+  const agent = Buffer.from(pre.agent_id, 'utf8');
+  const msg = Buffer.concat([
+    domain,
+    u16le(agent.length), agent,
+    u16le(score),
+    u16le(pre.confidence_bps),
+    u64le(pre.timestamp_unix),
+    payer32(pre.payer),
+    anchor32(pre.settlement_tx || pre.settlement_anchor),
+  ]);
+  return Buffer.from(keccak256.arrayBuffer(msg));
+}
+
+function fetchPublishedPubkey(baseUrl) {
+  const url = baseUrl.replace(/\/+$/, '') + '/.well-known/x402';
+  return new Promise((resolve, reject) => {
+    https.get(url, { headers: { 'User-Agent': 'twzrd-receipt-verifier/1.0' } }, (res) => {
+      let body = '';
+      res.on('data', (c) => (body += c));
+      res.on('end', () => {
+        try { resolve(JSON.parse(body).receipt.signature.public_key); }
+        catch (e) { reject(e); }
+      });
+    }).on('error', reject);
+  });
+}
+
+function verify(receipt, trustedPubkey) {
+  const out = { leaf_valid: false, signature_valid: false, errors: [] };
+  const pre = receipt.preimage || {};
+  const leafHex = String(receipt.leaf || '').toLowerCase().replace(/^0x/, '');
+
+  let recomputed;
+  try { recomputed = recomputeLeaf(pre); }
+  catch (e) { out.errors.push('could not recompute leaf: ' + e.message); return out; }
+  out.recomputed_leaf = '0x' + recomputed.toString('hex');
+  out.leaf_valid = recomputed.toString('hex') === leafHex;
+  if (!out.leaf_valid) out.errors.push('leaf mismatch: preimage does not hash to receipt.leaf');
+
+  const sig = receipt.signature;
+  if (!sig) { out.errors.push('missing signature (unsigned receipts are rejected)'); return out; }
+
+  const embedded = receipt.signing_pubkey;
+  if (embedded && embedded !== trustedPubkey) {
+    out.errors.push(`signing_pubkey ${embedded} != trusted published key ${trustedPubkey}`);
+    return out;
+  }
+
+  try {
+    out.signature_valid = nacl.sign.detached.verify(
+      new Uint8Array(recomputed),
+      new Uint8Array(b58decode(sig)),
+      new Uint8Array(b58decode(trustedPubkey)),
+    );
+  } 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 published key');
+
+  out.valid = out.leaf_valid && out.signature_valid && out.errors.length === 0;
+  out.trusted_pubkey = trustedPubkey;
+  return out;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0) { console.error('usage: verify_twzrd_receipt.js <receipt.json|-> [--pubkey KEY] [--base-url URL] [--self-test]'); process.exit(1); }
+  const receiptArg = args[0];
+  const getOpt = (name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; };
+  const selfTest = args.includes('--self-test');
+  const baseUrl = getOpt('--base-url') || DEFAULT_BASE_URL;
+
+  // 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);
+
+  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}]`);
+
+  const res = verify(receipt, trusted);
+  console.log(`leaf_valid       : ${res.leaf_valid}`);
+  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.preimage = tampered.preimage || {};
+    tampered.preimage.score = (tampered.preimage.score || 0) + 1;
+    const t = verify(tampered, trusted);
+    const passed = !t.valid;
+    console.log(`self-test (tampered score must FAIL): ${passed ? 'PASS' : 'BROKEN'}`);
+    ok = ok && passed;
+  }
+
+  process.exit(ok ? 0 : 1);
+}
+
+main().catch((e) => { console.error('error:', e.message); process.exit(1); });