feat: signer field + signer_sanctions verdict (TEC-295 Phase 2b)

Python-side mirror of agentscore/node-sdk#TBD and the api change in
agentscore/core#TBD. Breaking field rename plus a new response type:

* assess(resolve_signer=...) -> assess(signer=...) on both sync + async
* request body field resolve_signer -> signer (snake_case wire)
* ResolveSigner type -> Signer
* New SignerSanctions discriminated union: SignerSanctionsClear |
  SignerSanctionsHit | SignerSanctionsUnavailable
* New AssessResponse.signer_sanctions optional field
* __init__.py exports updated; ResolveSigner removed from public API

No back-compat alias. Callers passing `resolve_signer=...` get a
TypeError at call time. The api silently ignores `resolve_signer`
request fields if any straggler send them; this SDK won't.

Version 2.1.2 -> 2.2.0. Minor bump rather than major because internal
consumers (agentscore-commerce + pay) are the primary users and the
TypedDict surface catches the rename at type-check time.

CLAUDE.md + README + tests updated. 152/152 tests pass; ruff +
ty + uv.lock clean. uv.lock refreshed via uv sync --upgrade.

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

Author: vvillait88

.claude/CLAUDE.md

@@ -9,7 +9,7 @@ Two identity paths: `X-Wallet-Address` (wallet-based) and `X-Operator-Token` (cr
 ## Methods (sync + async)
 
 - `get_reputation` / `aget_reputation` — cached reputation lookup (free)
-- `assess` / `aassess` — identity gate with policy (paid). Accepts `operator_token` for non-wallet agents. Response includes `linked_wallets[]` and `resolved_operator`. Optional `resolve_signer: { address, network }` opts into server-side wallet-signer-match — the response then carries a `signer_match` block describing whether the supplied signer wallet resolves to the same operator as the claimed `address`.
+- `assess` / `aassess` — identity gate with policy (paid). Accepts `operator_token` for non-wallet agents. Response includes `linked_wallets[]` and `resolved_operator`. Optional `signer: { address, network }` opts into server-side wallet-signer-match — the response then carries a `signer_match` block describing whether the supplied signer wallet resolves to the same operator as the claimed `address`.
 - `create_session` / `acreate_session` — create verification session. Returns `agent_memory` + `next_steps`.
 - `poll_session` / `apoll_session` — poll session status, returns credential when verified, plus `next_steps.action`.
 - `create_credential` / `acreate_credential` — create operator credential (24h TTL default). Response includes `agent_memory`.

agentscore/__init__.py

@@ -33,11 +33,12 @@
     Reputation,
     ReputationResponse,
     ReputationStatus,
-    ResolveSigner,
     SessionCreateRequest,
     SessionCreateResponse,
     SessionPollResponse,
+    Signer,
     SignerMatch,
+    SignerSanctions,
     VerificationLevel,
     WalletAuthRequiresSigningBody,
     WalletSignerMismatchBody,
@@ -74,11 +75,12 @@
     "Reputation",
     "ReputationResponse",
     "ReputationStatus",
-    "ResolveSigner",
     "SessionCreateRequest",
     "SessionCreateResponse",
     "SessionPollResponse",
+    "Signer",
     "SignerMatch",
+    "SignerSanctions",
     "TimeoutError",
     "TokenExpiredError",
     "VerificationLevel",

agentscore/client.py

@@ -137,9 +137,9 @@ def _build_error_from_response(response: httpx.Response) -> AgentScoreError:
         DecisionPolicy,
         Network,
         ReputationResponse,
-        ResolveSigner,
         SessionCreateResponse,
         SessionPollResponse,
+        Signer,
     )
 
 
@@ -255,13 +255,13 @@ def assess(
         refresh: bool | None = None,
         policy: DecisionPolicy | None = None,
         operator_token: str | None = None,
-        resolve_signer: ResolveSigner | None = None,
+        signer: Signer | None = None,
     ) -> AssessResponse:
         """Assess a wallet or operator (paid, writes score on-the-fly).
 
-        ``resolve_signer`` opts into server-side wallet-signer-match: when supplied,
+        ``signer`` opts into server-side wallet-signer-match: when supplied,
         the API resolves the signer wallet against the claimed ``address`` and emits
-        a ``signer_match`` block on the response. See :class:`ResolveSigner`.
+        a ``signer_match`` block on the response. See :class:`Signer`.
         """
         body: dict[str, Any] = {}
         if address:
