@agent-score/commerce 2.6.2 → 2.6.4

package/dist/index.d.mts

@@ -1,11 +1,11 @@
 import { VerifyWalletSignerResult, DenialReason } from './core.mjs';
 export { AccountVerification, AgentIdentity, AgentMemoryHint, AgentScoreCore, AssessResult, CreateSessionOnMissing, DenialCode, EvaluateOutcome, OperatorVerification, PolicyCheck, PolicyResult, SignerVerdict, buildAgentMemoryHint } from './core.mjs';
 export { P as PaymentSigner, S as SignerNetwork, e as extractPaymentSigner, a as extractPaymentSignerFromAuth, b as extractSignerForPrecheck, r as readX402PaymentHeader } from './signer-3FAit11j.mjs';
-import { q as UCPSigningKey, n as UCPProfile } from './checkout-CzB9f_jf.mjs';
-export { A as AGENTSCORE_UCP_CAPABILITY, a as AgentScoreGatePolicy, C as Checkout, b as CheckoutContext, c as CheckoutGateConfig, d as CheckoutRailSpec, e as CheckoutRequest, f as CheckoutResult, g as ComposeMppxFn, D as DiscoveryProbeConfig, G as GateDenial, I as IsCachedAddressFn, M as MountUcpRoutesOptions, h as MppxComposeOutcome, O as OnSettledFn, P as PreValidateFn, i as PricingFn, j as PricingResult, R as RecipientsFn, k as ReferenceIdFn, l as RunGateFn, S as SettleOutcome, U as UCPCapabilityBinding, m as UCPPaymentHandlerBinding, o as UCPProfileBody, p as UCPServiceBinding, r as buildAipTrustedIssuers, s as buildUCPProfile, t as getIdentityStatus, u as makeMppxComposeHook, v as mppPaymentHandler, w as pricingResult, x as stripeSptPaymentHandler, y as validationEnvelope, z as validationResponseExpress, B as validationResponseFastify, E as validationResponseHono, F as validationResponseNextjs, H as validationResponseWeb, J as x402PaymentHandler } from './checkout-CzB9f_jf.mjs';
+import { q as UCPSigningKey, n as UCPProfile } from './checkout-BtdHSF_w.mjs';
+export { A as AGENTSCORE_UCP_CAPABILITY, a as AgentScoreGatePolicy, C as Checkout, b as CheckoutContext, c as CheckoutGateConfig, d as CheckoutRailSpec, e as CheckoutRequest, f as CheckoutResult, g as ComposeMppxFn, D as DiscoveryProbeConfig, G as GateDenial, I as IsCachedAddressFn, M as MountUcpRoutesOptions, h as MppxComposeOutcome, O as OnSettledFn, P as PreValidateFn, i as PricingFn, j as PricingResult, R as RecipientsFn, k as ReferenceIdFn, l as RunGateFn, S as SettleOutcome, U as UCPCapabilityBinding, m as UCPPaymentHandlerBinding, o as UCPProfileBody, p as UCPServiceBinding, r as buildAipTrustedIssuers, s as buildUCPProfile, t as getIdentityStatus, u as makeMppxComposeHook, v as mppPaymentHandler, w as pricingResult, x as stripeSptPaymentHandler, y as validationEnvelope, z as validationResponseExpress, B as validationResponseFastify, E as validationResponseHono, F as validationResponseNextjs, H as validationResponseWeb, J as x402PaymentHandler } from './checkout-BtdHSF_w.mjs';
 export { EnforcementMode, GateResult, IdentityStatus, PolicyBlock, buildGateFromPolicy, runGateWithEnforcement, shippingCountryAllowed, shippingStateAllowed, validateShippingAgainstPolicy } from './identity/policy.mjs';
-import { H as HeadersLike } from './network_kind-C0EMkdzz.mjs';
-export { 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 } from './network_kind-C0EMkdzz.mjs';
+import { H as HeadersLike } from './network_kind-D2xpo2Fj.mjs';
+export { M as MalformedPaymentCredential, 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 } from './network_kind-D2xpo2Fj.mjs';
 import { T as TempoRailSpec, X as X402BaseRailSpec, S as SolanaMppRailSpec, b as StripeRailSpec } from './rail_spec-BFZmW9RN.mjs';
 export { c as TempoSessionRailSpec } from './rail_spec-BFZmW9RN.mjs';
 import { Context } from 'hono';
