feat(decisioning): wire credential strip into dispatch + webhook + registry, add ctx_metadata guidance

The typed projections (`to_wire_account` / `to_wire_sync_accounts_row`
/ `to_wire_sync_governance_row` from PR #469) shipped as public-API
helpers but no framework code called them — adopters returning loose
dicts or Pydantic ``extra='allow'`` models bypassed the strip
entirely. This wires defense-in-depth across every wire-emit
boundary so the strip is load-bearing regardless of return shape.

H1 — `_invoke_platform_method` runs `strip_credentials_from_wire_result`
on every sync return, recursively scrubbing
`governance_agents[i].authentication` and `billing_entity.bank` from
dicts/lists. Method-gated to `CREDENTIAL_BEARING_METHODS` so non-account
tools (`get_products`, `get_signals`) skip the walk on the hot path.
Typed Pydantic response models pass through (the response-side schema
forbids `authentication` structurally).

H2 — `maybe_emit_sync_completion` re-applies the strip before passing
`result` to the buyer-controlled webhook URL. Defense-in-depth so the
strip fires regardless of upstream sanitization (custom shims,
direct adopter calls).

H3 — `_project_handoff` strips before `await registry.complete(...)`.
Durable registries (Postgres, Redis) write the artifact to disk; even
in-memory, `tasks/get` returns it verbatim.

M1 — INTERNAL_ERROR `caused_by` now carries only the exception class
name, not its `str()`. Any truncation length useful for diagnostics
(200 chars) also fits a full OAuth client secret. Full traceback
stays in server logs via `logger.exception`.

M2 — `adcp.server.responses._serialize` runs `_strip_write_only_fields`
on dict items before emit. Adopters hand-building responses with
``{**db_record, ...}`` no longer smuggle credentials through.

M3 — `_build_request_context` fail-closes when `ctx_metadata` carries
keys ending in `credential`, `credentials`, `token`, `secret`,
`api_key`, `apikey`, `password`, `bearer` (case-insensitive, walks
nested dicts). The AdCP context-echo contract round-trips metadata
into responses; credential-shaped keys belong in
`AuthInfo.credential` / typed credential classes. Documented in the
new "ctx_metadata: write-only credentials prohibited" section of
CLAUDE.md.

Paths now covered:
- Synchronous return path through `_invoke_platform_method`
- TaskHandoff completion path through `registry.complete`
- Sync-completion webhook path through `maybe_emit_sync_completion`
- INTERNAL_ERROR wire envelope (`caused_by.message` removed)
- Hand-built response builder path through
  `adcp.server.responses._serialize`
- ctx_metadata fail-closed gate at `_build_request_context`

Refs #463, #452. Completes the wiring PR #469's projections were missing.

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

Author: bokelley

CLAUDE.md

@@ -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**

src/adcp/decisioning/account_projection.py

@@ -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",

src/adcp/decisioning/dispatch.py

@@ -44,6 +44,9 @@
 from concurrent.futures import ThreadPoolExecutor
 from typing import TYPE_CHECKING, Any
 
+from adcp.decisioning.account_projection import (
+    strip_credentials_from_wire_result,
+)
 from adcp.decisioning.platform import (
     GOVERNANCE_SPECIALISMS,
     DecisioningCapabilities,
@@ -393,10 +396,78 @@ def _strict_validate_platform() -> bool:
 # INTERNAL_ERROR breadcrumbs (Emma AudioStack P2)
 # ---------------------------------------------------------------------------
 
-#: Cap on the message+repr we expose to the wire. Long stack traces or
-#: secret-shaped repr (e.g., a ``Credential`` repr that includes the
-#: token) get truncated. Stack trace lives in server logs only.
-_INTERNAL_ERROR_DETAIL_CHARS = 200
+#: Substring suffixes that flag a ctx_metadata key as credential-shaped.
+#: Lowercased for case-insensitive matching against the user-supplied
+#: key. The list intentionally errs broad — a key like
+#: ``"upstream.api_key"`` belongs in :class:`AuthInfo.credential`, not
+#: ``ctx.metadata`` which round-trips into responses.
+#:
+#: Drift policy: when the spec or adopter conventions add a new
+#: credential-shaped suffix, append here. The gate is fail-closed by
+#: design — false positives require the adopter to rename the key, NOT
+#: silently echo the credential.
+_CREDENTIAL_SHAPED_KEY_SUFFIXES: tuple[str, ...] = (
+    "credential",
+    "credentials",
+    "token",
+    "secret",
+    "api_key",
+    "apikey",
+    "password",
+    "bearer",
+)
+
+
+def _validate_ctx_metadata_credentials(metadata: Any) -> None:
+    """Fail-closed gate: ctx.metadata must not carry credential-shaped
+    keys.
+
+    The framework projects buyer-supplied ``context`` extensions into
+    ``tool_ctx.metadata`` and echoes context back on responses per
+    the AdCP spec. An adopter who treats ``metadata`` as a generic
+    KV bucket can accidentally round-trip a credential to the buyer.
+    The ergonomic path for credentials is
+    :class:`AuthInfo.credential` / typed credential classes
+    (:class:`ApiKeyCredential`, :class:`OAuthCredential`,
+    :class:`HttpSigCredential`); ``ctx.metadata`` is for non-secret
+    request-scope hints (correlation ids, feature flags, trace ids).
+
+    Matches against any key whose lowercased form ends with one of
+    :data:`_CREDENTIAL_SHAPED_KEY_SUFFIXES`. Sub-keys at any nesting
+    depth count — a buyer-supplied
+    ``{"upstream": {"api_token": "..."}}`` is rejected the same as
+    a flat ``{"api_token": "..."}``.
+
+    :raises ValueError: when any credential-shaped key is found. The
+        exception message names the offending key path so the adopter
+        knows which field to migrate to ``AuthInfo.credential``.
+    """
+    if not metadata:
+        return
+    if not isinstance(metadata, dict):
+        return
+    for key, value in metadata.items():
+        if isinstance(key, str):
+            lower = key.lower()
+            for suffix in _CREDENTIAL_SHAPED_KEY_SUFFIXES:
+                if lower.endswith(suffix):
+                    raise ValueError(
+                        "ctx_metadata may not contain credential-shaped keys; "
+                        "use AuthInfo.credential (or a typed credential class "
+                        "like ApiKeyCredential / OAuthCredential / "
+                        "HttpSigCredential) instead. Found: "
+                        f"{key!r} (matched suffix {suffix!r}). "
+                        "ctx.metadata round-trips into response context per "
+                        "the AdCP spec; placing a credential here echoes it "
+                        "to the buyer."
+                    )
+        if isinstance(value, dict):
+            try:
+                _validate_ctx_metadata_credentials(value)
+            except ValueError as exc:
+                # Re-raise with the parent key prefixed so the diagnostic
+                # walks the adopter to the offending path.
+                raise ValueError(f"In ctx_metadata[{key!r}]: {exc}") from None
 
 
 def _internal_error_message(method_name: str, exc: BaseException) -> str:
@@ -415,15 +486,18 @@ def _internal_error_details(exc: BaseException) -> dict[str, Any]:
     """Build the wire-side ``details`` payload for an INTERNAL_ERROR
     wrap.
 
-    ``details.caused_by`` carries the exception class name + truncated
-    str — no traceback, no module path, no chained ``__cause__``.
-    The class name lets adopters distinguish ``AttributeError``
-    (typo-shaped) from ``KeyError`` (missing-config-shaped) from
-    ``ConnectionError`` (network-shaped) at a glance.
+    ``details.caused_by`` carries ONLY the exception class name —
+    ``"AttributeError"`` (typo-shaped), ``"KeyError"``
+    (missing-config-shaped), ``"ConnectionError"`` (network-shaped) —
+    enough for the seller dev to triage at a glance. The exception's
+    ``str()`` is deliberately omitted: any truncation length large
+    enough to be useful (200 chars) is also large enough to leak a
+    full OAuth client secret or bearer token if the adopter raised
+    on secret material. The full traceback (with message) lives in
+    the server log via ``logger.exception``; only the wire response
+    is sanitized to a class-name breadcrumb.
 
     **``caused_by.type`` is a debug breadcrumb, not a wire contract.**
-    The value is Python's exception class name verbatim
-    (``"AttributeError"``, ``"KeyError"``, ``"ValidationError"``).
     Buyers built against the JS SDK won't see Python-flavoured class
     names from JS sellers — only Python sellers leak Python types.
     Treat this field as "hint to the seller dev reading their own
@@ -435,11 +509,6 @@ def _internal_error_details(exc: BaseException) -> dict[str, Any]:
     ``recovery`` (terminal/correctable/transient) which IS the
     cross-language contract.
 
-    Truncation is defense-in-depth against an adopter who throws on
-    secret material and ends up with a repr that includes the secret
-    value verbatim. The full traceback is in the server log via
-    ``logger.exception``; only the wire response is sanitized.
-
     **ValidationError special case** (Stability AI Emma P1 from the
     post-#340 matrix): when the platform method raises a pydantic
     ``ValidationError`` directly — typically because the seller's
@@ -454,13 +523,9 @@ def _internal_error_details(exc: BaseException) -> dict[str, Any]:
     where a structured field list is meaningful, so we don't
     generalize this to other exception types.
     """
-    raw = str(exc)
-    if len(raw) > _INTERNAL_ERROR_DETAIL_CHARS:
-        raw = raw[: _INTERNAL_ERROR_DETAIL_CHARS - 3] + "..."
     details: dict[str, Any] = {
         "caused_by": {
             "type": type(exc).__name__,
-            "message": raw,
         }
     }
     # Try to import lazily so a future refactor that splits the
@@ -876,6 +941,19 @@ def _build_request_context(
 
     auth_principal = auth_info.principal if auth_info is not None else None
 
+    # ctx_metadata credential gate — fail-closed before any platform
+    # method sees the metadata. Buyers can populate ``context``
+    # extensions on the wire request that the framework projects into
+    # ``tool_ctx.metadata``; an adopter who treats ``metadata`` as a
+    # general-purpose KV bucket might shove a credential through it,
+    # only to discover the value round-trips into the response (the
+    # framework echoes context into responses per the AdCP spec).
+    # The ergonomic path for credentials is :class:`AuthInfo.credential`
+    # / typed credential classes; ``metadata`` is for non-secret
+    # request-scope hints. See the "ctx_metadata: write-only credentials
+    # prohibited" section in CLAUDE.md.
+    _validate_ctx_metadata_credentials(tool_ctx.metadata)
+
     # Composite cache scope key when store is supplied (production
     # path). Falls back to tool_ctx.caller_identity for test fixtures.
     caller_identity: str | None
@@ -1053,7 +1131,14 @@ async def _invoke_platform_method(
             registry=registry,
             executor=executor,
         )
-    return result
+
+    # Defense-in-depth credential strip on every sync return. The typed
+    # projections (:func:`to_wire_account` etc.) handle the case where
+    # the adopter returns the framework's typed dataclasses; this
+    # boundary catches loose dicts and Pydantic models with
+    # ``extra='allow'``. Method-gated to avoid walking large product
+    # / signal catalogs that can't carry credentials.
+    return strip_credentials_from_wire_result(method_name, result)
 
 
 async def _project_handoff(
@@ -1141,16 +1226,27 @@ async def _run() -> None:
 
         # Persist terminal artifact. Pydantic responses get
         # ``model_dump()``; dict responses pass through.
+        #
+        # Credential strip BEFORE persistence: durable registries
+        # (Postgres, Redis) write the artifact to disk; even in-memory,
+        # ``tasks/get`` returns it verbatim. A bearer credential
+        # surviving the typed projection (e.g., Pydantic
+        # ``extra='allow'`` model carrying ``governance_agents[i].
+        # authentication``) would land in the buyer's ``tasks/get``
+        # poll AND the idempotency replay cache. Method-gated so
+        # non-account methods skip the recursive walk.
         if hasattr(result, "model_dump"):
-            await registry.complete(task_id, result.model_dump())
+            persisted = result.model_dump()
         elif isinstance(result, dict):
-            await registry.complete(task_id, result)
+            persisted = result
         else:
             # Adopter returned an unexpected type (not Pydantic, not
             # dict). Best effort: stringify into a 'value' wrapper so
             # tasks/get returns something. Real impls always return
             # the typed Pydantic response.
-            await registry.complete(task_id, {"value": str(result)})
+            persisted = {"value": str(result)}
+        persisted = strip_credentials_from_wire_result(method_name, persisted)
+        await registry.complete(task_id, persisted)
 
     # ``asyncio.create_task`` only weak-refs the resulting Task — under
     # GC pressure or with no outer awaiter, the task can be collected