@agent-score/commerce 2.6.3 → 2.6.4

package/dist/{network_kind-BIJM2peR.d.ts → network_kind-BmbWKNud.d.ts}

@@ -34,6 +34,28 @@ declare function hasX402Header(input: Request | HeadersLike): boolean;
 /** True when the request carries an mppx payment credential
  *  (`Authorization: Payment <jwt>`). Use to dispatch to the MPP settle path. */
 declare function hasMppxHeader(input: Request | HeadersLike): boolean;
+interface MalformedPaymentCredential {
+    /** Which credential channel carried the malformed value. */
+    channel: 'x402' | 'mpp';
+    message: string;
+}
+/**
+ * Wire-shape gate for payment credentials, cheap enough to run before any
+ * merchant hook. A request whose payment header cannot possibly be a
+ * credential (not base64/base64url JSON, not a JWT-shaped token) is rejected
+ * up front, so junk headers never trigger per-request hooks (`preValidate`,
+ * pricing, recipient minting) or the identity-gate API call.
+ *
+ * This is deliberately a SHAPE check only. Signature verification, payTo
+ * binding, and challenge validation stay where they are (the x402 validator
+ * and the mppx settle path) — those need per-request state the hooks produce.
+ * A well-formed-but-invalid credential still reaches the real validators and
+ * fails there.
+ *
+ * Returns `null` when every present credential channel is plausibly shaped
+ * (or no payment header is present).
+ */
+declare function malformedPaymentCredential(input: Request | HeadersLike): MalformedPaymentCredential | null;
 
 /**
  * USD ↔ atomic-unit conversion for token amounts.
@@ -209,4 +231,4 @@ declare function isEvmNetwork(input: NetworkLike): boolean;
  *  network spec — this helper treats it as false. */
 declare function isSolanaNetwork(input: NetworkLike): boolean;
 
-export { type BuildDefaultCheckoutRailsOptions as B, type HeadersLike as H, type BuildMppxComposeRailsOptions as a, asHeaders as b, buildDefaultCheckoutRails as c, buildMppxComposeRails as d, hasPaymentHeader as e, formatUsdCents as f, hasX402Header as g, hasMppxHeader as h, isEvmNetwork as i, isSolanaNetwork as j, loadSolanaFeePayer as l, readHeader as r, usdToAtomic as u };
+export { type BuildDefaultCheckoutRailsOptions as B, type HeadersLike as H, type MalformedPaymentCredential as M, type BuildMppxComposeRailsOptions as a, asHeaders as b, buildDefaultCheckoutRails as c, buildMppxComposeRails as d, hasPaymentHeader as e, formatUsdCents as f, hasX402Header as g, hasMppxHeader as h, isEvmNetwork as i, isSolanaNetwork as j, loadSolanaFeePayer as l, malformedPaymentCredential as m, readHeader as r, usdToAtomic as u };

package/dist/{network_kind-C0EMkdzz.d.mts → network_kind-D2xpo2Fj.d.mts}

@@ -34,6 +34,28 @@ declare function hasX402Header(input: Request | HeadersLike): boolean;
 /** True when the request carries an mppx payment credential
  *  (`Authorization: Payment <jwt>`). Use to dispatch to the MPP settle path. */
 declare function hasMppxHeader(input: Request | HeadersLike): boolean;
+interface MalformedPaymentCredential {
+    /** Which credential channel carried the malformed value. */
+    channel: 'x402' | 'mpp';
+    message: string;
+}
+/**
+ * Wire-shape gate for payment credentials, cheap enough to run before any
+ * merchant hook. A request whose payment header cannot possibly be a
+ * credential (not base64/base64url JSON, not a JWT-shaped token) is rejected
+ * up front, so junk headers never trigger per-request hooks (`preValidate`,
+ * pricing, recipient minting) or the identity-gate API call.
+ *
+ * This is deliberately a SHAPE check only. Signature verification, payTo
+ * binding, and challenge validation stay where they are (the x402 validator
+ * and the mppx settle path) — those need per-request state the hooks produce.
+ * A well-formed-but-invalid credential still reaches the real validators and
+ * fails there.
+ *
+ * Returns `null` when every present credential channel is plausibly shaped
+ * (or no payment header is present).
+ */
+declare function malformedPaymentCredential(input: Request | HeadersLike): MalformedPaymentCredential | null;
 
 /**
  * USD ↔ atomic-unit conversion for token amounts.
@@ -209,4 +231,4 @@ declare function isEvmNetwork(input: NetworkLike): boolean;
  *  network spec — this helper treats it as false. */
 declare function isSolanaNetwork(input: NetworkLike): boolean;
 
