agentscore-commerce 2.5.2__tar.gz → 2.5.4__tar.gz

{agentscore_commerce-2.5.2 → agentscore_commerce-2.5.4}/CLAUDE.md

@@ -8,7 +8,7 @@ Every helper is extracted from a real consumer, not speculated.
 
 | Submodule | What it is |
 |---|---|
-| `agentscore_commerce` (top-level) | `Checkout` orchestrator (the 2.0 high-level surface): one config object + hooks (pre_validate, compute_pricing, mint_recipients, compose_mppx, on_settled, gate), auto-derived x402+pympp servers, per-framework adapters `handle_fastapi`/`handle_flask`/`handle_django`/`handle_aiohttp`/`handle_sanic`, signed UCP routes via `mount_ucp_routes_{fastapi,flask,django,aiohttp,sanic}`, optional `discovery_probe` config for x402-crawler auto-routing. Plus `compute_first_checkout` — variable-cost pay-per-result helper (compute-first + exact-x402). Scope is exact-mode rails only (x402-exact Base, tempo/charge, solana/charge, Stripe SPT); does NOT use x402-upto (Permit2) or Settlement-Overrides — variable cost is captured by running the work pre-settle and emitting a 402 at the exact computed price. `create_quote_cache` — content-hash quote cache used by the compute-first helper (in-memory by default; pass `redis_url` for distributed deployments). `create_default_on_denied` — canonical `on_denied(reason)` factory matching `Checkout`'s gate hook (handles `wallet_signer_mismatch`, `wallet_not_trusted` unfixable fallback, `payment_required`, `token_expired`/`invalid_credential`/`api_error`); merchants pass `merchant_name` + `support_email` and override `wallet_not_trusted_message` / `payment_required_message` / `support_context` for vendor-specific copy. `has_payment_header` — discriminator that splits discovery legs (no payment credential → 402) from settle legs (`payment-signature` / `x-payment` / `Authorization: Payment <jwt>`); `has_x402_header` / `has_mppx_header` — granular dispatch helpers (x402 vs MPP credential present) for routes that branch on rail. `default_read_only_on_denied(reason)` — canonical `on_denied` for read-only resource gates (`GET /orders/:id`): collapses every denial to 401 `unauthorized` + `Cache-Control: no-store` while still spreading `denial_reason_to_body` so `agent_instructions` / `verify_url` ride through. Returns a `DefaultOnDeniedResult(body, status, headers)` dataclass; FastAPI / Flask / aiohttp / Sanic `on_denied` callbacks accept an optional 3-tuple `(body, status, headers)` — convert with `lambda req, reason: (r := default_read_only_on_denied(reason), (r.body, r.status, r.headers or {}))[1]` or a named wrapper. Django + ASGI middleware adapters return Response objects directly; construct `JsonResponse(r.body, status=r.status, headers=r.headers)` /  `JSONResponse(content=r.body, status_code=r.status, headers=r.headers)`. `extract_owner_scope(headers) -> OwnerScope` — pull canonical owner identity from `X-Wallet-Address` / `X-Operator-Token` with safe token hashing; pair with a wallet-or-token-scoped resource query so plaintext tokens never leave the request. Plus factories: `pricing_result` (cents → typed `PricingResult`), `validation_response_{fastapi,flask,django,aiohttp,sanic}` (4xx envelope per framework) |
+| `agentscore_commerce` (top-level) | `Checkout` orchestrator (the 2.0 high-level surface): one config object + hooks (pre_validate, compute_pricing, mint_recipients, compose_mppx, on_settled, gate), auto-derived x402+pympp servers, per-framework adapters `handle_fastapi`/`handle_flask`/`handle_django`/`handle_aiohttp`/`handle_sanic`, signed UCP routes via `mount_ucp_routes_{fastapi,flask,django,aiohttp,sanic}`, optional `discovery_probe` config for x402-crawler auto-routing. Plus `compute_first_checkout` — variable-cost pay-per-result helper (compute-first + exact-x402). Scope is exact-mode rails only (x402-exact Base, tempo/charge, solana/charge, Stripe SPT); does NOT use x402-upto (Permit2) or Settlement-Overrides — variable cost is captured by running the work pre-settle and emitting a 402 at the exact computed price. `create_quote_cache` — content-hash quote cache used by the compute-first helper (in-memory by default; pass `redis_url` for distributed deployments). `create_result_cache` — the neutral primitive under it: keyed JSON-value cache with the same body-hash key builder; use it to cache any probe-leg result a Checkout-class merchant replays on the settle leg (e.g. a paid upstream call made in `pre_validate`). `create_default_on_denied` — canonical `on_denied(reason)` factory matching `Checkout`'s gate hook (handles `wallet_signer_mismatch`, `wallet_not_trusted` unfixable fallback, `payment_required`, `token_expired`/`invalid_credential`/`api_error`); merchants pass `merchant_name` + `support_email` and override `wallet_not_trusted_message` / `payment_required_message` / `support_context` for vendor-specific copy. `has_payment_header` — discriminator that splits discovery legs (no payment credential → 402) from settle legs (`payment-signature` / `x-payment` / `Authorization: Payment <jwt>`); `has_x402_header` / `has_mppx_header` — granular dispatch helpers (x402 vs MPP credential present) for routes that branch on rail. `malformed_payment_credential` — wire-shape gate for payment credentials (not base64 JSON, not token-shaped → reject); `Checkout` runs it before any merchant hook by default (`credential_pre_check=False` opts out). `default_read_only_on_denied(reason)` — canonical `on_denied` for read-only resource gates (`GET /orders/:id`): collapses every denial to 401 `unauthorized` + `Cache-Control: no-store` while still spreading `denial_reason_to_body` so `agent_instructions` / `verify_url` ride through. Returns a `DefaultOnDeniedResult(body, status, headers)` dataclass; FastAPI / Flask / aiohttp / Sanic `on_denied` callbacks accept an optional 3-tuple `(body, status, headers)` — convert with `lambda req, reason: (r := default_read_only_on_denied(reason), (r.body, r.status, r.headers or {}))[1]` or a named wrapper. Django + ASGI middleware adapters return Response objects directly; construct `JsonResponse(r.body, status=r.status, headers=r.headers)` /  `JSONResponse(content=r.body, status_code=r.status, headers=r.headers)`. `extract_owner_scope(headers) -> OwnerScope` — pull canonical owner identity from `X-Wallet-Address` / `X-Operator-Token` with safe token hashing; pair with a wallet-or-token-scoped resource query so plaintext tokens never leave the request. Plus factories: `pricing_result` (cents → typed `PricingResult`), `validation_response_{fastapi,flask,django,aiohttp,sanic}` (4xx envelope per framework) |
 | `agentscore_commerce.identity.{fastapi,flask,django,aiohttp,sanic,middleware}` | Trust gate middleware (KYC, age, sanctions on both account name and signer wallet, jurisdiction). Each adapter exports a conditional variant that wraps the gate so it fires only on settle legs (anonymous discovery flows through and gets a 402 with all rails): FastAPI / ASGI expose `ConditionalAgentScoreGate`, Django exposes `ConditionalAgentScoreMiddleware`, Flask + Sanic expose `conditional_agentscore_gate(app, ...)`, aiohttp exposes `conditional_agentscore_gate_middleware(...)`. Adapters export ONLY framework-specific surface (gate classes / fns, accessors, `capture_wallet`); shared helpers like `has_payment_header` / `denial_reason_to_body` import from their canonical home (`agentscore_commerce.payment` and `agentscore_commerce.identity` respectively). The Flask / Sanic `agentscore_gate(app, ...)` function accepts an optional `condition=` callable for inline gating (`AgentScoreGate.__init__` does not). |
 | `agentscore_commerce.identity.policy` | Per-product compliance helpers: `PolicyBlock`, `build_gate_from_policy`, `run_gate_with_enforcement`, `shipping_country_allowed`, `shipping_state_allowed`, `validate_shipping_against_policy` (one-call country+state validator that raises `CheckoutValidationError` with the canonical envelope on miss) |
 | `agentscore_commerce.payment` | Networks/USDC/rails registries, paymentauth.org directive builders, `create_x402_server` (wraps `x402[evm]>=2.9` + `cdp-sdk` for `facilitator="coinbase"`; install via the `coinbase` extra), `build_x402_accepts_for_402` (build the 402's `accepts[]` from the registered scheme; derives the right `extra.name` per network), `build_default_checkout_rails(tempo=, x402_base=, solana_mpp=, stripe=)` (canonical 4-rail `rails` dict factory: merchants pass per-rail overrides instead of redeclaring the recipient sentinel + network/chain_id/token boilerplate. When a caller flips `network` without pinning `token` / `chain_id`, the underlying dataclass derives them from the network: Base Sepolia → Sepolia USDC + chain_id 84532, Solana devnet → devnet USDC mint. Explicit overrides always win. Solana's `network` field accepts both CAIP-2 (`solana:5eykt4UsFv8…` / `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`) AND the raw `@solana/mpp` form (`mainnet-beta` / `devnet` / `localnet`)), `build_mppx_compose_rails(amount_usd=, tempo_recipient=, solana_recipient=, ...)` (per-call intent factory replacing the hand-rolled `[("tempo/charge", {...}), ("solana/charge", {...}), ("stripe/charge", {...})]` list; auto-handles USD→atomic conversion for Solana; auto-drops the `stripe/charge` rail with a one-time `logging.warning` when `amount_usd < 0.50` since Stripe's fixed ~$0.30 fee makes sub-50-cent charges unprofitable — many Stripe accounts also reject PI creation below the floor with `amount_too_small`; sub-50-cent APIs pass `include_stripe=False` explicitly to silence the warning), `process_x402_settle` (verify+settle in one call), `create_mppx_server` (wraps `pympp[server,tempo,stripe]>=0.6`), `is_evm_network`/`is_solana_network` (CAIP-2 discriminators that hide the `startswith("eip155:")` / `startswith("solana:")` prefix matching), `has_payment_header` (settle-leg vs discovery-leg discriminator), `parse_did_pkh_address` (parses ``did:pkh:<family>:<chain>:<addr>`` into a `PaymentSigner`), dispatch-by-network, signer extraction, WWW-Authenticate header, Settlement-Overrides header |

{agentscore_commerce-2.5.2 → agentscore_commerce-2.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentscore-commerce
-Version: 2.5.2
+Version: 2.5.4
 Summary: Agent commerce SDK for Python — identity middleware (FastAPI, Flask, Django, AIOHTTP, Sanic, ASGI) + payment helpers + 402 builders + discovery + Stripe multichain. The full merchant-side toolkit for AgentScore-powered agent commerce.
 Project-URL: Homepage, https://www.agentscore.com
 Project-URL: Repository, https://github.com/agentscore/python-commerce
@@ -72,10 +72,10 @@ pip install 'agentscore-commerce[fastapi,x402,coinbase]'
 
 | Submodule | What it provides |
 |---|---|
-| `agentscore_commerce` (top-level) | `Checkout` orchestrator + `CheckoutContext` + `CheckoutGateConfig` + `CheckoutValidationError` + `DiscoveryProbeConfig` + `SettleOutcome` + `MppxComposeOutcome` + `PricingResult` (the 2.0 high-level surface: one config object, hooks for pre_validate/compute_pricing/on_settled/mint_recipients/compose_mppx, auto-derived x402+mppx servers, per-framework adapters `handle_fastapi`/`handle_flask`/`handle_django`/`handle_aiohttp`/`handle_sanic`, signed UCP routes via `mount_ucp_routes_{fastapi,flask,django,aiohttp,sanic}`); `pricing_result` (factory: cents-denominated → typed `PricingResult` with embedded `PricingBlock`); `validation_response_{fastapi,flask,django,aiohttp,sanic}` (per-framework 4xx envelope wrappers); `make_mppx_compose_hook` (canonical pympp compose adapter). |
+| `agentscore_commerce` (top-level) | `Checkout` orchestrator + `CheckoutContext` + `CheckoutGateConfig` + `CheckoutValidationError` + `DiscoveryProbeConfig` + `SettleOutcome` + `MppxComposeOutcome` + `PricingResult` (the 2.0 high-level surface: one config object, hooks for pre_validate/compute_pricing/on_settled/mint_recipients/compose_mppx, auto-derived x402+mppx servers, per-framework adapters `handle_fastapi`/`handle_flask`/`handle_django`/`handle_aiohttp`/`handle_sanic`, signed UCP routes via `mount_ucp_routes_{fastapi,flask,django,aiohttp,sanic}`); `create_result_cache` (neutral keyed JSON-value cache with a stable body-hash key builder; cache a probe-leg result, e.g. a paid upstream call made in `pre_validate`, and replay it on the settle leg) plus the compute-first-shaped `create_quote_cache` built on it; `pricing_result` (factory: cents-denominated → typed `PricingResult` with embedded `PricingBlock`); `validation_response_{fastapi,flask,django,aiohttp,sanic}` (per-framework 4xx envelope wrappers); `make_mppx_compose_hook` (canonical pympp compose adapter). |
 | `agentscore_commerce.identity.{fastapi,flask,django,aiohttp,sanic,middleware}` | Trust gate middleware: KYC, sanctions (account name + signer wallet), age, jurisdiction. `AgentScoreGate(...)` (or `agentscore_gate(app, ...)` on Flask/Sanic), `get_agentscore_data(...)`, `capture_wallet(...)`, `get_signer_verdict(...)`. The gate extracts the payment signer pre-evaluate and passes it to `/v1/assess`, so the API composes both wallet-binding (`signer_match`) and OFAC SDN wallet-address (`signer_sanctions`) verdicts on one round trip. |
 | `agentscore_commerce.identity` (package level) | Re-exports the denial helpers: `denial_reason_status`, `denial_reason_to_body`, `build_signer_mismatch_body`, `build_contact_support_next_steps`, `verification_agent_instructions`, `is_fixable_denial`, `FIXABLE_DENIAL_REASONS`. The per-framework adapter modules also expose `get_gate_quota_info(request)` for surfacing X-RateLimit info from gate state. Also re-exports the per-product policy helpers: `PolicyBlock`, `GateResult`, `EnforcementMode`, `IdentityStatus`, `build_gate_from_policy`, `run_gate_with_enforcement`, `shipping_country_allowed`, `shipping_state_allowed`, `validate_shipping_against_policy` (one-call country+state validator that raises `CheckoutValidationError` with the canonical envelope on miss), for multi-product merchants where each product carries its own compliance config: hard gate vs soft vs none, per-product shipping allowlists. Key + token helpers: `load_ucp_signing_key_from_env` (cached env-driven loader for the UCP signing key, reads `UCP_SIGNING_KEY_JWK_PRIVATE` JSON JWK, detects alg from shape, falls back to ephemeral when unset, sanitizes errors so key bytes never reach logs, concurrent-safe via `threading.Lock`; env-var names and `default_kid` / `default_alg` are overridable as kwargs); `hash_operator_token` (sha256 hex of plaintext `opc_...`, for merchants persisting `operator_token_id` to their own DB without ever storing the plaintext); `extract_owner_scope(headers) -> OwnerScope` (canonical owner-identity extractor for caller-scoped resource queries, reads `X-Wallet-Address` / `X-Operator-Token`, hashes the token so plaintext never leaves the request); `default_read_only_on_denied(reason)` (canonical `on_denied` for read-only resource gates: 401 + `Cache-Control: no-store` while still spreading `denial_reason_to_body`. Returns a `DefaultOnDeniedResult(body, status, headers)`; FastAPI / Flask / aiohttp / Sanic `on_denied` callbacks accept an optional 3-tuple `(body, status, headers)` to carry headers through; wrap with `lambda req, reason: (lambda r: (r.body, r.status, r.headers or {}))(default_read_only_on_denied(reason))`). |
-| `agentscore_commerce.payment` | `networks`, `USDC`, `rails` registries; `payment_directive`, `build_payment_directive`, `www_authenticate_header`, `payment_required_header`, `alias_amount_fields` (opt-in v1↔v2 amount-field shim that adds both `amount` and `maxAmountRequired` to an entry. The 402 builders do NOT apply it by default, strict x402 v2 settlement matches the agent's echoed requirement by exact comparison, so an extra field the server's rebuilt requirement lacks breaks settle; use only when you know a client is hardcoded to read `maxAmountRequired`), `settlement_override_header`, `dispatch_settlement_by_network`, `extract_payment_signer` (accepts positional `x402_payment_header` AND/OR `authorization_header=` kwarg; recovers signer from x402 EIP-3009 `payload.authorization.from` OR MPP `Authorization: Payment <base64>` `did:pkh:eip155:<chain>:<addr>` / `did:pkh:solana:<genesis>:<addr>` source DID), `detect_rail_from_headers` (returns `"x402"` / `"mpp"` / `None` from inbound headers), `register_x402_schemes_v1_v2`; drop-in x402 helpers: `validate_x402_network_config` (boot-time guard), `verify_x402_request` (parse + validate inbound X-Payment), `process_x402_settle` (verify-then-settle with one call), `classify_x402_settle_result` (maps the tagged settle result to a recommended HTTP status / code / next_steps so merchants get a controlled envelope without coupling to facilitator-specific error text), `classify_orchestration_error` (same `ClassifiedX402Error` shape but for uncaught exceptions thrown elsewhere in the orchestration; returns `None` for unknown errors so merchants rethrow instead of swallowing); `zero_amount_carve_out` (skip CDP / pympp upstream verify+settle for $0 settles where the upstream rejects value=0 payloads; parses the credential, lifts signer + network, returns a `ZeroSettleResult` shaped identically to the success path so callers branch on rail, not on result shape); `usd_to_atomic` (Decimal-based USD → atomic int, ROUND_HALF_UP, for Tempo / Solana / Base USDC amount construction). |
+| `agentscore_commerce.payment` | `networks`, `USDC`, `rails` registries; `payment_directive`, `build_payment_directive`, `www_authenticate_header`, `payment_required_header`, `alias_amount_fields` (opt-in v1↔v2 amount-field shim that adds both `amount` and `maxAmountRequired` to an entry. The 402 builders do NOT apply it by default, strict x402 v2 settlement matches the agent's echoed requirement by exact comparison, so an extra field the server's rebuilt requirement lacks breaks settle; use only when you know a client is hardcoded to read `maxAmountRequired`), `settlement_override_header`, `dispatch_settlement_by_network`, `extract_payment_signer` (accepts positional `x402_payment_header` AND/OR `authorization_header=` kwarg; recovers signer from x402 EIP-3009 `payload.authorization.from` OR MPP `Authorization: Payment <base64>` `did:pkh:eip155:<chain>:<addr>` / `did:pkh:solana:<genesis>:<addr>` source DID), `detect_rail_from_headers` (returns `"x402"` / `"mpp"` / `None` from inbound headers), `register_x402_schemes_v1_v2`; drop-in x402 helpers: `validate_x402_network_config` (boot-time guard), `verify_x402_request` (parse + validate inbound X-Payment), `process_x402_settle` (verify-then-settle with one call), `classify_x402_settle_result` (maps the tagged settle result to a recommended HTTP status / code / next_steps so merchants get a controlled envelope without coupling to facilitator-specific error text), `classify_orchestration_error` (same `ClassifiedX402Error` shape but for uncaught exceptions thrown elsewhere in the orchestration; returns `None` for unknown errors so merchants rethrow instead of swallowing); `zero_amount_carve_out` (skip CDP / pympp upstream verify+settle for $0 settles where the upstream rejects value=0 payloads, including credentials signed against a nonzero quote the merchant re-priced to $0 at settle; parses the credential, lifts signer + network, returns a `ZeroSettleResult` shaped identically to the success path so callers branch on rail, not on result shape), `malformed_payment_credential` (wire-shape gate: payment headers that are not base64 JSON and not token-shaped are rejected before merchant hooks run; `Checkout` applies it by default, opt out with `credential_pre_check=False`); `usd_to_atomic` (Decimal-based USD → atomic int, ROUND_HALF_UP, for Tempo / Solana / Base USDC amount construction). |
 | `agentscore_commerce.discovery` | `is_discovery_probe_request`, `build_discovery_probe_response` (with optional `x402_sample` for x402-aware crawlers like `awal x402 details`), `sample_x402_accept_for_network` (USDC sample-accept builder for known CAIP-2 networks), `build_well_known_mpp`, `build_llms_txt` + `llms_txt_identity_section` + `llms_txt_payment_section` (compact + verbose modes), `build_skill_md` (Claude-Skill-compatible `/skill.md` agent-discovery manifest; strictly agent-facing data only, no internal posture), `build_redemption_skill_md` (delivery-neutral redemption-code template, printed mailers, emailed codes, API trial credits all covered; `endpoint_path`/`delivery_intro`/`body_shape`/`body_rules`/`extra_recovery_rows` overrides for non-goods shapes), `build_merchant_index_json` (canonical `/` discovery body), `standard_endpoint_descriptions(kind=)` (canonical method+path → description map for goods vs api merchants; optional `include_order_status_route` for goods), `build_success_next_steps` (universal Passport-active success block), `build_agentscore_onboarding_steps` (canonical skill.md onboarding for goods or API merchants), `agentscore_openapi_snippets`, `build_bazaar_discovery_payload`, `NoindexNonDiscoveryMiddleware` (ASGI middleware emitting `X-Robots-Tag: noindex` on every path except the agent-discovery surfaces; pure helpers `is_discovery_path` + `DEFAULT_DISCOVERY_PATHS` for non-ASGI frameworks). Plus the UCP/JWKS publish surface: `build_signed_ucp_response`, `build_signed_jwks_response`, `well_known_preflight_response`, `default_a2a_services`, `bootstrap_ucp_signing_key`, framework-neutral `SignedDiscoveryResponse` + per-framework wrappers `signed_response_{fastapi,flask,django,aiohttp,sanic}`. |
 | `agentscore_commerce.challenge` | `build_402_body`, `build_accepted_methods`, `build_identity_metadata` (auto-attached by `Checkout` when an inbound `X-Wallet-Address` header is present), `build_how_to_pay`, `build_agent_instructions` (auto-emits per-rail `compatible_clients`: smoke-verified CLIs the agent should use; vendor override supported; pure helper `compatible_clients_by_rails(rails)` returns the same map for vendors building custom 402s), `build_pricing_block` (cents to dollar-string with optional shipping/tax), `first_encounter_agent_memory` (cross-merchant hint, returns the canonical block or `None` based on a per-merchant first-seen flag), `Receipt` + `ReceiptNextSteps` + `ProductInfo` + `ShippingAddress` (canonical 200-receipt dataclasses, universal across goods + API merchants); `respond_402`, a drop-in 402 emit that preserves pympp's `WWW-Authenticate` and layers x402's `PAYMENT-REQUIRED`. `build_validation_error`: structured 4xx body builder (`{error: {code, message}, required_fields?, example_body?, next_steps?, ...extra}`) so vendors compose body shapes by name instead of inlining at every validation site. |
 | `agentscore_commerce.stripe_multichain` | `create_multichain_payment_intent` (returns `MultichainPaymentIntentResult(payment_intent_id, deposit_addresses)`; read `result.deposit_addresses[network]` directly), `create_pay_to_address_from_stripe_pi(authorization_header=, amount_cents=, stripe=, pi_cache=, networks=, static_recipients=, metadata=, order_id=, preferred_network=)`, per-order payTo resolver: on the settle leg, reuses the buyer's signed-against payTo from the MPP credential (after `pi_cache.has_address` check OR a `static_recipients` match, the static address is always-accepted because the merchant owns it); on the discovery leg, mints a fresh PI for the rails NOT covered by `static_recipients`, caches the merged map, registers static addresses with `pi_cache.cache_address` so verify-leg lookups pass. `mint_multichain_recipients(...same kwargs)`, structured variant returning `MintMultichainRecipientsResult(recipients, payment_intent_id, reused_from_credential)` for the full per-rail map (typical multi-rail merchant hook). Solana MPP requires a static recipient: pass `static_recipients={"solana": "<wallet>"}` and pre-fund its USDC ATA once from any external wallet. Rotating (per-order, Stripe-minted) Solana recipients do not settle, since the settlement transaction does not create the recipient's token account; the SDK logs a warning when one is minted. The static recipient is reused forever, each settle pays only the ~$0.001 per-tx fee, and this also sidesteps the per-call ATA rent (~$0.50 against MPP spec §13.6). `SolanaMppRailSpec.ata_creation_required` defaults to `True` (data-only; solana method registration through `create_mppx_server` is a follow-up, merchants building the solana method directly via `pympp` should pass the flag themselves to the charge factory). `simulate_crypto_deposit`; `create_pi_cache` (TTL'd PI / deposit-address cache, Redis-backed when `redis_url` set, in-memory otherwise), `simulate_deposit_if_test_mode` (gates on `sk_test_` and looks up the PI for you), `STRIPE_TEST_TX_HASH_SUCCESS` / `STRIPE_TEST_TX_HASH_FAILED` constants. Peer dep on `stripe`. |

{agentscore_commerce-2.5.2 → agentscore_commerce-2.5.4}/README.md

@@ -24,10 +24,10 @@ pip install 'agentscore-commerce[fastapi,x402,coinbase]'
 
 | Submodule | What it provides |
 |---|---|
-| `agentscore_commerce` (top-level) | `Checkout` orchestrator + `CheckoutContext` + `CheckoutGateConfig` + `CheckoutValidationError` + `DiscoveryProbeConfig` + `SettleOutcome` + `MppxComposeOutcome` + `PricingResult` (the 2.0 high-level surface: one config object, hooks for pre_validate/compute_pricing/on_settled/mint_recipients/compose_mppx, auto-derived x402+mppx servers, per-framework adapters `handle_fastapi`/`handle_flask`/`handle_django`/`handle_aiohttp`/`handle_sanic`, signed UCP routes via `mount_ucp_routes_{fastapi,flask,django,aiohttp,sanic}`); `pricing_result` (factory: cents-denominated → typed `PricingResult` with embedded `PricingBlock`); `validation_response_{fastapi,flask,django,aiohttp,sanic}` (per-framework 4xx envelope wrappers); `make_mppx_compose_hook` (canonical pympp compose adapter). |
+| `agentscore_commerce` (top-level) | `Checkout` orchestrator + `CheckoutContext` + `CheckoutGateConfig` + `CheckoutValidationError` + `DiscoveryProbeConfig` + `SettleOutcome` + `MppxComposeOutcome` + `PricingResult` (the 2.0 high-level surface: one config object, hooks for pre_validate/compute_pricing/on_settled/mint_recipients/compose_mppx, auto-derived x402+mppx servers, per-framework adapters `handle_fastapi`/`handle_flask`/`handle_django`/`handle_aiohttp`/`handle_sanic`, signed UCP routes via `mount_ucp_routes_{fastapi,flask,django,aiohttp,sanic}`); `create_result_cache` (neutral keyed JSON-value cache with a stable body-hash key builder; cache a probe-leg result, e.g. a paid upstream call made in `pre_validate`, and replay it on the settle leg) plus the compute-first-shaped `create_quote_cache` built on it; `pricing_result` (factory: cents-denominated → typed `PricingResult` with embedded `PricingBlock`); `validation_response_{fastapi,flask,django,aiohttp,sanic}` (per-framework 4xx envelope wrappers); `make_mppx_compose_hook` (canonical pympp compose adapter). |
 | `agentscore_commerce.identity.{fastapi,flask,django,aiohttp,sanic,middleware}` | Trust gate middleware: KYC, sanctions (account name + signer wallet), age, jurisdiction. `AgentScoreGate(...)` (or `agentscore_gate(app, ...)` on Flask/Sanic), `get_agentscore_data(...)`, `capture_wallet(...)`, `get_signer_verdict(...)`. The gate extracts the payment signer pre-evaluate and passes it to `/v1/assess`, so the API composes both wallet-binding (`signer_match`) and OFAC SDN wallet-address (`signer_sanctions`) verdicts on one round trip. |
 | `agentscore_commerce.identity` (package level) | Re-exports the denial helpers: `denial_reason_status`, `denial_reason_to_body`, `build_signer_mismatch_body`, `build_contact_support_next_steps`, `verification_agent_instructions`, `is_fixable_denial`, `FIXABLE_DENIAL_REASONS`. The per-framework adapter modules also expose `get_gate_quota_info(request)` for surfacing X-RateLimit info from gate state. Also re-exports the per-product policy helpers: `PolicyBlock`, `GateResult`, `EnforcementMode`, `IdentityStatus`, `build_gate_from_policy`, `run_gate_with_enforcement`, `shipping_country_allowed`, `shipping_state_allowed`, `validate_shipping_against_policy` (one-call country+state validator that raises `CheckoutValidationError` with the canonical envelope on miss), for multi-product merchants where each product carries its own compliance config: hard gate vs soft vs none, per-product shipping allowlists. Key + token helpers: `load_ucp_signing_key_from_env` (cached env-driven loader for the UCP signing key, reads `UCP_SIGNING_KEY_JWK_PRIVATE` JSON JWK, detects alg from shape, falls back to ephemeral when unset, sanitizes errors so key bytes never reach logs, concurrent-safe via `threading.Lock`; env-var names and `default_kid` / `default_alg` are overridable as kwargs); `hash_operator_token` (sha256 hex of plaintext `opc_...`, for merchants persisting `operator_token_id` to their own DB without ever storing the plaintext); `extract_owner_scope(headers) -> OwnerScope` (canonical owner-identity extractor for caller-scoped resource queries, reads `X-Wallet-Address` / `X-Operator-Token`, hashes the token so plaintext never leaves the request); `default_read_only_on_denied(reason)` (canonical `on_denied` for read-only resource gates: 401 + `Cache-Control: no-store` while still spreading `denial_reason_to_body`. Returns a `DefaultOnDeniedResult(body, status, headers)`; FastAPI / Flask / aiohttp / Sanic `on_denied` callbacks accept an optional 3-tuple `(body, status, headers)` to carry headers through; wrap with `lambda req, reason: (lambda r: (r.body, r.status, r.headers or {}))(default_read_only_on_denied(reason))`). |
-| `agentscore_commerce.payment` | `networks`, `USDC`, `rails` registries; `payment_directive`, `build_payment_directive`, `www_authenticate_header`, `payment_required_header`, `alias_amount_fields` (opt-in v1↔v2 amount-field shim that adds both `amount` and `maxAmountRequired` to an entry. The 402 builders do NOT apply it by default, strict x402 v2 settlement matches the agent's echoed requirement by exact comparison, so an extra field the server's rebuilt requirement lacks breaks settle; use only when you know a client is hardcoded to read `maxAmountRequired`), `settlement_override_header`, `dispatch_settlement_by_network`, `extract_payment_signer` (accepts positional `x402_payment_header` AND/OR `authorization_header=` kwarg; recovers signer from x402 EIP-3009 `payload.authorization.from` OR MPP `Authorization: Payment <base64>` `did:pkh:eip155:<chain>:<addr>` / `did:pkh:solana:<genesis>:<addr>` source DID), `detect_rail_from_headers` (returns `"x402"` / `"mpp"` / `None` from inbound headers), `register_x402_schemes_v1_v2`; drop-in x402 helpers: `validate_x402_network_config` (boot-time guard), `verify_x402_request` (parse + validate inbound X-Payment), `process_x402_settle` (verify-then-settle with one call), `classify_x402_settle_result` (maps the tagged settle result to a recommended HTTP status / code / next_steps so merchants get a controlled envelope without coupling to facilitator-specific error text), `classify_orchestration_error` (same `ClassifiedX402Error` shape but for uncaught exceptions thrown elsewhere in the orchestration; returns `None` for unknown errors so merchants rethrow instead of swallowing); `zero_amount_carve_out` (skip CDP / pympp upstream verify+settle for $0 settles where the upstream rejects value=0 payloads; parses the credential, lifts signer + network, returns a `ZeroSettleResult` shaped identically to the success path so callers branch on rail, not on result shape); `usd_to_atomic` (Decimal-based USD → atomic int, ROUND_HALF_UP, for Tempo / Solana / Base USDC amount construction). |
+| `agentscore_commerce.payment` | `networks`, `USDC`, `rails` registries; `payment_directive`, `build_payment_directive`, `www_authenticate_header`, `payment_required_header`, `alias_amount_fields` (opt-in v1↔v2 amount-field shim that adds both `amount` and `maxAmountRequired` to an entry. The 402 builders do NOT apply it by default, strict x402 v2 settlement matches the agent's echoed requirement by exact comparison, so an extra field the server's rebuilt requirement lacks breaks settle; use only when you know a client is hardcoded to read `maxAmountRequired`), `settlement_override_header`, `dispatch_settlement_by_network`, `extract_payment_signer` (accepts positional `x402_payment_header` AND/OR `authorization_header=` kwarg; recovers signer from x402 EIP-3009 `payload.authorization.from` OR MPP `Authorization: Payment <base64>` `did:pkh:eip155:<chain>:<addr>` / `did:pkh:solana:<genesis>:<addr>` source DID), `detect_rail_from_headers` (returns `"x402"` / `"mpp"` / `None` from inbound headers), `register_x402_schemes_v1_v2`; drop-in x402 helpers: `validate_x402_network_config` (boot-time guard), `verify_x402_request` (parse + validate inbound X-Payment), `process_x402_settle` (verify-then-settle with one call), `classify_x402_settle_result` (maps the tagged settle result to a recommended HTTP status / code / next_steps so merchants get a controlled envelope without coupling to facilitator-specific error text), `classify_orchestration_error` (same `ClassifiedX402Error` shape but for uncaught exceptions thrown elsewhere in the orchestration; returns `None` for unknown errors so merchants rethrow instead of swallowing); `zero_amount_carve_out` (skip CDP / pympp upstream verify+settle for $0 settles where the upstream rejects value=0 payloads, including credentials signed against a nonzero quote the merchant re-priced to $0 at settle; parses the credential, lifts signer + network, returns a `ZeroSettleResult` shaped identically to the success path so callers branch on rail, not on result shape), `malformed_payment_credential` (wire-shape gate: payment headers that are not base64 JSON and not token-shaped are rejected before merchant hooks run; `Checkout` applies it by default, opt out with `credential_pre_check=False`); `usd_to_atomic` (Decimal-based USD → atomic int, ROUND_HALF_UP, for Tempo / Solana / Base USDC amount construction). |
 | `agentscore_commerce.discovery` | `is_discovery_probe_request`, `build_discovery_probe_response` (with optional `x402_sample` for x402-aware crawlers like `awal x402 details`), `sample_x402_accept_for_network` (USDC sample-accept builder for known CAIP-2 networks), `build_well_known_mpp`, `build_llms_txt` + `llms_txt_identity_section` + `llms_txt_payment_section` (compact + verbose modes), `build_skill_md` (Claude-Skill-compatible `/skill.md` agent-discovery manifest; strictly agent-facing data only, no internal posture), `build_redemption_skill_md` (delivery-neutral redemption-code template, printed mailers, emailed codes, API trial credits all covered; `endpoint_path`/`delivery_intro`/`body_shape`/`body_rules`/`extra_recovery_rows` overrides for non-goods shapes), `build_merchant_index_json` (canonical `/` discovery body), `standard_endpoint_descriptions(kind=)` (canonical method+path → description map for goods vs api merchants; optional `include_order_status_route` for goods), `build_success_next_steps` (universal Passport-active success block), `build_agentscore_onboarding_steps` (canonical skill.md onboarding for goods or API merchants), `agentscore_openapi_snippets`, `build_bazaar_discovery_payload`, `NoindexNonDiscoveryMiddleware` (ASGI middleware emitting `X-Robots-Tag: noindex` on every path except the agent-discovery surfaces; pure helpers `is_discovery_path` + `DEFAULT_DISCOVERY_PATHS` for non-ASGI frameworks). Plus the UCP/JWKS publish surface: `build_signed_ucp_response`, `build_signed_jwks_response`, `well_known_preflight_response`, `default_a2a_services`, `bootstrap_ucp_signing_key`, framework-neutral `SignedDiscoveryResponse` + per-framework wrappers `signed_response_{fastapi,flask,django,aiohttp,sanic}`. |
 | `agentscore_commerce.challenge` | `build_402_body`, `build_accepted_methods`, `build_identity_metadata` (auto-attached by `Checkout` when an inbound `X-Wallet-Address` header is present), `build_how_to_pay`, `build_agent_instructions` (auto-emits per-rail `compatible_clients`: smoke-verified CLIs the agent should use; vendor override supported; pure helper `compatible_clients_by_rails(rails)` returns the same map for vendors building custom 402s), `build_pricing_block` (cents to dollar-string with optional shipping/tax), `first_encounter_agent_memory` (cross-merchant hint, returns the canonical block or `None` based on a per-merchant first-seen flag), `Receipt` + `ReceiptNextSteps` + `ProductInfo` + `ShippingAddress` (canonical 200-receipt dataclasses, universal across goods + API merchants); `respond_402`, a drop-in 402 emit that preserves pympp's `WWW-Authenticate` and layers x402's `PAYMENT-REQUIRED`. `build_validation_error`: structured 4xx body builder (`{error: {code, message}, required_fields?, example_body?, next_steps?, ...extra}`) so vendors compose body shapes by name instead of inlining at every validation site. |
 | `agentscore_commerce.stripe_multichain` | `create_multichain_payment_intent` (returns `MultichainPaymentIntentResult(payment_intent_id, deposit_addresses)`; read `result.deposit_addresses[network]` directly), `create_pay_to_address_from_stripe_pi(authorization_header=, amount_cents=, stripe=, pi_cache=, networks=, static_recipients=, metadata=, order_id=, preferred_network=)`, per-order payTo resolver: on the settle leg, reuses the buyer's signed-against payTo from the MPP credential (after `pi_cache.has_address` check OR a `static_recipients` match, the static address is always-accepted because the merchant owns it); on the discovery leg, mints a fresh PI for the rails NOT covered by `static_recipients`, caches the merged map, registers static addresses with `pi_cache.cache_address` so verify-leg lookups pass. `mint_multichain_recipients(...same kwargs)`, structured variant returning `MintMultichainRecipientsResult(recipients, payment_intent_id, reused_from_credential)` for the full per-rail map (typical multi-rail merchant hook). Solana MPP requires a static recipient: pass `static_recipients={"solana": "<wallet>"}` and pre-fund its USDC ATA once from any external wallet. Rotating (per-order, Stripe-minted) Solana recipients do not settle, since the settlement transaction does not create the recipient's token account; the SDK logs a warning when one is minted. The static recipient is reused forever, each settle pays only the ~$0.001 per-tx fee, and this also sidesteps the per-call ATA rent (~$0.50 against MPP spec §13.6). `SolanaMppRailSpec.ata_creation_required` defaults to `True` (data-only; solana method registration through `create_mppx_server` is a follow-up, merchants building the solana method directly via `pympp` should pass the flag themselves to the charge factory). `simulate_crypto_deposit`; `create_pi_cache` (TTL'd PI / deposit-address cache, Redis-backed when `redis_url` set, in-memory otherwise), `simulate_deposit_if_test_mode` (gates on `sk_test_` and looks up the PI for you), `STRIPE_TEST_TX_HASH_SUCCESS` / `STRIPE_TEST_TX_HASH_FAILED` constants. Peer dep on `stripe`. |

{agentscore_commerce-2.5.2 → agentscore_commerce-2.5.4}/agentscore_commerce/__init__.py

@@ -145,7 +145,13 @@ from agentscore_commerce.payment import (
     load_solana_fee_payer,
     read_x402_payment_header,
 )
-from agentscore_commerce.quote_cache import CachedQuote, QuoteCache, create_quote_cache
+from agentscore_commerce.quote_cache import (
+    CachedQuote,
+    QuoteCache,
+    ResultCache,
+    create_quote_cache,
+    create_result_cache,
+)
 
 try:
     __version__ = _pkg_version("agentscore-commerce")
@@ -208,6 +214,7 @@ __all__ = [
     "PolicyResult",
     "PricingResult",
     "QuoteCache",
+    "ResultCache",
     "SettleOutcome",
     "SignerNetwork",
     "SignerVerdict",
@@ -242,6 +249,7 @@ __all__ = [
     "compute_first_checkout",
     "create_default_on_denied",
     "create_quote_cache",
+    "create_result_cache",
     "default_read_only_on_denied",
     "denial_reason_status",
     "denial_reason_to_body",

{agentscore_commerce-2.5.2 → agentscore_commerce-2.5.4}/agentscore_commerce/checkout.py

@@ -90,7 +90,11 @@ from agentscore_commerce.errors import CheckoutValidationError
 from agentscore_commerce.forwarded_proto import apply_forwarded_proto, read_forwarded_proto
 from agentscore_commerce.payment.constants import STRIPE_MIN_CHARGE_USD
 from agentscore_commerce.payment.mppx_failures import classify_mppx_failure
-from agentscore_commerce.payment.payment_header import has_mppx_header, has_x402_header
+from agentscore_commerce.payment.payment_header import (
+    has_mppx_header,
+    has_x402_header,
+    malformed_payment_credential,
+)
 from agentscore_commerce.payment.rail_spec import (
     RecipientLike,
     SolanaMppRailSpec,
@@ -752,6 +756,13 @@ class Checkout:
       CDP facilitator and pympp's tempo intents both reject $0 settles outright;
       this carve-out makes free-redemption flows work uniformly across rails.
       Default ``False`` (every payment header attempts a real settle).
+    * ``credential_pre_check``; reject payment credentials that fail the cheap
+      wire-shape check (not base64 JSON, not a token-shaped value) BEFORE any
+      merchant hook runs, so junk headers never trigger ``pre_validate`` /
+      pricing / recipient minting / the gate's assess call. Shape only —
+      signature and payTo verification stay on the settle path. Default
+      ``True``; set ``False`` for custom ``compose_mppx`` implementations that
+      accept non-standard credential encodings.
     """
 
     def __init__(
@@ -776,6 +787,7 @@ class Checkout:
         on_settled: OnSettledFn | None = None,
         is_cached_address: IsCachedAddressFn | None = None,
         zero_settle_carve_out: bool = False,
+        credential_pre_check: bool = True,
         gate: CheckoutGateConfig | None = None,
         discovery_extensions: dict[str, Any] | None = None,
         resource_info: dict[str, Any] | None = None,
@@ -841,6 +853,7 @@ class Checkout:
         self.on_settled = on_settled
         self.is_cached_address = is_cached_address
         self.zero_settle_carve_out = zero_settle_carve_out
+        self.credential_pre_check = credential_pre_check
         self.gate = gate
         # Lazily-built JWKS cache for AIP verification, shared across requests so issuer keys are
         # fetched once and cached (per the verifier's hard 24h cap). Built on first AIT.
@@ -1048,6 +1061,40 @@ class Checkout:
                     settle_phase="discovery_probe",
                 )
 
+        # Credential shape gate: runs BEFORE pre_validate / the identity gate /
+        # pricing / recipient minting so a junk payment header cannot trigger
+        # merchant hooks (which may do paid upstream work) or burn an assess
+        # call. Shape only — real verification stays on the settle path, which
+        # needs per-request state the hooks produce. Scoped to the credential
+        # channels this Checkout actually dispatches on, so e.g. an x402 header
+        # at a Tempo-only merchant keeps its current discovery-leg behavior.
+        if self.credential_pre_check:
+            malformed = malformed_payment_credential(request.headers)
+            enforced = malformed is not None and (
+                (self._x402_server_available() and self._x402_base_network is not None)
+                if malformed.channel == "x402"
+                else self.compose_mppx is not None
+            )
+            if enforced and malformed is not None:
+                return CheckoutResult(
+                    status=400,
+                    body=build_validation_error(
+                        code="payment_proof_invalid",
+                        message=malformed.message,
+                        next_steps={
+                            "action": "regenerate_payment_credential",
+                            "user_message": (
+                                "The payment credential could not be decoded. "
+                                "Rebuild it from a fresh 402 challenge and retry."
+                            ),
+                        },
+                    ),
+                    headers={},
+                    reference_id=ctx.reference_id,
+                    settled=False,
+                    settle_phase="credential_malformed",
+                )
+
         # Pre-validate (optional): resolve merchant-specific per-request state
         # (product lookup, code resolution, shipping checks, ...). May raise
         # CheckoutValidationError to short-circuit with a 4xx; otherwise return

{agentscore_commerce-2.5.2 → agentscore_commerce-2.5.4}/agentscore_commerce/payment/__init__.py

@@ -21,9 +21,11 @@ from agentscore_commerce.payment.mppx_server import MppxRailSpec, create_mppx_se
 from agentscore_commerce.payment.network_kind import is_evm_network, is_solana_network
 from agentscore_commerce.payment.networks import NetworkFamily, network_family, networks
 from agentscore_commerce.payment.payment_header import (
+    MalformedPaymentCredential,
     has_mppx_header,
     has_payment_header,
     has_x402_header,
+    malformed_payment_credential,
 )
 from agentscore_commerce.payment.rail_spec import (
     RecipientLike,
@@ -95,6 +97,7 @@ __all__ = [
     "X402_SUPPORTED_BASE_NETWORKS",
     "ClassifiedX402Error",
     "CustomScheme",
+    "MalformedPaymentCredential",
     "MppxRailSpec",
     "NetworkFamily",
     "PaymentHeadersRail",
@@ -148,6 +151,7 @@ __all__ = [
     "lazy_x402_server",
     "load_solana_fee_payer",
     "lookup_rail",
+    "malformed_payment_credential",
     "network_family",
     "networks",
     "parse_did_pkh_address",

{agentscore_commerce-2.5.2 → agentscore_commerce-2.5.4}/agentscore_commerce/payment/payment_header.py

@@ -15,7 +15,12 @@ Three credential channels are checked:
 
 from __future__ import annotations
 
+import base64
+import binascii
+import json
+import re
 from collections.abc import Mapping
+from dataclasses import dataclass
 from typing import Any
 
 
@@ -94,3 +99,63 @@ def has_mppx_header(request_or_headers: Any) -> bool:
     headers = _unwrap_headers(request_or_headers)
     auth = _read_header(headers, "authorization")
     return bool(isinstance(auth, str) and auth.startswith("Payment "))
+
+
+_JWT_SHAPE_RE = re.compile(r"^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$")
+
+
+def _decodes_to_json_object(token: str) -> bool:
+    try:
+        padded = token + "=" * (-len(token) % 4)
+        try:
+            raw = base64.b64decode(padded, validate=False)
+        except (ValueError, binascii.Error):
+            raw = base64.urlsafe_b64decode(padded)
+        return isinstance(json.loads(raw.decode("utf-8")), dict)
+    except (ValueError, UnicodeDecodeError, binascii.Error):
+        return False
+
+
+@dataclass(frozen=True)
+class MalformedPaymentCredential:
+    """Which credential channel carried the malformed value, and why."""
+
+    channel: str  # "x402" | "mpp"
+    message: str
+
+
+def malformed_payment_credential(request_or_headers: Any) -> MalformedPaymentCredential | None:
+    """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 (``pre_validate``, 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 MPP 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 ``None`` when every present credential channel is plausibly shaped
+    (or no payment header is present).
+    """
+    headers = _unwrap_headers(request_or_headers)
+    x402_token = _read_header(headers, "payment-signature") or _read_header(headers, "x-payment")
+    if x402_token:
+        if not _decodes_to_json_object(x402_token):
+            return MalformedPaymentCredential(
+                channel="x402",
+                message="X-Payment header is not decodable base64 JSON.",
+            )
+        return None
+    auth = _read_header(headers, "authorization")
+    if isinstance(auth, str) and auth.startswith("Payment "):
+        token = auth[len("Payment ") :].strip()
+        if not token or (not _decodes_to_json_object(token) and not _JWT_SHAPE_RE.match(token)):
+            return MalformedPaymentCredential(
+                channel="mpp",
+                message=("Authorization: Payment credential is neither base64-encoded JSON nor a token-shaped value."),
+            )
+    return None

{agentscore_commerce-2.5.2 → agentscore_commerce-2.5.4}/agentscore_commerce/payment/zero_settle.py

@@ -2,16 +2,25 @@
 
 CDP rejects EIP-3009 ``transferWithAuthorization`` with ``value=0`` as
 ``invalid_payload``; pympp's tempo intents accept only ``hash`` and
-``transaction`` payload types (rejecting the ``proof`` payload that ``mppx``
-emits 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
+``transaction`` payload types — the wallet-bound ``proof`` payload that the
+mppx client emits for $0 settles (and that the mppx server verifies) has no
+pympp counterpart yet. Both upstream verify+settle paths therefore 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.
 
 ``zero_amount_carve_out`` is that path: parse the credential, lift the signer,
 return ``ZeroSettleResult(signer_address, signer_network, tx_hash=None)``.
 Identity is still authenticated by the merchant's gate above; the redemption
-code is single-use; nothing on-chain to verify.
+code is single-use; nothing on-chain to verify. The recovered signer block is
+UNAUTHENTICATED (parse-only) on the MPP path — treat it as an attribution
+hint, not a verified identity.
+
+Known divergence from the Node SDK: node-commerce delegates $0 Tempo settles
+to mppx's native zero-amount proof path (verified) and carves out only x402 +
+Solana. This module keeps the Tempo carve-out because pympp has no proof
+payload support; revisit when pympp ships it so both SDKs converge on
+upstream verification.
 """
 
 from __future__ import annotations

{agentscore_commerce-2.5.2 → agentscore_commerce-2.5.4}/agentscore_commerce/quote_cache.py

@@ -1,7 +1,17 @@
-"""Short-TTL body-hash quote cache for the compute-first + exact-x402 pattern.
+"""Short-TTL body-hash caches.
 
-The probe leg writes (run-work → cache); the settle leg reads (cache hit →
-settle exact at the cached price → return the cached body).
+:func:`create_result_cache` 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`` ``pre_validate`` hook, so
+a payment retry (or a junk payment header) never pays upstream twice.
+
+:func:`create_quote_cache` is the compute-first-flavored wrapper used by
+``compute_first_checkout``: the cached value is a :class:`CachedQuote`
+(``body`` / ``price_cents`` / ``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 ``dict``; optional ``redis_url`` lazy-imports
 ``redis.asyncio`` for multi-instance deployments. ``redis`` is an optional
@@ -46,6 +56,16 @@ def _canonicalize(value: Any) -> Any:
     return value
 
 
+@dataclass
+class ResultCache:
+    """Async neutral result cache returned by :func:`create_result_cache`."""
+
+    body_hash_key: Any  # (prefix: str, body: dict) -> str
+    read: Any  # (key: str) -> Any | None
+    write: Any  # (key: str, value: Any) -> None
+    clear: Any  # () -> None
+
+
 @dataclass
 class QuoteCache:
     """Async quote cache returned by :func:`create_quote_cache`."""
@@ -56,20 +76,21 @@ class QuoteCache:
     clear: Any  # () -> None
 
 
-def create_quote_cache(
+def create_result_cache(
     *,
     ttl_ms: int = DEFAULT_TTL_MS,
     redis_url: str | None = None,
-    key_prefix: str = "quote:",
-) -> QuoteCache:
-    """Build a fresh quote cache.
-
-    Each call owns its own state (memory dict + Redis client). Set
-    ``redis_url`` for a Redis-backed cache; otherwise the cache is
-    in-process only and replicas diverge under load.
+    key_prefix: str = "result:",
+) -> ResultCache:
+    """Build a fresh neutral result cache.
+
+    Each call owns its own state (memory dict + Redis client). Values must
+    survive ``json.dumps`` round-trips. Set ``redis_url`` for a Redis-backed
+    cache; otherwise the cache is in-process only and replicas diverge under
+    load.
     """
-    mem_state: dict[str, tuple[CachedQuote, float]] = {}
-    _get_redis = memoized_redis(url=redis_url, label="quote-cache")
+    mem_state: dict[str, tuple[Any, float]] = {}
+    _get_redis = memoized_redis(url=redis_url, label="result-cache")
 
     def _body_hash_key(prefix: str, body: dict[str, Any]) -> str:
         canonical = json.dumps(_canonicalize(body), separators=(",", ":"))
@@ -82,40 +103,25 @@ def create_quote_cache(
             if expires_at <= now:
                 del mem_state[k]
 
-    async def _read(key: str) -> CachedQuote | None:
+    async def _read(key: str) -> Any | None:
         r = await _get_redis()
         if r is not None:
             with contextlib.suppress(Exception):
                 raw = await r.get(f"{key_prefix}{key}")
                 if raw is None:
                     return None
-                data = json.loads(raw)
-                return CachedQuote(
-                    body=data["body"],
-                    price_cents=data["price_cents"],
-                    recipients=data.get("recipients", {}),
-                )
+                return json.loads(raw)
         _evict_expired()
         entry = mem_state.get(key)
         return entry[0] if entry else None
 
-    async def _write(
-        key: str,
-        body: dict[str, Any],
-        price_cents: float,
-        *,
-        recipients: dict[str, str] | None = None,
-    ) -> None:
-        cached = CachedQuote(body=body, price_cents=price_cents, recipients=recipients or {})
+    async def _write(key: str, value: Any) -> None:
         r = await _get_redis()
         if r is not None:
             with contextlib.suppress(Exception):
-                payload = json.dumps(
-                    {"body": cached.body, "price_cents": cached.price_cents, "recipients": cached.recipients}
-                )
-                await r.set(f"{key_prefix}{key}", payload, px=ttl_ms)
+                await r.set(f"{key_prefix}{key}", json.dumps(value), px=ttl_ms)
                 return
-        mem_state[key] = (cached, time.monotonic() * 1000 + ttl_ms)
+        mem_state[key] = (value, time.monotonic() * 1000 + ttl_ms)
 
     async def _clear() -> None:
         mem_state.clear()
@@ -124,9 +130,53 @@ def create_quote_cache(
             with contextlib.suppress(Exception):
                 await r.flushdb()
 
-    return QuoteCache(
+    return ResultCache(
         body_hash_key=_body_hash_key,
         read=_read,
         write=_write,
         clear=_clear,
     )
+
+
+def create_quote_cache(
+    *,
+    ttl_ms: int = DEFAULT_TTL_MS,
+    redis_url: str | None = None,
+    key_prefix: str = "quote:",
+) -> QuoteCache:
+    """Build a fresh quote cache (a result cache with the quote-shaped ``write``).
+
+    Each call owns its own state (memory dict + Redis client). Set
+    ``redis_url`` for a Redis-backed cache; otherwise the cache is
+    in-process only and replicas diverge under load.
+    """
+    cache = create_result_cache(ttl_ms=ttl_ms, redis_url=redis_url, key_prefix=key_prefix)
+
+    async def _read(key: str) -> CachedQuote | None:
+        data = await cache.read(key)
+        if data is None:
+            return None
+        return CachedQuote(
+            body=data["body"],
+            price_cents=data["price_cents"],
+            recipients=data.get("recipients", {}),
+        )
+
+    async def _write(
+        key: str,
+        body: dict[str, Any],
+        price_cents: float,
+        *,
+        recipients: dict[str, str] | None = None,
+    ) -> None:
+        await cache.write(
+            key,
+            {"body": body, "price_cents": price_cents, "recipients": recipients or {}},
+        )
+
+    return QuoteCache(
+        body_hash_key=cache.body_hash_key,
+        read=_read,
+        write=_write,
+        clear=cache.clear,
+    )

{agentscore_commerce-2.5.2 → agentscore_commerce-2.5.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentscore-commerce"
-version = "2.5.2"
+version = "2.5.4"
 description = "Agent commerce SDK for Python — identity middleware (FastAPI, Flask, Django, AIOHTTP, Sanic, ASGI) + payment helpers + 402 builders + discovery + Stripe multichain. The full merchant-side toolkit for AgentScore-powered agent commerce."
 readme = "README.md"
 license = "MIT"

{agentscore_commerce-2.5.2 → agentscore_commerce-2.5.4}/tests/test_aip_checkout.py

@@ -137,7 +137,7 @@ def _req(headers: dict[str, str]) -> CheckoutRequest:
     return CheckoutRequest(
         method="POST",
         url=URL,
-        headers={"x-payment": "stub-x402-payload", **headers},
+        headers={"x-payment": "eyJzdHViIjogdHJ1ZX0=", **headers},
         body={"product_id": "p1", "quantity": 1},
     )
 
@@ -608,7 +608,7 @@ class TestCheckoutAipRendererHonorsProblemJson:
     async def test_edge_deny_renders_problem_json_through_fastapi_adapter(self) -> None:
         checkout = _make_checkout(CheckoutGateConfig(api_key="as_test_key", require_kyc=True, aip=AIP))
         request = _starlette_request(
-            {"x-payment": "stub-x402-payload", "agent-identity": "eyJhbGciOiJFZERTQSJ9.e30.sig"}
+            {"x-payment": "eyJzdHViIjogdHJ1ZX0=", "agent-identity": "eyJhbGciOiJFZERTQSJ9.e30.sig"}
         )
         resp = await checkout.handle_fastapi(request)
         assert resp.status_code == 401
@@ -620,7 +620,7 @@ class TestCheckoutAipRendererHonorsProblemJson:
         # The override is AIP-only: a missing-identity denial (no Agent-Identity header) through the
         # same renderer must stay on the application/json default, untouched.
         checkout = _make_checkout(CheckoutGateConfig(api_key="as_test_key", require_kyc=True, aip=AIP))
-        request = _starlette_request({"x-payment": "stub-x402-payload"})
+        request = _starlette_request({"x-payment": "eyJzdHViIjogdHJ1ZX0="})
         resp = await checkout.handle_fastapi(request)
         assert resp.media_type == "application/json"
         body = json.loads(resp.body)
@@ -797,7 +797,7 @@ class TestCheckoutStaticGateEnforcement:
         req = CheckoutRequest(
             method="POST",
             url=URL,
-            headers={"x-payment": "stub-x402-payload"},
+            headers={"x-payment": "eyJzdHViIjogdHJ1ZX0="},
             body={"product_id": "p1", "quantity": 1},
             raw=object(),
         )