fix(commerce): denial body emits {error: {code, message}} (parity with node)

Mirror of node-commerce a5ad32c. denial_reason_to_body now emits
{"error": {"code": ..., "message": ...}} matching the core API canonical
shape, replacing the previous {"error": "<code>"} string form.

Adds DenialReason.message override; per-code default messages in
_response.py (_DEFAULT_MESSAGES). Bulk-updates 7 test files (FastAPI,
Flask, Django, AIOHTTP, Sanic, middleware, signer_match) to read
body["error"]["code"].

483 → 485 tests pass; coverage 95.86%; ruff + ty clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: vvillait88

agentscore_commerce/identity/_response.py

@@ -3,6 +3,11 @@
 Every adapter (ASGI, FastAPI, Flask, Django, AIOHTTP, Sanic) renders the same
 body shape for a denial — this helper keeps them in sync and in one place.
 Includes the wallet-signer-match fields and the agent_memory payload.
+
+Body shape: ``{"error": {"code": ..., "message": ...}, ...}`` — matches the
+canonical AgentScore core API response shape so downstream agents see one
+consistent ``error.code`` + ``error.message`` pair regardless of which layer
+produced the denial.
 """
 
 from __future__ import annotations
@@ -136,13 +141,42 @@ def build_missing_identity_reason() -> DenialReason:
     )
 
 
+_DEFAULT_MESSAGES: dict[str, str] = {
+    "missing_identity": "No identity provided. Send X-Wallet-Address (wallet) or X-Operator-Token (credential).",
+    "identity_verification_required": (
+        "Identity verification is required to access this resource. Visit verify_url to complete KYC."
+    ),
+    "wallet_not_trusted": "The wallet does not meet the merchant compliance policy.",
+    "api_error": "AgentScore is unreachable. This is transient — retry in a few seconds.",
+    "payment_required": "AgentScore tier does not support assess. Contact support.",
+    "wallet_signer_mismatch": (
+        "Payment signer does not match the wallet claimed via X-Wallet-Address. The signer and the "
+        "claimed wallet must both resolve to the same AgentScore operator."
+    ),
+    "wallet_auth_requires_wallet_signing": (
+        "X-Wallet-Address was sent with a rail that has no wallet signature (Stripe SPT / card). "
+        "Switch to X-Operator-Token, or use a wallet-signing rail (Tempo MPP, x402)."
+    ),
+    "token_expired": (
+        "The operator token is expired or revoked. A fresh verification session has been minted — "
+        "visit verify_url to mint a new token."
+    ),
+    "invalid_credential": (
+        "The operator token is not recognized. Switch to a different stored token, or drop the "
+        "header to bootstrap a fresh session."
+    ),
+}
+
+
 def denial_reason_to_body(reason: DenialReason) -> dict[str, Any]:
     """Marshal a DenialReason dataclass into a flat dict suitable for the 403 JSON body.
 
     Shared across all adapters. Omits falsy optional fields so the body stays compact.
