fix(x402): derive WWW-Authenticate realm from host, not full endpoint URL (#93)

Surfaced by `npx mppx@latest validate` against store: the challenge
realm was `https://agents.agentscore.com/purchase` (full URL with path)
while martin/sayer (Node) emit the bare host.

Root cause: the Python Checkout auto-derived the MPP realm from the full
endpoint `url`. The Node SDK passes `new URL(APP_URL).host`; the
WWW-Authenticate realm should be the bare protection-space host.
`_realm_from_url` normalizes the derived realm to the host, restoring
parity. Falls back to the input unchanged when it has no parseable host
(already-bare host, relative path).

Advisory-only (the challenge was fully valid and settles); this clears
the validator warning and aligns the two SDKs.

Unit test covers full-URL, host:port, bare-host, and relative-path
cases. Full suite green (1841 passed, 95.36% coverage), ruff + ty clean.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: vvillait88

agentscore_commerce/checkout.py

@@ -149,6 +149,20 @@ def _spec_method_name(spec: CheckoutRailSpec) -> str:
     return "stripe/spt"  # StripeRailSpec is the only remaining variant in CheckoutRailSpec.
 
 
+def _realm_from_url(url: str) -> str:
+    """Derive the WWW-Authenticate ``realm`` from the checkout endpoint URL.
+
+    The realm identifies the protection space and, by convention (and to match the Node
+    SDK, which passes ``new URL(APP_URL).host``), is the bare host, not the full endpoint
+    URL. ``Checkout(url="https://agents.example.com/purchase")`` yields realm
+    ``agents.example.com``. Falls back to the input unchanged when it has no parseable host
+    (e.g. already a bare host, or a relative path).
+    """
+    from urllib.parse import urlparse
+
+    return urlparse(url).netloc or url
+
+
 @dataclass
 class CheckoutRequest:
     """Framework-neutral HTTP request input to :meth:`Checkout.handle`.
@@ -907,7 +921,7 @@ def __init__(
                 getter = lazy_mppx_server(
                     rails=mpp_rails,
                     secret_key=mppx_secret_key,
-                    realm=url,
+                    realm=_realm_from_url(url),
                 )
                 compose_mppx = make_mppx_compose_hook(server_getter=getter)
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentscore-commerce"
-version = "2.5.10"
+version = "2.5.11"
 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"

tests/test_checkout.py

@@ -985,3 +985,15 @@ def test_rails_key_for_mppx_method_returns_none_when_rail_absent() -> None:
     assert checkout._rails_key_for_mppx_method("solana") is None
     assert checkout._rails_key_for_mppx_method("stripe") is None
     assert checkout._rails_key_for_mppx_method("tempo") == "tempo"
+
+
+def test_realm_from_url_derives_bare_host():
+    from agentscore_commerce.checkout import _realm_from_url
+
+    # Full endpoint URL -> bare host (matches the Node SDK's new URL(APP_URL).host),
+    # so the WWW-Authenticate realm is the protection space, not the full path.
+    assert _realm_from_url("https://agents.agentscore.com/purchase") == "agents.agentscore.com"
+    assert _realm_from_url("https://agents.example.com:8443/x/y") == "agents.example.com:8443"
+    # No parseable host: pass through unchanged.
+    assert _realm_from_url("agents.example.com") == "agents.example.com"
+    assert _realm_from_url("/purchase") == "/purchase"