security: do not expose legacy adapter exception text in protocol errors

[bokelley]

Summary

The generic failure paths for legacy request and response adapters include
type(exc).__name__ and str(exc) in buyer-facing AdCP error envelopes. An
unexpected adapter exception may contain internal model names, URLs, query
fragments, filesystem paths, or credential material.

This is the SDK-level form of the error-disclosure class identified while
Prebid Sales Agent audited its shared error normalizer:
prebid/salesagent#2193

Current behavior

On current main (28801dbc2e739541dd40ed2431dcf5aec74f408f):

• A generic exception from legacy_adapter.adapt_request() becomes an
  INVALID_REQUEST whose message includes the exception class and raw text:
  

  adcp-client-python/src/adcp/server/mcp_tools.py

  Lines 2861 to 2876 in 28801db

  	try:
  	params = legacy_adapter.adapt_request(params)
  	except Exception as exc:
  	raise ADCPTaskError(
  	operation=method_name,
  	errors=[
  	Error(
  	code="INVALID_REQUEST",
  	message=(
  	f"Legacy adapter for {method_name!r} at "
  	f"AdCP {wire_version} failed: "
  	f"{type(exc).__name__}: {exc}"
  	),
  	)
  	],
  	) from exc

• A generic exception from legacy_adapter.normalize_response() becomes an
  INTERNAL_ERROR with the same disclosure:
  

  adcp-client-python/src/adcp/server/mcp_tools.py

  Lines 3148 to 3166 in 28801db

  	if legacy_adapter is not None and legacy_adapter.normalize_response is not None:
  	if isinstance(result, dict) and "adcp_error" not in result:
  	try:
  	result = legacy_adapter.normalize_response(result)
  	except Exception as exc:
  	raise ADCPTaskError(
  	operation=method_name,
  	errors=[
  	Error(
  	code="INTERNAL_ERROR",
  	message=(
  	f"Legacy response normalizer for "
  	f"{method_name!r} at AdCP "
  	f"{wire_version} failed: "
  	f"{type(exc).__name__}: {exc}"
  	),
  	)
  	],
  	) from exc

The A2A executor already applies the safer default for an unexpected handler
exception: it logs the traceback and sends a fixed Skill execution failed
message. Legacy-adapter failures should have the same trust boundary.

Proposed behavior

• Treat explicitly typed, buyer-correctable adapter errors as public only when
  their contract says their message is safe for the wire.
• For every other request-adapter exception, preserve INVALID_REQUEST if that
  classification is intentional but send a fixed public message and log the
  original exception with exc_info.
• For every unexpected response-normalizer exception, retain INTERNAL_ERROR
  and send a fixed public message; the original exception belongs only in
  operator diagnostics.
• Centralize this policy so MCP and A2A cannot diverge.

Acceptance criteria

1. A synthetic exception containing a sentinel hostname, query fragment, and
   secret does not place the sentinel in any MCP or A2A wire field.
2. The original exception and traceback remain available to operator logging.
3. Public, explicitly typed buyer-correctable adapter errors retain actionable
   messages.
4. Error codes, recovery metadata, and request-context echo remain unchanged.
5. Tests exercise both the request-adapter and response-normalizer failure
   paths through the real transport-facing dispatcher.

[bokelley]

Triage

Classification: Bug — confirmed information-disclosure vulnerability
Bucket(s): server (no exact label match found — gap noted in run summary)
Status: ready-for-human
Milestone: (omitted — no target version identified)

What the experts said:

• security-reviewer: BLOCKER confirmed at two sites (mcp_tools.py:2872, mcp_tools.py:3162). Both embed f"{type(exc).__name__}: {exc}" directly in buyer-facing Error.message. Realistic credential-leak vector: httpx.HTTPStatusError includes full request URL (embedded API keys in DSP integrations), psycopg2/SQLAlchemy exceptions include DSN with password, OAuth errors include raw token. dispatch.py already applies the correct pattern with a fixed string + logger.exception() — citing this explicitly as the prior art. The four typed-exception str(exc) sites in the same file are intentional and safe.
• ad-tech-protocol-expert: Non-breaking. AdCP spec treats Error.message as advisory human-readable text with no machine-parseable contract — a fixed opaque string is spec-compliant. Changing message from dynamic to fixed is a patch-level hardening, not a version bump. Notes a possible third site at webhook_supervisor.py:601 — verified that DeliveryAttempt.error_message is stored as operator-internal delivery tracking, not echoed to buyers, so it is likely out of scope (should be confirmed during implementation).

My take: Both experts agree the two mcp_tools.py sites are a confirmed, exploitable vulnerability with no preconditions beyond a valid buyer credential. The fix is mechanical — follow the dispatch.py _internal_error_details pattern already in the codebase — but this path is security-sensitive, so flagging for human assignment per policy.

Implementation scope:

• src/adcp/server/mcp_tools.py line 2872: replace f"{type(exc).__name__}: {exc}" with "Legacy adapter request adaptation failed; see server logs for cause". Add logger.error("Legacy adapter for %r at AdCP %s failed during adapt_request", method_name, wire_version, exc_info=True) before the raise.
• src/adcp/server/mcp_tools.py line 3162: same treatment — "Legacy response normalizer failed; see server logs for cause" and logger.error(...) with exc_info=True.
• Optionally surface {"type": type(exc).__name__} in Error.details.caused_by following the _exception_cause_details pattern in dispatch.py to aid operator triage without leaking content.
• Confirm webhook_supervisor.py:601 is operator-only before deciding whether it is in scope.
• Required checks: pytest on the adapter-failure paths with a sentinel string that must not appear in any wire field; mypy src/; ruff check ..
• Acceptance: tests 1 and 2 from the issue are the primary gate; non-breaking per code and protocol (Error.code unchanged, Error.message is advisory only).

@bokelley — security-sensitive path, flagging for your assignment or to designate a reviewer.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_016xTsfFQ8sZZUBAgUQUnPdc

---

Generated by Claude Code