@xfuel/verify 0.3.0 → 0.3.3

package/dist/index.js

@@ -13,7 +13,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.REFUSAL_SCHEMA = exports.verifyRefusal = exports.isRefusalDocument = exports.HEAD_BINDING_PAYLOAD_VERSION = exports.outerHeadDisagrees = exports.signedHeadBinding = exports.headBindingVerdict = exports.RECEIPT_LANE_BOUNDARY = exports.RECEIPT_LANE_ORDERING = exports.RECEIPT_LANE_RULE = exports.RECEIPT_LANE_SCHEMA = exports.anchorChangedSinceBinding = exports.deriveSettled = exports.deriveSettledBy = exports.receiptLaneDecision = exports.receiptLaneFromVerification = exports.buildReceiptLane = exports.jwksHostAllowed = exports.isPinnedTrustedJwk = exports.jwkThumbprint = exports.KEY_UNTRUSTED = exports.DEFAULT_TRUSTED_JWKS_HOSTS = exports.DEFAULT_TRUSTED_ISSUER_KIDS = exports.verifyIssuerJws = exports.resolvePinnedIssuerJwk = exports.canonicalSignedPayload = exports.BASE_SEPOLIA_RPC_URL = exports.ZK_VERIFIER_ADDRESS = exports.decodeJwsPayload = exports.receiptPayerClaimsFromEnvelope = exports.verifyPayerBinding = exports.SOLANA_USDC_MINT_DEVNET = exports.SOLANA_USDC_MINT_MAINNET = exports.SOLANA_RPC_URL = exports.fetchSolanaTransaction = exports.inferUsdcOutflowFromBalances = exports.extractUsdcTransfersFromTx = exports.isSolanaBase58Pubkey = exports.parseSolanaPaymentRef = exports.verifySolanaPayer = exports.BASE_RPC_URL = exports.ERC20_TRANSFER_TOPIC = exports.USDC_ADDRESSES = exports.fetchBaseTransactionReceipt = exports.sumUsdcTransfersFromPayer = exports.isEvmAddress = exports.parseBasePaymentRef = exports.verifyBasePayer = exports.computeInferenceBinding = exports.computePaymentCommitment = void 0;
-exports.issuerHistoryDocumentHash = exports.readIssuerHistoryPin = exports.CANONICAL_PAYLOAD_VERSION = exports.verifyCanonicalPreimageBytes = exports.BASE_MAINNET_CHAIN_ID = exports.SOLANA_GENESIS = exports.ANCHOR_DOES_NOT_PROVE = exports.ANCHOR_PROVES = exports.leafHash = exports.parseAnchorMemo = exports.extractMemos = exports.verifyMerkleInclusion = exports.verifyAnchoredRoot = exports.REFUSAL_DOES_NOT_PROVE = exports.REFUSAL_PROVES = exports.REFUSAL_PAYLOAD_VERSION = void 0;
+exports.ISSUER_ROTATION_CONTEXT = exports.ISSUER_REGISTRATION_CONTEXT = exports.canonicalPublicKey = exports.verifyRegistrationSignature = exports.verifyCitizenRotation = exports.serializeIssuerPin = exports.rotationStatement = exports.registrationPreimage = exports.readIssuerPinClaim = exports.loadIssuerPinBytes = exports.issuerPinFileHash = exports.issuerPinContentUrl = exports.assessIssuerPin = exports.BASE_MAINNET_CHAIN_ID = exports.SOLANA_GENESIS = exports.ANCHOR_DOES_NOT_PROVE = exports.ANCHOR_PROVES = exports.leafHash = exports.parseAnchorMemo = exports.extractMemos = exports.verifyMerkleInclusion = exports.verifyAnchoredRoot = exports.CARRY_FORWARD_STATUS = exports.PINNED_ANCHOR_EPOCHS = exports.verifyCarryForward = exports.EPOCH2_OPENING_ROOT = exports.matchEpoch1Prefix = exports.epoch1PrefixRoot = exports.EPOCH1_SIZE2_ROOT = exports.EPOCH1_SIZE1_ROOT = exports.EPOCH1_GENESIS_DIGEST = exports.EPOCH1_FINAL_SIZE = exports.EPOCH1_FINAL_ROOT = exports.TREE_HEAD_SCHEMA_V2 = exports.TREE_HEAD_SCHEMA_V1 = exports.canonicalUnloggedRows = exports.unloggedReasonForTask = exports.unloggedIdCommitment = exports.verifyUnloggedCommitment = exports.verifyUnloggedSection = exports.verifyEpochInclusion = exports.verifyEpochRecord = exports.verifyEpochLink = exports.acceptTreeHeadSchema = exports.requestDigestOfPreimage = exports.verifyRequestDigest = exports.REFUSAL_DOES_NOT_PROVE = exports.REFUSAL_PROVES = exports.REFUSAL_PAYLOAD_VERSION = exports.REFUSAL_SCHEMA_V2 = void 0;
+exports.issuerHistoryDocumentHash = exports.readIssuerHistoryPin = exports.CANONICAL_PAYLOAD_VERSION = exports.verifyCanonicalPreimageBytes = exports.compileAnchorWallets = exports.verifyAnchorWalletDocument = exports.verifyTreeHeadTrust = exports.headOmitsPinnedSigner = exports.HEAD_TRUST_MESSAGES = exports.LEGACY_HEAD_UNPINNED_SIGNER = exports.ANCHOR_WALLET_SOURCES_NOT_CONSULTED = exports.PINNED_SOLANA_ANCHOR_FEE_PAYER = exports.PINNED_BASE_ANCHOR_WALLET = exports.ISSUER_PIN_CHAIN_REFUSED = exports.ISSUER_ROTATION_UNCONTROLLED = exports.ISSUER_PIN_MUTABLE_REF = exports.ISSUER_PIN_DOWNGRADE = exports.ISSUER_SELF_SIG_INVALID = exports.ISSUER_PIN_HASH_MISMATCH = exports.ISSUER_PIN_MISMATCH = exports.CITIZEN_FREEZE_PURPOSE = exports.CITIZEN_FREEZE_SCHEMA = exports.PUBLISHED_ISSUER_PIN_KID = exports.ISSUER_PIN_CHAIN_ID = exports.ISSUER_PIN_PATH = exports.ISSUER_PIN_SCHEMA = exports.ISSUER_PIN_VERSION = void 0;
 exports.canonicalPayloadVersion = canonicalPayloadVersion;
 exports.canonicalIssuerPayload = canonicalIssuerPayload;
 exports.sumUsdcTransfersToPayee = sumUsdcTransfersToPayee;