@@ -274,8 +274,8 @@ def assess(
             body["refresh"] = refresh
         if policy is not None:
             body["policy"] = dict(policy)
-        if resolve_signer is not None:
-            body["resolve_signer"] = dict(resolve_signer)
+        if signer is not None:
+            body["signer"] = dict(signer)
         client = self._get_sync_client()
         data, response = self._send_sync_with_response(lambda: client.post("/v1/assess", json=body))
         quota = _extract_quota(response)
@@ -393,11 +393,11 @@ async def aassess(
         refresh: bool | None = None,
         policy: DecisionPolicy | None = None,
         operator_token: str | None = None,
-        resolve_signer: ResolveSigner | None = None,
+        signer: Signer | None = None,
     ) -> AssessResponse:
         """Assess a wallet or operator (paid, writes score on-the-fly).
 
-        ``resolve_signer`` opts into server-side wallet-signer-match — async mirror of
+        ``signer`` opts into server-side wallet-signer-match — async mirror of
         :meth:`assess`.
         """
         body: dict[str, Any] = {}
@@ -411,8 +411,8 @@ async def aassess(
             body["refresh"] = refresh
         if policy is not None:
             body["policy"] = dict(policy)
-        if resolve_signer is not None:
-            body["resolve_signer"] = dict(resolve_signer)
+        if signer is not None:
+            body["signer"] = dict(signer)
         client = self._get_async_client()
         data, response = await self._send_async_with_response(lambda: client.post("/v1/assess", json=body))
         quota = _extract_quota(response)

agentscore/types.py

@@ -169,7 +169,7 @@ class DecisionPolicy(TypedDict, total=False):
     allowed_jurisdictions: list[str]
 
 
-class ResolveSigner(TypedDict):
+class Signer(TypedDict):
     """Server-side wallet-signer-match request.
 
     When passed to ``assess()`` / ``aassess()``, the API resolves this signer wallet
@@ -191,7 +191,7 @@ class SignerMatch(TypedDict, total=False):
     """Server-side wallet-signer-match verdict.
 
     Emitted on ``AssessResponse.signer_match`` when the request supplied
-    ``resolve_signer``. Mirrors the verdict shape commerce SDK gates produce locally;
+    ``signer``. Mirrors the verdict shape commerce SDK gates produce locally;
     SDK consumers spread this into 403 bodies verbatim instead of re-deriving via 2
     extra ``/v1/assess`` round trips.
 
@@ -223,6 +223,46 @@ class SignerMatch(TypedDict, total=False):
     agent_instructions: str
 
 
+class SignerSanctionsClear(TypedDict):
+    """Server-side wallet-sanctions verdict — address NOT on the OFAC SDN list."""
+
+    status: Literal["clear"]
+
+
+class SignerSanctionsHit(TypedDict):
+    """Server-side wallet-sanctions verdict — address IS on the OFAC SDN list.
+
+    Under ``policy.require_sanctions_clear``, this verdict flips the response
+    ``decision`` to ``deny`` with ``decision_reasons`` including ``sanctions_flagged``.
+    """
+
+    sanctioned: Literal[True]
+    # Raw OFAC Digital Currency Address label the hit was published under (``ETH``,
+    # ``XBT``, ``USDT``, ``SOL``, ...). Investigation-history metadata; the gate's
+    # enforcement axis is the format-classified family, not this label.
+    ofac_label: str
+    # SDN entry's Identity ID. Same ``sdn_uid`` may surface multiple addresses (one
+    # entity, multiple wallets); join key for audit.
+    sdn_uid: str
+    # ISO date OFAC initially designated the entity. ``None`` if upstream omits.
+    listed_at: str | None
+
+
+class SignerSanctionsUnavailable(TypedDict):
+    """Server-side wallet-sanctions verdict — lookup itself failed.
+
+    Under ``policy.require_sanctions_clear``, the gate fail-closes — falsely allowing
+    a sanctioned settle is an OFAC strict-liability violation; falsely denying a clean
+    buyer is bad UX.
+    """
+
+    status: Literal["unavailable"]
+
+
+# Discriminated union: branch on ``status`` (clear/unavailable) vs ``sanctioned`` (True).
+SignerSanctions = SignerSanctionsClear | SignerSanctionsHit | SignerSanctionsUnavailable
+
+
 class _AssessResponseRequired(TypedDict):
     decision: str | None
     decision_reasons: list[str]
@@ -264,8 +304,11 @@ class AssessResponse(_AssessResponseRequired, total=False):
     policy_result: PolicyResult | None
     explanation: NotRequired[list[PolicyExplanation]]
     # Server-side wallet-signer-match verdict, returned only when the request supplied
-    # ``resolve_signer``. Empty otherwise.
+    # ``signer``. Empty otherwise.
     signer_match: NotRequired[SignerMatch]
+    # Server-side OFAC SDN wallet-address verdict, returned only when the request supplied
+    # ``signer``. Empty otherwise.
+    signer_sanctions: NotRequired[SignerSanctions]
     # Quota state for this account, captured from response headers on the success path.
     # Use to monitor approach-to-cap proactively (warn at 80%, alert at 95%) before 429.
     quota: NotRequired[QuotaInfo]

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentscore-py"
-version = "2.1.2"
+version = "2.2.0"
 description = "Python client for the AgentScore APIs"
 readme = "README.md"
 license = "MIT"