@xfuel/verify 0.3.0 → 0.3.3

package/dist/cli.js

@@ -17,12 +17,17 @@
  *   3 = input error
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+const node_module_1 = require("node:module");
 const node_fs_1 = require("node:fs");
 const index_js_1 = require("./index.js");
 const anchor_witness_js_1 = require("./anchor-witness.js");
+const jws_js_1 = require("./jws.js");
 const preimage_js_1 = require("./preimage.js");
 const issuer_history_js_1 = require("./issuer-history.js");
 const canonical_preimage_js_1 = require("./canonical-preimage.js");
+const v11_receipt_js_1 = require("./v11-receipt.js");
+const issuer_pin_js_1 = require("./issuer-pin.js");
+const anchor_trust_js_1 = require("./anchor-trust.js");
 const HELP = `
 xfuel-verify — Offline verification for Chit402 receipts
 
@@ -51,10 +56,35 @@ Options:
   --check-payer       Query Base or Solana RPC. Base confirms payer, payee, asset, amount
   --solana-rpc <url>  Solana RPC URL (default: https://api.mainnet-beta.solana.com or SOLANA_RPC_URL)
   --rpc <url>         Base RPC URL (default: https://mainnet.base.org)
+  --version           Print @xfuel/verify version and exit
   --rpc               With a receipt, an inclusion proof, and a tree head: check the
-                      leaf, then the Solana memo and the Base calldata for that root
+                      leaf, then the Solana memo and the Base calldata for that root.
+                      The tree head must carry a valid ES256 issuer signature, and
+                      the anchor wallets must match the signed head.
+                      A v2 head also needs the signed epoch record.
+                      A tree-head file with --rpc enters this mode.
+                      The same files without --rpc check the head signature and the
+                      index/size-bound inclusion offline. They do not call chain RPC.
+  --epoch-record <f>  Signed epoch record JSON. Skips the network fetch.
+  --epoch-url <url>   GET this epoch record. Default: the receipt verify_url
+                      origin plus /v1/receipts/tree/epoch
   --inclusion <file>  Inclusion proof JSON (chit402.inclusion.v1)
-  --head <file>       Signed tree head JSON (chit402.tree_head.v1)
+  --head <file>       Signed tree head JSON (chit402.tree_head.v1 or v2)
+  --anchor-wallets-file <path>
+                      Signed chit402.anchor_wallets.v1 document. Wallets in a
+                      verified document are added to the package pin. A head
+                      that names any other wallet fails.
+  --carry-old-head <file>
+  --carry-old-inclusion <file>
+  --carry-head <file>
+  --carry-inclusion <file>
+                      Earlier signed head, its inclusion proof, the current
+                      signed head, and the current inclusion proof. Repeat
+                      --carry-inclusion for each current index of the leaf.
+                      The issued time and epoch are the earlier head's signed
+                      claims. The logged time, epoch, and leaf index are the
+                      current head's signed claims. A receipt in the current
+                      epoch does not use these flags.
   --json              Output JSON instead of human-readable
   --quiet             Only output errors
   --strict-issuer-history
@@ -78,15 +108,24 @@ Trust:
   issuer_jwk whose RFC 7638 thumbprint equals a pinned trusted kid. The
   embedded key alone is not a trust root. Untrusted keys report "key untrusted".
 
-  Amount, payer, payee, and tx are read from verified signed claims. A mismatch
-  with the unsigned outer payment / caller_binding copy is a failure.
+  Amount, payer, payee, and tx are read from verified signed claims. Every
+  signed field is compared with the outer receipt at the same path. A mismatch
+  fails. Outer fields the signature does not cover are printed as UNVERIFIED.
+  The outer document schema is not a copy of the JWS schema. Log mode (a
+  receipt, an inclusion proof, and a tree head) runs these receipt checks too.
 
 Network behavior:
-  By default, no network requests are made. Network is only used when:
-  - --fetch-jwks or --jwks-url is passed
-  - --check-nullifier is passed (queries Base RPC for on-chain anchor)
-  - --check-payer is passed (queries Base or Solana RPC for USDC settlement)
-  - --rpc is passed with a receipt, an inclusion proof, and a tree head
+  JWKS, nullifiers, and anchors are not fetched unless you pass a flag.
+  Issuer history is fetched by default when the receipt names a history URL
+  and neither --issuer-history-file nor --no-issuer-history is set. A payload
+  v10 receipt fails (exit 1) when that fetch cannot run. Offline mode is
+  --issuer-history-file <snapshot>, or --no-issuer-history to skip the window.
+  Other network uses:
+  - --fetch-jwks or --jwks-url
+  - --check-nullifier (Base RPC)
+  - --check-payer (Base or Solana RPC)
+  - --rpc with a receipt, an inclusion proof, and a tree head
+  - a v2 head, which fetches GET /v1/receipts/tree/epoch unless --epoch-record
 
   Solana payer verify uses SOLANA_RPC_URL when set, else the public mainnet RPC.
 
@@ -94,11 +133,34 @@ Anchored root:
   xfuel-verify receipt.json inclusion.json head.json --rpc
   xfuel-verify receipt.json --inclusion inclusion.json --head head.json --rpc https://mainnet.base.org
 
-  Checks the Merkle inclusion, fetches the Solana transaction and requires the
-  SPL Memo to contain the root, and checks the Base calldata the same way.
-  Prints what this proves and what it does not prove. Exit 0 when both chains
-  match, 2 when the leaf is included but an anchor is still pending, 1 when a
-  check fails.
+  Also runs the single-receipt checks (issuer signature and signed-versus-outer
+  comparison). Those must pass before Overall can be VERIFIED. Then it checks
+  the tree head's ES256 issuer signature (production pin, issuer
+  history, or JWKS, same rules as a receipt). The signed root, size, epoch,
+  and anchors must match the head. Then it checks Merkle inclusion, requires
+  the Solana memo and fee payer, and requires the Base calldata and sender.
+  The sender and fee payer must be on the issuer anchor-wallet list (the
+  package pin, plus a verified /.well-known/anchor-wallets.json or
+  issuer-history anchor_wallets list). The on-chain issuer-root registry and
+  the DNS anchor are not read. Prints what this proves and what it does not
+  prove. Exit 0 when the receipt checks pass and both chains match, 2 when the
+  leaf is included but an anchor is still pending, or when the leaf is past
+  the anchored tree (PENDING, not a tamper failure), and the receipt checks
+  did not fail, 1 when a check fails. A pending leaf must sit at an index
+  at or past the anchored size, and PENDING applies only when the receipt
+  itself verifies. A failed signature, field, or preimage is a failure.
+  With --rpc, a claimed anchor must name a Solana fee payer that is on the
+  anchor-wallet list, and the head root must equal the newest memo that
+  payer actually paid. A memo from any other payer is ignored.
+
+  A receipt or head with issuer_key_pin is a pinned era. Pass the pin file
+  and its commit SHA plus SHA-256. The verifier does not fetch a branch.
+  --issuer-pin <file> --issuer-pin-commit <40-hex> --issuer-pin-sha256 <64-hex>
+  Optional with that pin: --issuer-pin-sig, --issuer-witnesses,
+  --issuer-prior-pin, --issuer-prior-commit, --issuer-prior-sha256, --issuer-control.
+  Those flags do not start the check on their own. A prior pin does not
+  replace the published specimen key. Sepolia only (eip155:84532).
+  See docs/product/issuer-key-pin.md.
 
 Receipt lane (unsigned, beside book_seq):
   settled_by is observed_transfer when the USDC transfer was checked on Base
@@ -116,8 +178,8 @@ Receipt lane (unsigned, beside book_seq):
   88201, 88403, and 88596).
 
 Examples:
-  # Local binding verification (no network)
-  xfuel-verify my-receipt.json
+  # Skip the issuer-history fetch. A v10 receipt otherwise needs that network call.
+  xfuel-verify my-receipt.json --no-issuer-history
 
   # Verify issuer signature with JWKS file
   xfuel-verify my-receipt.json --jwks-file issuer-jwks.json
@@ -144,6 +206,12 @@ function parseArgs(args) {
         anchorFlag: false,
         inclusionFile: null,
         headFile: null,
+        epochRecordFile: null,
+        epochUrl: null,
+        carryOldHeadFile: null,
+        carryOldInclusionFile: null,
+        carryHeadFile: null,
+        carryInclusionFiles: [],
         positionals: [],
         json: false,
         quiet: false,
@@ -153,10 +221,26 @@ function parseArgs(args) {
         canonicalPreimageFile: null,
         noIssuerHistory: false,
         noPreimage: false,
+        issuerPinFile: null,
+        issuerPinCommit: null,
+        issuerPinSha256: null,
+        issuerPinSigFile: null,
+        issuerWitnessesFile: null,
+        issuerPriorPinFile: null,
+        issuerPriorCommit: null,
+        issuerPriorSha256: null,
+        issuerControlFile: null,
+        version: false,
+        anchorWalletsFile: null,
+        salt: null,
+        open: [],
     };
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
-        if (arg === '--help' || arg === '-h') {
+        if (arg === '--version' || arg === '-V') {
+            result.version = true;
+        }
+        else if (arg === '--help' || arg === '-h') {
             result.help = true;
         }
         else if (arg === '--check-nullifier') {
@@ -195,6 +279,24 @@ function parseArgs(args) {
         else if (arg === '--head' && args[i + 1]) {
             result.headFile = args[++i];
         }
+        else if (arg === '--epoch-record' && args[i + 1]) {
+            result.epochRecordFile = args[++i];
+        }
+        else if (arg === '--epoch-url' && args[i + 1]) {
+            result.epochUrl = args[++i];
+        }
+        else if (arg === '--carry-old-head' && args[i + 1]) {
+            result.carryOldHeadFile = args[++i];
+        }
+        else if (arg === '--carry-old-inclusion' && args[i + 1]) {
+            result.carryOldInclusionFile = args[++i];
+        }
+        else if (arg === '--carry-head' && args[i + 1]) {
+            result.carryHeadFile = args[++i];
+        }
+        else if (arg === '--carry-inclusion' && args[i + 1]) {
+            result.carryInclusionFiles.push(args[++i]);
+        }
         else if (arg === '--solana-rpc' && args[i + 1]) {
             result.solanaRpcUrl = args[++i];
         }
@@ -204,15 +306,51 @@ function parseArgs(args) {
         else if (arg === '--issuer-history-file' && args[i + 1]) {
             result.issuerHistoryFile = args[++i];
         }
+        else if (arg === '--salt' && args[i + 1]) {
+            result.salt = args[++i];
+        }
+        else if (arg === '--open' && args[i + 1]) {
+            result.open.push(args[++i]);
+        }
         else if (arg === '--canonical-preimage' && args[i + 1]) {
             result.canonicalPreimageFile = args[++i];
         }
         else if (arg === '--no-issuer-history') {
             result.noIssuerHistory = true;
         }
+        else if (arg === '--anchor-wallets-file' && args[i + 1]) {
+            result.anchorWalletsFile = args[++i];
+        }
         else if (arg === '--no-preimage') {
             result.noPreimage = true;
         }
+        else if (arg === '--issuer-pin' && args[i + 1]) {
+            result.issuerPinFile = args[++i];
+        }
+        else if (arg === '--issuer-pin-commit' && args[i + 1]) {
+            result.issuerPinCommit = args[++i];
+        }
+        else if (arg === '--issuer-pin-sha256' && args[i + 1]) {
+            result.issuerPinSha256 = args[++i];
+        }
+        else if (arg === '--issuer-pin-sig' && args[i + 1]) {
+            result.issuerPinSigFile = args[++i];
+        }
+        else if (arg === '--issuer-witnesses' && args[i + 1]) {
+            result.issuerWitnessesFile = args[++i];
+        }
+        else if (arg === '--issuer-prior-pin' && args[i + 1]) {
+            result.issuerPriorPinFile = args[++i];
+        }
+        else if (arg === '--issuer-prior-commit' && args[i + 1]) {
+            result.issuerPriorCommit = args[++i];
+        }
+        else if (arg === '--issuer-prior-sha256' && args[i + 1]) {
+            result.issuerPriorSha256 = args[++i];
+        }
+        else if (arg === '--issuer-control' && args[i + 1]) {
+            result.issuerControlFile = args[++i];
+        }
         else if (arg === '--json') {
             result.json = true;
         }
@@ -250,6 +388,15 @@ function readJson(file) {
     const content = file === '-' ? (0, node_fs_1.readFileSync)(0, 'utf8') : (0, node_fs_1.readFileSync)(file, 'utf8');
     return JSON.parse(content);
 }
+function headStatus(file) {
+    try {
+        const doc = readJson(file);
+        return typeof doc?.status === 'string' ? doc.status : null;
+    }
+    catch {
+        return null;
+    }
+}
 function printLane(lane) {
     const bit = (value) => (value == null ? 'unknown' : (value ? 'true' : 'false'));
     console.log(`  Receipt lane (unsigned)`);
@@ -282,7 +429,18 @@ function printAnchor(result, json, quiet) {
     console.log('  Anchored receipt root');
     console.log('  ─────────────────────────────────────────────────');
     console.log(`  Root:          ${result.root || '—'}`);
-    console.log(`  Inclusion:     ${mark(result.inclusion.valid)}${result.inclusion.reason ? ` (${result.inclusion.reason})` : ''}`);
+    console.log(`  Head signature:${result.head_signature.valid ? ' ✓ YES' : ' ✗ NO'}${result.head_signature.trust ? ` (${result.head_signature.trust})` : ''}`);
+    if (result.head_signature.kid)
+        console.log(`  Head kid:      ${result.head_signature.kid}`);
+    if (result.head_signature.message)
+        console.log(`  Head reason:   ${result.head_signature.message}`);
+    const unlogged = result.inclusion.unlogged_reason ? ` unlogged:${result.inclusion.unlogged_reason}` : '';
+    if (result.overall === 'pending') {
+        console.log(`  Inclusion:     PENDING${result.inclusion.reason ? ` (${result.inclusion.reason})` : ''}`);
+    }
+    else {
+        console.log(`  Inclusion:     ${mark(result.inclusion.valid)}${result.inclusion.reason ? ` (${result.inclusion.reason})` : ''}${unlogged}`);
+    }
     console.log(`  Leaf source:   ${result.inclusion.leaf_source}`);
     console.log(`  Solana:        ${result.solana.checked ? mark(result.solana.valid) : (result.solana.reason || 'not checked')}`);
     if (result.solana.signature)
@@ -291,11 +449,18 @@ function printAnchor(result, json, quiet) {
         console.log(`  Slot:          ${result.solana.slot}`);
     if (result.solana.cluster)
         console.log(`  Cluster:       ${result.solana.cluster}`);
+    if (result.solana.fee_payer)
+        console.log(`  Fee payer:     ${result.solana.fee_payer}`);
     if (result.solana.memo)
         console.log(`  Memo:          ${result.solana.memo}`);
     if (result.solana.reason && !result.solana.valid)
         console.log(`  Solana reason: ${result.solana.reason}`);
+    if (result.issuer_pin?.checked) {
+        console.log(`  Issuer pin:    ${result.issuer_pin.ok ? '✓ YES' : '✗ NO'}${result.issuer_pin.code ? ` (${result.issuer_pin.code})` : ''}`);
+    }
     console.log(`  Base:          ${result.base.checked ? mark(result.base.valid) : (result.base.reason || 'not checked')}`);
+    if (result.base.from)
+        console.log(`  Base from:     ${result.base.from}`);
     if (result.base.tx)
         console.log(`  Base tx:       ${result.base.tx}`);
     if (result.base.chain_id != null)
@@ -313,15 +478,207 @@ function printAnchor(result, json, quiet) {
     for (const line of result.does_not_prove)
         console.log(`  ${line}`);
     console.log('');
+    if (result.overall === 'pending') {
+        console.log(`  Anchored size: ${result.inclusion.anchored_tree_size ?? '—'}`);
+        console.log(`  Live size:     ${result.inclusion.live_tree_size ?? '—'}`);
+    }
     console.log(`  Overall: ${result.overall.toUpperCase()}`);
     if (result.errors.length > 0)
         console.log(`  Errors:  ${result.errors.join(', ')}`);
+    if (result.errors.includes(anchor_trust_js_1.LEGACY_HEAD_UNPINNED_SIGNER)) {
+        console.log(`  ${anchor_trust_js_1.HEAD_TRUST_MESSAGES[anchor_trust_js_1.LEGACY_HEAD_UNPINNED_SIGNER]}`);
+    }
     console.log('');
 }
+function headNeedsEpochRecord(head) {
+    const schema = head.schema;
+    const version = head.payload_version;
+    return head.epoch != null || schema === 'chit402.tree_head.v2' || version === 2;
+}
+function epochUrlFromReceipt(receipt) {
+    const raw = receipt?.verify_url;
+    if (!raw)
+        return null;
+    try {
+        return `${new URL(raw).origin}/v1/receipts/tree/epoch`;
+    }
+    catch {
+        return null;
+    }
+}
+async function loadEpochRecord(args, receipt) {
+    if (args.epochRecordFile) {
+        return JSON.parse((0, node_fs_1.readFileSync)(args.epochRecordFile, 'utf8'));
+    }
+    const url = args.epochUrl || epochUrlFromReceipt(receipt);
+    if (!url)
+        return null;
+    const res = await fetch(url);
+    if (!res.ok)
+        return null;
+    const body = await res.json();
+    if (!body?.issuer_signature?.jws)
+        return null;
+    return body;
+}
+function epochSignatureOk(record, jws, jwks, trustedKids) {
+    const sig = record.issuer_signature;
+    const embedded = sig && 'issuer_jwk' in sig
+        ? sig.issuer_jwk
+        : undefined;
+    const kid = (0, jws_js_1.readJwsHeader)(jws)?.kid;
+    const keys = [];
+    for (const key of jwks?.keys || []) {
+        if (!key || key.kty !== 'EC')
+            continue;
+        const jwk = key;
+        if (kid && jwk.kid !== kid)
+            continue;
+        keys.push(jwk);
+    }
+    if (embedded && trustedKids?.includes((0, jws_js_1.jwkThumbprint)(embedded)))
+        keys.push(embedded);
+    for (const key of keys) {
+        const verified = (0, jws_js_1.verifyIssuerJws)(jws, key);
+        if (!verified.valid || !verified.payload)
+            continue;
+        const payload = verified.payload;
+        if (JSON.stringify(payload.epochs ?? null) !== JSON.stringify(record.epochs ?? null))
+            return false;
+        if (JSON.stringify(payload.orphans ?? []) !== JSON.stringify(record.orphans ?? []))
+            return false;
+        const payloadUnlogged = payload.unlogged === undefined ? null : payload.unlogged;
+        const recordUnlogged = record.unlogged === undefined ? null : record.unlogged;
+        if (JSON.stringify(payloadUnlogged) !== JSON.stringify(recordUnlogged))
+            return false;
+        return true;
+    }
+    return false;
+}
+function packageVersion() {
+    const require = (0, node_module_1.createRequire)(__filename);
+    const pkg = require('../package.json');
+    return pkg.version || '0.0.0';
+}
+function looksLikeTreeHead(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const doc = value;
+    if (doc.status === 'not_yet_published')
+        return true;
+    if (typeof doc.schema === 'string' && doc.schema.startsWith('chit402.tree_head.'))
+        return true;
+    return Boolean(doc.anchors && doc.root && !doc.task_id);
+}
+function readOfflineWitness(args) {
+    let head = null;
+    let inclusion = null;
+    for (const file of args.positionals.slice(1)) {
+        let doc;
+        try {
+            doc = readJson(file);
+        }
+        catch (err) {
+            throw new Error(`Error reading ${file}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const row = doc;
+        if (looksLikeTreeHead(doc))
+            head = doc;
+        else if (doc && typeof doc === 'object' && (Array.isArray(row.proof) || row.leaf_index != null)) {
+            inclusion = doc;
+        }
+    }
+    return { head, inclusion };
+}
+function fileLooksLikeHead(file) {
+    if (!file)
+        return false;
+    try {
+        return looksLikeTreeHead(readJson(file));
+    }
+    catch {
+        return false;
+    }
+}
+function historyHostAllowed(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')
+            return false;
+        if (parsed.protocol === 'http:' && parsed.hostname !== '127.0.0.1' && parsed.hostname !== 'localhost')
+            return false;
+        if (parsed.protocol === 'https:') {
+            return index_js_1.DEFAULT_TRUSTED_JWKS_HOSTS.some((host) => host.toLowerCase() === parsed.hostname.toLowerCase());
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function loadAnchorIssuerHistory(args, receipt) {
+    if (args.issuerHistoryFile) {
+        return JSON.parse((0, node_fs_1.readFileSync)(args.issuerHistoryFile, 'utf8'));
+    }
+    if (args.noIssuerHistory)
+        return null;
+    const url = (0, issuer_history_js_1.historyUrlFromReceipt)(receipt);
+    if (!url || !historyHostAllowed(url))
+        return null;
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(4000) });
+        if (!res.ok)
+            return null;
+        return await res.json();
+    }
+    catch {
+        return null;
+    }
+}
+async function loadAnchorWalletDocument(args, receipt) {
+    if (args.anchorWalletsFile) {
+        return JSON.parse((0, node_fs_1.readFileSync)(args.anchorWalletsFile, 'utf8'));
+    }
+    if (args.noIssuerHistory)
+        return null;
+    const historyUrl = (0, issuer_history_js_1.historyUrlFromReceipt)(receipt);
+    const epochOrigin = (() => {
+        if (!args.epochUrl)
+            return null;
+        try {
+            return new URL(args.epochUrl).origin;
+        }
+        catch {
+            return null;
+        }
+    })();
+    const origin = epochOrigin || (historyUrl ? new URL(historyUrl).origin : null);
+    if (!origin)
+        return null;
+    const url = `${origin}/.well-known/anchor-wallets.json`;
+    if (!historyHostAllowed(url))
+        return null;
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(4000) });
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            return null;
+        return await res.json();
+    }
+    catch {
+        return null;
+    }
+}
 async function runAnchor(args) {
     const receiptPath = args.file;
     const inclusionPath = args.inclusionFile || args.positionals[1] || null;
     const headPath = args.headFile || (args.inclusionFile ? null : args.positionals[2]) || null;
+    const headCandidates = [args.headFile, headPath, ...args.positionals];
+    if (headCandidates.some((file) => file && headStatus(file) === 'not_yet_published')) {
+        console.error('Tree head is not_yet_published.');
+        return 3;
+    }
     if (!receiptPath || !inclusionPath || !headPath) {
         console.error('Anchor check needs a receipt, an inclusion proof, and a tree head.');
         console.error('  xfuel-verify receipt.json inclusion.json head.json --rpc');
@@ -339,29 +696,198 @@ async function runAnchor(args) {
         console.error(`Error reading anchor inputs: ${err instanceof Error ? err.message : String(err)}`);
         return 3;
     }
+    let fileJwks;
+    if (args.jwksFile) {
+        try {
+            fileJwks = JSON.parse((0, node_fs_1.readFileSync)(args.jwksFile, 'utf8'));
+        }
+        catch (err) {
+            console.error(`Error reading JWKS file: ${err instanceof Error ? err.message : String(err)}`);
+            return 3;
+        }
+    }
+    const loaded = await (0, index_js_1.loadIssuerJwks)(receipt, {
+        jwks: fileJwks,
+        jwksUri: args.jwksUrl || undefined,
+        fetchJwks: args.fetchJwks,
+    });
+    const trustedKids = args.noTrustedKid
+        ? []
+        : (args.trustedKids ?? [...index_js_1.DEFAULT_TRUSTED_ISSUER_KIDS]);
+    let issuerHistory = null;
+    let anchorWalletDocument = null;
+    try {
+        issuerHistory = await loadAnchorIssuerHistory(args, receipt);
+        anchorWalletDocument = await loadAnchorWalletDocument(args, receipt);
+    }
+    catch (err) {
+        console.error(`Error reading issuer trust files: ${err instanceof Error ? err.message : String(err)}`);
+        return 3;
+    }
+    let epochRecord = null;
+    let verifyEpochSignature;
+    if (headNeedsEpochRecord(head)) {
+        try {
+            epochRecord = await loadEpochRecord(args, receipt);
+        }
+        catch {
+            epochRecord = null;
+        }
+        if (epochRecord?.issuer_signature?.jws) {
+            verifyEpochSignature = (jws) => epochSignatureOk(epochRecord, jws, loaded.jwks, trustedKids);
+        }
+    }
+    let issuerPin;
+    const pinClaim = (0, issuer_pin_js_1.readIssuerPinClaim)(receipt).claimed || (0, issuer_pin_js_1.readIssuerPinClaim)(head).claimed;
+    const pinRequested = Boolean(args.issuerPinFile) || pinClaim;
+    if (pinRequested) {
+        try {
+            const claimRef = (0, issuer_pin_js_1.readIssuerPinClaim)(receipt).ref || (0, issuer_pin_js_1.readIssuerPinClaim)(head).ref;
+            const ref = (args.issuerPinCommit || args.issuerPinSha256 || claimRef)
+                ? {
+                    commit: args.issuerPinCommit || claimRef?.commit || '',
+                    path: claimRef?.path || 'docs/well-known/issuer-key.json',
+                    sha256: (args.issuerPinSha256 || claimRef?.sha256 || '').toLowerCase(),
+                }
+                : null;
+            let witnesses;
+            if (args.issuerWitnessesFile)
+                witnesses = JSON.parse((0, node_fs_1.readFileSync)(args.issuerWitnessesFile, 'utf8'));
+            const priorRef = args.issuerPriorPinFile
+                ? {
+                    commit: args.issuerPriorCommit || '',
+                    path: 'docs/well-known/issuer-key.json',
+                    sha256: (args.issuerPriorSha256 || '').toLowerCase(),
+                }
+                : null;
+            issuerPin = {
+                pinBytes: args.issuerPinFile ? (0, node_fs_1.readFileSync)(args.issuerPinFile, 'utf8') : null,
+                sigBytes: args.issuerPinSigFile ? (0, node_fs_1.readFileSync)(args.issuerPinSigFile, 'utf8') : null,
+                ref,
+                witnesses,
+                priorPinBytes: args.issuerPriorPinFile ? (0, node_fs_1.readFileSync)(args.issuerPriorPinFile, 'utf8') : null,
+                priorRef,
+                controlJws: args.issuerControlFile ? (0, node_fs_1.readFileSync)(args.issuerControlFile, 'utf8').trim() : null,
+                required: true,
+            };
+        }
+        catch (err) {
+            console.error(`Error reading issuer pin: ${err instanceof Error ? err.message : String(err)}`);
+            return 3;
+        }
+    }
     const result = await (0, anchor_witness_js_1.verifyAnchoredRoot)({
         receipt,
         inclusion,
         head,
         baseRpcUrl: args.rpcUrl || undefined,
         solanaRpcUrl: args.solanaRpcUrl || undefined,
+        checkNewestAnchor: args.sawRpc,
+        epochRecord,
+        verifyEpochSignature,
+        issuerPin,
+        jwks: loaded.jwks,
+        trustedKids,
+        issuerHistory,
+        strictIssuerHistory: args.strictIssuerHistory,
+        anchorWalletDocument: anchorWalletDocument,
     });
-    const verified = await (0, index_js_1.verifyReceipt)(receipt, { head });
-    const lane = verified.receipt_lane;
+    let canonicalPreimage = null;
+    if (args.canonicalPreimageFile) {
+        canonicalPreimage = (0, node_fs_1.readFileSync)(args.canonicalPreimageFile, 'utf8');
+    }
+    const historyBytes = args.issuerHistoryFile ? (0, node_fs_1.readFileSync)(args.issuerHistoryFile, 'utf8') : null;
+    const verified = await (0, index_js_1.verifyReceipt)(receipt, {
+        jwks: loaded.jwks,
+        jwksUri: args.jwksUrl || undefined,
+        fetchJwks: args.fetchJwks,
+        trustedKids,
+        checkNullifier: args.checkNullifier,
+        checkPayer: args.checkPayer,
+        rpcUrl: args.rpcUrl || undefined,
+        solanaRpcUrl: args.solanaRpcUrl || undefined,
+        requirePreimages: !args.noPreimage,
+        issuerHistory: args.issuerHistoryFile ? issuerHistory : null,
+        issuerHistoryBytes: historyBytes,
+        fetchIssuerHistory: !args.noIssuerHistory && !args.issuerHistoryFile,
+        strictIssuerHistory: args.strictIssuerHistory,
+        skipIssuerHistory: args.noIssuerHistory,
+        canonicalPreimage,
+        head,
+    });
+    // Inclusion was already checked above. Passing it again re-derives the leaf
+    // from book_chain.row_hash only, which rejects a receipt that stores row_hash
+    // at the top level. Log mode still requires the receipt itself. A missing or
+    // stripped issuer signature, a partial check, or a signed-versus-outer
+    // mismatch fails the combined result. An inclusion match is not VERIFIED.
+    const issuerSig = receipt.issuer_signature;
+    const signaturePresent = Boolean(issuerSig?.jws || issuerSig?.value);
+    const receiptVerified = signaturePresent
+        && verified.issuer_signature.valid === true
+        && (verified.overall === 'verified' || verified.overall === 'verified_carried_forward')
+        && verified.claim_mismatches.length === 0;
+    const receiptFailed = !receiptVerified;
+    const receiptErrors = [...verified.errors];
+    if (!signaturePresent) {
+        receiptErrors.push(verified.issuer_signature.reason || 'receipt_signature_missing');
+    }
+    else if (verified.overall === 'partial') {
+        receiptErrors.push(verified.issuer_signature.reason || 'receipt_check_partial');
+    }
+    const errors = receiptFailed
+        ? [...result.errors, ...receiptErrors.filter((err) => !result.errors.includes(err))]
+        : result.errors;
+    const combined = {
+        ...result,
+        errors,
+        overall: receiptFailed ? 'failed' : result.overall,
+        receipt_lane: verified.receipt_lane,
+        receipt_check: {
+            overall: result.overall === 'pending' && !receiptFailed ? 'pending' : verified.overall,
+            verified_scope: verified.verified_scope,
+            claim_mismatches: verified.claim_mismatches,
+            unsigned_fields: verified.unsigned_fields,
+            errors: verified.errors,
+        },
+    };
     if (args.json) {
-        console.log(JSON.stringify({ ...result, receipt_lane: lane }, null, 2));
+        console.log(JSON.stringify(combined, null, 2));
     }
     else {
-        printAnchor(result, false, args.quiet);
+        printAnchor(combined, false, args.quiet);
+        if (!args.quiet || receiptFailed) {
+            const anchorPending = result.overall === 'pending';
+            const receiptLabel = anchorPending && !receiptFailed
+                ? 'PENDING'
+                : verified.overall.toUpperCase();
+            console.log(`  Receipt checks: ${receiptLabel} (signed claims only)`);
+            if (verified.claim_mismatches.length > 0) {
+                for (const mismatch of verified.claim_mismatches) {
+                    console.log(`  ${mismatch.field}: outer ${mismatch.outer} ≠ signed ${mismatch.signed}`);
+                }
+            }
+            if (!(anchorPending && !receiptFailed))
+                printUnsigned(verified.unsigned_fields);
+            console.log('');
+        }
         if (!args.quiet)
-            printLane(lane);
+            printLane(verified.receipt_lane);
     }
-    if (result.overall === 'verified')
+    if (combined.overall === 'verified')
         return 0;
-    if (result.overall === 'partial')
+    if (combined.overall === 'partial' || combined.overall === 'pending')
         return 2;
     return 1;
 }
+function printUnsigned(fields) {
+    console.log('  Scope:         signed claims only. Unsigned fields are UNVERIFIED.');
+    if (fields.length === 0)
+        return;
+    console.log(`  Unsigned fields (${fields.length})`);
+    console.log('  ─────────────────────────────────────────────────');
+    for (const field of fields)
+        console.log(`  UNVERIFIED     ${field}`);
+}
 async function runRefusal(doc, args) {
     const trustedKids = args.trustedKids ?? index_js_1.DEFAULT_TRUSTED_ISSUER_KIDS;
     const result = (0, index_js_1.verifyRefusal)(doc, {
@@ -384,7 +910,7 @@ async function runRefusal(doc, args) {
         issuer_history: result.issuer_history,
     }) : null;
     const history = args.skipIssuerHistory
-        ? { checked: false, ok: true, unreachable: false, warning: null, reason: null, kid: result.kid ?? null }
+        ? { checked: false, ok: true, unreachable: false, warning: null, reason: null, kid: result.kid ?? null, document: null, loaded: false }
         : await (0, issuer_history_js_1.checkReceiptIssuerHistory)(doc, {
             document: args.issuerHistory,
             documentBytes: args.issuerHistoryBytes,
@@ -444,13 +970,30 @@ async function runRefusal(doc, args) {
 }
 async function main() {
     const args = parseArgs(process.argv.slice(2));
-    const anchorMode = args.anchorFlag
+    if (args.version) {
+        console.log(`@xfuel/verify ${packageVersion()}`);
+        return 0;
+    }
+    let anchorMode = args.anchorFlag
         || Boolean(args.inclusionFile || args.headFile)
         || (args.positionals.length >= 3 && args.sawRpc);
+    if (!anchorMode && args.sawRpc && args.positionals.some((file) => fileLooksLikeHead(file))) {
+        anchorMode = true;
+    }
     if (args.help) {
         console.log(HELP);
         return 0;
     }
+    let offlineWitness = null;
+    if (!anchorMode) {
+        try {
+            offlineWitness = readOfflineWitness(args);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            return 3;
+        }
+    }
     if (anchorMode)
         return runAnchor(args);
     if (!args.file) {
@@ -465,7 +1008,19 @@ async function main() {
         console.error(`Error reading receipt: ${err instanceof Error ? err.message : String(err)}`);
         return 3;
     }
-    if (!receipt.task_id) {
+    const v11 = receipt.v === 11 || (receipt.issuer_signature?.jws
+        ? (() => {
+            try {
+                const part = String(receipt.issuer_signature.jws).split('.')[1];
+                const payload = JSON.parse(Buffer.from(part, 'base64url').toString('utf8'));
+                return payload?.v === 11;
+            }
+            catch {
+                return false;
+            }
+        })()
+        : false);
+    if (!receipt.task_id && !v11) {
         console.error('Invalid receipt: missing task_id');
         return 3;
     }
@@ -531,6 +1086,42 @@ async function main() {
             return 3;
         }
     }
+    const carryAsked = args.carryOldHeadFile || args.carryOldInclusionFile
+        || args.carryHeadFile || args.carryInclusionFiles.length > 0;
+    let carry = null;
+    if (carryAsked) {
+        try {
+            carry = {
+                oldHead: args.carryOldHeadFile ? readJson(args.carryOldHeadFile) : {},
+                oldInclusion: args.carryOldInclusionFile ? readJson(args.carryOldInclusionFile) : { error: 'not_in_tree' },
+                currentHead: args.carryHeadFile ? readJson(args.carryHeadFile) : {},
+                currentInclusions: args.carryInclusionFiles.length > 0
+                    ? args.carryInclusionFiles.map((file) => readJson(file))
+                    : [{ error: 'not_in_tree' }],
+            };
+        }
+        catch (err) {
+            console.error(`Error reading carry-forward files: ${err instanceof Error ? err.message : String(err)}`);
+            return 3;
+        }
+    }
+    let open;
+    if (args.open.length > 0) {
+        open = {};
+        try {
+            for (const spec of args.open) {
+                const opened = (0, v11_receipt_js_1.readOpenFile)(spec);
+                if (opened.kind === 'output')
+                    open.output = opened.bytes;
+                else
+                    open[opened.kind] = opened.text;
+            }
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            return 3;
+        }
+    }
     const result = await (0, index_js_1.verifyReceipt)(receipt, {
         jwks,
         jwksUri: args.jwksUrl || undefined,
@@ -547,6 +1138,11 @@ async function main() {
         strictIssuerHistory: args.strictIssuerHistory,
         skipIssuerHistory: args.noIssuerHistory,
         canonicalPreimage,
+        salt: args.salt,
+        open,
+        head: offlineWitness?.head ?? undefined,
+        inclusion: offlineWitness?.inclusion ?? undefined,
+        carry,
     });
     if (args.json) {
         console.log(JSON.stringify(result, null, 2));
@@ -619,6 +1215,8 @@ async function main() {
             }
         }
         console.log('');
+        printUnsigned(result.unsigned_fields);
+        console.log('');
         console.log(`  Nullifier`);
         console.log(`  ─────────────────────────────────────────────────`);
         if (result.nullifier.nullifier) {
@@ -644,6 +1242,18 @@ async function main() {
         else if (result.issuer_history.warning) {
             console.log(`  Issuer history: ${result.issuer_history.warning}`);
         }
+        if (result.carry_forward?.status === 'VERIFIED_CARRIED_FORWARD') {
+            const carried = result.carry_forward;
+            console.log(`  Log`);
+            console.log(`  ─────────────────────────────────────────────────`);
+            console.log(`  Status:        ${carried.status}`);
+            console.log(`  Issued at:     ${carried.issued_at}`);
+            console.log(`  Issued epoch:  ${carried.issued_epoch}`);
+            console.log(`  Logged at:     ${carried.logged_at}`);
+            console.log(`  Logged epoch:  ${carried.logged_epoch}`);
+            console.log(`  Leaf index:    ${carried.leaf_index}`);
+            console.log('');
+        }
         console.log(`  Overall: ${result.overall.toUpperCase()}`);
         if (result.errors.length > 0) {
             console.log(`  Errors:  ${result.errors.join(', ')}`);
@@ -652,6 +1262,7 @@ async function main() {
     }
     switch (result.overall) {
         case 'verified':
+        case 'verified_carried_forward':
             return 0;
         case 'failed':
             return 1;
@@ -661,10 +1272,43 @@ async function main() {
             return 1;
     }
 }
+/**
+ * Node's fetch keeps its undici agent on this symbol after the first request.
+ * There is no public handle for that pool. Closing it lets the loop drain.
+ */
+const UNDICI_GLOBAL_DISPATCHER = Symbol.for('undici.globalDispatcher.1');
+function fetchDispatcher() {
+    const bag = globalThis;
+    return bag[UNDICI_GLOBAL_DISPATCHER];
+}
+/**
+ * process.exit() while a fetch keep-alive socket is already CLOSING aborts
+ * on Windows: Assertion failed: !(handle->flags & UV_HANDLE_CLOSING)
+ * (src/win/async.c). Set the code and close the pool so the loop can drain.
+ */
+async function finish(code) {
+    process.exitCode = code;
+    const dispatcher = fetchDispatcher();
+    if (!dispatcher)
+        return;
+    try {
+        const closing = dispatcher.close?.();
+        if (closing)
+            await closing;
+    }
+    catch {
+        try {
+            await dispatcher.destroy?.();
+        }
+        catch {
+            // The verification result is already the exit code.
+        }
+    }
+}
 main()
-    .then((code) => process.exit(code))
+    .then((code) => finish(code))
     .catch((err) => {
     console.error('Unexpected error:', err);
-    process.exit(3);
+    return finish(3);
 });
 //# sourceMappingURL=cli.js.map