feat(server): SubdomainTenantRouter middleware for multi-tenant deployments

[bokelley]

Summary

JS already ships subdomain tenant routing; Python adopters hand-roll it (salesagent's domain_routing.py is ~250 LOC). Ship a Starlette middleware that resolves Host header → tenant, populates a contextvar, hands down to AccountStore/TaskStore/etc.

Design

Surface

• SubdomainTenantRouter Protocol with resolve(host: str) -> Tenant | None method
• Starlette middleware that:
  • Reads Host header
  • Calls the resolver
  • Populates a contextvar with the resolved tenant
  • 404s on unknown hosts
• Reference implementation backed by a static dict mapping (development/test)
• Production adopters back the Protocol with their tenant table

Composition

Tenant-scoped contextvar threads down to AccountStore, TaskStore, BuyerAgentRegistry, etc., letting all downstream stores filter by tenant without explicit plumbing.

Cross-references

• RFC: docs/proposals/v3-identity-bundle-design.md
• JS parity tracker: adcp-client#1249

🤖 Generated with Claude Code

[bokelley]

Triage

Classification: Feature request
Bucket(s): middleware, server
Status: ready-for-human

What the experts said:

• security-reviewer: Two blockers — raw Host must be normalized (port-strip, case-fold, label-depth limit, proxy-trust config) before resolver lookup; and the current_tenant ContextVar needs an explicit cross-check that the bearer token's tenant_id matches the subdomain-resolved tenant, since BearerTokenAuthMiddleware currently overwrites the router's ContextVar value silently with no cross-validation.
• ad-tech-protocol-expert: Design fits the existing RequestContext.tenant_id contract ("typically from host header or URL path") and is independent of the pending v3-identity RFC; the Tenant return type is unspecified and must be resolved before implementation (recommendation: str | None to match existing current_tenant and ToolContext.tenant_id shape).
• code-reviewer: Must reuse adcp.server.auth.current_tenant — a new ContextVar silently breaks auth_context_factory and leaves ToolContext.tenant_id as None; resolve() should return str | None not a new Tenant type; middleware ordering must be documented (subdomain outer, bearer inner).

My take: The feature is architecturally sound, non-breaking, and independent of the pending v3-identity RFC — but Host header normalization and ContextVar cross-check ownership are security-sensitive design decisions that need explicit resolution by @bokelley before a PR can be opened. Three concrete questions to unblock:

1. ContextVar ownership — reuse adcp.server.auth.current_tenant and add a cross-check in BearerTokenAuthMiddleware that principal.tenant_id == current_tenant.get() before overwriting, or use a separate current_subdomain_tenant var that auth reads for the cross-check?
2. Return type — resolve() -> str | None (consistent with all existing tenant-ID fields) or a new Tenant dataclass with additional fields?
3. Unknown-host response — raw HTTP 404 or JSONResponse envelope (consistent with BearerTokenAuthMiddleware._unauthenticated())?

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code