@xfuel/verify 0.1.1 → 0.2.1

package/dist/index.js

@@ -12,13 +12,18 @@
  * See docs/specs/RECEIPT_V2_SEMANTICS.md for the verification algorithm.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-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.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.canonicalPayloadVersion = canonicalPayloadVersion;
 exports.canonicalIssuerPayload = canonicalIssuerPayload;
+exports.sumUsdcTransfersToPayee = sumUsdcTransfersToPayee;
+exports.reconcileSettledTransfer = reconcileSettledTransfer;
 exports.verifyIssuerSignature = verifyIssuerSignature;
 exports.verifyIssuerSignatureWithJwks = verifyIssuerSignatureWithJwks;
 exports.verifyBinding = verifyBinding;
 exports.verifyNullifier = verifyNullifier;
 exports.hashCanonicalPayload = hashCanonicalPayload;
+exports.diffOuterClaims = diffOuterClaims;
+exports.fetchIssuerJwks = fetchIssuerJwks;
 exports.receiptPayerClaims = receiptPayerClaims;
 exports.verifyReceipt = verifyReceipt;
 const ethers_1 = require("ethers");
@@ -59,28 +64,28 @@ const ZK_VERIFIER_ABI = [
     'function usedNullifiers(bytes32) view returns (bool)',
 ];
 /**
- * Canonical, order-stable payload an issuer signature covers.
- * MUST match `canonicalSignedPayload` in services/gateway/src/receipt.js exactly.
- *
- * Signed fields (15 total):
- *   1. task_id
- *   2. payment.rail
- *   3. payment.ref
- *   4. payment.gross_amount
- *   5. payment.net_amount
- *   6. payment.fee_amount
- *   7. payment.protocol_fee_bps ?? payment.fee_bps
- *   8. payment.platform_fee
- *   9. payment.platform_fee_bps
- *  10. provider_cogs.actual
- *  11. route.model
- *  12. route.model_commitment.commitment
- *  13. route.provider
- *  14. output.hash
- *  15. binding.expected_commitment
+ * HMAC payload version.
+ * Versions <= 7 keep the historical net/fee field list.
+ * Version 8 signs settled_amount plus the internal accounting breakdown.
+ * Lockstep with `canonicalPayloadVersion` in services/gateway/src/receipt.js
+ * for the v8 list (the v7 list here is the historical 15-field public formula).
  */