@@ -653,21 +653,26 @@ declare class CheckoutValidationError extends Error {
 }
 
 /**
- * Short-TTL body-hash quote cache for the compute-first + exact-x402 pattern
- * (see {@link computeFirstCheckout}).
+ * Short-TTL body-hash caches.
  *
- * Standard x402-fetch retry semantics resign the buyer's ORIGINAL request body
- * — there's no `result_id` echo channel through the protocol. The cache is
- * therefore keyed by a stable content-hash of the request body. Same body →
- * same hash → same cache slot. The probe leg writes (run-work → cache); the
- * settle leg reads (cache hit → settle exact at the cached price → return the
- * cached body).
+ * `createResultCache` is the neutral primitive: a keyed JSON-value cache with
+ * a stable content-hash key builder. Use it to cache any per-request result a
+ * merchant computes on the probe leg and replays on the settle leg — e.g. the
+ * output of a paid upstream call made in a `Checkout.preValidate` hook, so a
+ * payment retry (or a junk payment header) never pays upstream twice.
+ *
+ * `createQuoteCache` is the compute-first-flavored wrapper used by
+ * {@link computeFirstCheckout}: the cached value is a `CachedQuote`
+ * (`{body, priceCents, recipients}`). Standard x402-fetch retry semantics
+ * resign the buyer's ORIGINAL request body — there's no `result_id` echo
+ * channel through the protocol — so both caches key by a stable content-hash
+ * of the request body. Same body → same hash → same cache slot.
  *
  * Default in-memory `Map`; optional `redisUrl` lazy-imports `ioredis` for
  * multi-instance deployments. `ioredis` is an optional peer dep.
  */