-    Always includes ``error`` set from ``reason.code``.
+    Emits ``error: {code, message}`` matching the core API canonical shape; ``message``
+    falls back to a per-code default when ``reason.message`` is None.
     """
-    body: dict[str, Any] = {"error": reason.code}
+    message = reason.message or _DEFAULT_MESSAGES.get(reason.code, "")
+    body: dict[str, Any] = {"error": {"code": reason.code, "message": message}}
     if reason.decision is not None:
         body["decision"] = reason.decision
     if reason.reasons:

agentscore_commerce/identity/types.py

@@ -65,6 +65,8 @@ class DenialReason:
     """Reason a request was denied by the gate middleware."""
 
     code: DenialCode
+    # Human-readable explanation. When None, denial_reason_to_body substitutes a per-code default.
+    message: str | None = None
     decision: str | None = None
     reasons: list[str] = field(default_factory=list)
     verify_url: str | None = None

tests/test_aiohttp.py

@@ -84,7 +84,7 @@ async def test_denies_untrusted_wallet(self):
             resp = await client.get("/", headers={"X-Wallet-Address": "0xabc"})
             assert resp.status == 403
             data = await resp.json()
-            assert data["error"] == "wallet_not_trusted"
+            assert data["error"]["code"] == "wallet_not_trusted"
             assert data["reasons"] == ["not_kyc"]
 
     @pytest.mark.asyncio
@@ -94,7 +94,7 @@ async def test_missing_identity_returns_403(self):
             resp = await client.get("/")
             assert resp.status == 403
             data = await resp.json()
-            assert data["error"] == "missing_identity"
+            assert data["error"]["code"] == "missing_identity"
 
     @pytest.mark.asyncio
     async def test_fail_open_allows_through_when_identity_missing(self):
@@ -124,7 +124,7 @@ async def test_returns_403_payment_required_on_402(self):
             resp = await client.get("/", headers={"X-Wallet-Address": "0xabc"})
             assert resp.status == 403
             data = await resp.json()
-            assert data["error"] == "payment_required"
+            assert data["error"]["code"] == "payment_required"
 
     @pytest.mark.asyncio
     @respx.mock
@@ -135,7 +135,7 @@ async def test_returns_503_api_error_on_500(self):
             resp = await client.get("/", headers={"X-Wallet-Address": "0xabc"})
             assert resp.status == 503
             data = await resp.json()
-            assert data["error"] == "api_error"
+            assert data["error"]["code"] == "api_error"
 
     @pytest.mark.asyncio
     @respx.mock
@@ -217,7 +217,7 @@ async def test_creates_session_and_returns_403_with_session_data(self):
             resp = await client.get("/")
             assert resp.status == 403
             data = await resp.json()
-            assert data["error"] == "identity_verification_required"
+            assert data["error"]["code"] == "identity_verification_required"
             assert data["session_id"] == "sess_abc123"
             assert data["verify_url"] == "https://agentscore.sh/verify/sess_abc123"
             assert data["poll_secret"] == "ps_secret"
@@ -237,7 +237,7 @@ async def test_falls_back_to_missing_identity_on_session_api_failure(self):
             resp = await client.get("/")
             assert resp.status == 403
             data = await resp.json()
-            assert data["error"] == "missing_identity"
+            assert data["error"]["code"] == "missing_identity"
 
 
 class TestCaptureWallet:
@@ -338,7 +338,7 @@ async def handler(_req):
         resp = await client.get("/", headers={"x-operator-token": "opc_exp"})
         assert resp.status == 401
         body = await resp.json()
-        assert body["error"] == "token_expired"
+        assert body["error"]["code"] == "token_expired"
         assert json.loads(body["agent_instructions"]) == {"action": "deliver_verify_url_and_poll"}
 
 
@@ -361,4 +361,4 @@ async def handler(_req):
         resp = await client.get("/", headers={"x-wallet-address": "0xabc"})
         assert resp.status == 503
         body = await resp.json()
-        assert body["error"] == "api_error"
+        assert body["error"]["code"] == "api_error"

tests/test_django.py

@@ -67,15 +67,15 @@ def test_blocks_untrusted_wallet(self) -> None:
             resp = mw(request)
             assert resp.status_code == 403
             data = json.loads(resp.content)
-            assert data["error"] == "wallet_not_trusted"
+            assert data["error"]["code"] == "wallet_not_trusted"
 
     def test_missing_wallet_returns_403(self) -> None:
         mw = self._make_middleware()
         request = self.factory.get("/")
         resp = mw(request)
         assert resp.status_code == 403
         data = json.loads(resp.content)
-        assert data["error"] == "missing_identity"
+        assert data["error"]["code"] == "missing_identity"
 
     def test_missing_wallet_fail_open(self) -> None:
         mw = self._make_middleware(fail_open=True)
@@ -97,7 +97,7 @@ def test_api_error_fail_closed(self) -> None:
             resp = mw(request)
             assert resp.status_code == 503
             data = json.loads(resp.content)
-            assert data["error"] == "api_error"
+            assert data["error"]["code"] == "api_error"
 
     def test_payment_required_fail_open(self) -> None:
         mw = self._make_middleware(fail_open=True)
@@ -113,7 +113,7 @@ def test_payment_required_fail_closed(self) -> None:
             resp = mw(request)
             assert resp.status_code == 403
             data = json.loads(resp.content)
-            assert data["error"] == "payment_required"
+            assert data["error"]["code"] == "payment_required"
 
     def test_extract_chain_passed_to_api(self) -> None:
         def custom_extract_chain(_request):
@@ -189,7 +189,7 @@ def test_deny_includes_reasons_from_compliance(self) -> None:
             resp = mw(request)
             assert resp.status_code == 403
             data = json.loads(resp.content)
-            assert data["error"] == "wallet_not_trusted"
+            assert data["error"]["code"] == "wallet_not_trusted"
             assert "kyc_required" in data["reasons"]
             assert "sanctions_check_pending" in data["reasons"]
 
@@ -223,7 +223,7 @@ def test_verify_url_available_in_raw_on_deny(self) -> None:
             resp = mw(request)
             assert resp.status_code == 403
             data = json.loads(resp.content)
-            assert data["error"] == "wallet_not_trusted"
+            assert data["error"]["code"] == "wallet_not_trusted"
 
 
 class TestDjangoCreateSessionOnMissing:
@@ -261,7 +261,7 @@ def test_creates_session_and_returns_403_with_session_data(self) -> None:
             resp = mw(request)
         assert resp.status_code == 403
         data = json.loads(resp.content)
-        assert data["error"] == "identity_verification_required"
+        assert data["error"]["code"] == "identity_verification_required"
         assert data["session_id"] == "sess_abc"
         assert data["verify_url"] == "https://agentscore.sh/verify/sess_abc"
         assert data["poll_secret"] == "ps_secret"
@@ -281,7 +281,7 @@ def test_falls_back_to_missing_identity_on_session_helper_failure(self) -> None:
             resp = mw(request)
         assert resp.status_code == 403
         data = json.loads(resp.content)
-        assert data["error"] == "missing_identity"
+        assert data["error"]["code"] == "missing_identity"
 
 
 class TestDjangoIdentityModel:
@@ -321,7 +321,7 @@ def test_missing_identity_returns_403(self) -> None:
         resp = mw(request)
         assert resp.status_code == 403
         data = json.loads(resp.content)
-        assert data["error"] == "missing_identity"
+        assert data["error"]["code"] == "missing_identity"
 
     def test_missing_identity_fail_open(self) -> None:
         mw = self._make_middleware(fail_open=True)

tests/test_fastapi.py

@@ -64,15 +64,15 @@ def test_denies_untrusted_wallet(self):
         assert resp.status_code == 403
         body = resp.json()
         # FastAPI wraps HTTPException detail in {"detail": {...}}.
-        assert body["detail"]["error"] == "wallet_not_trusted"
+        assert body["detail"]["error"]["code"] == "wallet_not_trusted"
         assert body["detail"]["reasons"] == ["not_kyc"]
 
     def test_missing_identity_returns_403(self):
         gate = AgentScoreGate(api_key="ask_test")
         client = TestClient(_make_app(gate))
         resp = client.get("/")
         assert resp.status_code == 403
-        assert resp.json()["detail"]["error"] == "missing_identity"
+        assert resp.json()["detail"]["error"]["code"] == "missing_identity"
 
     def test_fail_open_allows_through_when_identity_missing(self):
         gate = AgentScoreGate(api_key="ask_test", fail_open=True)
@@ -96,7 +96,7 @@ def test_raises_on_402_payment_required(self):
         client = TestClient(_make_app(gate))
         resp = client.get("/", headers={"X-Wallet-Address": "0xabc"})
         assert resp.status_code == 403
-        assert resp.json()["detail"]["error"] == "payment_required"
+        assert resp.json()["detail"]["error"]["code"] == "payment_required"
 
     @respx.mock
     def test_api_error_returns_403_api_error(self):
@@ -105,7 +105,7 @@ def test_api_error_returns_403_api_error(self):
         client = TestClient(_make_app(gate))
         resp = client.get("/", headers={"X-Wallet-Address": "0xabc"})
         assert resp.status_code == 503
-        assert resp.json()["detail"]["error"] == "api_error"
+        assert resp.json()["detail"]["error"]["code"] == "api_error"
 
 
 class TestOnDenied:
@@ -181,7 +181,7 @@ def test_creates_session_and_returns_403_with_session_data(self):
         resp = client.get("/")
         assert resp.status_code == 403
         detail = resp.json()["detail"]
-        assert detail["error"] == "identity_verification_required"
+        assert detail["error"]["code"] == "identity_verification_required"
         assert detail["session_id"] == "sess_abc123"
         assert detail["verify_url"] == "https://agentscore.sh/verify/sess_abc123"
         assert detail["poll_secret"] == "ps_secret"
@@ -202,7 +202,7 @@ def test_falls_back_to_missing_identity_on_session_api_failure(self):
         client = TestClient(_make_app(gate))
         resp = client.get("/")
         assert resp.status_code == 403
-        assert resp.json()["detail"]["error"] == "missing_identity"
+        assert resp.json()["detail"]["error"]["code"] == "missing_identity"
 
 
 class TestCaptureWallet:
@@ -318,7 +318,7 @@ def index():
     assert resp.status_code == 401
     # FastAPI wraps the denial body under HTTPException.detail.
     detail = resp.json()["detail"]
-    assert detail["error"] == "token_expired"
+    assert detail["error"]["code"] == "token_expired"
     assert json.loads(detail["agent_instructions"]) == {"action": "deliver_verify_url_and_poll"}
 
 
@@ -337,4 +337,4 @@ def index():
     client = TestClient(app, raise_server_exceptions=False)
     resp = client.get("/", headers={"x-wallet-address": "0xabc"})
     assert resp.status_code == 503
-    assert resp.json()["detail"]["error"] == "api_error"
+    assert resp.json()["detail"]["error"]["code"] == "api_error"