Release 2.10.0: verify session before paying, single-flight PaymentIntent creation, sweep (#142)

## Summary

Release 2.10.0, parity with node-commerce 2.13.0, plus the maintenance
sweep. Worked with Varun.

**Verification session without a payment credential.** On an
identity-gated `Checkout` the gate runs only on the settle leg, so a
buyer with no identity reached the session-bearing 403 only by first
sending a payment credential (a Stripe SPT buyer had to mint a token to
learn they needed to verify). Now the discovery 402 carries an
`identity_bootstrap` block (`header`, `value`, `instructions`) whenever
the store is identity-gated and the request has no identity header, and
a request carrying `X-Verification-Session: create` (case-insensitive),
no identity and no payment credential runs the gate, which returns its
existing session 403 with `verify_url`, `session_id`, `poll_secret` and
`poll_url`. It is opt-in because discovery scanners replay the Bazaar
example body on a schedule, and minting on every identity-less 402 would
create a session and a pending order per probe. Gateless merchants
neither advertise nor honor it. The generated `llms.txt` identity
section and the Stripe/Link onboarding step name the header.

**Concurrent PaymentIntent creation.** Concurrent creates under one
idempotency key collide at Stripe as a resource-specific 429 that says
not to retry (seen in production from the Node SDK).
`create_multichain_payment_intent` is synchronous, so the race exists
across the worker threads of a threaded server (Flask, Django); keyed
calls now share one in-flight call, with followers waiting on the leader
and a failure reaching every waiter before the key clears. Unkeyed calls
are unchanged.

**Sweep.** `uv lock --upgrade` (x402 2.23.0 to 2.24.0, starlette 1.7.0,
uvicorn 0.54.0, sentry-sdk 2.71.0, werkzeug 3.1.9, regex, plus the ruff
and ty dev bumps) and the uv pin passed to `setup-uv` in the CI, publish
and security workflows moves from 0.12.17 to 0.12.20. The x402 move was
checked against its wheels: every EVM `constants.py` (including the Base
USDC name that the EIP-712 domain depends on) is byte-identical; the
changes are in the HTTP server and middleware.

## Type of change

- [ ] Bug fix (no breaking change)
- [x] New feature (no breaking change)
- [ ] Breaking change (existing callers must update)
- [ ] Docs, tests, or internal maintenance only

## Public API

Additive. New export `VERIFICATION_SESSION_HEADER` from the top-level
package. Identity-gated 402 bodies gain a top-level `identity_bootstrap`
object; a merchant `body_extras` key of the same name still wins.
`create_multichain_payment_intent` keeps its signature. No migration
needed.

## Test plan

- `tests/test_checkout_verification_bootstrap.py` drives the real
`handle_fastapi` adapter (the Python gate reads identity from the native
request): the 402 advertises the header only on a gated store with no
identity; the header returns the session 403; name and value match
case-insensitively; an identity header or other value is ignored; a
gateless store neither advertises nor honors it. With the new logic
disabled, the three behavior tests fail and the three controls pass.
- `tests/test_stripe_multichain.py`: three threads sharing a key make
one Stripe call; distinct and unkeyed calls do not share; a failure
reaches every waiter and the key clears for the next call. The sharing
tests fail on the previous code.
- Ran locally, as CI runs them: ruff check, ruff format --check, ty
(package and examples), vulture, pytest (1878 passed, 4 skipped, 95.40%
coverage). osv-scanner over `uv.lock`: 144 packages, no issues. No
prerelease versions in the lock.

## Checklist

- [x] Tests cover the new behavior, and the suite passes locally
- [x] Lint, format, and type checks pass
- [x] Docs and README examples updated if the public surface changed
- [x] No secrets, credentials, or personal data in the diff or the tests

Author: vvillait88

.github/workflows/ci.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v10.2.0
         with:
-          version: "0.12.17"
+          version: "0.12.20"
 
       - name: Set up Python
         run: uv python install 3.12

.github/workflows/publish.yml

@@ -21,7 +21,7 @@ jobs:
 
       - uses: astral-sh/setup-uv@v10.2.0
         with:
-          version: "0.12.17"
+          version: "0.12.20"
 
       - name: Set version from tag
         run: sed -i "s/^version = .*/version = \"${GITHUB_REF_NAME#v}\"/" pyproject.toml

.github/workflows/security.yml

@@ -41,7 +41,7 @@ jobs:
       - uses: useblacksmith/checkout@v1
       - uses: astral-sh/setup-uv@v10.2.0
         with:
-          version: "0.12.17"
+          version: "0.12.20"
       - uses: actions/setup-python@v7
         with:
           python-version: "3.13"

CLAUDE.md

@@ -83,6 +83,8 @@ Two identity types: wallet (`X-Wallet-Address`) and operator-token (`X-Operator-
 
 `create_session_on_missing` auto-mints a verification session when no identity is present AND when `wallet_not_trusted` carries fixable reasons (`kyc_required` / `kyc_pending` / `kyc_failed`) — both paths rewrite the denial to `identity_verification_required` before reaching `on_denied`. When the merchant omits `create_session_on_missing` from `CheckoutGateConfig`, `Checkout` auto-defaults it from `gate.api_key` + `gate.base_url` + `gate.context` + `gate.merchant_name`. Merchants that need `on_before_session` side effects (e.g. pre-minting an order_id) supply their own config to override.
 
+**Getting a verify_url before paying.** On an identity-gated `Checkout`, the gate runs only on a settle leg, so a buyer with no identity reached the session 403 only by sending a payment credential first (an SPT buyer had to mint one). The discovery 402 carries an `identity_bootstrap` block naming `X-Verification-Session: create` whenever the request has no identity header, and a request carrying that header, no identity and no payment credential runs the gate, which answers with the same session-bearing 403. It is opt-in on purpose: scanners replay the Bazaar example body on a schedule, so minting on every identity-less 402 would create a session and (on goods stores) a pending order per probe. Gateless merchants neither advertise nor honor it. Parity with node-commerce.
+
 `build_verification_required_body(reason, message=?, agent_instructions=?, extra=?)` — canonical body builder for the `identity_verification_required` denial. Spreads `verify_url` / `session_id` / `poll_secret` / `poll_url` / `agent_instructions` from the gate-minted reason into a 4xx envelope with merchant-specific message + optional extras. Saves the per-merchant mapping boilerplate.
 
 `get_signer_verdict(request)` (per-adapter) returns the cached `signer_match` + `signer_sanctions` verdicts the gate composed on its primary `/v1/assess` call (single round trip; merchants build a 403 with `build_signer_mismatch_body(result=verdict.signer_match)` when `kind != "pass"`).

agentscore_commerce/__init__.py

@@ -14,6 +14,7 @@
 from importlib.metadata import version as _pkg_version
 
 from agentscore_commerce.checkout import (
+    VERIFICATION_SESSION_HEADER,
     Checkout,
     CheckoutContext,
     CheckoutGateConfig,
@@ -168,6 +169,7 @@
     "AIP_A2A_EXTENSION_URI",
     "FIXABLE_DENIAL_REASONS",
     "UCP_A2A_EXTENSION_URI",
+    "VERIFICATION_SESSION_HEADER",
     "A2AAgentCard",
     "A2AAgentCardCapabilities",
     "A2AAgentCardExtension",

agentscore_commerce/checkout.py

@@ -714,6 +714,31 @@ def _resolve_resource_url(request: CheckoutRequest) -> str:
     return apply_forwarded_proto(request.url, read_forwarded_proto(request.headers))
 
 
+VERIFICATION_SESSION_HEADER = "X-Verification-Session"
+"""Request header that asks an identity-gated Checkout for a verification session without paying.
+
+The discovery 402 advertises it; a request carrying it and no identity or payment credential runs
+the gate, which answers with its session-bearing 403 (verify_url + poll data). Opt-in so crawlers
+replaying a valid example body never mint sessions or pending orders.
+"""
+_VERIFICATION_SESSION_VALUE = "create"
+
+
+def _carries_identity(headers_lower: Mapping[str, str]) -> bool:
+    from agentscore_commerce.aip.request import has_agent_identity_header_parts
+
+    return bool(
+        headers_lower.get("x-operator-token")
+        or headers_lower.get("x-wallet-address")
+        or has_agent_identity_header_parts(headers_lower)
+    )
+
+
+def _requests_verification_session(headers_lower: Mapping[str, str]) -> bool:
+    value = headers_lower.get(VERIFICATION_SESSION_HEADER.lower()) or ""
+    return value.strip().lower() == _VERIFICATION_SESSION_VALUE
+
+
 def _resolve_identity_metadata(ctx: CheckoutContext) -> dict[str, Any] | None:
     """Compose the identity_metadata block from request + assess state.
 
@@ -1257,7 +1282,14 @@ async def handle(self, request: CheckoutRequest) -> CheckoutResult:
         #     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 has_payment_header:
+        request_headers_lower = normalize_headers_to_lowercase(request.headers)
+        bootstraps_session = (
+            not has_payment_header
+            and self._has_identity_gate()
+            and not _carries_identity(request_headers_lower)
+            and _requests_verification_session(request_headers_lower)
+        )
+        if has_payment_header or bootstraps_session:
             gate_result = (
                 await self._run_gate(ctx) if self.gate is not None else await self._run_wallet_sanctions_only(ctx)
             )
@@ -2959,6 +2991,23 @@ async def _emit_402(
         # wallet intent. Saves agents a round trip: they learn required_signer
         # + linked_wallets at discovery instead of at the 403 on retry.
         identity_metadata = _resolve_identity_metadata(ctx)
+        identity_bootstrap: dict[str, Any] | None = None
+        if self._has_identity_gate() and not _carries_identity(normalize_headers_to_lowercase(ctx.request.headers)):
+            identity_bootstrap = {
+                "header": VERIFICATION_SESSION_HEADER,
+                "value": _VERIFICATION_SESSION_VALUE,
+                "instructions": (
+                    "This purchase requires a verified identity. Without an operator token, repeat this same "
+                    f"request with the header {VERIFICATION_SESSION_HEADER}: {_VERIFICATION_SESSION_VALUE} and "
+                    "no payment credential. The response is a 403 carrying verify_url, session_id, poll_secret "
+                    "and poll_url: give verify_url to the buyer, poll poll_url for an operator_token, then pay "
+                    "with X-Operator-Token set."
+                ),
+            }
+        body_extra = {
+            **({"identity_bootstrap": identity_bootstrap} if identity_bootstrap else {}),
+            **(ctx.pricing.body_extras or {}),
+        }
 
         # Enrich the declared Bazaar discovery extension with the request method +
         # route so info.input.method (required by the v2 discovery schema) and
@@ -2994,7 +3043,7 @@ async def _emit_402(
                 ),
             ),
             product=ctx.pricing.product,
-            extra=ctx.pricing.body_extras,
+            extra=body_extra or None,
             x402=X402PaymentRequired(
                 version=2,
                 accepts=x402_accepts,

agentscore_commerce/discovery/agentscore_content.py

@@ -123,8 +123,9 @@ def build_agentscore_onboarding_steps(
     )
     stripe_fallback_step = (
         "If your only payment method is a Stripe / Link card (no crypto), install `@stripe/link-cli` "
-        "instead of agentscore-pay and use it on the SPT rail. Identity gating still applies: the "
-        "merchant's 403 with `verify_url` lets you bootstrap a Passport even with no crypto wallet involved."
+        "instead of agentscore-pay and use it on the SPT rail. Identity gating still applies: send the "
+        "purchase request with `X-Verification-Session: create` before minting a token, and the "
+        "merchant's 403 with `verify_url` bootstraps a Passport even with no crypto wallet involved."
     )
     returning_user_step = (
         "Returning user note: if you've paid an AgentScore-gated merchant before from this wallet, "

agentscore_commerce/discovery/llms_txt.py

@@ -56,7 +56,8 @@ def llms_txt_identity_section(
         "Solana MPP). The wallet you claim must sign the payment.\n"
         "- **`X-Operator-Token: opc_...`**: works on every rail, including Stripe SPT. "
         f"Reusable across AgentScore merchants until expiry.{aip_bullet}\n"
-        "- **Neither**: you get a 403 with `verify_url`. Complete the session flow once and "
+        "- **Neither**: send the purchase request with `X-Verification-Session: create` and no payment "
+        "credential, and the 403 carries `verify_url`. Complete the session flow once and "
         f"reuse the resulting `opc_...` everywhere.{compliance_note}"
     )
 

agentscore_commerce/stripe_multichain/payment_intent.py

@@ -4,8 +4,9 @@
 chains, returning the PI id + deposit addresses per network. Distinct from the Stripe SPT flow.
 """
 
-from dataclasses import dataclass
-from typing import Any, Protocol
+import threading
+from dataclasses import dataclass, field
+from typing import Any, Protocol, cast
 
 from agentscore_commerce.errors import CheckoutValidationError
 
@@ -27,10 +28,24 @@ class MultichainPaymentIntentResult:
 _DEFAULT_NETWORKS: tuple[str, ...] = ("tempo", "base", "solana")
 
 
+@dataclass
+class _Flight:
+    done: threading.Event = field(default_factory=threading.Event)
+    result: MultichainPaymentIntentResult | None = None
+    error: BaseException | None = None
+
+
+# Concurrent creates under one idempotency key collide at Stripe as a resource-specific 429
+# (``stripe-should-retry: false``). The call is synchronous, so the race exists across the worker
+# threads of a threaded server; identical requests racing there share the first call.
+_in_flight: dict[str, _Flight] = {}
+_in_flight_lock = threading.Lock()
+
+
 def create_multichain_payment_intent(
     *,
-    stripe: Any,  # StripeClientLike, kept loose so vendors can pass their actual `stripe.StripeClient`
-    amount: int,  # in cents (Stripe convention)
+    stripe: Any,
+    amount: int,
     currency: str = "usd",
     networks: list[str] | None = None,
     metadata: dict[str, str] | None = None,
@@ -39,7 +54,50 @@ def create_multichain_payment_intent(
     """Create a Stripe PaymentIntent with multichain crypto deposit_options.
 
     Returns the PI id + per-network deposit addresses. Raises if Stripe doesn't return any addresses.
+    Concurrent calls sharing an ``idempotency_key`` share one Stripe request.
     """
+    kwargs: dict[str, Any] = {
+        "stripe": stripe,
+        "amount": amount,
+        "currency": currency,
+        "networks": networks,
+        "metadata": metadata,
+        "idempotency_key": idempotency_key,
+    }
+    if idempotency_key is None:
+        return _create_multichain_payment_intent_once(**kwargs)
+    with _in_flight_lock:
+        flight = _in_flight.get(idempotency_key)
+        leader = flight is None
+        if flight is None:
+            flight = _Flight()
+            _in_flight[idempotency_key] = flight
+    if not leader:
+        flight.done.wait()
+        if flight.error is not None:
+            raise flight.error
+        return cast("MultichainPaymentIntentResult", flight.result)
+    try:
+        flight.result = _create_multichain_payment_intent_once(**kwargs)
+        return flight.result
+    except BaseException as err:
+        flight.error = err
+        raise
+    finally:
+        with _in_flight_lock:
+            _in_flight.pop(idempotency_key, None)
+        flight.done.set()
+
+
+def _create_multichain_payment_intent_once(
+    *,
+    stripe: Any,  # StripeClientLike, kept loose so vendors can pass their actual `stripe.StripeClient`
+    amount: int,  # in cents (Stripe convention)
+    currency: str = "usd",
+    networks: list[str] | None = None,
+    metadata: dict[str, str] | None = None,
+    idempotency_key: str | None = None,
+) -> MultichainPaymentIntentResult:
     resolved_networks = list(networks) if networks else list(_DEFAULT_NETWORKS)
     params: dict[str, Any] = {
         "amount": amount,

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentscore-commerce"
-version = "2.9.2"
+version = "2.10.0"
 description = "Agentic 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 agentic commerce."
 readme = "README.md"
 license = "MIT"