@@ -25,11 +26,16 @@ exports.verifyNullifier = verifyNullifier;
 exports.hashCanonicalPayload = hashCanonicalPayload;
 exports.claimIdVerdict = claimIdVerdict;
 exports.diffOuterClaims = diffOuterClaims;
+exports.unsignedOuterFields = unsignedOuterFields;
+exports.loadIssuerJwks = loadIssuerJwks;
 exports.fetchIssuerJwks = fetchIssuerJwks;
 exports.receiptPayerClaims = receiptPayerClaims;
+exports.verifyReceiptUpToV10 = verifyReceiptUpToV10;
 exports.verifyReceipt = verifyReceipt;
 const ethers_1 = require("ethers");
 const anchor_witness_js_1 = require("./anchor-witness.js");
+const row_hash_js_1 = require("./row-hash.js");
+const carry_forward_js_1 = require("./carry-forward.js");
 const node_crypto_1 = require("node:crypto");
 const binding_js_1 = require("./binding.js");
 Object.defineProperty(exports, "computePaymentCommitment", { enumerable: true, get: function () { return binding_js_1.computePaymentCommitment; } });
@@ -57,6 +63,7 @@ const payer_js_1 = require("./payer.js");
 Object.defineProperty(exports, "verifyPayerBinding", { enumerable: true, get: function () { return payer_js_1.verifyPayerBinding; } });
 Object.defineProperty(exports, "receiptPayerClaimsFromEnvelope", { enumerable: true, get: function () { return payer_js_1.receiptPayerClaimsFromEnvelope; } });
 Object.defineProperty(exports, "decodeJwsPayload", { enumerable: true, get: function () { return payer_js_1.decodeJwsPayload; } });
+const v11_receipt_js_1 = require("./v11-receipt.js");
 const jws_js_1 = require("./jws.js");
 const head_binding_js_1 = require("./head-binding.js");
 const receipt_lane_js_1 = require("./receipt-lane.js");