-interface QuoteCacheOptions {
-    /** Quote lifetime in milliseconds. Default `5 * 60_000` (5 min). */
+interface ResultCacheOptions {
+    /** Entry lifetime in milliseconds. Default `5 * 60_000` (5 min). */
     ttlMs?: number;
     /** Redis connection URL. Default: `process.env.REDIS_URL`. When unset or the
      *  lazy `ioredis` import fails, falls back to in-process `Map`. */
@@ -675,6 +680,7 @@ interface QuoteCacheOptions {
     /** Per-instance key prefix so multiple caches sharing a Redis don't collide. */
     keyPrefix?: string;
 }
+type QuoteCacheOptions = ResultCacheOptions;
 interface CachedQuote {
     body: Record<string, unknown>;
     priceCents: number;
@@ -683,6 +689,15 @@ interface CachedQuote {
      *  same logical purchase). Empty object when no `mintRecipients` hook is wired. */
     recipients: Record<string, string>;
 }
+interface ResultCache<T> {
+    /** Build a stable content-hash key from a per-merchant prefix and a request body.
+     *  Property order in the body does NOT affect the hash (keys are sorted recursively). */
+    bodyHashKey(prefix: string, body: Record<string, unknown>): string;
+    read(key: string): Promise<T | null>;
+    write(key: string, value: T): Promise<void>;
+    /** Clear all entries. Primarily for tests. */
+    clear(): Promise<void>;
+}
 interface QuoteCache {
     /** Build a stable content-hash key from a per-merchant prefix and a request body.
      *  Property order in the body does NOT affect the hash (keys are sorted recursively). */
@@ -692,8 +707,11 @@ interface QuoteCache {
     /** Clear all entries. Primarily for tests. */
     clear(): Promise<void>;
 }
-/** Build a fresh cache. Each call owns its own state (memory map + Redis
- *  client). */
+/** Build a fresh neutral result cache. Each call owns its own state (memory
+ *  map + Redis client). Values must survive `JSON.stringify` round-trips. */
+declare function createResultCache<T>(opts?: ResultCacheOptions): ResultCache<T>;
+/** Build a fresh compute-first quote cache (a `ResultCache<CachedQuote>` with
+ *  the quote-shaped `write` signature). */
 declare function createQuoteCache(opts?: QuoteCacheOptions): QuoteCache;
 
 /**
@@ -1088,4 +1106,4 @@ declare const buildVerifyContextFromRequest: (req: Request, authority?: string)
 /** True when the request carries an AIP credential (at least one `Agent-Identity` header). */
 declare const hasAgentIdentityHeader: (req: Request) => boolean;
 
-export { type A2AAgentCard, type A2AAgentCardCapabilities, type A2AAgentCardExtension, type A2AAgentCardSignature, type A2AAgentInterface, type A2AAgentProvider, type A2AAgentSkill, A2A_DEFAULT_TRANSPORT, A2A_PROTOCOL_VERSION, AIP_A2A_EXTENSION_URI, AIP_COVERED_COMPONENTS, AIP_SIGNATURE_TAG, type CachedQuote, CheckoutValidationError, type ComputeFirstHandler, type ComputeFirstMintContext, type ComputeFirstMppContext, type ComputeFirstOptions, type ComputeFirstRails, type ComputeFirstSettledContext, type ComputeFirstWorkContext, type CreateDefaultOnDeniedOptions, type DefaultOnDeniedResult, DenialReason, FIXABLE_DENIAL_REASONS, type GeneratedUCPKey, type JWKSResponse, MAX_POP_WINDOW_SECONDS, type MintedRecipients, type OwnerScope, type QuoteCache, type QuoteCacheOptions, type SignMessageInput, type SignedUCPProfile, SolanaMppRailSpec, StripeRailSpec, type SuccessBodyArgs, TempoRailSpec, UCPProfile, UCPSigningKey, UCPVerificationError, UCP_A2A_EXTENSION_URI, type VerifyFailureReason, type VerifyMessageSignatureInput, type VerifyMessageSignatureResult, VerifyRequestContext, VerifyWalletSignerResult, type WorkOutcome, X402BaseRailSpec, aipA2AExtension, buildA2AAgentCard, buildContactSupportNextSteps, buildJWKSResponse, buildSignerMismatchBody, buildVerificationRequiredBody, buildVerifyContextFromRequest, computeFirstCheckout, createDefaultOnDenied, createQuoteCache, defaultReadOnlyOnDenied, denialReasonStatus, denialReasonToBody, extractOwnerScope, generateUCPSigningKey, hasAgentIdentityHeader, hashOperatorToken, isFixableDenial, loadUCPSigningKeyFromEnv, normalizeAddress, signMessage, signUCPProfile, ucpA2AExtension, verificationAgentInstructions, verifyMessageSignature, verifyUCPProfile };
+export { type A2AAgentCard, type A2AAgentCardCapabilities, type A2AAgentCardExtension, type A2AAgentCardSignature, type A2AAgentInterface, type A2AAgentProvider, type A2AAgentSkill, A2A_DEFAULT_TRANSPORT, A2A_PROTOCOL_VERSION, AIP_A2A_EXTENSION_URI, AIP_COVERED_COMPONENTS, AIP_SIGNATURE_TAG, type CachedQuote, CheckoutValidationError, type ComputeFirstHandler, type ComputeFirstMintContext, type ComputeFirstMppContext, type ComputeFirstOptions, type ComputeFirstRails, type ComputeFirstSettledContext, type ComputeFirstWorkContext, type CreateDefaultOnDeniedOptions, type DefaultOnDeniedResult, DenialReason, FIXABLE_DENIAL_REASONS, type GeneratedUCPKey, type JWKSResponse, MAX_POP_WINDOW_SECONDS, type MintedRecipients, type OwnerScope, type QuoteCache, type QuoteCacheOptions, type ResultCache, type ResultCacheOptions, type SignMessageInput, type SignedUCPProfile, SolanaMppRailSpec, StripeRailSpec, type SuccessBodyArgs, TempoRailSpec, UCPProfile, UCPSigningKey, UCPVerificationError, UCP_A2A_EXTENSION_URI, type VerifyFailureReason, type VerifyMessageSignatureInput, type VerifyMessageSignatureResult, VerifyRequestContext, VerifyWalletSignerResult, type WorkOutcome, X402BaseRailSpec, aipA2AExtension, buildA2AAgentCard, buildContactSupportNextSteps, buildJWKSResponse, buildSignerMismatchBody, buildVerificationRequiredBody, buildVerifyContextFromRequest, computeFirstCheckout, createDefaultOnDenied, createQuoteCache, createResultCache, defaultReadOnlyOnDenied, denialReasonStatus, denialReasonToBody, extractOwnerScope, generateUCPSigningKey, hasAgentIdentityHeader, hashOperatorToken, isFixableDenial, loadUCPSigningKeyFromEnv, normalizeAddress, signMessage, signUCPProfile, ucpA2AExtension, verificationAgentInstructions, verifyMessageSignature, verifyUCPProfile };

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import { VerifyWalletSignerResult, DenialReason } from './core.js';
 export { AccountVerification, AgentIdentity, AgentMemoryHint, AgentScoreCore, AssessResult, CreateSessionOnMissing, DenialCode, EvaluateOutcome, OperatorVerification, PolicyCheck, PolicyResult, SignerVerdict, buildAgentMemoryHint } from './core.js';
 export { P as PaymentSigner, S as SignerNetwork, e as extractPaymentSigner, a as extractPaymentSignerFromAuth, b as extractSignerForPrecheck, r as readX402PaymentHeader } from './signer-3FAit11j.js';
-import { q as UCPSigningKey, n as UCPProfile } from './checkout-C4RD7M0Z.js';
-export { A as AGENTSCORE_UCP_CAPABILITY, a as AgentScoreGatePolicy, C as Checkout, b as CheckoutContext, c as CheckoutGateConfig, d as CheckoutRailSpec, e as CheckoutRequest, f as CheckoutResult, g as ComposeMppxFn, D as DiscoveryProbeConfig, G as GateDenial, I as IsCachedAddressFn, M as MountUcpRoutesOptions, h as MppxComposeOutcome, O as OnSettledFn, P as PreValidateFn, i as PricingFn, j as PricingResult, R as RecipientsFn, k as ReferenceIdFn, l as RunGateFn, S as SettleOutcome, U as UCPCapabilityBinding, m as UCPPaymentHandlerBinding, o as UCPProfileBody, p as UCPServiceBinding, r as buildAipTrustedIssuers, s as buildUCPProfile, t as getIdentityStatus, u as makeMppxComposeHook, v as mppPaymentHandler, w as pricingResult, x as stripeSptPaymentHandler, y as validationEnvelope, z as validationResponseExpress, B as validationResponseFastify, E as validationResponseHono, F as validationResponseNextjs, H as validationResponseWeb, J as x402PaymentHandler } from './checkout-C4RD7M0Z.js';
+import { q as UCPSigningKey, n as UCPProfile } from './checkout-B-Z5_EQP.js';
+export { A as AGENTSCORE_UCP_CAPABILITY, a as AgentScoreGatePolicy, C as Checkout, b as CheckoutContext, c as CheckoutGateConfig, d as CheckoutRailSpec, e as CheckoutRequest, f as CheckoutResult, g as ComposeMppxFn, D as DiscoveryProbeConfig, G as GateDenial, I as IsCachedAddressFn, M as MountUcpRoutesOptions, h as MppxComposeOutcome, O as OnSettledFn, P as PreValidateFn, i as PricingFn, j as PricingResult, R as RecipientsFn, k as ReferenceIdFn, l as RunGateFn, S as SettleOutcome, U as UCPCapabilityBinding, m as UCPPaymentHandlerBinding, o as UCPProfileBody, p as UCPServiceBinding, r as buildAipTrustedIssuers, s as buildUCPProfile, t as getIdentityStatus, u as makeMppxComposeHook, v as mppPaymentHandler, w as pricingResult, x as stripeSptPaymentHandler, y as validationEnvelope, z as validationResponseExpress, B as validationResponseFastify, E as validationResponseHono, F as validationResponseNextjs, H as validationResponseWeb, J as x402PaymentHandler } from './checkout-B-Z5_EQP.js';
 export { EnforcementMode, GateResult, IdentityStatus, PolicyBlock, buildGateFromPolicy, runGateWithEnforcement, shippingCountryAllowed, shippingStateAllowed, validateShippingAgainstPolicy } from './identity/policy.js';
-import { H as HeadersLike } from './network_kind-BIJM2peR.js';
-export { 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 } from './network_kind-BIJM2peR.js';
+import { H as HeadersLike } from './network_kind-BmbWKNud.js';
+export { M as MalformedPaymentCredential, 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 } from './network_kind-BmbWKNud.js';
 import { T as TempoRailSpec, X as X402BaseRailSpec, S as SolanaMppRailSpec, b as StripeRailSpec } from './rail_spec-BFZmW9RN.js';
 export { c as TempoSessionRailSpec } from './rail_spec-BFZmW9RN.js';
 import { Context } from 'hono';
@@ -653,21 +653,26 @@ declare class CheckoutValidationError extends Error {
 }
 
 /**
- * Short-TTL body-hash quote cache for the compute-first + exact-x402 pattern
- * (see {@link computeFirstCheckout}).
+ * Short-TTL body-hash caches.
  *
- * Standard x402-fetch retry semantics resign the buyer's ORIGINAL request body
- * — there's no `result_id` echo channel through the protocol. The cache is
- * therefore keyed by a stable content-hash of the request body. Same body →
- * same hash → same cache slot. The probe leg writes (run-work → cache); the
- * settle leg reads (cache hit → settle exact at the cached price → return the
- * cached body).
+ * `createResultCache` is the neutral primitive: a keyed JSON-value cache with
+ * a stable content-hash key builder. Use it to cache any per-request result a
+ * merchant computes on the probe leg and replays on the settle leg — e.g. the
+ * output of a paid upstream call made in a `Checkout.preValidate` hook, so a
+ * payment retry (or a junk payment header) never pays upstream twice.
+ *
+ * `createQuoteCache` is the compute-first-flavored wrapper used by
+ * {@link computeFirstCheckout}: the cached value is a `CachedQuote`
+ * (`{body, priceCents, recipients}`). Standard x402-fetch retry semantics
+ * resign the buyer's ORIGINAL request body — there's no `result_id` echo
+ * channel through the protocol — so both caches key by a stable content-hash
+ * of the request body. Same body → same hash → same cache slot.
  *
  * Default in-memory `Map`; optional `redisUrl` lazy-imports `ioredis` for
  * multi-instance deployments. `ioredis` is an optional peer dep.
  */
-interface QuoteCacheOptions {
-    /** Quote lifetime in milliseconds. Default `5 * 60_000` (5 min). */
+interface ResultCacheOptions {
+    /** Entry lifetime in milliseconds. Default `5 * 60_000` (5 min). */
     ttlMs?: number;
     /** Redis connection URL. Default: `process.env.REDIS_URL`. When unset or the
      *  lazy `ioredis` import fails, falls back to in-process `Map`. */
@@ -675,6 +680,7 @@ interface QuoteCacheOptions {
     /** Per-instance key prefix so multiple caches sharing a Redis don't collide. */
     keyPrefix?: string;
 }
+type QuoteCacheOptions = ResultCacheOptions;
 interface CachedQuote {
     body: Record<string, unknown>;
     priceCents: number;
@@ -683,6 +689,15 @@ interface CachedQuote {
      *  same logical purchase). Empty object when no `mintRecipients` hook is wired. */
     recipients: Record<string, string>;
 }
+interface ResultCache<T> {
+    /** Build a stable content-hash key from a per-merchant prefix and a request body.
+     *  Property order in the body does NOT affect the hash (keys are sorted recursively). */
+    bodyHashKey(prefix: string, body: Record<string, unknown>): string;
+    read(key: string): Promise<T | null>;
+    write(key: string, value: T): Promise<void>;
+    /** Clear all entries. Primarily for tests. */
+    clear(): Promise<void>;
+}
 interface QuoteCache {
     /** Build a stable content-hash key from a per-merchant prefix and a request body.
      *  Property order in the body does NOT affect the hash (keys are sorted recursively). */
@@ -692,8 +707,11 @@ interface QuoteCache {
     /** Clear all entries. Primarily for tests. */
     clear(): Promise<void>;
 }
-/** Build a fresh cache. Each call owns its own state (memory map + Redis
- *  client). */
+/** Build a fresh neutral result cache. Each call owns its own state (memory
+ *  map + Redis client). Values must survive `JSON.stringify` round-trips. */
+declare function createResultCache<T>(opts?: ResultCacheOptions): ResultCache<T>;
+/** Build a fresh compute-first quote cache (a `ResultCache<CachedQuote>` with
+ *  the quote-shaped `write` signature). */
 declare function createQuoteCache(opts?: QuoteCacheOptions): QuoteCache;
 
 /**
@@ -1088,4 +1106,4 @@ declare const buildVerifyContextFromRequest: (req: Request, authority?: string)
 /** True when the request carries an AIP credential (at least one `Agent-Identity` header). */
 declare const hasAgentIdentityHeader: (req: Request) => boolean;
 
-export { type A2AAgentCard, type A2AAgentCardCapabilities, type A2AAgentCardExtension, type A2AAgentCardSignature, type A2AAgentInterface, type A2AAgentProvider, type A2AAgentSkill, A2A_DEFAULT_TRANSPORT, A2A_PROTOCOL_VERSION, AIP_A2A_EXTENSION_URI, AIP_COVERED_COMPONENTS, AIP_SIGNATURE_TAG, type CachedQuote, CheckoutValidationError, type ComputeFirstHandler, type ComputeFirstMintContext, type ComputeFirstMppContext, type ComputeFirstOptions, type ComputeFirstRails, type ComputeFirstSettledContext, type ComputeFirstWorkContext, type CreateDefaultOnDeniedOptions, type DefaultOnDeniedResult, DenialReason, FIXABLE_DENIAL_REASONS, type GeneratedUCPKey, type JWKSResponse, MAX_POP_WINDOW_SECONDS, type MintedRecipients, type OwnerScope, type QuoteCache, type QuoteCacheOptions, type SignMessageInput, type SignedUCPProfile, SolanaMppRailSpec, StripeRailSpec, type SuccessBodyArgs, TempoRailSpec, UCPProfile, UCPSigningKey, UCPVerificationError, UCP_A2A_EXTENSION_URI, type VerifyFailureReason, type VerifyMessageSignatureInput, type VerifyMessageSignatureResult, VerifyRequestContext, VerifyWalletSignerResult, type WorkOutcome, X402BaseRailSpec, aipA2AExtension, buildA2AAgentCard, buildContactSupportNextSteps, buildJWKSResponse, buildSignerMismatchBody, buildVerificationRequiredBody, buildVerifyContextFromRequest, computeFirstCheckout, createDefaultOnDenied, createQuoteCache, defaultReadOnlyOnDenied, denialReasonStatus, denialReasonToBody, extractOwnerScope, generateUCPSigningKey, hasAgentIdentityHeader, hashOperatorToken, isFixableDenial, loadUCPSigningKeyFromEnv, normalizeAddress, signMessage, signUCPProfile, ucpA2AExtension, verificationAgentInstructions, verifyMessageSignature, verifyUCPProfile };
+export { type A2AAgentCard, type A2AAgentCardCapabilities, type A2AAgentCardExtension, type A2AAgentCardSignature, type A2AAgentInterface, type A2AAgentProvider, type A2AAgentSkill, A2A_DEFAULT_TRANSPORT, A2A_PROTOCOL_VERSION, AIP_A2A_EXTENSION_URI, AIP_COVERED_COMPONENTS, AIP_SIGNATURE_TAG, type CachedQuote, CheckoutValidationError, type ComputeFirstHandler, type ComputeFirstMintContext, type ComputeFirstMppContext, type ComputeFirstOptions, type ComputeFirstRails, type ComputeFirstSettledContext, type ComputeFirstWorkContext, type CreateDefaultOnDeniedOptions, type DefaultOnDeniedResult, DenialReason, FIXABLE_DENIAL_REASONS, type GeneratedUCPKey, type JWKSResponse, MAX_POP_WINDOW_SECONDS, type MintedRecipients, type OwnerScope, type QuoteCache, type QuoteCacheOptions, type ResultCache, type ResultCacheOptions, type SignMessageInput, type SignedUCPProfile, SolanaMppRailSpec, StripeRailSpec, type SuccessBodyArgs, TempoRailSpec, UCPProfile, UCPSigningKey, UCPVerificationError, UCP_A2A_EXTENSION_URI, type VerifyFailureReason, type VerifyMessageSignatureInput, type VerifyMessageSignatureResult, VerifyRequestContext, VerifyWalletSignerResult, type WorkOutcome, X402BaseRailSpec, aipA2AExtension, buildA2AAgentCard, buildContactSupportNextSteps, buildJWKSResponse, buildSignerMismatchBody, buildVerificationRequiredBody, buildVerifyContextFromRequest, computeFirstCheckout, createDefaultOnDenied, createQuoteCache, createResultCache, defaultReadOnlyOnDenied, denialReasonStatus, denialReasonToBody, extractOwnerScope, generateUCPSigningKey, hasAgentIdentityHeader, hashOperatorToken, isFixableDenial, loadUCPSigningKeyFromEnv, normalizeAddress, signMessage, signUCPProfile, ucpA2AExtension, verificationAgentInstructions, verifyMessageSignature, verifyUCPProfile };

package/dist/index.js

@@ -22253,6 +22253,7 @@ __export(index_exports, {
   computeFirstCheckout: () => computeFirstCheckout,
   createDefaultOnDenied: () => createDefaultOnDenied,
   createQuoteCache: () => createQuoteCache,
+  createResultCache: () => createResultCache,
   defaultReadOnlyOnDenied: () => defaultReadOnlyOnDenied,
   denialReasonStatus: () => denialReasonStatus,
   denialReasonToBody: () => denialReasonToBody,
@@ -22277,6 +22278,7 @@ __export(index_exports, {
   loadSolanaFeePayer: () => loadSolanaFeePayer,
   loadUCPSigningKeyFromEnv: () => loadUCPSigningKeyFromEnv,
   makeMppxComposeHook: () => makeMppxComposeHook,
+  malformedPaymentCredential: () => malformedPaymentCredential,
   mppPaymentHandler: () => mppPaymentHandler,
   normalizeAddress: () => normalizeAddress,
   pricingResult: () => pricingResult,
@@ -22664,7 +22666,7 @@ function createAgentScoreCore(options) {
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
   const agentMemoryHint = buildAgentMemoryHint(aipTrustedIssuers);
-  const defaultUa = `@agent-score/commerce@${"2.6.2"}`;
+  const defaultUa = `@agent-score/commerce@${"2.6.4"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
   const sdk = new import_sdk.AgentScore({ apiKey, baseUrl, userAgent: userAgentHeader });
   const sessionSdkCache = /* @__PURE__ */ new Map();
@@ -23291,6 +23293,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/identity/tokens.ts
 function hashOperatorToken(plaintext) {
@@ -25530,6 +25565,7 @@ var Checkout = class {
    *  agent-supplied `payTo` to this set (anti funds-drain). Empty for pure per-order minting. */
   x402StaticRecipients;
   zeroSettleCarveOut;
+  credentialPreCheck;
   gate;
   discoveryExtensions;
   resourceInfo;
@@ -25611,6 +25647,7 @@ var Checkout = class {
     this.isCachedAddress = opts.isCachedAddress;
     this.x402StaticRecipients = collectStaticX402Recipients(opts.rails);
     this.zeroSettleCarveOut = opts.zeroSettleCarveOut ?? false;
+    this.credentialPreCheck = opts.credentialPreCheck ?? true;
     this.gate = opts.gate;
     this.discoveryExtensions = opts.discoveryExtensions;
     this.resourceInfo = opts.resourceInfo;
@@ -25748,6 +25785,27 @@ var Checkout = class {
         };
       }
     }
+    if (this.credentialPreCheck) {
+      const malformed = malformedPaymentCredential(request.headers);
+      const enforced = malformed !== null && (malformed.channel === "x402" ? this.x402ServerAvailable() && this.x402BaseNetwork !== null : this.composeMppx !== void 0);
+      if (enforced) {
+        return {
+          status: 400,
+          body: buildValidationError({
+            code: "payment_proof_invalid",
+            message: malformed.message,
+            nextSteps: {
+              action: "regenerate_payment_credential",
+              user_message: "The payment credential could not be decoded. Rebuild it from a fresh 402 challenge and retry."
+            }
+          }),
+          headers: {},
+          referenceId: ctx.referenceId,
+          settled: false,
+          settlePhase: "credential_malformed"
+        };
+      }
+    }
     if (this.preValidate !== void 0) {
       try {
         const state = await this.preValidate(ctx);
@@ -26070,21 +26128,34 @@ var Checkout = class {
     if (ctx.pricing.amountUsd !== 0) return null;
     const headers = normalizeHeadersToLowercase(ctx.request.headers);
     let zero;
+    let railKey;
     if (rail === "x402-base") {
-      const x402Header = headers["payment-signature"] ?? headers["x-payment"];
-      let payload = null;
-      if (typeof x402Header === "string" && x402Header.length > 0) {
-        try {
-          payload = JSON.parse(atob(x402Header));
-        } catch {
-          payload = null;
-        }
+      const fakeRequest = new Request(ctx.request.url, {
+        method: ctx.request.method,
+        headers: ctx.request.headers
+      });
+      const verified = await verifyX402Request({
+        request: fakeRequest,
+        isCachedAddress: (addr) => this.asyncIsCachedAddress(addr, ctx),
+        acceptedNetwork: this.x402BaseNetwork ?? ""
+      });
+      if (!verified.ok) {
+        return {
+          status: verified.status,
+          body: verified.body,
+          headers: {},
+          referenceId: ctx.referenceId,
+          settled: false,
+          settlePhase: "verify_failed"
+        };
       }
-      zero = zeroAmountCarveOut({ rail, payload });
+      zero = zeroAmountCarveOut({ rail, payload: verified.payload });
+      railKey = this.x402RailKey();
     } else {
       zero = zeroAmountCarveOut({ rail, authorizationHeader: headers["authorization"] });
+      if (zero.signerNetwork !== "solana") return null;
+      railKey = this.railsKeyForMppxMethod("solana") ?? this.mppRailKey();
     }
-    const railKey = rail === "x402-base" ? this.x402RailKey() : this.mppRailKey();
     const outcome = {
       rail: rail === "x402-base" ? "x402" : "mpp",
       paymentResponseHeader: null,
@@ -26880,11 +26951,11 @@ function canonicalize2(value) {
   }
   return value;
 }
-function createQuoteCache(opts = {}) {
+function createResultCache(opts = {}) {
   const ttlMs = opts.ttlMs ?? 5 * 6e4;
-  const keyPrefix = opts.keyPrefix ?? "quote:";
+  const keyPrefix = opts.keyPrefix ?? "result:";
   const memMap = /* @__PURE__ */ new Map();
-  const getRedis = memoizedRedis({ url: opts.redisUrl, label: "quote-cache" });
+  const getRedis = memoizedRedis({ url: opts.redisUrl, label: "result-cache" });
   const evictExpired = () => {
     const now = Date.now();
     for (const [k, v] of memMap.entries()) {
@@ -26911,17 +26982,16 @@ function createQuoteCache(opts = {}) {
       const entry = memMap.get(key);
       return entry ? entry.entry : null;
     },
-    async write(key, body, priceCents, recipients = {}) {
-      const cached2 = { body, priceCents, recipients };
+    async write(key, value) {
       const r = await getRedis();
       if (r) {
         try {
-          await r.set(`${keyPrefix}${key}`, JSON.stringify(cached2), "PX", ttlMs);
+          await r.set(`${keyPrefix}${key}`, JSON.stringify(value), "PX", ttlMs);
           return;
         } catch {
         }
       }
-      memMap.set(key, { entry: cached2, expiresAt: Date.now() + ttlMs });
+      memMap.set(key, { entry: value, expiresAt: Date.now() + ttlMs });
     },
     async clear() {
       memMap.clear();
@@ -26935,6 +27005,17 @@ function createQuoteCache(opts = {}) {
     }
   };
 }
+function createQuoteCache(opts = {}) {
+  const cache = createResultCache({ ...opts, keyPrefix: opts.keyPrefix ?? "quote:" });
+  return {
+    bodyHashKey: cache.bodyHashKey,
+    read: cache.read,
+    async write(key, body, priceCents, recipients = {}) {
+      await cache.write(key, { body, priceCents, recipients });
+    },
+    clear: cache.clear
+  };
+}
 
 // src/checkout_compute_first.ts
 var DEFAULT_TTL_MS = 5 * 6e4;
@@ -27452,6 +27533,7 @@ function defaultReadOnlyOnDenied(reason) {
   computeFirstCheckout,
   createDefaultOnDenied,
   createQuoteCache,
+  createResultCache,
   defaultReadOnlyOnDenied,
   denialReasonStatus,
   denialReasonToBody,
@@ -27476,6 +27558,7 @@ function defaultReadOnlyOnDenied(reason) {
   loadSolanaFeePayer,
   loadUCPSigningKeyFromEnv,
   makeMppxComposeHook,
+  malformedPaymentCredential,
   mppPaymentHandler,
   normalizeAddress,
   pricingResult,