agentscore-commerce 2.1.1__tar.gz → 2.3.0__tar.gz

{agentscore_commerce-2.1.1 → agentscore_commerce-2.3.0}/.github/workflows/security.yml

@@ -27,7 +27,10 @@ jobs:
           chmod +x osv-scanner
 
       - name: Scan dependencies
-        run: ./osv-scanner scan source --lockfile=uv.lock --format=table
+        # `--config osv-scanner.toml` honors the in-repo allowlist (e.g. PYSEC-2025-183;
+        # see the toml for justifications). Keep the pip-audit `--ignore-vuln` flags below
+        # in sync with the same IDs.
+        run: ./osv-scanner scan source --lockfile=uv.lock --config=osv-scanner.toml --format=table
 
   pip-audit:
     name: Python Audit
@@ -44,6 +47,9 @@ jobs:
         run: pip install pip-audit
 
       - name: Audit dependencies
+        # `--ignore-vuln` allowlist mirrors `osv-scanner.toml` (e.g. PYSEC-2025-183;
+        # see that file for justifications). Keep both lists in sync.
         run: |
           uv export --format requirements-txt --no-hashes > requirements.txt
-          pip-audit -r requirements.txt --disable-pip --no-deps
+          pip-audit -r requirements.txt --disable-pip --no-deps \
+            --ignore-vuln PYSEC-2025-183

{agentscore_commerce-2.1.1 → agentscore_commerce-2.3.0}/CLAUDE.md

@@ -14,7 +14,7 @@ Every helper is extracted from a real consumer, not speculated.
 | `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.discovery` | Discovery probe (`is_discovery_probe_request`, `build_discovery_probe_response`), Bazaar wrapper, `/.well-known/mpp.json`, `llms.txt` builder, `skill.md` builder (Claude-Skill-compatible agent-discovery manifest), `build_redemption_skill_md` (delivery-neutral; printed/emailed/API-trial codes all covered via `delivery_intro`/`body_shape`/`body_rules`/`extra_recovery_rows` overrides), `build_merchant_index_json` + `standard_endpoint_descriptions(kind=)` (canonical `/` discovery body for goods or API merchants), `build_success_next_steps` (universal Passport-active success block), `build_agentscore_onboarding_steps`, OpenAPI snippets, `NoindexNonDiscoveryMiddleware` ASGI middleware. 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` | 402-body builders: accepted_methods, identity_metadata (auto-attached by `Checkout` when wallet header present), how_to_pay, agent_instructions, build_402_body, pricing, agent_memory, `build_validation_error` (4xx body builder), `Receipt`/`ReceiptNextSteps`/`ProductInfo`/`ShippingAddress` (canonical 200-receipt dataclasses) |
-| `agentscore_commerce.stripe_multichain` | Multichain PaymentIntent helper (`create_multichain_payment_intent` returns `MultichainPaymentIntentResult`; read `result.deposit_addresses[network]` directly), `create_pay_to_address_from_stripe_pi(authorization_header=, amount_cents=, stripe=, pi_cache=, networks=, metadata=, order_id=, preferred_network=)` — one-call per-order payTo resolver matching `Checkout.mint_recipients`: on the settle leg, reuses the buyer's signed-against payTo from the MPP credential (after `pi_cache.has_address` check); on the discovery leg, mints a fresh PI via `create_multichain_payment_intent` and caches the addresses + PI mapping. Testnet simulator (`simulate_crypto_deposit`, `simulate_deposit_if_test_mode`), `simulate_deposit_for_outcome(outcome=, deposit_address=, get_payment_intent_id=, stripe_secret_key=, stripe_version=)` (dispatches the simulator based on a Checkout / compute_first_checkout settle outcome; replaces the per-merchant rail-switch + thin `simulate_deposit_if_testnet(addr, network)` wrapper), `network_for_outcome` (outcome → simulator network arg, handles both Checkout-shaped `rail_key` and compute-first-shaped `mpp_method`, accepts bare scheme names AND `<scheme>/charge` forms), `create_pi_cache`, `create_mppx_stripe` |
+| `agentscore_commerce.stripe_multichain` | Multichain PaymentIntent helper (`create_multichain_payment_intent` returns `MultichainPaymentIntentResult`; 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=)` — one-call per-order payTo resolver matching `Checkout.mint_recipients`: 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`. `mint_multichain_recipients(...same kwargs) -> MintMultichainRecipientsResult(recipients, payment_intent_id, reused_from_credential)` — structured variant returning the full per-rail map; prefer this when the merchant's `mint_recipients` hook needs all rail addresses (typical multi-rail merchant), and to avoid the "returned-string-is-ambiguous" trap on the settle leg when `static_recipients` is configured. Use `static_recipients={"solana": "<wallet>"}` for low-margin endpoints where rotating per-PI Solana addresses can't absorb MPP spec §13.6's ~$0.50 ATA rent per call — the SDK skips Stripe minting on that network and reuses the static recipient forever; pair with a one-time external USDC pre-funding of the recipient's ATA and every settle pays only the per-tx fee. `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). Testnet simulator (`simulate_crypto_deposit`, `simulate_deposit_if_test_mode`), `simulate_deposit_for_outcome(outcome=, deposit_address=, get_payment_intent_id=, stripe_secret_key=, stripe_version=)` (dispatches the simulator based on a Checkout / compute_first_checkout settle outcome; replaces the per-merchant rail-switch + thin `simulate_deposit_if_testnet(addr, network)` wrapper), `network_for_outcome` (outcome → simulator network arg, handles both Checkout-shaped `rail_key` and compute-first-shaped `mpp_method`, accepts bare scheme names AND `<scheme>/charge` forms), `create_pi_cache`, `create_mppx_stripe` |
 | `agentscore_commerce.api` | Re-exports `AgentScore` from `agentscore` SDK |
 | `agentscore_commerce.middleware.{fastapi,flask,django,aiohttp,sanic,asgi}` | Framework-specific rate-limit middleware. FastAPI exposes `rate_limit_fastapi(...)` (FastAPI dependency) plus the ASGI `RateLimitMiddleware` re-export; Flask exposes `rate_limit_flask(app, ...)` (installs a `before_request` hook); Django exposes a class-based async `RateLimitMiddleware` configured via `settings.AGENTSCORE_RATE_LIMIT`; aiohttp exposes `rate_limit_aiohttp(...)` middleware factory; Sanic exposes `rate_limit_sanic(app, ...)` installer; `asgi.RateLimitMiddleware` is a generic ASGI middleware that works with any starlette-compatible app. Shared options: `window_seconds` (default 60), `max_requests` (default 60), `key_resolver` (default first hop of `x-forwarded-for`), `redis_url` (lazy-imports `redis.asyncio` when set, in-memory `dict` fallback otherwise), `key_prefix`. `redis` is an optional peer dep (install via the `redis` extra). |
 
