adcontextprotocol
diff --git a/‎CLAUDE.md‎
Lines changed: 41 additions & 0 deletions b/‎CLAUDE.md‎
Lines changed: 41 additions & 0 deletions
diff --git a/‎src/adcp/decisioning/account_projection.py‎
Lines changed: 109 additions & 0 deletions b/‎src/adcp/decisioning/account_projection.py‎
Lines changed: 109 additions & 0 deletions
@@ -43,6 +43,47 @@ All other source code should import from `adcp.types` (the public API).
 - Add specific `type: ignore` comments (e.g., `# type: ignore[no-any-return]`) rather than blanket ignores
 - Test type checking in CI across multiple Python versions (3.10+)
 
+## ctx_metadata: write-only credentials prohibited
+
+`RequestContext.metadata` (populated from the wire request's `context` extension)
+is **echoed back into responses** per the AdCP context-echo contract. Adopters who
+treat `metadata` as a generic KV bucket and store a credential there will discover
+it round-trips to the buyer — and lands in the idempotency replay cache.
+
+The dispatcher fail-closes on credential-shaped keys at `_build_request_context`.
+If you see a `ValueError` like `ctx_metadata may not contain credential-shaped
+keys`, migrate the value to `AuthInfo.credential` or a typed credential class.
+
+**Wrong** — credential stored in metadata, round-trips into response context:
+
+```python
+ctx = RequestContext(metadata={"upstream.api_token": secret})  # ValueError
+```
+
+**Right** — credential stored in the typed `AuthInfo.credential` field:
+
+```python
+auth = AuthInfo(
+    kind="api_key",
+    key_id="kid_1",
+    principal="agent.example.com",
+    credential=ApiKeyCredential(kind="api_key", key_id="kid_1"),
+)
+ctx = RequestContext(auth_info=auth, metadata={"correlation_id": "req_xyz"})
+```
+
+The credential-shaped key suffix list is in
+`adcp.decisioning.dispatch._CREDENTIAL_SHAPED_KEY_SUFFIXES` and matches
+case-insensitively at any nesting depth: `credential`, `credentials`, `token`,
+`secret`, `api_key`, `apikey`, `password`, `bearer`. Keys that don't match
+(`correlation_id`, `feature_flag.beta_pricing`, `trace_id`) pass through.
+
+For credentials the framework propagates to upstream calls (governance agents,
+signal providers, audience activations), use the typed credential classes from
+`adcp.decisioning`: `ApiKeyCredential`, `OAuthCredential`, `HttpSigCredential`.
+The framework dispatch threads these explicitly without going through the
+context-echo path.
+
 ## Testing Strategy
 
 **Mock at the Right Level**
 
@@ -329,9 +329,118 @@ def to_wire_sync_governance_row(row: SyncGovernanceResultRow) -> dict[str, Any]:
     return wire
 
 
+# ---------------------------------------------------------------------------
+# Defense-in-depth scrubber — runs at every wire-emit boundary
+# ---------------------------------------------------------------------------
+
+
+#: Methods whose response payload may carry credential-shaped fields.
+#: The dispatcher gates the recursive scrubber on this set so unrelated
+#: tools (``get_products``, ``get_signals``) skip the walk entirely —
+#: the scrubber is O(n) in result size and not free for large catalogs.
+#:
+#: This set is intentionally broad: any tool whose response surfaces
+#: an ``Account`` envelope (``billing_entity``, ``governance_agents``)
+#: or a joined record carrying those keys belongs here.
+CREDENTIAL_BEARING_METHODS: frozenset[str] = frozenset(
+    {
+        "list_accounts",
+        "sync_accounts",
+        "sync_governance",
+        "create_media_buy",
+        "update_media_buy",
+        "get_media_buys",
+        "sync_creatives",
+        "list_creatives",
+    }
+)
+
+
+def _scrub_dict(value: dict[str, Any]) -> dict[str, Any]:
+    """Return a copy of ``value`` with credential-shaped fields stripped.
+
+    Strips:
+
+    * ``governance_agents[i].authentication`` — write-only credential.
+    * ``billing_entity.bank`` — write-only bank coordinates.
+
+    Walks recursively into nested dicts and lists. Returns a NEW dict —
+    the input is not mutated, so callers (idempotency replay cache,
+    middleware) can rely on input stability.
+    """
+    out: dict[str, Any] = {}
+    for key, sub in value.items():
+        if key == "governance_agents" and isinstance(sub, list):
+            out[key] = [_scrub_governance_agent_dict(a) if isinstance(a, dict) else a for a in sub]
+        elif key == "billing_entity" and isinstance(sub, dict):
+            out[key] = {k: v for k, v in _scrub_value(sub).items() if k != "bank"}
+        else:
+            out[key] = _scrub_value(sub)
+    return out
+
+
+def _scrub_governance_agent_dict(agent: dict[str, Any]) -> dict[str, Any]:
+    """Strip ``authentication`` from a governance-agent dict and recurse
+    into the remaining fields."""
+    return {k: _scrub_value(v) for k, v in agent.items() if k != "authentication"}
+
+
+def _scrub_value(value: Any) -> Any:
+    """Recurse into dicts / lists; return primitives unchanged."""
+    if isinstance(value, dict):
+        return _scrub_dict(value)
+    if isinstance(value, list):
+        return [_scrub_value(v) for v in value]
+    return value
+
+
+def strip_credentials_from_wire_result(method_name: str, result: Any) -> Any:
+    """Strip write-only credential fields from a wire-shape result.
+
+    Defense-in-depth boundary called by the dispatcher on every
+    response that may surface an :class:`Account` envelope. Removes
+    ``governance_agents[i].authentication`` and ``billing_entity.bank``
+    recursively — the same fields the typed projections
+    (:func:`to_wire_account`, :func:`to_wire_sync_governance_row`)
+    strip when the adopter returns the framework's typed dataclasses.
+
+    Adopters returning a loose dict (or a Pydantic model with
+    ``extra='allow'``) bypass the typed projections; this scrubber
+    catches them. Adopters returning the typed dataclasses get
+    double-stripped — the second pass is a no-op since the typed
+    projections already removed the fields.
+
+    Method gate: the scrubber is O(n) in result size; we only run it
+    on methods in :data:`CREDENTIAL_BEARING_METHODS`. Non-account
+    methods (``get_products``, ``get_signals``, ``activate_signal``)
+    skip the walk entirely and pass through unchanged.
+
+    The input is not mutated — returns a new value.
+    """
+    if method_name not in CREDENTIAL_BEARING_METHODS:
+        return result
+    if isinstance(result, dict):
+        return _scrub_dict(result)
+    if isinstance(result, list):
+        return [_scrub_value(v) for v in result]
+    # Typed Pydantic response models pass through unchanged — the
+    # response-side codegen'd shapes don't define ``authentication``
+    # on ``GovernanceAgent`` or ``bank`` on the response-side
+    # ``BusinessEntity``, so the schema enforces the strip
+    # structurally. Dumping-and-scrubbing a model would force
+    # downstream callers to lose typed-model identity for no
+    # security gain. The leak vector is loose dicts and Pydantic
+    # ``extra='allow'`` models that smuggle credentials past the
+    # codegen schema; both arrive as ``dict`` after the adopter's
+    # method returns or via the registry's ``model_dump`` path.
+    return result
+
+
 __all__ = [
+    "CREDENTIAL_BEARING_METHODS",
     "project_account_for_response",
     "project_business_entity_for_response",
+    "strip_credentials_from_wire_result",
     "to_wire_account",
     "to_wire_sync_accounts_row",
     "to_wire_sync_governance_row",