-function canonicalIssuerPayload(receipt) {
-    return JSON.stringify([
+function canonicalPayloadVersion(receipt) {
+    const stamped = receipt.hmac_attestation?.payload_version
+        ?? receipt.signature?.payload_version;
+    if (stamped != null)
+        return Number(stamped);
+    const issuerV = receipt.issuer_signature?.payload_version;
+    if (issuerV != null)
+        return Number(issuerV);
+    const payment = receipt.payment;
+    if (payment?.accounting || (payment && Object.prototype.hasOwnProperty.call(payment, 'settled_amount'))) {
+        return 8;
+    }
+    return 7;
+}
+function canonicalFieldsV7(receipt) {
+    return [
         receipt.task_id ?? null,
         receipt.payment?.rail ?? null,
         receipt.payment?.ref ?? null,
@@ -96,7 +101,204 @@ function canonicalIssuerPayload(receipt) {
         receipt.route?.provider ?? null,
         receipt.output?.hash ?? null,
         receipt.binding?.expected_commitment ?? null,
-    ]);
+    ];
+}
+function canonicalFieldsV8(receipt) {
+    const breakdown = receipt.payment?.accounting?.internal_breakdown;
+    const caller = receipt.caller_binding;
+    return [
+        receipt.task_id ?? null,
+        receipt.payment?.rail ?? null,
+        receipt.payment?.ref ?? null,
+        receipt.payment?.gross_amount ?? null,
+        receipt.payment?.settled_amount ?? null,
+        breakdown?.route_margin_bps ?? null,
+        breakdown?.route_margin_amount ?? null,
+        breakdown?.receipt_floor_amount ?? null,
+        breakdown?.provider_cogs_amount ?? null,
+        breakdown?.tier2_proof_amount ?? null,
+        receipt.provider_cogs?.actual ?? null,
+        receipt.route?.model ?? null,
+        receipt.route?.model_commitment?.commitment ?? null,
+        receipt.route?.provider ?? null,
+        receipt.output?.hash ?? null,
+        receipt.binding?.expected_commitment ?? null,
+        caller?.payer_wallet ?? null,
+        caller?.agent_pubkey ?? null,
+        caller?.api_key_hash ?? null,
+    ];
+}
+/**
+ * Canonical, order-stable payload an HMAC issuer signature covers.
+ * v8 matches `canonicalSignedPayload` in services/gateway/src/receipt.js.
+ * v7 and earlier stay on the historical 15-field list so old signatures verify.
+ */
+function canonicalIssuerPayload(receipt) {
+    const fields = canonicalPayloadVersion(receipt) >= 8
+        ? canonicalFieldsV8(receipt)
+        : canonicalFieldsV7(receipt);
+    return JSON.stringify(fields);
+}
+function topicAddress(topic) {
+    const hex = topic.toLowerCase().replace(/^0x/, '');
+    return `0x${hex.slice(-40)}`;
+}
+/**
+ * Sum USDC Transfer values to `payee` in a transaction's logs.
+ * Non-Transfer logs are ignored. When `usdcAddress` is set, other contracts are ignored.
+ */
+function sumUsdcTransfersToPayee(logs, payee, usdcAddress) {
+    if (!payee || !(0, base_payer_js_1.isEvmAddress)(payee))
+        return null;
+    const payeeLower = payee.toLowerCase();
+    const usdcLower = usdcAddress?.toLowerCase();
+    let total = 0n;
+    let found = false;
+    for (const log of logs || []) {
+        if (usdcLower && log.address?.toLowerCase() !== usdcLower)
+            continue;
+        const topics = log.topics || [];
+        if (topics[0]?.toLowerCase() !== base_payer_js_1.ERC20_TRANSFER_TOPIC)
+            continue;
+        if (topics.length < 3 || !topics[2])
+            continue;
+        if (topicAddress(topics[2]) !== payeeLower)
+            continue;
+        found = true;
+        total += BigInt(log.data || '0x0');
+    }
+    return found ? total : null;
+}
+/**
+ * Payment facts for on-chain reconciliation.
+ * A JWS is used only after `verifyIssuerSignatureWithJwks` accepts the key.
+ * An untrusted or invalid JWS is not decoded into the comparison, and the
+ * unsigned outer `payment` copy is not a fallback for those claims.
+ * Receipts with no JWS still use the outer payment (legacy envelopes).
+ */
+function trustedPaymentForReconcile(receipt, options) {
+    const outerVersion = Number(receipt.issuer_signature?.payload_version ?? canonicalPayloadVersion(receipt));
+    const jws = receipt.issuer_signature?.jws;
+    if (!jws) {
+        return { ok: true, version: outerVersion, payment: receipt.payment || {} };
+    }
+    const verification = verifyIssuerSignatureWithJwks(receipt, options.jwks, {
+        trustedKids: options.trustedKids,
+    });
+    if (!verification.valid || verification.key_trusted === false) {
+        return {
+            ok: false,
+            version: outerVersion,
+            reason: verification.reason || jws_js_1.KEY_UNTRUSTED,
+        };
+    }
+    const claims = verification.payload;
+    const claimPayment = (claims?.payment && typeof claims.payment === 'object')
+        ? claims.payment
+        : null;
+    if (!claimPayment) {
+        return { ok: false, version: outerVersion, reason: 'no_signed_amount' };
+    }
+    const version = typeof claims?.payload_version === 'number'
+        ? claims.payload_version
+        : outerVersion;
+    return { ok: true, version: Number(version), payment: claimPayment };
+}
+/**
+ * Optional on-chain reconciliation. Given a tx receipt's logs, the signed
+ * amount the payee was supposed to receive must equal the USDC Transfer to payee.
+ *
+ * The amount and payee come from JWS claims only after a key-trust check
+ * (JWKS by kid, or an embedded key whose thumbprint is a pinned kid). An
+ * untrusted signature does not contribute those facts.
+ *
+ * v8 compares `settled_amount` (falling back to `gross_amount`): that is the
+ * on-chain transfer. v7 and earlier compare `net_amount`, which those receipts
+ * defined as "amount after fees". A single direct transfer of gross will not
+ * match a net that subtracts a fee that never moved on chain.
+ */
+function reconcileSettledTransfer(receipt, logs, options = {}) {
+    const trusted = trustedPaymentForReconcile(receipt, options);
+    if (!trusted.ok) {
+        return {
+            checked: false,
+            matches: false,
+            payload_version: trusted.version,
+            signed_field: null,
+            signed_amount: null,
+            transfer_amount: null,
+            payee: null,
+            reason: trusted.reason,
+        };
+    }
+    const { version, payment } = trusted;
+    const payee = payment.payee ?? null;
+    let signed_field = null;
+    let signed_amount = null;
+    if (version >= 8) {
+        if (payment.settled_amount != null && payment.settled_amount !== '') {
+            signed_field = 'settled_amount';
+            signed_amount = String(payment.settled_amount);
+        }
+        else if (payment.gross_amount != null && payment.gross_amount !== '') {
+            signed_field = 'gross_amount';
+            signed_amount = String(payment.gross_amount);
+        }
+    }
+    else {
+        signed_field = 'net_amount';
+        signed_amount = payment.net_amount != null ? String(payment.net_amount) : null;
+    }
+    if (!payee || !(0, base_payer_js_1.isEvmAddress)(payee)) {
+        return {
+            checked: false,
+            matches: false,
+            payload_version: version,
+            signed_field,
+            signed_amount,
+            transfer_amount: null,
+            payee,
+            reason: 'no_payee',
+        };
+    }
+    if (signed_amount == null) {
+        return {
+            checked: false,
+            matches: false,
+            payload_version: version,
+            signed_field,
+            signed_amount,
+            transfer_amount: null,
+            payee,
+            reason: 'no_signed_amount',
+        };
+    }
+    const transfer = sumUsdcTransfersToPayee(logs, payee, options.usdcAddress);
+    if (transfer == null) {
+        return {
+            checked: true,
+            matches: false,
+            payload_version: version,
+            signed_field,
+            signed_amount,
+            transfer_amount: null,
+            payee,
+            reason: 'no_transfer_to_payee',
+        };
+    }
+    const matches = BigInt(signed_amount) === transfer;
+    return {
+        checked: true,
+        matches,
+        payload_version: version,
+        signed_field,
+        signed_amount,
+        transfer_amount: transfer.toString(),
+        payee,
+        reason: matches
+            ? undefined
+            : `amount_mismatch: signed ${signed_field} ${signed_amount} !== transfer ${transfer.toString()}`,
+    };
 }
 /**
  * Verify a receipt's ES256 issuer signature against a JWK (public key).
@@ -146,59 +348,122 @@ function verifyIssuerSignature(receipt, jwk) {
  * @param receipt - Receipt JSON with issuer_signature
  * @param jwks - JWKS with keys array
  */
-function verifyIssuerSignatureWithJwks(receipt, jwks) {
+function jwksCandidates(jwks, kid) {
+    const keys = jwks?.keys || [];
+    const es256 = keys.filter((k) => (0, jws_js_1.isEs256PublicJwk)(k) && (k.alg == null || k.alg === 'ES256'));
+    if (!kid)
+        return es256;
+    return es256.filter((k) => k.kid === kid);
+}
+/**
+ * Verify an issuer signature against trusted keys only.
+ *
+ * Trust, in order:
+ *   1. A JWKS entry matched by `kid` (supplied file or fetched issuer JWKS).
+ *   2. An embedded `issuer_jwk` whose RFC 7638 thumbprint equals a pinned trusted kid.
+ *
+ * An embedded key that merely verifies the bytes is `key untrusted`.
+ */
+function verifyIssuerSignatureWithJwks(receipt, jwks, options = {}) {
     const sig = receipt.issuer_signature;
     if (!sig) {
-        return { checked: false, valid: false, reason: 'no_issuer_signature' };
-    }
-    const pinned = (0, jws_js_1.resolvePinnedIssuerJwk)(receipt);
-    if (pinned && sig.jws) {
-        const jwsResult = (0, jws_js_1.verifyIssuerJws)(sig.jws, pinned);
-        return {
-            checked: true,
-            valid: jwsResult.valid,
-            kid: pinned.kid || sig.kid,
-            reason: jwsResult.reason,
-        };
+        return { checked: false, valid: false, key_trusted: false, reason: 'no_issuer_signature' };
     }
+    const trustedKids = options.trustedKids ?? jws_js_1.DEFAULT_TRUSTED_ISSUER_KIDS;
+    const header = sig.jws ? (0, jws_js_1.readJwsHeader)(sig.jws) : null;
+    const kid = header?.kid || sig.kid;
+    const embedded = (0, jws_js_1.resolvePinnedIssuerJwk)(receipt);
+    const pinned = !!(embedded && (0, jws_js_1.isPinnedTrustedJwk)(embedded, trustedKids));
     if (sig.jws) {
-        if (!jwks || !Array.isArray(jwks.keys) || jwks.keys.length === 0) {
-            return { checked: false, valid: false, reason: 'empty_jwks' };
-        }
-        const candidates = sig.kid
-            ? jwks.keys.filter(k => k.kid === sig.kid && k.alg === 'ES256')
-            : jwks.keys.filter(k => k.alg === 'ES256');
-        if (candidates.length === 0) {
-            return { checked: false, valid: false, reason: 'no_matching_key' };
-        }
-        for (const jwk of candidates) {
+        const fromJwks = jwksCandidates(jwks, kid);
+        for (const jwk of fromJwks) {
             const jwsResult = (0, jws_js_1.verifyIssuerJws)(sig.jws, jwk);
             if (jwsResult.valid) {
-                return { checked: true, valid: true, kid: jwk.kid || sig.kid };
+                return {
+                    checked: true,
+                    valid: true,
+                    key_trusted: true,
+                    trust: 'jwks',
+                    kid: jwk.kid || kid,
+                    payload: jwsResult.payload,
+                };
+            }
+        }
+        if (pinned && embedded) {
+            const pinResult = (0, jws_js_1.verifyIssuerJws)(sig.jws, embedded);
+            if (pinResult.valid) {
+                return {
+                    checked: true,
+                    valid: true,
+                    key_trusted: true,
+                    trust: 'pinned_kid',
+                    kid: embedded.kid || (0, jws_js_1.jwkThumbprint)(embedded),
+                    payload: pinResult.payload,
+                };
             }
+            return {
+                checked: true,
+                valid: false,
+                key_trusted: true,
+                kid: kid || embedded.kid,
+                reason: pinResult.reason || 'signature_invalid',
+            };
+        }
+        if (embedded && (0, jws_js_1.verifyIssuerJws)(sig.jws, embedded).valid) {
+            return {
+                checked: true,
+                valid: false,
+                key_trusted: false,
+                kid: embedded.kid || kid,
+                reason: jws_js_1.KEY_UNTRUSTED,
+            };
+        }
+        if (fromJwks.length === 0 && !pinned) {
+            return {
+                checked: true,
+                valid: false,
+                key_trusted: false,
+                kid,
+                reason: jws_js_1.KEY_UNTRUSTED,
+            };
         }
-        return { checked: true, valid: false, reason: 'signature_invalid' };
+        return {
+            checked: true,
+            valid: false,
+            key_trusted: fromJwks.length > 0 || pinned,
+            kid,
+            reason: 'signature_invalid',
+        };
     }
     if (!sig.value) {
-        return { checked: false, valid: false, reason: 'no_issuer_signature' };
+        return { checked: false, valid: false, key_trusted: false, reason: 'no_issuer_signature' };
+    }
+    if (!jwks || !Array.isArray(jwks.keys)) {
+        return {
+            checked: false,
+            valid: false,
+            key_trusted: false,
+            kid: sig.kid,
+            reason: 'JWKS not provided — pass jwks option to verify issuer signature',
+        };
     }
-    if (!jwks || !Array.isArray(jwks.keys) || jwks.keys.length === 0) {
-        return { checked: false, valid: false, reason: 'empty_jwks' };
+    if (jwks.keys.length === 0) {
+        return { checked: false, valid: false, key_trusted: false, kid: sig.kid, reason: 'empty_jwks' };
     }
     // Find matching key by kid, or try all ES256 keys if no kid on signature
     const candidates = sig.kid
         ? jwks.keys.filter(k => k.kid === sig.kid && k.alg === 'ES256')
         : jwks.keys.filter(k => k.alg === 'ES256');
     if (candidates.length === 0) {
-        return { checked: false, valid: false, reason: 'no_matching_key' };
+        return { checked: false, valid: false, key_trusted: false, kid: sig.kid, reason: 'no_matching_key' };
     }
     for (const jwk of candidates) {
         const result = verifyIssuerSignature(receipt, jwk);
         if (result.valid) {
-            return result;
+            return { ...result, key_trusted: true, trust: 'jwks', kid: jwk.kid || sig.kid };
         }
     }
-    return { checked: true, valid: false, reason: 'signature_invalid' };
+    return { checked: true, valid: false, key_trusted: true, kid: sig.kid, reason: 'signature_invalid' };
 }
 /**
  * Verify a receipt's payment binding locally (no network required).
@@ -206,8 +471,18 @@ function verifyIssuerSignatureWithJwks(receipt, jwks) {
  * This recomputes the commitment from the receipt's fields and compares
  * it to the stored `binding.expected_commitment`.
  */
+function noCommitmentReason(rail) {
+    if (rail === 'unmetered' || rail === 'tfuel') {
+        return 'No binding present on receipt (unmetered or TFUEL rail)';
+    }
+    if (rail === 'usdc' || rail === 'reported') {
+        return 'No payment-binding commitment (expected_commitment is null)';
+    }
+    return 'No binding present on receipt (may be unmetered or TFUEL rail)';
+}
 function verifyBinding(receipt) {
     const binding = receipt.binding;
+    const railHint = binding?.rail || receipt.payment?.rail || null;
     if (!binding) {
         return {
             verified: false,
@@ -215,7 +490,17 @@ function verifyBinding(receipt) {
             recomputed: null,
             matches: false,
             covers: [],
-            reason: 'No binding present on receipt (may be unmetered or TFUEL rail)',
+            reason: noCommitmentReason(railHint),
+        };
+    }
+    if (binding.expected_commitment == null || binding.expected_commitment === '') {
+        return {
+            verified: false,
+            expected: null,
+            recomputed: null,
+            matches: false,
+            covers: binding.covers || [],
+            reason: noCommitmentReason(railHint),
         };
     }
     const paymentRef = receipt.payment?.ref ?? null;
@@ -328,89 +613,341 @@ exports.canonicalSignedPayload = canonicalIssuerPayload;
 function hashCanonicalPayload(receipt) {
     return (0, ethers_1.keccak256)((0, ethers_1.toUtf8Bytes)((0, exports.canonicalSignedPayload)(receipt)));
 }
+function claimString(value) {
+    if (value == null || value === '')
+        return null;
+    return String(value);
+}
+function asRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    return value;
+}
+function normFact(value, address = false) {
+    const text = claimString(value);
+    if (text == null)
+        return null;
+    return address ? text.toLowerCase() : text;
+}
 /**
- * Full receipt verification — binding + issuer signature + optional nullifier check.
+ * Fields a verifier may quote. Compared only when both the unsigned outer
+ * copy and the JWS payload carry a value.
+ */
+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: '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)),
+        });
+    }
+    return mismatches;
+}
+function receiptViewFromClaims(receipt, claims) {
+    const payment = asRecord(claims.payment);
+    const binding = asRecord(claims.binding);
+    const route = asRecord(claims.route);
+    const output = asRecord(claims.output);
+    const caller = asRecord(claims.caller_binding);
+    const modelCommitment = claimString(route?.model_commitment);
+    return {
+        ...receipt,
+        task_id: claimString(claims.task_id) || receipt.task_id,
+        payment: {
+            rail: claimString(payment?.rail) ?? undefined,
+            ref: claimString(payment?.ref),
+            gross_amount: claimString(payment?.gross_amount),
+            settled_amount: claimString(payment?.settled_amount),
+            net_amount: claimString(payment?.net_amount),
+            asset: claimString(payment?.asset),
+            payee: claimString(payment?.payee),
+            fee_amount: claimString(payment?.fee_amount),
+            protocol_fee_bps: typeof payment?.protocol_fee_bps === 'number' ? payment.protocol_fee_bps : null,
+            platform_fee: claimString(payment?.platform_fee),
+            platform_fee_bps: typeof payment?.platform_fee_bps === 'number' ? payment.platform_fee_bps : null,
+        },
+        route: {
+            model: claimString(route?.model) ?? undefined,
+            provider: claimString(route?.provider) ?? undefined,
+            model_commitment: modelCommitment ? { commitment: modelCommitment } : null,
+        },
+        output: output?.hash ? { hash: claimString(output.hash) ?? undefined } : null,
+        caller_binding: caller
+            ? {
+                payer_wallet: claimString(caller.payer_wallet),
+                agent_pubkey: claimString(caller.agent_pubkey),
+                api_key_hash: claimString(caller.api_key_hash),
+            }
+            : null,
+        provider_cogs: asRecord(claims.provider_cogs)?.actual != null
+            ? { actual: claimString(asRecord(claims.provider_cogs)?.actual) ?? undefined }
+            : receipt.provider_cogs,
+        binding: {
+            expected_commitment: binding && 'expected_commitment' in binding
+                ? (claimString(binding.expected_commitment) ?? undefined)
+                : undefined,
+            amount: claimString(binding?.amount)
+                || claimString(payment?.net_amount)
+                || claimString(payment?.gross_amount)
+                || '0',
+            rail: claimString(binding?.rail) || claimString(payment?.rail) || undefined,
+            covers: Array.isArray(binding?.covers) ? binding.covers : ['payment', 'settlement'],
+            model_commitment: claimString(binding?.model_commitment) || modelCommitment,
+            output_hash: claimString(binding?.output_hash) || claimString(output?.hash),
+        },
+    };
+}
+function payerClaimsFromPayload(payload) {
+    const payment = asRecord(payload.payment);
+    const caller = asRecord(payload.caller_binding);
+    return {
+        payment: {
+            ref: claimString(payment?.ref),
+            gross_amount: claimString(payment?.gross_amount),
+            payee: claimString(payment?.payee),
+            asset: claimString(payment?.asset),
+            rail: claimString(payment?.rail),
+        },
+        caller_binding: caller ? { payer_wallet: claimString(caller.payer_wallet) } : null,
+    };
+}
+function factsFromClaims(claims) {
+    if (!claims) {
+        return { hub: null, model: null, amount_usdc: null, tx: null, output_hash: null };
+    }
+    const payment = asRecord(claims.payment);
+    const route = asRecord(claims.route);
+    const output = asRecord(claims.output);
+    return {
+        hub: claimString(route?.provider),
+        model: claimString(route?.model),
+        amount_usdc: claimString(payment?.gross_amount),
+        tx: claimString(payment?.ref),
+        output_hash: claimString(output?.hash),
+    };
+}
+function issuerJwksUri(receipt) {
+    const fromVerification = receipt.verification?.jwks_uri;
+    if (typeof fromVerification === 'string' && fromVerification.startsWith('https://'))
+        return fromVerification;
+    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;
+    return null;
+}
+function httpsUrl(uri) {
+    try {
+        return new URL(uri).protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+function mergeJwks(primary, extra) {
+    const keys = [...(primary?.keys || []), ...(extra?.keys || [])];
+    if (keys.length === 0)
+        return undefined;
+    const seen = new Set();
+    const deduped = [];
+    for (const key of keys) {
+        const id = `${key.kid || ''}:${key.x || ''}:${key.y || ''}`;
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        deduped.push(key);
+    }
+    return { keys: deduped };
+}
+/** Fetch a JWKS document. Caller decides whether the URL is a trust root. */
+async function fetchIssuerJwks(uri, fetchImpl = globalThis.fetch) {
+    if (!httpsUrl(uri))
+        throw new Error('jwks_uri must be https');
+    const res = await fetchImpl(uri);
+    if (!res.ok)
+        throw new Error(`jwks_fetch_failed: ${res.status}`);
+    const body = await res.json();
+    if (!body || !Array.isArray(body.keys))
+        throw new Error('jwks_malformed');
+    return body;
+}
+/**
+ * Full receipt verification — trusted issuer signature, signed-claim facts,
+ * optional on-chain payer and nullifier checks.
  *
- * @param receipt The Chit402 receipt JSON
- * @param options.jwks JWKS for issuer signature verification (no network fetch)
- * @param options.checkNullifier Whether to verify nullifier on-chain (requires network)
- * @param options.rpcUrl RPC URL for on-chain checks
+ * Facts (amount, payer, payee, asset, tx, model) are taken only from a JWS
+ * that verified under a trusted key. The embedded `issuer_jwk` is not trusted
+ * unless its RFC 7638 thumbprint is a pinned kid, or the same key is in a JWKS.
  */
-/** Extract JWS claims for payer binding when present. */
+/** Extract JWS claims for payer binding. Prefers the JWS payload over the outer copy. */
 function receiptPayerClaims(receipt) {
     return (0, payer_js_1.receiptPayerClaimsFromEnvelope)(receipt);
 }
 async function verifyReceipt(receipt, options = {}) {
     const errors = [];
-    // Verify binding locally
-    const binding = verifyBinding(receipt);
-    if (!binding.matches && binding.expected) {
-        errors.push('Payment binding mismatch');
-    }
-    // Verify issuer signature — pinned JWK in receipt, optional JWKS file, or legacy detached sig
-    let issuer_signature;
-    const pinned = (0, jws_js_1.resolvePinnedIssuerJwk)(receipt);
-    if (pinned && receipt.issuer_signature?.jws) {
-        const jwsResult = (0, jws_js_1.verifyIssuerJws)(receipt.issuer_signature.jws, pinned);
-        issuer_signature = {
-            checked: true,
-            valid: jwsResult.valid,
-            kid: pinned.kid || receipt.issuer_signature.kid,
-            reason: jwsResult.reason,
-        };
-        if (!jwsResult.valid) {
-            errors.push(`Issuer signature invalid: ${jwsResult.reason}`);
+    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}`);
         }
     }
-    else if (options.jwks) {
-        issuer_signature = verifyIssuerSignatureWithJwks(receipt, options.jwks);
+    let issuer_signature;
+    if (receipt.issuer_signature?.jws || receipt.issuer_signature?.value) {
+        issuer_signature = verifyIssuerSignatureWithJwks(receipt, jwks, { trustedKids });
         if (issuer_signature.checked && !issuer_signature.valid) {
-            errors.push(`Issuer signature invalid: ${issuer_signature.reason}`);
+            errors.push(issuer_signature.reason === jws_js_1.KEY_UNTRUSTED
+                ? jws_js_1.KEY_UNTRUSTED
+                : `Issuer signature invalid: ${issuer_signature.reason}`);
         }
     }
     else if (receipt.issuer_signature) {
         issuer_signature = {
             checked: false,
             valid: false,
+            key_trusted: false,
             kid: receipt.issuer_signature.kid,
-            reason: receipt.issuer_signature.jws
-                ? 'No pinned issuer_jwk and JWKS not provided — pass jwks option or use a receipt with issuer_signature.issuer_jwk'
-                : 'JWKS not provided — pass jwks option to verify issuer signature',
+            reason: 'JWKS not provided — pass jwks option to verify issuer signature',
         };
     }
     else {
         issuer_signature = {
             checked: false,
             valid: false,
+            key_trusted: false,
             reason: 'No issuer signature present on receipt',
         };
     }
-    // Verify payer on-chain when requested (Base USDC or Solana USDC)
+    const decoded = receipt.issuer_signature?.jws
+        ? (0, payer_js_1.decodeJwsPayload)(receipt.issuer_signature.jws)
+        : null;
+    const claim_mismatches = diffOuterClaims(receipt, decoded);
+    for (const mismatch of claim_mismatches) {
+        errors.push(`outer/signed mismatch: ${mismatch.field} (outer ${mismatch.outer}, signed ${mismatch.signed})`);
+    }
+    const verifiedClaims = issuer_signature.valid ? issuer_signature.payload : undefined;
+    let binding;
+    if (receipt.issuer_signature?.jws) {
+        if (verifiedClaims) {
+            binding = verifyBinding(receiptViewFromClaims(receipt, verifiedClaims));
+        }
+        else {
+            binding = {
+                verified: false,
+                expected: null,
+                recomputed: null,
+                matches: false,
+                covers: [],
+                reason: issuer_signature.reason === jws_js_1.KEY_UNTRUSTED
+                    ? 'Binding not checked — issuer key untrusted'
+                    : 'Binding not checked — issuer signature not verified',
+            };
+        }
+    }
+    else {
+        binding = verifyBinding(receipt);
+    }
+    if (!binding.matches && binding.expected) {
+        errors.push('Payment binding mismatch');
+    }
+    const signedPayerClaims = verifiedClaims ? payerClaimsFromPayload(verifiedClaims) : null;
     let payer;
     if (options.checkPayer) {
-        const payerResult = await (0, payer_js_1.verifyPayerBinding)(receiptPayerClaims(receipt), {
-            rpcUrl: options.rpcUrl,
-            solanaRpcUrl: options.solanaRpcUrl,
-            fetchSolanaTransaction: options.fetchSolanaTransaction,
-            fetchBaseReceipt: options.fetchBaseReceipt,
-        });
+        if (!signedPayerClaims) {
+            payer = {
+                checked: false,
+                valid: false,
+                reason: 'Payer facts come from verified signed claims — issuer signature is not trusted',
+            };
+        }
+        else {
+            const payerResult = await (0, payer_js_1.verifyPayerBinding)(signedPayerClaims, {
+                rpcUrl: options.rpcUrl,
+                solanaRpcUrl: options.solanaRpcUrl,
+                fetchSolanaTransaction: options.fetchSolanaTransaction,
+                fetchBaseReceipt: options.fetchBaseReceipt,
+            });
+            payer = {
+                checked: payerResult.checked,
+                valid: payerResult.valid,
+                rail: payerResult.rail,
+                reason: payerResult.reason,
+                payer_wallet: payerResult.payerWallet ?? signedPayerClaims.caller_binding?.payer_wallet ?? null,
+                payee: signedPayerClaims.payment?.payee ?? null,
+                asset: signedPayerClaims.payment?.asset ?? null,
+                amount: payerResult.expectedAmount ?? signedPayerClaims.payment?.gross_amount ?? null,
+            };
+            if (payerResult.checked && !payerResult.valid) {
+                errors.push(`Payer binding mismatch: ${payerResult.reason}`);
+            }
+        }
+    }
+    else if (signedPayerClaims?.caller_binding?.payer_wallet && signedPayerClaims.payment?.ref) {
         payer = {
-            checked: payerResult.checked,
-            valid: payerResult.valid,
-            rail: payerResult.rail,
-            reason: payerResult.reason,
+            checked: false,
+            valid: false,
+            payer_wallet: signedPayerClaims.caller_binding.payer_wallet,
+            payee: signedPayerClaims.payment.payee ?? null,
+            asset: signedPayerClaims.payment.asset ?? null,
+            amount: signedPayerClaims.payment.gross_amount ?? null,
+            reason: 'On-chain payer check not requested — pass checkPayer: true',
         };
-        if (payerResult.checked && !payerResult.valid) {
-            errors.push(`Payer binding mismatch: ${payerResult.reason}`);
-        }
     }
-    else if (receipt.caller_binding?.payer_wallet && receipt.payment?.ref) {
+    else if (!receipt.issuer_signature?.jws && receipt.caller_binding?.payer_wallet && receipt.payment?.ref) {
         payer = {
             checked: false,
             valid: false,
             reason: 'On-chain payer check not requested — pass checkPayer: true',
         };
     }
+    else if (receipt.issuer_signature?.jws && !issuer_signature.valid) {
+        payer = {
+            checked: false,
+            valid: false,
+            reason: 'Payer facts come from verified signed claims — issuer signature is not trusted',
+        };
+    }
     else {
         payer = {
             checked: false,
@@ -418,7 +955,6 @@ async function verifyReceipt(receipt, options = {}) {
             reason: 'No payer_wallet or payment.ref to verify',
         };
     }
-    // Verify nullifier on-chain if requested
     let nullifier;
     if (options.checkNullifier && receipt.proof?.nullifier) {
         nullifier = await verifyNullifier(receipt, {
@@ -439,52 +975,39 @@ async function verifyReceipt(receipt, options = {}) {
                 : 'On-chain check not requested',
         };
     }
-    // Extract frozen fields
-    const hub = receipt.route?.provider ?? null;
-    const model = receipt.route?.model ?? null;
-    const amount_usdc = receipt.payment?.gross_amount ?? null;
-    const tx = receipt.payment?.ref ?? null;
-    const output_hash = receipt.output?.hash ?? null;
-    // Determine overall status with strict signature semantics:
-    // - If JWKS provided and signature invalid/kid mismatch/no matching key → 'failed'
-    // - If receipt has issuer_signature but no JWKS provided → 'partial' (cannot verify)
-    // - Unsigned receipts can be 'partial' or 'verified' based on binding
-    let overall;
-    // Check for signature verification failure (JWKS provided but signature invalid)
-    const jwksProvided = !!options.jwks;
+    const facts = factsFromClaims(verifiedClaims);
     const hasIssuerSig = !!receipt.issuer_signature;
-    const hasPinnedJwk = !!pinned && !!receipt.issuer_signature?.jws;
-    const issuerSigInvalid = (jwksProvided || hasPinnedJwk) && hasIssuerSig && !issuer_signature.valid;
-    // Binding failure
-    const bindingFailed = binding.expected && !binding.matches;
-    const payerFailed = options.checkPayer && payer.checked && !payer.valid;
-    if (issuerSigInvalid || bindingFailed || payerFailed) {
-        // JWKS provided but signature invalid, OR binding mismatch → failed
+    const jwksWasSupplied = !!(options.jwks || options.jwksUri || (options.fetchJwks && jwks));
+    const signatureFailed = hasIssuerSig && !issuer_signature.valid && (!!issuer_signature.checked
+        || jwksWasSupplied
+        || issuer_signature.reason === jws_js_1.KEY_UNTRUSTED
+        || issuer_signature.reason === 'no_matching_key'
+        || issuer_signature.reason === 'empty_jwks');
+    const mismatchFailed = claim_mismatches.length > 0;
+    const bindingFailed = !!(binding.expected && !binding.matches);
+    const payerFailed = !!(options.checkPayer && payer.checked && !payer.valid);
+    const nullifierFailed = !!(options.checkNullifier
+        && receipt.proof?.nullifier
+        && nullifier.anchored === false);
+    const signatureUnchecked = hasIssuerSig && !issuer_signature.checked;
+    let overall;
+    if (signatureFailed || mismatchFailed || bindingFailed || payerFailed || nullifierFailed) {
         overall = 'failed';
     }
-    else if (hasIssuerSig && !jwksProvided && !hasPinnedJwk) {
-        // Receipt has signature but no offline key material → partial
+    else if (signatureUnchecked) {
         overall = 'partial';
     }
-    else if (binding.matches
-        && (!options.checkPayer || payer.valid)
-        && (!options.checkNullifier || nullifier.anchored)) {
-        // Binding matches, signature OK (or no signature), nullifier OK → verified
-        overall = 'verified';
-    }
-    else if (binding.matches
-        || issuer_signature.valid
-        || (options.checkPayer && payer.valid)
-        || (nullifier.verified && nullifier.anchored)) {
-        // At least one check passed → partial
+    else if (!binding.expected && !hasIssuerSig && !options.checkPayer) {
         overall = 'partial';
     }
-    else if (!binding.expected && !receipt.proof?.nullifier && !hasIssuerSig) {
-        // No binding/sig/nullifier to verify (unmetered/demo) → partial
-        overall = 'partial';
+    else if ((binding.matches || !binding.expected)
+        && (!options.checkPayer || payer.valid)
+        && (!options.checkNullifier || !receipt.proof?.nullifier || nullifier.anchored === true)
+        && (issuer_signature.valid || !hasIssuerSig)) {
+        overall = 'verified';
     }
     else {
-        overall = 'failed';
+        overall = 'partial';
     }
     return {
         receipt_id: receipt.task_id,
@@ -492,11 +1015,12 @@ async function verifyReceipt(receipt, options = {}) {
         issuer_signature,
         payer,
         nullifier,
-        output_hash,
-        hub,
-        model,
-        amount_usdc,
-        tx,
+        output_hash: facts.output_hash,
+        hub: facts.hub,
+        model: facts.model,
+        amount_usdc: facts.amount_usdc,
+        tx: facts.tx,
+        claim_mismatches,
         overall,
         errors,
     };
@@ -504,6 +1028,12 @@ async function verifyReceipt(receipt, options = {}) {
 var jws_js_2 = require("./jws.js");
 Object.defineProperty(exports, "resolvePinnedIssuerJwk", { enumerable: true, get: function () { return jws_js_2.resolvePinnedIssuerJwk; } });
 Object.defineProperty(exports, "verifyIssuerJws", { enumerable: true, get: function () { return jws_js_2.verifyIssuerJws; } });
+Object.defineProperty(exports, "DEFAULT_TRUSTED_ISSUER_KIDS", { enumerable: true, get: function () { return jws_js_2.DEFAULT_TRUSTED_ISSUER_KIDS; } });
+Object.defineProperty(exports, "DEFAULT_TRUSTED_JWKS_HOSTS", { enumerable: true, get: function () { return jws_js_2.DEFAULT_TRUSTED_JWKS_HOSTS; } });
+Object.defineProperty(exports, "KEY_UNTRUSTED", { enumerable: true, get: function () { return jws_js_2.KEY_UNTRUSTED; } });
+Object.defineProperty(exports, "jwkThumbprint", { enumerable: true, get: function () { return jws_js_2.jwkThumbprint; } });
+Object.defineProperty(exports, "isPinnedTrustedJwk", { enumerable: true, get: function () { return jws_js_2.isPinnedTrustedJwk; } });
+Object.defineProperty(exports, "jwksHostAllowed", { enumerable: true, get: function () { return jws_js_2.jwksHostAllowed; } });
 exports.default = {
     verifyBinding,
     verifyIssuerSignature,
@@ -521,7 +1051,10 @@ exports.default = {
     computePaymentCommitment: binding_js_1.computePaymentCommitment,
     computeInferenceBinding: binding_js_1.computeInferenceBinding,
     canonicalIssuerPayload,
+    canonicalPayloadVersion,
     canonicalSignedPayload: exports.canonicalSignedPayload,
+    reconcileSettledTransfer,
+    sumUsdcTransfersToPayee,
     hashCanonicalPayload,
     ZK_VERIFIER_ADDRESS: exports.ZK_VERIFIER_ADDRESS,
     BASE_RPC_URL: base_payer_js_1.BASE_RPC_URL,