@@ -88,7 +88,11 @@ Two identity types: wallet (`X-Wallet-Address`) and operator-token (`X-Operator-
 
 Captured wallets: `capture_wallet(...)` is fire-and-forget. Reads `operator_token` stashed during gating and POSTs to `/v1/credentials/wallets`. No-ops for wallet-authenticated requests.
 
-Wallet-signer-match + signer-sanctions: the gate adapter calls `extract_payment_signer(x402_header)` pre-evaluate and passes `signer={address, network}` to the SDK's `assess`. The API returns both `signer_match` (wallet-binding) and `signer_sanctions` (OFAC SDN wallet-address) on the same response; commerce caches the raw body alongside the projected verdicts so `get_signer_verdict` is a pure cache read. Under `policy.require_sanctions_clear`, an OFAC SDN signer hit already flips `decision -> deny` before the handler runs.
+Wallet-signer-match + signer-sanctions: the gate adapter calls `extract_payment_signer(x402_header)` pre-evaluate and passes `signer={address, network}` to the SDK's `assess`. The API returns both `signer_match` (wallet-binding) and `signer_sanctions` (OFAC SDN wallet-address) on the same response; commerce caches the raw body alongside the projected verdicts so `get_signer_verdict` is a pure cache read. **Wallet-OFAC SDN enforcement on the `signer` block is unconditional** whenever a signer is present — no `policy.require_sanctions_clear` opt-in required. An SDN hit (or `sanctions_check_unavailable`) flips `decision -> deny` and the gate returns 403 before the handler runs.
+
+### Always-on wallet OFAC default for gateless merchants
+
+Merchants who do NOT configure a `gate` on `Checkout` (or `compute_first_checkout`) still get wallet OFAC SDN enforcement on every settle leg. The SDK resolves the API key from `AGENTSCORE_API_KEY` (or `gate.api_key` if a partial gate config is present), reads `AGENTSCORE_BASE_URL` for staging/dev overrides, extracts the payment signer, and calls `/v1/assess` with the signer block. SDN hit → 403 with `wallet_not_trusted` + `decision_reasons: ["sanctions_flagged"]`. No key → one-time `[checkout]` / `[<name>.compute_first]` warning + skip (dev/testnet pattern; see `agentscore_commerce/_warnings.py`). Stripe SPT (no extractable wallet signer) skips silently — Stripe runs its own OFAC screen at customer creation. `_has_identity_gate()` detects identity-bearing flags (`require_kyc`, `require_sanctions_clear`, `min_age`, `allowed/blocked_jurisdictions`); when none are set, the 402 body omits `agent_memory` and per-rail commands strip the `-H 'X-Operator-Token: ...'` flag (gateless merchants have no operator to identify). Gate configured WITHOUT `api_key` falls through to the wallet-OFAC-only path so the merchant gets the strict-liability floor instead of silently allowing.
 
 ### Fail-open (opt-in)
 

{agentscore_commerce-2.1.1 → agentscore_commerce-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentscore-commerce
-Version: 2.1.1
+Version: 2.3.0
 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://agentscore.sh
 Project-URL: Repository, https://github.com/agentscore/python-commerce
@@ -78,7 +78,7 @@ pip install 'agentscore-commerce[fastapi,x402,coinbase]'
 | `agentscore_commerce.payment` | `networks`, `USDC`, `rails` registries; `payment_directive`, `build_payment_directive`, `www_authenticate_header`, `payment_required_header`, `alias_amount_fields` (v1↔v2 amount field shim that emits both `amount` and `maxAmountRequired` so v1-only x402 parsers like Coinbase awal can read v2 bodies), `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.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=, 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); on the discovery leg, mints a fresh PI and caches it. `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.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). Use `static_recipients={"solana": "<wallet>"}` for low-margin endpoints where Solana per-call ATA rent (~$0.50 against MPP spec §13.6) dominates revenue — the SDK skips Stripe minting on that network, reuses the static recipient forever, and (with a one-time external pre-funding of the recipient's USDC ATA) lets every settle pay only the ~$0.001 per-tx fee. `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.api` | Everything from `agentscore-py` re-exported in one place: `AgentScore` + `AgentScoreError`, `AGENTSCORE_TEST_ADDRESSES` + `is_agentscore_test_address`. **Don't add `agentscore-py` as a separate dep**: the two can drift versions and cause subtle type mismatches. |
 | `agentscore_commerce.middleware.{fastapi,flask,django,aiohttp,sanic,asgi}` | Framework-specific rate-limit middleware. FastAPI: `rate_limit_fastapi(...)` (FastAPI dependency) plus the ASGI `RateLimitMiddleware` re-export. Flask: `rate_limit_flask(app, ...)` installer. Django: class-based async `RateLimitMiddleware` configured via `settings.AGENTSCORE_RATE_LIMIT`. aiohttp: `rate_limit_aiohttp(...)` middleware factory. Sanic: `rate_limit_sanic(app, ...)` installer. `asgi.RateLimitMiddleware` works with any starlette-compatible app. Shared options: `window_seconds` (default 60), `max_requests` (default 60), `key_resolver` (default first hop of `x-forwarded-for`), `redis_url` (lazy-imports `redis.asyncio` when set, in-memory `dict` fallback otherwise), `key_prefix`. `redis` is an optional peer dep (install via the `redis` extra). |
 

{agentscore_commerce-2.1.1 → agentscore_commerce-2.3.0}/README.md

@@ -30,7 +30,7 @@ pip install 'agentscore-commerce[fastapi,x402,coinbase]'
 | `agentscore_commerce.payment` | `networks`, `USDC`, `rails` registries; `payment_directive`, `build_payment_directive`, `www_authenticate_header`, `payment_required_header`, `alias_amount_fields` (v1↔v2 amount field shim that emits both `amount` and `maxAmountRequired` so v1-only x402 parsers like Coinbase awal can read v2 bodies), `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.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=, 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); on the discovery leg, mints a fresh PI and caches it. `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.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). Use `static_recipients={"solana": "<wallet>"}` for low-margin endpoints where Solana per-call ATA rent (~$0.50 against MPP spec §13.6) dominates revenue — the SDK skips Stripe minting on that network, reuses the static recipient forever, and (with a one-time external pre-funding of the recipient's USDC ATA) lets every settle pay only the ~$0.001 per-tx fee. `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.api` | Everything from `agentscore-py` re-exported in one place: `AgentScore` + `AgentScoreError`, `AGENTSCORE_TEST_ADDRESSES` + `is_agentscore_test_address`. **Don't add `agentscore-py` as a separate dep**: the two can drift versions and cause subtle type mismatches. |
 | `agentscore_commerce.middleware.{fastapi,flask,django,aiohttp,sanic,asgi}` | Framework-specific rate-limit middleware. FastAPI: `rate_limit_fastapi(...)` (FastAPI dependency) plus the ASGI `RateLimitMiddleware` re-export. Flask: `rate_limit_flask(app, ...)` installer. Django: class-based async `RateLimitMiddleware` configured via `settings.AGENTSCORE_RATE_LIMIT`. aiohttp: `rate_limit_aiohttp(...)` middleware factory. Sanic: `rate_limit_sanic(app, ...)` installer. `asgi.RateLimitMiddleware` works with any starlette-compatible app. Shared options: `window_seconds` (default 60), `max_requests` (default 60), `key_resolver` (default first hop of `x-forwarded-for`), `redis_url` (lazy-imports `redis.asyncio` when set, in-memory `dict` fallback otherwise), `key_prefix`. `redis` is an optional peer dep (install via the `redis` extra). |
 

agentscore_commerce-2.3.0/agentscore_commerce/_warnings.py

@@ -0,0 +1,39 @@
+"""Shared one-shot warning helpers for the SDK.
+
+Module-level state ensures each warning fires at most once per process,
+regardless of how many ``Checkout`` / ``compute_first_checkout`` instances
+trigger it. Mirrors ``node-commerce/src/_warnings.ts``.
+"""
+
+from __future__ import annotations
+
+import logging
+
+_warned_no_api_key = False
+
+
+def warn_missing_api_key_once(label: str) -> None:
+    """Emit a one-time warning when AGENTSCORE_API_KEY is unset.
+
+    Triggered on a settle path that would otherwise enforce wallet OFAC SDN
+    sanctions. Both ``Checkout`` and ``compute_first_checkout`` route through
+    this so a single multi-surface app sees the warning ONCE, not once per
+    surface.
+
+    ``label`` is the caller's identifier for the log message; e.g.
+    ``"checkout"`` or the compute-first handler's ``name``.
+    """
+    global _warned_no_api_key
+    if _warned_no_api_key:
+        return
+    _warned_no_api_key = True
+    logging.getLogger(__name__).warning(
+        f"[{label}] AGENTSCORE_API_KEY is not set — wallet OFAC SDN sanctions are NOT being enforced. "
+        "Set the env var to enable strict-liability protection on settle."
+    )
+
+
+def _reset_warned_no_api_key() -> None:
+    """Test-only: reset the warn-once flag."""
+    global _warned_no_api_key
+    _warned_no_api_key = False

{agentscore_commerce-2.1.1 → agentscore_commerce-2.3.0}/agentscore_commerce/challenge/how_to_pay.py

@@ -43,7 +43,7 @@ async def build_how_to_pay(
     retry_body_json: str,
     total_usd: float | str,
     rails: dict[str, TempoRailSpec | X402BaseRailSpec | SolanaMppRailSpec | StripeRailSpec],
-    op_token_placeholder: str = "<your_opc_token>",  # noqa: S107 — literal placeholder, not a secret
+    op_token_placeholder: str | None = "<your_opc_token>",  # noqa: S107 — literal placeholder, not a secret
     max_spend: float | str | None = None,
     decimals: int = 2,
 ) -> dict[str, Any]:
@@ -62,6 +62,12 @@ async def build_how_to_pay(
     ≥ $1 the default is still ``ceil(total) + 1`` formatted at ``decimals``; for
     sub-dollar totals the default uses ``total.toFixed(decimals)`` so the cap
     flag reflects the real amount instead of always being ``"1.00"``.
+
+    ``op_token_placeholder`` defaults to ``"<your_opc_token>"``. Pass ``None``
+    (gateless merchants) to strip the ``-H 'X-Operator-Token: ...'`` snippet
+    from every rail command — appropriate when the merchant doesn't run an
+    identity gate. The wallet OFAC SDN default (TEC-311) does NOT need an
+    operator token, so gateless merchants emit cleaner commands.
     """
     total_num = float(total_usd) if isinstance(total_usd, str) else total_usd
     if max_spend is not None:
@@ -70,7 +76,9 @@ async def build_how_to_pay(
         max_spend_str = f"{math.ceil(total_num) + 1:.{decimals}f}"
     else:
         max_spend_str = f"{total_num:.{decimals}f}"
-    op_token = op_token_placeholder
+    gateless = op_token_placeholder is None
+    op_token = op_token_placeholder or "<your_opc_token>"
+    op_token_header_flag = "" if gateless else f"-H 'X-Operator-Token: {op_token}' "
     block: dict[str, Any] = {}
 
     tempo = rails.get("tempo")
@@ -79,11 +87,11 @@ async def build_how_to_pay(
         chain_id = tempo.chain_id
         recommend = tempo.recommend
         tempo_command = (
-            f"tempo request -X POST -H 'X-Operator-Token: {op_token}' -H 'Content-Type: application/json' "
+            f"tempo request -X POST {op_token_header_flag}-H 'Content-Type: application/json' "
             f"--json '{retry_body_json}' --max-spend {max_spend_str} {url}"
         )
         pay_command = (
-            f"agentscore-pay pay POST {url} --chain tempo -H 'X-Operator-Token: {op_token}' "
+            f"agentscore-pay pay POST {url} --chain tempo {op_token_header_flag}"
             f"-H 'Content-Type: application/json' -d '{retry_body_json}' --max-spend {max_spend_str}"
         )
         entry: dict[str, Any] = {
@@ -115,7 +123,7 @@ async def build_how_to_pay(
                 f"least ${max_spend_str}. If the CLI is not installed, run the setup commands above first."
             ),
             "command": (
-                f"agentscore-pay pay POST {url} --chain base -H 'X-Operator-Token: {op_token}' "
+                f"agentscore-pay pay POST {url} --chain base {op_token_header_flag}"
                 f"-H 'Content-Type: application/json' -d '{retry_body_json}' --max-spend {max_spend_str}"
             ),
             "what_it_does": (
@@ -135,7 +143,7 @@ async def build_how_to_pay(
                 f"is at least ${max_spend_str}. If the CLI is not installed, run the setup commands above first."
             ),
             "command": (
-                f"agentscore-pay pay POST {url} --chain solana -H 'X-Operator-Token: {op_token}' "
+                f"agentscore-pay pay POST {url} --chain solana {op_token_header_flag}"
                 f"-H 'Content-Type: application/json' -d '{retry_body_json}' --max-spend {max_spend_str}"
             ),
             "what_it_does": (
@@ -182,6 +190,9 @@ async def build_how_to_pay(
                 ),
                 (
                     f"link-cli mpp pay {url} --spend-request-id $SPEND_ID --method POST "
+                    f"--data '{retry_body_json}' --output-json"
+                    if gateless
+                    else f"link-cli mpp pay {url} --spend-request-id $SPEND_ID --method POST "
                     f"--data '{retry_body_json}' --header 'X-Operator-Token: {op_token}' --output-json"
                 ),
             ]

{agentscore_commerce-2.1.1 → agentscore_commerce-2.3.0}/agentscore_commerce/checkout.py

@@ -706,6 +706,30 @@ class Checkout:
         body's ``extensions`` field so Bazaar crawlers and other spec-compliant
         clients read the route's declared input/output schema."""
 
+    def _has_identity_gate(self) -> bool:
+        """Return True when the merchant configured an identity-bearing flag.
+
+        The identity-bearing flags are ``require_kyc``, ``require_sanctions_clear``
+        (name screening on the KYC identity), ``min_age``, or jurisdiction
+        lists. Wallet OFAC SDN enforcement (the always-on default) does NOT
+        count as an identity gate; agents don't need an AgentScore credential
+        to satisfy it.
+
+        Used to conditionally emit AgentScore identity boilerplate in 402
+        bodies (``agent_memory``, ``X-Operator-Token`` references in per-rail
+        commands).
+        """
+        g = self.gate
+        if g is None:
+            return False
+        return bool(
+            g.require_kyc
+            or g.require_sanctions_clear
+            or g.min_age is not None
+            or (g.allowed_jurisdictions and len(g.allowed_jurisdictions) > 0)
+            or (g.blocked_jurisdictions and len(g.blocked_jurisdictions) > 0)
+        )
+
     async def _get_x402_server(self) -> Any:
         """Resolve the x402 server.
 
@@ -899,13 +923,22 @@ class Checkout:
 
         ctx.pricing = await _maybe_await(self.compute_pricing(ctx))
 
-        # Per-request gate: runs on the settle leg only (anonymous discovery
-        # passes through to 402). Sets ctx.assess["identity_status"]; 403s
-        # short-circuit. Merchant-supplied per_request_policy resolves the
-        # policy block (read from the product row, tier, etc.).
+        # Per-request compliance: runs on the settle leg only (anonymous
+        # discovery passes through to 402).
+        #
+        # Two paths converge here:
+        #   - Merchants with an explicit ``gate`` config run the full identity
+        #     policy (KYC / age / sanctions / jurisdiction) via ``_run_gate``.
+        #   - Merchants WITHOUT a ``gate`` config still get wallet OFAC SDN
+        #     enforcement via ``_run_wallet_sanctions_only`` — the always-on
+        #     strict-liability default. Falls back to AGENTSCORE_API_KEY env
+        #     var when set; logs a warning and skips when no key is set
+        #     (dev/testnet pattern).
         has_payment_header = has_x402_header(request.headers) or has_mppx_header(request.headers)
-        if self.gate is not None and has_payment_header:
-            gate_result = await self._run_gate(ctx)
+        if has_payment_header:
+            gate_result = (
+                await self._run_gate(ctx) if self.gate is not None else await self._run_wallet_sanctions_only(ctx)
+            )
             if gate_result is not None:
                 return gate_result
 
@@ -1402,6 +1435,13 @@ class Checkout:
             result = await _maybe_await(gate.run_gate(ctx))
             return self._coerce_run_gate_result(ctx, result)
 
+        # Gate configured without an API key — full policy enforcement requires
+        # /v1/assess access, which we can't reach. Fall through to wallet OFAC
+        # SDN enforcement (the strict-liability default) so the merchant still
+        # gets the basic protection layer instead of silently allowing.
+        if not gate.api_key:
+            return await self._run_wallet_sanctions_only(ctx)
+
         # 2. per_request_policy resolves per-product compliance (e.g. wine vs
         # generic merch). Return None to skip the gate entirely for this request.
         policy: Any = None
@@ -1500,6 +1540,117 @@ class Checkout:
         )
         return None
 
+    async def _run_wallet_sanctions_only(self, ctx: CheckoutContext) -> CheckoutResult | None:
+        """Wallet OFAC SDN enforcement.
+
+        Runs on settle (payment header present) when either ``self.gate`` is
+        None OR a gate is configured but has no ``api_key`` to reach
+        ``/v1/assess`` for full policy enforcement (fallback to the
+        strict-liability default).
+
+        Env knobs:
+          - ``AGENTSCORE_API_KEY`` — required. No key → one-time warning + skip
+            (dev/testnet pattern; production should always configure a key).
+          - ``AGENTSCORE_BASE_URL`` — optional override for staging/dev API
+            (e.g. ``https://api-dev.agentscore.sh`` or ``http://localhost:3002``).
+
+        Stripe SPT (no extractable wallet signer) → skip silently; Stripe runs
+        its own OFAC screen on the buyer's Stripe account at customer creation.
+
+        Calls ``/v1/assess`` with the signer wallet as both the primary address
+        and the signer block. The API enforces signer-sanctions unconditionally
+        when a signer is present (no policy flag needed). Denies on OFAC SDN
+        hit; fail-closed on unavailable lookup (strict liability — falsely
+        allowing a sanctioned settle is an OFAC violation, falsely denying a
+        clean buyer is just bad UX).
+        """
+        import os
+
+        from agentscore_commerce._warnings import warn_missing_api_key_once
+
+        api_key = (self.gate.api_key if self.gate is not None else None) or os.environ.get("AGENTSCORE_API_KEY")
+        if not api_key:
+            warn_missing_api_key_once("checkout")
+            return None
+
+        from agentscore_commerce.payment.signer import extract_payment_signer, read_x402_payment_header
+
+        x402_header = read_x402_payment_header(ctx.request.headers)
+        authorization_header: str | None = None
+        for header_key, header_value in ctx.request.headers.items():
+            if header_key.lower() == "authorization":
+                authorization_header = header_value
+                break
+        signer = extract_payment_signer(x402_header, authorization_header=authorization_header)
+        if signer is None:
+            # Stripe SPT path — no wallet signer, no OFAC check possible. Stripe
+            # screens its own customer accounts; we have nothing to add here.
+            return None
+
+        from agentscore_commerce.api import AgentScore
+        from agentscore_commerce.identity._denial import denial_reason_status
+        from agentscore_commerce.identity._response import denial_reason_to_body
+        from agentscore_commerce.identity.types import DenialReason
+
+        base_url = os.environ.get("AGENTSCORE_BASE_URL")
+        client_kwargs: dict[str, Any] = {"api_key": api_key}
+        if base_url:
+            client_kwargs["base_url"] = base_url
+        client = AgentScore(**client_kwargs)
+        from agentscore.errors import (
+            AgentScoreError,
+            InvalidCredentialError,
+            TokenExpiredError,
+        )
+
+        try:
+            result = await client.aassess(
+                address=signer.address,
+                signer={"address": signer.address, "network": signer.network},
+            )
+        except (TokenExpiredError, InvalidCredentialError) as err:
+            # 401 — credential issues map to invalid_credential. These are
+            # unusual on the wallet-OFAC-only path (no operator_token) but
+            # carried for parity with node's mapping.
+            reason = DenialReason(
+                code="invalid_credential" if isinstance(err, InvalidCredentialError) else "token_expired",
+                message=str(err),
+            )
+            return CheckoutResult(
+                status=denial_reason_status(reason),
+                body=denial_reason_to_body(reason),
+                headers={},
+                reference_id=ctx.reference_id,
+                settled=False,
+            )
+        except (AgentScoreError, Exception) as err:
+            # 503 — API outage or network failure. Fail-closed: strict-liability.
+            reason = DenialReason(code="api_error", message=str(err))
+            return CheckoutResult(
+                status=denial_reason_status(reason),
+                body=denial_reason_to_body(reason),
+                headers={},
+                reference_id=ctx.reference_id,
+                settled=False,
+            )
+
+        decision = result.get("decision") if isinstance(result, dict) else None
+        if decision == "deny":
+            decision_reasons = result.get("decision_reasons") or [] if isinstance(result, dict) else []
+            reason = DenialReason(
+                code="wallet_not_trusted",
+                reasons=list(decision_reasons),
+                decision=decision,
+            )
+            return CheckoutResult(
+                status=denial_reason_status(reason),
+                body=denial_reason_to_body(reason),
+                headers={},
+                reference_id=ctx.reference_id,
+                settled=False,
+            )
+        return None
+
     def _coerce_run_gate_result(
         self,
         ctx: CheckoutContext,
@@ -1849,6 +2000,10 @@ class Checkout:
             total_usd=f"{ctx.pricing.amount_usd:.{pricing_decimals}f}",
             rails=how_to_pay_rails,
             decimals=pricing_decimals,
+            # Merchants without an identity-bearing policy flag get clean commands
+            # without an X-Operator-Token header — agents don't need one to satisfy
+            # wallet OFAC enforcement (the always-on default per TEC-311).
+            op_token_placeholder=None if not self._has_identity_gate() else "<your_opc_token>",
         )
         pricing_block = ctx.pricing.block or build_pricing_block(
             subtotal_cents=ctx.pricing.amount_usd * 100,
@@ -1898,7 +2053,10 @@ class Checkout:
             pricing=pricing_block,
             amount_usd=f"{ctx.pricing.amount_usd:.{pricing_decimals}f}",
             retry_body=ctx.request.body,
-            agent_memory=first_encounter_agent_memory(first_encounter=True),
+            # Merchants without an identity-bearing gate get a clean 402: no
+            # AgentScore-identity bootstrap describing a verification flow they
+            # don't run. Wallet OFAC (the always-on default) doesn't need it.
+            agent_memory=first_encounter_agent_memory(first_encounter=self._has_identity_gate()),
             product=ctx.pricing.product,
             extra=ctx.pricing.body_extras,
             x402=X402PaymentRequired(

{agentscore_commerce-2.1.1 → agentscore_commerce-2.3.0}/agentscore_commerce/checkout_compute_first.py

@@ -34,7 +34,7 @@ from __future__ import annotations
 import logging
 import uuid
 from dataclasses import dataclass, field
-from datetime import datetime, timezone
+from datetime import UTC, datetime, timezone
 from decimal import Decimal
 from typing import TYPE_CHECKING, Any
 
@@ -434,6 +434,91 @@ class ComputeFirstCheckout:
         )
         return 402, body_402, headers
 
+    async def _enforce_wallet_sanctions(
+        self,
+        request: ComputeFirstRequest,
+        reference_id: str,
+    ) -> tuple[int, dict[str, Any], dict[str, str]] | None:
+        """Always-on wallet OFAC SDN enforcement for compute-first merchants.
+
+        Mirrors :meth:`Checkout._run_wallet_sanctions_only`. Resolves API key
+        from ``AGENTSCORE_API_KEY``, optional base URL from
+        ``AGENTSCORE_BASE_URL``, extracts the signer from the payment header,
+        calls ``/v1/assess`` with the signer block (no policy). Denies on SDN
+        hit or unavailable lookup. Skips silently for Stripe SPT (no wallet
+        signer) and when no API key is set (log-once warning).
+        """
+        import os
+
+        from agentscore_commerce._warnings import warn_missing_api_key_once
+
+        api_key = os.environ.get("AGENTSCORE_API_KEY")
+        if not api_key:
+            warn_missing_api_key_once(f"{self.name}.compute_first")
+            return None
+
+        from agentscore_commerce.payment.signer import extract_payment_signer, read_x402_payment_header
+
+        x402_header = read_x402_payment_header(request.headers)
+        authorization_header: str | None = None
+        for header_key, header_value in request.headers.items():
+            if header_key.lower() == "authorization":
+                authorization_header = header_value
+                break
+        signer = extract_payment_signer(x402_header, authorization_header=authorization_header)
+        if signer is None:
+            return None  # Stripe SPT — no wallet signer to screen
+
+        from agentscore_commerce.api import AgentScore
+
+        base_url = os.environ.get("AGENTSCORE_BASE_URL")
+        client_kwargs: dict[str, Any] = {"api_key": api_key}
+        if base_url:
+            client_kwargs["base_url"] = base_url
+        client = AgentScore(**client_kwargs)
+
+        from agentscore_commerce.identity._denial import denial_reason_status
+        from agentscore_commerce.identity._response import denial_reason_to_body
+        from agentscore_commerce.identity.types import DenialReason
+
+        denial_reason: DenialReason | None = None
+        try:
+            result = await client.aassess(
+                address=signer.address,
+                signer={"address": signer.address, "network": signer.network},
+            )
+        except Exception as err:
+            denial_reason = DenialReason(code="api_error", message=str(err))
+            result = None
+
+        if denial_reason is None:
+            decision = result.get("decision") if isinstance(result, dict) else None
+            if decision == "deny":
+                decision_reasons = list(result.get("decision_reasons") or []) if isinstance(result, dict) else []
+                denial_reason = DenialReason(
+                    code="wallet_not_trusted",
+                    reasons=decision_reasons,
+                    decision=decision,
+                )
+
+        if denial_reason is not None:
+            # Spread denial_reason_to_body so agent_instructions / verify_url
+            # ride through (parity with node's enforceWalletSanctions which
+            # spreads denialReasonToBody into the compute-first envelope).
+            denial_body = denial_reason_to_body(denial_reason)
+            return (
+                denial_reason_status(denial_reason),
+                {
+                    "id": reference_id,
+                    "endpoint": self.name,
+                    "created_at": datetime.now(UTC).isoformat(),
+                    "payment_status": "failed",
+                    **denial_body,
+                },
+                {"Content-Type": "application/json"},
+            )
+        return None
+
     async def _handle_x402_settle(
         self,
         request: ComputeFirstRequest,
@@ -693,6 +778,13 @@ class ComputeFirstCheckout:
                     {"Content-Type": "application/json"},
                 )
             recipients = quote.recipients if hasattr(quote, "recipients") else {}
+            # Wallet OFAC SDN enforcement (always-on default — mirrors
+            # Checkout._run_wallet_sanctions_only). Strict-liability check
+            # before the rail-specific settle so funds don't move (x402) or
+            # order doesn't fulfill (MPP) for a sanctioned wallet.
+            ofac_denial = await self._enforce_wallet_sanctions(request, reference_id)
+            if ofac_denial is not None:
+                return ofac_denial
             if has_x402_header(request.headers):
                 return await self._handle_x402_settle(
                     request, reference_id, quote.body, int(quote.price_cents), recipients

{agentscore_commerce-2.1.1 → agentscore_commerce-2.3.0}/agentscore_commerce/identity/core.py

@@ -415,10 +415,10 @@ class AgentScoreCore:
         request — single round trip. Returns ``None`` when the gate didn't run with
         a signer (operator-token-only paths, discovery legs).
 
-        Under ``policy.require_sanctions_clear``, OFAC SDN wallet-address hits are
-        already enforced by the gate (decision -> deny before the handler runs);
-        merchant code typically only needs this for the signer_match wallet-binding
-        verdict.
+        Wallet-OFAC SDN enforcement is unconditional whenever a signer is in the
+        request — SDN wallet-address hits are already enforced by the gate
+        (decision -> deny before the handler runs); merchant code typically only
+        needs this for the signer_match wallet-binding verdict.
         """
         claimed_norm = normalize_address(claimed_address)
         key = self._cache_key(address=claimed_norm)

{agentscore_commerce-2.1.1 → agentscore_commerce-2.3.0}/agentscore_commerce/identity/middleware.py

@@ -322,10 +322,10 @@ def get_signer_verdict(request: Request) -> SignerVerdict | None:
     Returns ``None`` when the gate didn't run with a signer: operator-token-only paths,
     discovery legs that arrive without a payment credential, and fail-open pass-throughs.
 
-    Under ``policy.require_sanctions_clear``, OFAC SDN wallet-address hits already flip the
-    gate to ``decision=deny`` before the handler runs — merchant code typically only reads
-    ``signer_match`` for the wallet-binding verdict (e.g. via
-    :func:`build_signer_mismatch_body`).
+    Wallet-OFAC SDN enforcement is unconditional whenever a signer is in the request —
+    SDN wallet-address hits already flip the gate to ``decision=deny`` before the handler
+    runs. Merchant code typically only reads ``signer_match`` for the wallet-binding
+    verdict (e.g. via :func:`build_signer_mismatch_body`).
     """
     state = request.scope.get("state", {}).get(GATE_STATE_KEY)
     if not state or not state.get("wallet_address"):

{agentscore_commerce-2.1.1 → agentscore_commerce-2.3.0}/agentscore_commerce/identity/types.py

@@ -128,10 +128,10 @@ class SignerVerdict:
     ``/v1/assess`` call (single round trip). ``signer_match`` describes the wallet-
     binding; ``signer_sanctions`` describes the OFAC SDN wallet-address check.
 
-    Under ``policy.require_sanctions_clear``, a ``signer_sanctions`` hit OR an
-    unavailable lookup already flips ``decision -> deny`` inside the gate before the
-    handler runs — merchant code typically only needs to read ``signer_match`` here
-    for the wallet-binding verdict.
+    Wallet-OFAC SDN enforcement is unconditional whenever a signer is in the request —
+    a ``signer_sanctions`` hit OR an unavailable lookup already flips
+    ``decision -> deny`` inside the gate before the handler runs. Merchant code
+    typically only needs to read ``signer_match`` here for the wallet-binding verdict.
     """
 
     signer_match: VerifyWalletSignerResult | None = None