@@ -64,6 +71,7 @@ const refusal_js_1 = require("./refusal.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 anchor_trust_js_1 = require("./anchor-trust.js");
 /** ZKVerifierSP1 contract on Base mainnet. */
 exports.ZK_VERIFIER_ADDRESS = '0x9373499645292715a2275A78eD65B14215C41c06';
 /** Base Sepolia testnet RPC. */
@@ -649,66 +657,118 @@ function asRecord(value) {
         return null;
     return value;
 }
-function normFact(value, address = false) {
-    const text = claimString(value);
-    if (text == null)
+function isPlain(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function formatClaim(value) {
+    if (value == null)
         return null;
-    return address ? text.toLowerCase() : text;
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return JSON.stringify(value);
+}
+/** 0x hex is compared case-insensitively. Checksum case is not a different claim. */
+function sameLeaf(signed, outer) {
+    if (Array.isArray(signed) || Array.isArray(outer)) {
+        return JSON.stringify(signed) === JSON.stringify(outer);
+    }
+    if (typeof signed === 'string' && typeof outer === 'string') {
+        if (/^0x[0-9a-fA-F]+$/.test(signed) && /^0x[0-9a-fA-F]+$/.test(outer)) {
+            return signed.toLowerCase() === outer.toLowerCase();
+        }
+        return signed === outer;
+    }
+    if (signed == null || outer == null)
+        return signed == null && outer == null;
+    return Object.is(signed, outer);
 }
 /**
- * Fields a verifier may quote. Compared only when both the unsigned outer
- * copy and the JWS payload carry a value.
+ * The outer receipt `schema` (`xfuel.receipt.v3`) is the document type.
+ * The JWS `schema` (`chit402.foreign_payout.v1`) is the payload type.
+ * They share a name and are not copies of each other.
+ */
+function schemaIsNotACopy(path) {
+    return path === 'schema';
+}
+function compareSignedNode(signed, outer, prefix, mismatches) {
+    if (!isPlain(signed))
+        return;
+    if (!isPlain(outer)) {
+        mismatches.push({
+            field: prefix || '$',
+            outer: formatClaim(outer),
+            signed: formatClaim(signed),
+        });
+        return;
+    }
+    for (const key of Object.keys(signed)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (schemaIsNotACopy(path))
+            continue;
+        if (!Object.prototype.hasOwnProperty.call(outer, key))
+            continue;
+        const sv = signed[key];
+        const ov = outer[key];
+        if (isPlain(sv) && isPlain(ov)) {
+            compareSignedNode(sv, ov, path, mismatches);
+            continue;
+        }
+        if (!sameLeaf(sv, ov)) {
+            mismatches.push({ field: path, outer: formatClaim(ov), signed: formatClaim(sv) });
+        }
+    }
+}
+/**
+ * Walk every signed claim. When the outer receipt has the same path, the
+ * values must match, including null against a filled-in outer copy. A path
+ * the outer receipt omits is not a copy, so it is not a mismatch.
  */
-const CLAIM_COMPARE = [
-    { field: 'task_id', outer: (r) => r.task_id, signed: (c) => c.task_id },
-    { field: 'payment.rail', outer: (r) => r.payment?.rail, signed: (c) => asRecord(c.payment)?.rail },
-    { field: 'payment.ref', outer: (r) => r.payment?.ref, signed: (c) => asRecord(c.payment)?.ref },
-    { field: 'payment.gross_amount', outer: (r) => r.payment?.gross_amount, signed: (c) => asRecord(c.payment)?.gross_amount },
-    { field: 'payment.settled_amount', outer: (r) => r.payment?.settled_amount, signed: (c) => asRecord(c.payment)?.settled_amount },
-    { field: 'payment.net_amount', outer: (r) => r.payment?.net_amount, signed: (c) => asRecord(c.payment)?.net_amount },
-    { field: 'payment.asset', outer: (r) => r.payment?.asset, signed: (c) => asRecord(c.payment)?.asset, address: true },
-    { field: 'payment.payee', outer: (r) => r.payment?.payee, signed: (c) => asRecord(c.payment)?.payee, address: true },
-    { field: 'caller_binding.payer_wallet', outer: (r) => r.caller_binding?.payer_wallet, signed: (c) => asRecord(c.caller_binding)?.payer_wallet, address: true },
-    { field: 'caller_binding.agent_pubkey', outer: (r) => r.caller_binding?.agent_pubkey, signed: (c) => asRecord(c.caller_binding)?.agent_pubkey },
-    { field: 'caller_binding.api_key_hash', outer: (r) => r.caller_binding?.api_key_hash, signed: (c) => asRecord(c.caller_binding)?.api_key_hash },
-    { field: 'claim_id', outer: (r) => r.claim_id, signed: (c) => c.claim_id },
-    { field: 'route.model', outer: (r) => r.route?.model, signed: (c) => asRecord(c.route)?.model },
-    { field: 'route.provider', outer: (r) => r.route?.provider, signed: (c) => asRecord(c.route)?.provider },
-    { field: 'output.hash', outer: (r) => r.output?.hash, signed: (c) => asRecord(c.output)?.hash },
-    { field: 'binding.expected_commitment', outer: (r) => r.binding?.expected_commitment, signed: (c) => asRecord(c.binding)?.expected_commitment },
-    { field: 'provider_cogs.actual', outer: (r) => r.provider_cogs?.actual, signed: (c) => asRecord(c.provider_cogs)?.actual },
-];
-/** Flag unsigned outer copies that disagree with the JWS payload. */
 function diffOuterClaims(receipt, claims) {
     if (!claims)
         return [];
     const mismatches = [];
-    for (const spec of CLAIM_COMPARE) {
-        const outer = normFact(spec.outer(receipt), spec.address);
-        const signed = normFact(spec.signed(claims), spec.address);
-        if (outer == null || signed == null || outer === signed)
-            continue;
-        mismatches.push({
-            field: spec.field,
-            outer: claimString(spec.outer(receipt)),
-            signed: claimString(spec.signed(claims)),
-        });
+    compareSignedNode(claims, receipt, '', mismatches);
+    return mismatches;
+}
+function pushUnsignedLeaves(value, path, paths) {
+    if (isPlain(value)) {
+        const keys = Object.keys(value).sort();
+        if (keys.length === 0) {
+            paths.push(path);
+            return;
+        }
+        for (const key of keys)
+            pushUnsignedLeaves(value[key], `${path}.${key}`, paths);
+        return;
     }
-    // v9 head pair. Compared when the outer key is present, including a null
-    // signed hash against a filled-in outer copy. v8 claims skip this.
-    if ((0, head_binding_js_1.headBindingVerdict)(claims) === 'ok') {
-        const disagree = (0, head_binding_js_1.outerHeadDisagrees)(receipt, claims);
-        if (disagree) {
-            const outerValue = disagree === 'tree_head_hash' ? receipt.tree_head_hash : receipt.tolerance;
-            const signedValue = disagree === 'tree_head_hash' ? claims.tree_head_hash : claims.tolerance;
-            mismatches.push({
-                field: disagree,
-                outer: outerValue == null ? null : JSON.stringify(outerValue),
-                signed: signedValue == null ? null : JSON.stringify(signedValue),
-            });
+    paths.push(path);
+}
+function collectUnsigned(outer, signed, prefix, paths) {
+    if (!isPlain(outer))
+        return;
+    const signedObj = isPlain(signed) ? signed : null;
+    for (const key of Object.keys(outer).sort()) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        // The signature container is the credential that was checked, not an unsigned claim.
+        if (!prefix && key === 'issuer_signature')
+            continue;
+        const signedHas = !!signedObj && Object.prototype.hasOwnProperty.call(signedObj, key);
+        if (!signedHas || schemaIsNotACopy(path)) {
+            pushUnsignedLeaves(outer[key], path, paths);
+            continue;
         }
+        const sv = signedObj[key];
+        if (isPlain(outer[key]) && isPlain(sv))
+            collectUnsigned(outer[key], sv, path, paths);
     }
-    return mismatches;
+}
+/** Outer paths the signed claims do not cover. Sorted. Not a failure by themselves. */
+function unsignedOuterFields(receipt, claims) {
+    const paths = [];
+    collectUnsigned(receipt, claims, '', paths);
+    return paths;
 }
 function receiptViewFromClaims(receipt, claims) {
     const payment = asRecord(claims.payment);
@@ -794,10 +854,10 @@ function factsFromClaims(claims) {
     };
 }
 function issuerJwksUri(receipt) {
-    const fromVerification = receipt.verification?.jwks_uri;
+    const fromVerification = receipt?.verification?.jwks_uri;
     if (typeof fromVerification === 'string' && fromVerification.startsWith('https://'))
         return fromVerification;
-    const jws = receipt.issuer_signature?.jws;
+    const jws = receipt?.issuer_signature?.jws;
     const header = jws ? (0, jws_js_1.readJwsHeader)(jws) : null;
     if (header?.jku && header.jku.startsWith('https://'))
         return header.jku;
@@ -826,6 +886,36 @@ function mergeJwks(primary, extra) {
     }
     return { keys: deduped };
 }
+/**
+ * Key sources shared by receipt verification and the epoch-record check:
+ * a caller-supplied JWKS, `--jwks-url` (any https URL), and `--fetch-jwks`
+ * from an allowlisted host. A failed fetch is an error. It does not add a key.
+ */
+async function loadIssuerJwks(source, options = {}) {
+    const errors = [];
+    let jwks = options.jwks;
+    const trustedHosts = options.trustedJwksHosts ?? jws_js_1.DEFAULT_TRUSTED_JWKS_HOSTS;
+    if (options.jwksUri || options.fetchJwks) {
+        const uri = options.jwksUri || issuerJwksUri(source);
+        const allowed = !!uri && (options.jwksUri ? httpsUrl(uri) : (0, jws_js_1.jwksHostAllowed)(uri, trustedHosts));
+        if (uri && allowed) {
+            try {
+                const fetched = await fetchIssuerJwks(uri, options.fetchImpl);
+                jwks = mergeJwks(jwks, fetched);
+            }
+            catch (err) {
+                errors.push(`JWKS fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        else if (options.jwksUri) {
+            errors.push('JWKS URI rejected — only https URLs are fetched');
+        }
+        else if (options.fetchJwks && uri) {
+            errors.push(`JWKS host untrusted: ${uri}`);
+        }
+    }
+    return { jwks, errors };
+}
 /** Fetch a JWKS document. Caller decides whether the URL is a trust root. */
 async function fetchIssuerJwks(uri, fetchImpl = globalThis.fetch) {
     if (!httpsUrl(uri))
@@ -857,9 +947,55 @@ function normalizeBoundRoot(root) {
     return /^[0-9a-f]{64}$/.test(hex) ? hex : null;
 }
 /**
- * True when the supplied head is the signed prefix, or a later head whose
- * inclusion proof contains this receipt's leaf.
+ * Row hash for an offline leaf. Null and `''` are missing: do not hash `task_id|`.
+ */
+function inclusionRow(receipt, inclusion) {
+    const bound = (0, row_hash_js_1.boundRowHash)(receipt, inclusion);
+    if (!bound.ok)
+        return bound;
+    if (bound.row == null || bound.row === '')
+        return { ok: false, reason: 'no_leaf' };
+    return { ok: true, row: bound.row };
+}
+/**
+ * Bind a supplied inclusion proof to its leaf index and tree size.
+ * The head's size, when present, has to be the inclusion's size.
+ */
+function offlineInclusionBound(receipt, head, inclusion) {
+    const index = inclusion.leaf_index;
+    const size = inclusion.tree_size ?? head?.tree_size;
+    if (index == null || size == null || !Array.isArray(inclusion.proof)) {
+        return { ok: false, reason: 'inclusion_failed' };
+    }
+    if (head?.tree_size != null && inclusion.tree_size != null
+        && Number(head.tree_size) !== Number(inclusion.tree_size)) {
+        return { ok: false, reason: 'tree_size_mismatch' };
+    }
+    const root = normalizeBoundRoot(head?.root) || normalizeBoundRoot(inclusion.root);
+    if (!root)
+        return { ok: false, reason: 'bad_root' };
+    if (receipt.task_id == null)
+        return { ok: false, reason: 'missing_task_id' };
+    const bound = inclusionRow(receipt, inclusion);
+    if (!bound.ok)
+        return bound;
+    const leaf = (0, anchor_witness_js_1.leafHash)(Buffer.from(`${receipt.task_id}|${bound.row}`));
+    if (typeof inclusion.leaf === 'string' && /^[0-9a-fA-F]{64}$/.test(inclusion.leaf)
+        && inclusion.leaf.toLowerCase() !== leaf.toString('hex')) {
+        return { ok: false, reason: 'leaf_mismatch' };
+    }
+    const included = (0, anchor_witness_js_1.verifyMerkleInclusion)(leaf, Number(index), Number(size), root, inclusion.proof);
+    return included ? { ok: true } : { ok: false, reason: 'inclusion_failed' };
+}
+/**
+ * `{ root }` and `{ root, tree_size }` only compare a signed tree_head_hash.
+ * Any other supplied head is an offline tree-head witness and needs a signature.
  */
+function offlineHeadNeedsSignature(head) {
+    if (!head || typeof head !== 'object')
+        return false;
+    return Object.keys(head).some((key) => key !== 'root' && key !== 'tree_size');
+}
 function suppliedHeadCovers(receipt, signedRoot, head, inclusion) {
     const signed = normalizeBoundRoot(signedRoot);
     const supplied = normalizeBoundRoot(head?.root);
@@ -871,8 +1007,10 @@ function suppliedHeadCovers(receipt, signedRoot, head, inclusion) {
         return true;
     if (receipt.task_id == null)
         return false;
-    const row = inclusion.row_hash ?? receipt.book_chain?.row_hash ?? '';
-    const leaf = (0, anchor_witness_js_1.leafHash)(Buffer.from(`${receipt.task_id}|${row}`));
+    const bound = inclusionRow(receipt, inclusion);
+    if (!bound.ok)
+        return false;
+    const leaf = (0, anchor_witness_js_1.leafHash)(Buffer.from(`${receipt.task_id}|${bound.row}`));
     if (typeof inclusion.leaf === 'string' && /^[0-9a-fA-F]{64}$/.test(inclusion.leaf)
         && inclusion.leaf.toLowerCase() !== leaf.toString('hex')) {
         return false;
@@ -882,30 +1020,29 @@ function suppliedHeadCovers(receipt, signedRoot, head, inclusion) {
         return false;
     return (0, anchor_witness_js_1.verifyMerkleInclusion)(leaf, Number(inclusion.leaf_index), Number(size), supplied, inclusion.proof);
 }
+/** v1–v10 verifier. A v11 payload is `unsupported_version` and is not checked as v10. */
+async function verifyReceiptUpToV10(receipt, options = {}) {
+    return (0, v11_receipt_js_1.verifyReceiptUpToV10)(receipt, options, verifyReceipt);
+}
 async function verifyReceipt(receipt, options = {}) {
+    const preDecoded = receipt?.issuer_signature?.jws
+        ? (0, payer_js_1.decodeJwsPayload)(receipt.issuer_signature.jws)
+        : null;
+    if (preDecoded?.v === 11) {
+        return (0, v11_receipt_js_1.verifyV11Receipt)(receipt, options);
+    }
     const errors = [];
     const trustedKids = options.trustedKids ?? jws_js_1.DEFAULT_TRUSTED_ISSUER_KIDS;
     const trustedHosts = options.trustedJwksHosts ?? jws_js_1.DEFAULT_TRUSTED_JWKS_HOSTS;
-    let jwks = options.jwks;
-    if (options.jwksUri || options.fetchJwks) {
-        const uri = options.jwksUri || issuerJwksUri(receipt);
-        const allowed = !!uri && (options.jwksUri ? httpsUrl(uri) : (0, jws_js_1.jwksHostAllowed)(uri, trustedHosts));
-        if (uri && allowed) {
-            try {
-                const fetched = await fetchIssuerJwks(uri, options.fetchImpl);
-                jwks = mergeJwks(jwks, fetched);
-            }
-            catch (err) {
-                errors.push(`JWKS fetch failed: ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }
-        else if (options.jwksUri) {
-            errors.push('JWKS URI rejected — only https URLs are fetched');
-        }
-        else if (options.fetchJwks && uri) {
-            errors.push(`JWKS host untrusted: ${uri}`);
-        }
-    }
+    const loadedKeys = await loadIssuerJwks(receipt, {
+        jwks: options.jwks,
+        jwksUri: options.jwksUri,
+        fetchJwks: options.fetchJwks,
+        trustedJwksHosts: trustedHosts,
+        fetchImpl: options.fetchImpl,
+    });
+    const jwks = loadedKeys.jwks;
+    errors.push(...loadedKeys.errors);
     let issuer_signature;
     if (receipt.issuer_signature?.jws || receipt.issuer_signature?.value) {
         issuer_signature = verifyIssuerSignatureWithJwks(receipt, jwks, { trustedKids });
@@ -936,6 +1073,7 @@ async function verifyReceipt(receipt, options = {}) {
         ? (0, payer_js_1.decodeJwsPayload)(receipt.issuer_signature.jws)
         : null;
     const claim_mismatches = diffOuterClaims(receipt, decoded);
+    const unsigned_fields = unsignedOuterFields(receipt, decoded);
     for (const mismatch of claim_mismatches) {
         errors.push(`outer/signed mismatch: ${mismatch.field} (outer ${mismatch.outer}, signed ${mismatch.signed})`);
     }
@@ -960,6 +1098,79 @@ async function verifyReceipt(receipt, options = {}) {
             errors.push('tree_head_mismatch');
         }
     }
+    const issuedAt = (verifiedClaims && 'iat' in verifiedClaims ? verifiedClaims.iat : null)
+        ?? decoded?.iat
+        ?? receipt.created_at
+        ?? null;
+    const historyPin = (0, issuer_history_js_1.readIssuerHistoryPin)(verifiedClaims);
+    const payloadVersion = Number(verifiedClaims?.payload_version);
+    // Payload v10 signs the history pin. A missing pin fails even when the
+    // caller did not pass a history file or ask for a fetch.
+    const pinRequired = !options.skipIssuerHistory
+        && Number.isFinite(payloadVersion)
+        && payloadVersion >= canonical_preimage_js_1.CANONICAL_PAYLOAD_VERSION;
+    const historyAsked = pinRequired || (!options.skipIssuerHistory && !!(options.issuerHistory
+        || options.issuerHistoryBytes
+        || options.fetchIssuerHistory
+        || options.strictIssuerHistory
+        || options.issuerHistoryUrl
+        || historyPin));
+    const issuer_history = historyAsked
+        ? await (0, issuer_history_js_1.checkReceiptIssuerHistory)(receipt, {
+            document: options.issuerHistory ?? null,
+            documentBytes: options.issuerHistoryBytes ?? null,
+            fetchHistory: options.fetchIssuerHistory === true || options.strictIssuerHistory === true,
+            strict: options.strictIssuerHistory === true,
+            historyUrl: options.issuerHistoryUrl ?? null,
+            jwks,
+            trustedKids,
+            fetchImpl: options.fetchImpl,
+            trustedHosts,
+            issuedAt,
+            kid: issuer_signature.kid ?? receipt.issuer_signature?.kid ?? null,
+            pin: historyPin,
+            requirePin: pinRequired,
+        })
+        : {
+            checked: false,
+            ok: true,
+            unreachable: false,
+            warning: null,
+            reason: null,
+            kid: issuer_signature.kid ?? receipt.issuer_signature?.kid ?? null,
+            document: null,
+            loaded: false,
+        };
+    // Offline: a tree-head witness is trusted only when its ES256 signature
+    // covers the outer size, root, and the other fields anchor mode already
+    // compares. A missing signature is head_signature_missing. The history
+    // body loaded above is the one this check trusts. Chain RPC is not used.
+    let headTrustFailed = false;
+    const suppliedHead = options.head;
+    if (offlineHeadNeedsSignature(suppliedHead)) {
+        const trust = (0, anchor_trust_js_1.verifyTreeHeadTrust)(suppliedHead, {
+            jwks,
+            trustedKids,
+            issuerHistory: issuer_history.document,
+            strictIssuerHistory: options.strictIssuerHistory === true,
+        });
+        if (!trust.ok) {
+            headTrustFailed = true;
+            errors.push(trust.reason || 'head_signature_invalid');
+        }
+        else if (issuer_history.loaded && !issuer_history.document) {
+            headTrustFailed = true;
+            errors.push('issuer_history_invalid');
+        }
+    }
+    let inclusionFailed = false;
+    if (options.inclusion && (options.inclusion.proof || options.inclusion.leaf_index != null)) {
+        const bound = offlineInclusionBound(receipt, options.head ?? null, options.inclusion);
+        if (!bound.ok) {
+            inclusionFailed = true;
+            errors.push(bound.reason);
+        }
+    }
     let binding;
     if (receipt.issuer_signature?.jws) {
         if (verifiedClaims) {
@@ -1100,47 +1311,6 @@ async function verifyReceipt(receipt, options = {}) {
                 errors.push(`canonical preimage: ${fileCheck.reason}`);
         }
     }
-    const issuedAt = (verifiedClaims && 'iat' in verifiedClaims ? verifiedClaims.iat : null)
-        ?? decoded?.iat
-        ?? receipt.created_at
-        ?? null;
-    const historyPin = (0, issuer_history_js_1.readIssuerHistoryPin)(verifiedClaims);
-    const payloadVersion = Number(verifiedClaims?.payload_version);
-    // Payload v10 signs the history pin. A missing pin fails even when the
-    // caller did not pass a history file or ask for a fetch.
-    const pinRequired = !options.skipIssuerHistory
-        && Number.isFinite(payloadVersion)
-        && payloadVersion >= canonical_preimage_js_1.CANONICAL_PAYLOAD_VERSION;
-    const historyAsked = pinRequired || (!options.skipIssuerHistory && !!(options.issuerHistory
-        || options.issuerHistoryBytes
-        || options.fetchIssuerHistory
-        || options.strictIssuerHistory
-        || options.issuerHistoryUrl
-        || historyPin));
-    const issuer_history = historyAsked
-        ? await (0, issuer_history_js_1.checkReceiptIssuerHistory)(receipt, {
-            document: options.issuerHistory ?? null,
-            documentBytes: options.issuerHistoryBytes ?? null,
-            fetchHistory: options.fetchIssuerHistory === true || options.strictIssuerHistory === true,
-            strict: options.strictIssuerHistory === true,
-            historyUrl: options.issuerHistoryUrl ?? null,
-            jwks,
-            trustedKids,
-            fetchImpl: options.fetchImpl,
-            trustedHosts,
-            issuedAt,
-            kid: issuer_signature.kid ?? receipt.issuer_signature?.kid ?? null,
-            pin: historyPin,
-            requirePin: pinRequired,
-        })
-        : {
-            checked: false,
-            ok: true,
-            unreachable: false,
-            warning: null,
-            reason: null,
-            kid: issuer_signature.kid ?? receipt.issuer_signature?.kid ?? null,
-        };
     if (issuer_history.warning)
         warnings.push(issuer_history.warning);
     if (issuer_history.checked && !issuer_history.ok && issuer_history.reason) {
@@ -1164,7 +1334,7 @@ async function verifyReceipt(receipt, options = {}) {
     let overall;
     const preimageFailed = !preimages.ok;
     const historyFailed = issuer_history.checked && !issuer_history.ok;
-    if (signatureFailed || mismatchFailed || bindingFailed || payerFailed || nullifierFailed || claimRefused || headMissing || headMismatch || preimageFailed || historyFailed || canonicalPreimageFailed) {
+    if (signatureFailed || mismatchFailed || bindingFailed || payerFailed || nullifierFailed || claimRefused || headMissing || headMismatch || headTrustFailed || inclusionFailed || preimageFailed || historyFailed || canonicalPreimageFailed) {
         overall = 'failed';
     }
     else if (signatureUnchecked) {
@@ -1190,11 +1360,49 @@ async function verifyReceipt(receipt, options = {}) {
         errors.push('refusal document is not a payment receipt');
         overall = 'failed';
     }
+    let carry_forward;
+    if (options.carry) {
+        const bound = (0, row_hash_js_1.boundRowHash)(receipt, { row_hash: options.carry.row_hash });
+        const leaf = !bound.ok || bound.row == null || bound.row === '' || receipt.task_id == null
+            ? null
+            : (0, anchor_witness_js_1.leafHash)(Buffer.from(`${receipt.task_id}|${bound.row}`));
+        const verdict = !bound.ok
+            ? { applicable: true, ok: false, status: null, reason: bound.reason }
+            : (bound.row == null || bound.row === '')
+                ? { applicable: true, ok: false, status: null, reason: 'row_hash_missing' }
+                : leaf
+                    ? (0, carry_forward_js_1.verifyCarryForward)({
+                        leaf,
+                        oldHead: options.carry.oldHead,
+                        oldInclusion: options.carry.oldInclusion,
+                        currentHead: options.carry.currentHead,
+                        currentInclusions: options.carry.currentInclusions,
+                        trustedKids,
+                        jwks,
+                    })
+                    : { applicable: true, ok: false, status: null, reason: 'not_in_tree' };
+        if (verdict.applicable && !verdict.ok) {
+            errors.push(verdict.reason);
+            overall = 'failed';
+        }
+        else if (verdict.applicable && verdict.ok && overall === 'verified') {
+            overall = 'verified_carried_forward';
+            carry_forward = {
+                status: verdict.status,
+                issued_at: verdict.issued_at,
+                issued_epoch: verdict.issued_epoch,
+                logged_at: verdict.logged_at,
+                logged_epoch: verdict.logged_epoch,
+                leaf_index: verdict.leaf_index,
+            };
+        }
+    }
     const signedPayment = asRecord(verifiedClaims?.payment);
     const signedSettlement = asRecord(verifiedClaims?.settlement);
     const receipt_lane = (0, receipt_lane_js_1.receiptLaneFromVerification)({
         receipt,
         claims: {
+            schema: verifiedSchema,
             payment: signedPayment ? {
                 ref: typeof signedPayment.ref === 'string' ? signedPayment.ref : null,
                 rail: typeof signedPayment.rail === 'string' ? signedPayment.rail : null,
@@ -1220,6 +1428,8 @@ async function verifyReceipt(receipt, options = {}) {
         amount_usdc: facts.amount_usdc,
         tx: facts.tx,
         claim_mismatches,
+        unsigned_fields,
+        verified_scope: 'signed_claims',
         claim_id,
         head_binding: signedBinding
             ? { tree_head_hash: signedBinding.tree_head_hash, tolerance: signedBinding.tolerance }
@@ -1228,6 +1438,7 @@ async function verifyReceipt(receipt, options = {}) {
         preimages,
         issuer_history,
         warnings,
+        ...(carry_forward ? { carry_forward } : {}),
         overall,
         errors,
     };
@@ -1261,9 +1472,37 @@ var refusal_js_2 = require("./refusal.js");
 Object.defineProperty(exports, "isRefusalDocument", { enumerable: true, get: function () { return refusal_js_2.isRefusalDocument; } });
 Object.defineProperty(exports, "verifyRefusal", { enumerable: true, get: function () { return refusal_js_2.verifyRefusal; } });
 Object.defineProperty(exports, "REFUSAL_SCHEMA", { enumerable: true, get: function () { return refusal_js_2.REFUSAL_SCHEMA; } });
+Object.defineProperty(exports, "REFUSAL_SCHEMA_V2", { enumerable: true, get: function () { return refusal_js_2.REFUSAL_SCHEMA_V2; } });
 Object.defineProperty(exports, "REFUSAL_PAYLOAD_VERSION", { enumerable: true, get: function () { return refusal_js_2.REFUSAL_PAYLOAD_VERSION; } });
 Object.defineProperty(exports, "REFUSAL_PROVES", { enumerable: true, get: function () { return refusal_js_2.REFUSAL_PROVES; } });
 Object.defineProperty(exports, "REFUSAL_DOES_NOT_PROVE", { enumerable: true, get: function () { return refusal_js_2.REFUSAL_DOES_NOT_PROVE; } });
+var request_binding_js_1 = require("./request-binding.js");
+Object.defineProperty(exports, "verifyRequestDigest", { enumerable: true, get: function () { return request_binding_js_1.verifyRequestDigest; } });
+Object.defineProperty(exports, "requestDigestOfPreimage", { enumerable: true, get: function () { return request_binding_js_1.requestDigestOfPreimage; } });
+var epoch_js_1 = require("./epoch.js");
+Object.defineProperty(exports, "acceptTreeHeadSchema", { enumerable: true, get: function () { return epoch_js_1.acceptTreeHeadSchema; } });
+Object.defineProperty(exports, "verifyEpochLink", { enumerable: true, get: function () { return epoch_js_1.verifyEpochLink; } });
+Object.defineProperty(exports, "verifyEpochRecord", { enumerable: true, get: function () { return epoch_js_1.verifyEpochRecord; } });
+Object.defineProperty(exports, "verifyEpochInclusion", { enumerable: true, get: function () { return epoch_js_1.verifyEpochInclusion; } });
+Object.defineProperty(exports, "verifyUnloggedSection", { enumerable: true, get: function () { return epoch_js_1.verifyUnloggedSection; } });
+Object.defineProperty(exports, "verifyUnloggedCommitment", { enumerable: true, get: function () { return epoch_js_1.verifyUnloggedCommitment; } });
+Object.defineProperty(exports, "unloggedIdCommitment", { enumerable: true, get: function () { return epoch_js_1.unloggedIdCommitment; } });
+Object.defineProperty(exports, "unloggedReasonForTask", { enumerable: true, get: function () { return epoch_js_1.unloggedReasonForTask; } });
+Object.defineProperty(exports, "canonicalUnloggedRows", { enumerable: true, get: function () { return epoch_js_1.canonicalUnloggedRows; } });
+Object.defineProperty(exports, "TREE_HEAD_SCHEMA_V1", { enumerable: true, get: function () { return epoch_js_1.TREE_HEAD_SCHEMA_V1; } });
+Object.defineProperty(exports, "TREE_HEAD_SCHEMA_V2", { enumerable: true, get: function () { return epoch_js_1.TREE_HEAD_SCHEMA_V2; } });
+Object.defineProperty(exports, "EPOCH1_FINAL_ROOT", { enumerable: true, get: function () { return epoch_js_1.EPOCH1_FINAL_ROOT; } });
+Object.defineProperty(exports, "EPOCH1_FINAL_SIZE", { enumerable: true, get: function () { return epoch_js_1.EPOCH1_FINAL_SIZE; } });
+Object.defineProperty(exports, "EPOCH1_GENESIS_DIGEST", { enumerable: true, get: function () { return epoch_js_1.EPOCH1_GENESIS_DIGEST; } });
+Object.defineProperty(exports, "EPOCH1_SIZE1_ROOT", { enumerable: true, get: function () { return epoch_js_1.EPOCH1_SIZE1_ROOT; } });
+Object.defineProperty(exports, "EPOCH1_SIZE2_ROOT", { enumerable: true, get: function () { return epoch_js_1.EPOCH1_SIZE2_ROOT; } });
+Object.defineProperty(exports, "epoch1PrefixRoot", { enumerable: true, get: function () { return epoch_js_1.epoch1PrefixRoot; } });
+Object.defineProperty(exports, "matchEpoch1Prefix", { enumerable: true, get: function () { return epoch_js_1.matchEpoch1Prefix; } });
+Object.defineProperty(exports, "EPOCH2_OPENING_ROOT", { enumerable: true, get: function () { return epoch_js_1.EPOCH2_OPENING_ROOT; } });
+var carry_forward_js_2 = require("./carry-forward.js");
+Object.defineProperty(exports, "verifyCarryForward", { enumerable: true, get: function () { return carry_forward_js_2.verifyCarryForward; } });
+Object.defineProperty(exports, "PINNED_ANCHOR_EPOCHS", { enumerable: true, get: function () { return carry_forward_js_2.PINNED_ANCHOR_EPOCHS; } });
+Object.defineProperty(exports, "CARRY_FORWARD_STATUS", { enumerable: true, get: function () { return carry_forward_js_2.CARRY_FORWARD_STATUS; } });
 var anchor_witness_js_2 = require("./anchor-witness.js");
 Object.defineProperty(exports, "verifyAnchoredRoot", { enumerable: true, get: function () { return anchor_witness_js_2.verifyAnchoredRoot; } });
 Object.defineProperty(exports, "verifyMerkleInclusion", { enumerable: true, get: function () { return anchor_witness_js_2.verifyMerkleInclusion; } });
@@ -1274,6 +1513,44 @@ Object.defineProperty(exports, "ANCHOR_PROVES", { enumerable: true, get: functio
 Object.defineProperty(exports, "ANCHOR_DOES_NOT_PROVE", { enumerable: true, get: function () { return anchor_witness_js_2.ANCHOR_DOES_NOT_PROVE; } });
 Object.defineProperty(exports, "SOLANA_GENESIS", { enumerable: true, get: function () { return anchor_witness_js_2.SOLANA_GENESIS; } });
 Object.defineProperty(exports, "BASE_MAINNET_CHAIN_ID", { enumerable: true, get: function () { return anchor_witness_js_2.BASE_MAINNET_CHAIN_ID; } });
+var issuer_pin_js_1 = require("./issuer-pin.js");
+Object.defineProperty(exports, "assessIssuerPin", { enumerable: true, get: function () { return issuer_pin_js_1.assessIssuerPin; } });
+Object.defineProperty(exports, "issuerPinContentUrl", { enumerable: true, get: function () { return issuer_pin_js_1.issuerPinContentUrl; } });
+Object.defineProperty(exports, "issuerPinFileHash", { enumerable: true, get: function () { return issuer_pin_js_1.issuerPinFileHash; } });
+Object.defineProperty(exports, "loadIssuerPinBytes", { enumerable: true, get: function () { return issuer_pin_js_1.loadIssuerPinBytes; } });
+Object.defineProperty(exports, "readIssuerPinClaim", { enumerable: true, get: function () { return issuer_pin_js_1.readIssuerPinClaim; } });
+Object.defineProperty(exports, "registrationPreimage", { enumerable: true, get: function () { return issuer_pin_js_1.registrationPreimage; } });
+Object.defineProperty(exports, "rotationStatement", { enumerable: true, get: function () { return issuer_pin_js_1.rotationStatement; } });
+Object.defineProperty(exports, "serializeIssuerPin", { enumerable: true, get: function () { return issuer_pin_js_1.serializeIssuerPin; } });
+Object.defineProperty(exports, "verifyCitizenRotation", { enumerable: true, get: function () { return issuer_pin_js_1.verifyCitizenRotation; } });
+Object.defineProperty(exports, "verifyRegistrationSignature", { enumerable: true, get: function () { return issuer_pin_js_1.verifyRegistrationSignature; } });
+Object.defineProperty(exports, "canonicalPublicKey", { enumerable: true, get: function () { return issuer_pin_js_1.canonicalPublicKey; } });
+Object.defineProperty(exports, "ISSUER_REGISTRATION_CONTEXT", { enumerable: true, get: function () { return issuer_pin_js_1.ISSUER_REGISTRATION_CONTEXT; } });
+Object.defineProperty(exports, "ISSUER_ROTATION_CONTEXT", { enumerable: true, get: function () { return issuer_pin_js_1.ISSUER_ROTATION_CONTEXT; } });
+Object.defineProperty(exports, "ISSUER_PIN_VERSION", { enumerable: true, get: function () { return issuer_pin_js_1.ISSUER_PIN_VERSION; } });
+Object.defineProperty(exports, "ISSUER_PIN_SCHEMA", { enumerable: true, get: function () { return issuer_pin_js_1.ISSUER_PIN_SCHEMA; } });
+Object.defineProperty(exports, "ISSUER_PIN_PATH", { enumerable: true, get: function () { return issuer_pin_js_1.ISSUER_PIN_PATH; } });
+Object.defineProperty(exports, "ISSUER_PIN_CHAIN_ID", { enumerable: true, get: function () { return issuer_pin_js_1.ISSUER_PIN_CHAIN_ID; } });
+Object.defineProperty(exports, "PUBLISHED_ISSUER_PIN_KID", { enumerable: true, get: function () { return issuer_pin_js_1.PUBLISHED_ISSUER_PIN_KID; } });
+Object.defineProperty(exports, "CITIZEN_FREEZE_SCHEMA", { enumerable: true, get: function () { return issuer_pin_js_1.CITIZEN_FREEZE_SCHEMA; } });
+Object.defineProperty(exports, "CITIZEN_FREEZE_PURPOSE", { enumerable: true, get: function () { return issuer_pin_js_1.CITIZEN_FREEZE_PURPOSE; } });
+Object.defineProperty(exports, "ISSUER_PIN_MISMATCH", { enumerable: true, get: function () { return issuer_pin_js_1.ISSUER_PIN_MISMATCH; } });
+Object.defineProperty(exports, "ISSUER_PIN_HASH_MISMATCH", { enumerable: true, get: function () { return issuer_pin_js_1.ISSUER_PIN_HASH_MISMATCH; } });
+Object.defineProperty(exports, "ISSUER_SELF_SIG_INVALID", { enumerable: true, get: function () { return issuer_pin_js_1.ISSUER_SELF_SIG_INVALID; } });
+Object.defineProperty(exports, "ISSUER_PIN_DOWNGRADE", { enumerable: true, get: function () { return issuer_pin_js_1.ISSUER_PIN_DOWNGRADE; } });
+Object.defineProperty(exports, "ISSUER_PIN_MUTABLE_REF", { enumerable: true, get: function () { return issuer_pin_js_1.ISSUER_PIN_MUTABLE_REF; } });
+Object.defineProperty(exports, "ISSUER_ROTATION_UNCONTROLLED", { enumerable: true, get: function () { return issuer_pin_js_1.ISSUER_ROTATION_UNCONTROLLED; } });
+Object.defineProperty(exports, "ISSUER_PIN_CHAIN_REFUSED", { enumerable: true, get: function () { return issuer_pin_js_1.ISSUER_PIN_CHAIN_REFUSED; } });
+var anchor_trust_js_2 = require("./anchor-trust.js");
+Object.defineProperty(exports, "PINNED_BASE_ANCHOR_WALLET", { enumerable: true, get: function () { return anchor_trust_js_2.PINNED_BASE_ANCHOR_WALLET; } });
+Object.defineProperty(exports, "PINNED_SOLANA_ANCHOR_FEE_PAYER", { enumerable: true, get: function () { return anchor_trust_js_2.PINNED_SOLANA_ANCHOR_FEE_PAYER; } });
+Object.defineProperty(exports, "ANCHOR_WALLET_SOURCES_NOT_CONSULTED", { enumerable: true, get: function () { return anchor_trust_js_2.ANCHOR_WALLET_SOURCES_NOT_CONSULTED; } });
+Object.defineProperty(exports, "LEGACY_HEAD_UNPINNED_SIGNER", { enumerable: true, get: function () { return anchor_trust_js_2.LEGACY_HEAD_UNPINNED_SIGNER; } });
+Object.defineProperty(exports, "HEAD_TRUST_MESSAGES", { enumerable: true, get: function () { return anchor_trust_js_2.HEAD_TRUST_MESSAGES; } });
+Object.defineProperty(exports, "headOmitsPinnedSigner", { enumerable: true, get: function () { return anchor_trust_js_2.headOmitsPinnedSigner; } });
+Object.defineProperty(exports, "verifyTreeHeadTrust", { enumerable: true, get: function () { return anchor_trust_js_2.verifyTreeHeadTrust; } });
+Object.defineProperty(exports, "verifyAnchorWalletDocument", { enumerable: true, get: function () { return anchor_trust_js_2.verifyAnchorWalletDocument; } });
+Object.defineProperty(exports, "compileAnchorWallets", { enumerable: true, get: function () { return anchor_trust_js_2.compileAnchorWallets; } });
 var canonical_preimage_js_2 = require("./canonical-preimage.js");
 Object.defineProperty(exports, "verifyCanonicalPreimageBytes", { enumerable: true, get: function () { return canonical_preimage_js_2.verifyCanonicalPreimageBytes; } });
 Object.defineProperty(exports, "CANONICAL_PAYLOAD_VERSION", { enumerable: true, get: function () { return canonical_preimage_js_2.CANONICAL_PAYLOAD_VERSION; } });