-export { type BuildDefaultCheckoutRailsOptions as B, type HeadersLike as H, type BuildMppxComposeRailsOptions as a, asHeaders as b, buildDefaultCheckoutRails as c, buildMppxComposeRails as d, hasPaymentHeader as e, formatUsdCents as f, hasX402Header as g, hasMppxHeader as h, isEvmNetwork as i, isSolanaNetwork as j, loadSolanaFeePayer as l, readHeader as r, usdToAtomic as u };
+export { type BuildDefaultCheckoutRailsOptions as B, type HeadersLike as H, type MalformedPaymentCredential as M, type BuildMppxComposeRailsOptions as a, asHeaders as b, buildDefaultCheckoutRails as c, buildMppxComposeRails as d, hasPaymentHeader as e, formatUsdCents as f, hasX402Header as g, hasMppxHeader as h, isEvmNetwork as i, isSolanaNetwork as j, loadSolanaFeePayer as l, malformedPaymentCredential as m, readHeader as r, usdToAtomic as u };

package/dist/payment/index.d.mts

@@ -5,7 +5,7 @@ export { B as BuildX402AcceptsForOptions, C as CreateX402ServerOptions, X as X40
 export { a as aliasAmountFields, p as paymentRequiredHeader, w as wwwAuthenticateHeader } from '../wwwauthenticate-Dgm-_af9.mjs';
 import { S as SignerNetwork } from '../signer-3FAit11j.mjs';
 export { P as PaymentSigner, e as extractPaymentSigner, a as extractPaymentSignerFromAuth, b as extractSignerForPrecheck, r as readX402PaymentHeader } from '../signer-3FAit11j.mjs';
-export { B as BuildDefaultCheckoutRailsOptions, a as BuildMppxComposeRailsOptions, H as HeadersLike, b as asHeaders, c as buildDefaultCheckoutRails, d as buildMppxComposeRails, f as formatUsdCents, h as hasMppxHeader, e as hasPaymentHeader, g as hasX402Header, i as isEvmNetwork, j as isSolanaNetwork, l as loadSolanaFeePayer, r as readHeader, u as usdToAtomic } from '../network_kind-C0EMkdzz.mjs';
+export { B as BuildDefaultCheckoutRailsOptions, a as BuildMppxComposeRailsOptions, H as HeadersLike, M as MalformedPaymentCredential, b as asHeaders, c as buildDefaultCheckoutRails, d as buildMppxComposeRails, f as formatUsdCents, h as hasMppxHeader, e as hasPaymentHeader, g as hasX402Header, i as isEvmNetwork, j as isSolanaNetwork, l as loadSolanaFeePayer, m as malformedPaymentCredential, r as readHeader, u as usdToAtomic } from '../network_kind-D2xpo2Fj.mjs';
 
 /**
  * Build the base64-encoded `request` blob for an MPP Payment directive (per the
@@ -786,25 +786,32 @@ declare function settlementOverrideHeader(overrides: SettlementOverrides): {
 };
 
 /**
- * Zero-amount carve-out: skip upstream verify+settle for $0 orders.
- *
- * CDP rejects EIP-3009 `transferWithAuthorization` with `value=0` as
- * `invalid_payload`; `mppx`'s tempo intents accept only `hash` and
- * `transaction` payload types (rejecting the `proof` payload that gets
- * emitted for $0 settles). Both upstream verify+settle paths fail when the
- * authorized amount is zero, so merchants that drop the settle to $0 in a
- * redemption-code flow need a way to skip verify+settle entirely while
- * still recovering the signer for wallet-capture attribution.
- *
- * `zeroAmountCarveOut` is that path: parse the credential, lift the
- * signer, return `{ signerAddress, signerNetwork, txHash: null }`. Identity
- * is still authenticated by the merchant's gate above; the redemption code
- * is single-use; nothing on-chain to verify.
- *
- * The MPP path uses inline base64+JSON parsing (no `mppx` dependency at
- * runtime) so the zero-settle path stays dependency-free. The full
- * `extractPaymentSigner` path is still mppx-backed for production traffic
- * where the credential is a real mppx-shaped object.
+ * Zero-amount carve-out: skip upstream verify+settle for $0 orders on the
+ * rails that cannot settle $0 upstream.
+ *
+ * Scope (which rail takes the carve-out is decided in `Checkout.handleZeroSettle`):
+ *
+ * - **x402 Base**: CDP rejects EIP-3009 `transferWithAuthorization` with
+ *   `value=0` as `invalid_payload`, so $0 x402 orders take the carve-out. The
+ *   credential is still run through `verifyX402Request` (signature shape +
+ *   payTo binding) before the carve-out is honored.
+ * - **Tempo (and other EVM MPP)**: NOT carved out. mppx >= 0.8 settles
+ *   zero-amount challenges natively via the wallet-bound EIP-712 proof
+ *   credential (full verification, access-key authorization, replay
+ *   protection), so $0 Tempo orders flow through the normal MPP settle path.
+ * - **Solana MPP**: `@solana/mpp` has no proof-credential contract, so there
+ *   is nothing upstream to verify a $0 credential against. The carve-out
+ *   parses the credential and lifts the signer for wallet-capture
+ *   attribution; that signer block is UNAUTHENTICATED (parse-only) and must
+ *   not be trusted for anything beyond attribution hints. Identity is still
+ *   authenticated by the merchant's gate above; redemption codes are
+ *   single-use; nothing settles on-chain.
+ *
+ * `zeroAmountCarveOut` parses the credential, lifts the signer, and returns
+ * `{ signerAddress, signerNetwork, txHash: null }`. The MPP path uses inline
+ * base64+JSON parsing (no `mppx` dependency at runtime) so this module stays
+ * dependency-free; it is also how `handleZeroSettle` classifies the rail
+ * (Solana vs EVM did:pkh source) to decide carve-out vs delegation.
  */
 
 type ZeroSettleRail = 'x402-base' | 'tempo' | 'solana';

package/dist/payment/index.d.ts

@@ -5,7 +5,7 @@ export { B as BuildX402AcceptsForOptions, C as CreateX402ServerOptions, X as X40
 export { a as aliasAmountFields, p as paymentRequiredHeader, w as wwwAuthenticateHeader } from '../wwwauthenticate-Dgm-_af9.js';
 import { S as SignerNetwork } from '../signer-3FAit11j.js';
 export { P as PaymentSigner, e as extractPaymentSigner, a as extractPaymentSignerFromAuth, b as extractSignerForPrecheck, r as readX402PaymentHeader } from '../signer-3FAit11j.js';
-export { B as BuildDefaultCheckoutRailsOptions, a as BuildMppxComposeRailsOptions, H as HeadersLike, b as asHeaders, c as buildDefaultCheckoutRails, d as buildMppxComposeRails, f as formatUsdCents, h as hasMppxHeader, e as hasPaymentHeader, g as hasX402Header, i as isEvmNetwork, j as isSolanaNetwork, l as loadSolanaFeePayer, r as readHeader, u as usdToAtomic } from '../network_kind-BIJM2peR.js';
+export { B as BuildDefaultCheckoutRailsOptions, a as BuildMppxComposeRailsOptions, H as HeadersLike, M as MalformedPaymentCredential, b as asHeaders, c as buildDefaultCheckoutRails, d as buildMppxComposeRails, f as formatUsdCents, h as hasMppxHeader, e as hasPaymentHeader, g as hasX402Header, i as isEvmNetwork, j as isSolanaNetwork, l as loadSolanaFeePayer, m as malformedPaymentCredential, r as readHeader, u as usdToAtomic } from '../network_kind-BmbWKNud.js';
 
 /**
  * Build the base64-encoded `request` blob for an MPP Payment directive (per the
@@ -786,25 +786,32 @@ declare function settlementOverrideHeader(overrides: SettlementOverrides): {
 };
 
 /**
- * Zero-amount carve-out: skip upstream verify+settle for $0 orders.
- *
- * CDP rejects EIP-3009 `transferWithAuthorization` with `value=0` as
- * `invalid_payload`; `mppx`'s tempo intents accept only `hash` and
- * `transaction` payload types (rejecting the `proof` payload that gets
- * emitted for $0 settles). Both upstream verify+settle paths fail when the
- * authorized amount is zero, so merchants that drop the settle to $0 in a
- * redemption-code flow need a way to skip verify+settle entirely while
- * still recovering the signer for wallet-capture attribution.
- *
- * `zeroAmountCarveOut` is that path: parse the credential, lift the
- * signer, return `{ signerAddress, signerNetwork, txHash: null }`. Identity
- * is still authenticated by the merchant's gate above; the redemption code
- * is single-use; nothing on-chain to verify.
- *
- * The MPP path uses inline base64+JSON parsing (no `mppx` dependency at
- * runtime) so the zero-settle path stays dependency-free. The full
- * `extractPaymentSigner` path is still mppx-backed for production traffic
- * where the credential is a real mppx-shaped object.
+ * Zero-amount carve-out: skip upstream verify+settle for $0 orders on the
+ * rails that cannot settle $0 upstream.
+ *
+ * Scope (which rail takes the carve-out is decided in `Checkout.handleZeroSettle`):
+ *
+ * - **x402 Base**: CDP rejects EIP-3009 `transferWithAuthorization` with
+ *   `value=0` as `invalid_payload`, so $0 x402 orders take the carve-out. The
+ *   credential is still run through `verifyX402Request` (signature shape +
+ *   payTo binding) before the carve-out is honored.
+ * - **Tempo (and other EVM MPP)**: NOT carved out. mppx >= 0.8 settles
+ *   zero-amount challenges natively via the wallet-bound EIP-712 proof
+ *   credential (full verification, access-key authorization, replay
+ *   protection), so $0 Tempo orders flow through the normal MPP settle path.
+ * - **Solana MPP**: `@solana/mpp` has no proof-credential contract, so there
+ *   is nothing upstream to verify a $0 credential against. The carve-out
+ *   parses the credential and lifts the signer for wallet-capture
+ *   attribution; that signer block is UNAUTHENTICATED (parse-only) and must
+ *   not be trusted for anything beyond attribution hints. Identity is still
+ *   authenticated by the merchant's gate above; redemption codes are
+ *   single-use; nothing settles on-chain.
+ *
+ * `zeroAmountCarveOut` parses the credential, lifts the signer, and returns
+ * `{ signerAddress, signerNetwork, txHash: null }`. The MPP path uses inline
+ * base64+JSON parsing (no `mppx` dependency at runtime) so this module stays
+ * dependency-free; it is also how `handleZeroSettle` classifies the rail
+ * (Solana vs EVM did:pkh source) to decide carve-out vs delegation.
  */
 
 type ZeroSettleRail = 'x402-base' | 'tempo' | 'solana';

package/dist/payment/index.js

@@ -53,6 +53,7 @@ __export(payment_exports, {
   lazyX402Server: () => lazyX402Server,
   loadSolanaFeePayer: () => loadSolanaFeePayer,
   lookupRail: () => lookupRail,
+  malformedPaymentCredential: () => malformedPaymentCredential,
   mppxChallengeHeaders: () => mppxChallengeHeaders,
   networkFamily: () => networkFamily,
   networks: () => networks,
@@ -1427,6 +1428,39 @@ function hasMppxHeader(input) {
   const headers = asHeaders(input);
   return Boolean(readHeader(headers, "authorization")?.startsWith("Payment "));
 }
+var JWT_SHAPE_RE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+function decodesToJsonObject(token) {
+  try {
+    const parsed = JSON.parse(Buffer.from(token, "base64").toString("utf8"));
+    return typeof parsed === "object" && parsed !== null;
+  } catch {
+    return false;
+  }
+}
+function malformedPaymentCredential(input) {
+  const headers = asHeaders(input);
+  const x402Token = readHeader(headers, "payment-signature") ?? readHeader(headers, "x-payment");
+  if (x402Token !== null && x402Token.length > 0) {
+    if (!decodesToJsonObject(x402Token)) {
+      return {
+        channel: "x402",
+        message: "X-Payment header is not decodable base64 JSON."
+      };
+    }
+    return null;
+  }
+  const auth = readHeader(headers, "authorization");
+  if (auth !== null && auth.startsWith("Payment ")) {
+    const token = auth.slice("Payment ".length).trim();
+    if (token.length === 0 || !decodesToJsonObject(token) && !JWT_SHAPE_RE.test(token)) {
+      return {
+        channel: "mpp",
+        message: "Authorization: Payment credential is neither base64-encoded JSON nor a token-shaped value."
+      };
+    }
+  }
+  return null;
+}
 
 // src/payment/network_kind.ts
 function readNetwork(input) {
@@ -1478,6 +1512,7 @@ function isSolanaNetwork(input) {
   lazyX402Server,
   loadSolanaFeePayer,
   lookupRail,
+  malformedPaymentCredential,
   mppxChallengeHeaders,
   networkFamily,
   networks,