@xfuel/verify 0.3.1 → 0.3.4

package/dist/cli.js

@@ -17,13 +17,18 @@
  *   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 shell_js_1 = require("./shell.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
 
@@ -52,14 +57,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.
+                      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 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
@@ -83,8 +109,11 @@ 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:
   JWKS, nullifiers, and anchors are not fetched unless you pass a flag.
@@ -105,11 +134,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
@@ -138,6 +190,13 @@ Examples:
 
   # Pipe from curl
   curl -s https://api.chit402.com/receipt/task-123?format=json | xfuel-verify -
+
+  # Public shell. INCLUDED_SHELL is not VERIFIED.
+  xfuel-verify shell.json
+
+  # Owner view. VERIFIED needs a trusted issuer key, an inclusion proof,
+  # and a signed payment. The key inside the holder is not enough.
+  xfuel-verify shell.json --jws owner-view.json --inclusion inclusion.json --head head.json
 `;
 function parseArgs(args) {
     const result = {
@@ -157,6 +216,10 @@ function parseArgs(args) {
         headFile: null,
         epochRecordFile: null,
         epochUrl: null,
+        carryOldHeadFile: null,
+        carryOldInclusionFile: null,
+        carryHeadFile: null,
+        carryInclusionFiles: [],
         positionals: [],
         json: false,
         quiet: false,
@@ -166,10 +229,29 @@ 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,
+        acceptShell: false,
+        jwsFile: null,
+        salt: null,
+        open: [],
+        url: null,
     };
     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') {
@@ -214,6 +296,18 @@ function parseArgs(args) {
         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];
         }
@@ -223,15 +317,60 @@ 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 === '--accept-shell') {
+            result.acceptShell = true;
+        }
+        else if (arg === '--jws' && args[i + 1]) {
+            result.jwsFile = args[++i];
+        }
+        else if (arg === '--url' && args[i + 1]) {
+            result.url = args[++i];
+        }
+        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;
         }
@@ -310,7 +449,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)
@@ -319,11 +469,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)
@@ -341,9 +498,16 @@ 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) {
@@ -403,20 +567,139 @@ function epochSignatureOk(record, jws, jwks, trustedKids) {
             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) {
-        const candidates = [args.headFile, headPath, ...args.positionals];
-        if (candidates.some((file) => file && headStatus(file) === 'not_yet_published')) {
-            console.error('Tree head is not_yet_published.');
-            return 3;
-        }
         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');
         return 3;
@@ -433,6 +716,34 @@ 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)) {
@@ -443,25 +754,46 @@ async function runAnchor(args) {
             epochRecord = null;
         }
         if (epochRecord?.issuer_signature?.jws) {
-            let fileJwks;
-            if (args.jwksFile) {
-                try {
-                    fileJwks = JSON.parse((0, node_fs_1.readFileSync)(args.jwksFile, 'utf8'));
+            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(),
                 }
-                catch (err) {
-                    console.error(`Error reading JWKS file: ${err instanceof Error ? err.message : String(err)}`);
-                    return 3;
+                : 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(),
                 }
-            }
-            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]);
-            verifyEpochSignature = (jws) => epochSignatureOk(epochRecord, jws, loaded.jwks, trustedKids);
+                : 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)({
@@ -470,25 +802,112 @@ async function runAnchor(args) {
         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,
+    });
+    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,
     });
-    const verified = await (0, index_js_1.verifyReceipt)(receipt, { head });
-    const lane = verified.receipt_lane;
+    // 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, {
@@ -511,7 +930,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,
@@ -571,14 +990,45 @@ 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;
     }
-    if (anchorMode)
+    if (args.url && !args.jwsFile) {
+        try {
+            const response = await fetch(args.url);
+            await response.arrayBuffer();
+        }
+        catch {
+            // A failed fetch is still not a pass.
+        }
+        console.log('owner_proof_required');
+        console.log('  Overall: OWNER_PROOF_REQUIRED');
+        return 1;
+    }
+    let offlineWitness = null;
+    if (!anchorMode) {
+        try {
+            offlineWitness = readOfflineWitness(args);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            return 3;
+        }
+    }
+    // A shell plus a holder is not anchor mode. Inclusion is checked with the
+    // holder. Anchor mode would verify the unsigned shell and skip the key.
+    if (anchorMode && !args.jwsFile && !args.acceptShell)
         return runAnchor(args);
     if (!args.file) {
         console.log(HELP);
@@ -592,7 +1042,150 @@ async function main() {
         console.error(`Error reading receipt: ${err instanceof Error ? err.message : String(err)}`);
         return 3;
     }
-    if (!receipt.task_id) {
+    if ((0, shell_js_1.isReceiptShell)(receipt) || args.acceptShell || args.jwsFile) {
+        if (!(0, shell_js_1.isReceiptShell)(receipt)) {
+            console.error('Invalid shell: schema is not chit402.receipt_shell.v1');
+            return 3;
+        }
+        if (!args.jwsFile) {
+            console.log(shell_js_1.INCLUDED_SHELL_LINE);
+            console.log('  Overall: INCLUDED_SHELL');
+            return args.acceptShell ? 0 : 1;
+        }
+        let holder;
+        try {
+            const text = (0, node_fs_1.readFileSync)(args.jwsFile, 'utf8');
+            let parsed = text;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = text;
+            }
+            holder = (0, shell_js_1.holderDocumentFromOwnerView)(parsed);
+        }
+        catch (err) {
+            console.error(`Error reading JWS: ${err instanceof Error ? err.message : String(err)}`);
+            return 3;
+        }
+        const shellDoc = receipt;
+        const compared = (0, shell_js_1.compareShellToJws)(shellDoc, holder);
+        if (!compared.ok) {
+            console.log('shell_jws_mismatch');
+            if (compared.field)
+                console.log(`  Field:         ${compared.field}`);
+            console.log('  Overall: FAILED');
+            return 1;
+        }
+        let jwks;
+        if (args.jwksFile) {
+            try {
+                jwks = 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;
+            }
+        }
+        let inclusion = offlineWitness?.inclusion ?? null;
+        let head = offlineWitness?.head ?? null;
+        try {
+            if (args.inclusionFile)
+                inclusion = readJson(args.inclusionFile);
+            if (args.headFile)
+                head = readJson(args.headFile);
+        }
+        catch (err) {
+            console.error(`Error reading inclusion: ${err instanceof Error ? err.message : String(err)}`);
+            return 3;
+        }
+        const trustedKids = args.noTrustedKid
+            ? []
+            : (args.trustedKids ?? [...index_js_1.DEFAULT_TRUSTED_ISSUER_KIDS]);
+        const result = await (0, index_js_1.verifyReceipt)(holder, {
+            jwks,
+            jwksUri: args.jwksUrl || undefined,
+            fetchJwks: args.fetchJwks,
+            trustedKids,
+            checkPayer: args.checkPayer,
+            rpcUrl: args.rpcUrl || undefined,
+            solanaRpcUrl: args.solanaRpcUrl || undefined,
+            requirePreimages: false,
+            skipIssuerHistory: args.noIssuerHistory || !args.issuerHistoryFile,
+            issuerHistory: null,
+            fetchIssuerHistory: false,
+            salt: args.salt,
+            head: head ?? undefined,
+            inclusion: inclusion ?? undefined,
+        });
+        const inclusionErrors = result.errors.filter((err) => /inclusion|leaf|row_hash|bad_root|tree_size|tree_head|no_leaf/.test(err));
+        const shellLeaf = (shellDoc.inclusion && typeof shellDoc.inclusion === 'object')
+            ? shellDoc.inclusion.leaf_hash
+            : null;
+        const provedLeaf = inclusion && typeof inclusion.leaf === 'string'
+            ? inclusion.leaf
+            : null;
+        // A head the user wrote by hand ({root, tree_size}) is not a log. The
+        // inclusion only counts against a head that carries an issuer JWS;
+        // verifyReceipt() checks that JWS against the same trust set.
+        const headSig = head && typeof head === 'object'
+            ? head.issuer_signature
+            : null;
+        const headSigned = !!headSig && typeof headSig.jws === 'string' && headSig.jws.split('.').length === 3;
+        const verdict = (0, shell_js_1.shellHolderVerdict)({
+            signatureValid: result.issuer_signature.valid === true,
+            keyTrusted: result.issuer_signature.key_trusted === true,
+            signatureReason: result.issuer_signature.reason || (result.issuer_signature.key_trusted ? null : 'key untrusted'),
+            inclusionSupplied: inclusion != null,
+            inclusionOk: inclusion != null && inclusionErrors.length === 0,
+            inclusionReason: inclusion == null ? 'inclusion_missing' : (inclusionErrors[0] || null),
+            headSigned,
+            paymentRef: result.tx,
+            bindingExpected: !!result.binding.expected,
+            bindingMatches: result.binding.matches === true,
+            shellLeaf: shellLeaf == null ? null : String(shellLeaf),
+            provedLeaf,
+        });
+        if (!verdict.verified || (result.overall !== 'verified' && result.overall !== 'verified_carried_forward')) {
+            const reason = verdict.reason || result.errors[0] || 'failed';
+            console.log(reason);
+            console.log('  Overall: FAILED');
+            return 1;
+        }
+        if (args.checkPayer && !result.payer.valid) {
+            console.log(result.payer.reason || 'payment_unchecked');
+            console.log('  Overall: FAILED');
+            return 1;
+        }
+        const issuer = holder.issuer_signature;
+        if (args.salt) {
+            const opened = (0, shell_js_1.openV11Commitment)({
+                payload: (0, shell_js_1.decodeJwsPayload)(issuer?.jws),
+                saltHex: args.salt || '',
+                body: Buffer.alloc(0),
+            });
+            if (!opened.ok) {
+                console.log(opened.reason || 'commitment_mismatch');
+                console.log('  Overall: FAILED');
+                return 1;
+            }
+        }
+        console.log('  Overall: VERIFIED');
+        return 0;
+    }
+    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;
     }
@@ -658,6 +1251,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,
@@ -674,6 +1303,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));
@@ -746,6 +1380,8 @@ async function main() {
             }
         }
         console.log('');
+        printUnsigned(result.unsigned_fields);
+        console.log('');
         console.log(`  Nullifier`);
         console.log(`  ─────────────────────────────────────────────────`);
         if (result.nullifier.nullifier) {
@@ -771,6 +1407,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(', ')}`);
@@ -779,6 +1427,7 @@ async function main() {
     }
     switch (result.overall) {
         case 'verified':
+        case 'verified_carried_forward':
             return 0;
         case 'failed':
             return 1;