feat(examples): v3 reference seller — canonical multi-tenant runnable example

[bokelley]

Summary

A complete runnable seller adopters fork-and-modify. Multi-file directory under examples/v3_reference_seller/ integrating every Tier 1/2/3 component end-to-end.

Scope

Models (SQLAlchemy)

• Tenant — multi-tenant root
• BuyerAgent — round-2 spine record
• Account — v3-spec columns including 3.1-ready billing_entity, reporting_bucket, billing_capability
• MediaBuy

Components

• BuyerAgentRegistry Postgres impl
• BrandJsonJwksResolver + BrandAuthorizationResolver (stub until adcp#3690)
• HTTP-Sig verification end-to-end + bearer fallback
• Postgres-backed WebhookDeliverySupervisor
• AuditSink impl with DB + Slack
• Subdomain tenant routing
• MCP+A2A on one binary
• Minimal admin REST API for agent/tenant CRUD
• docker-compose with Postgres + Alembic migrations
• README clone-and-modify guide

Size

~3–5k LOC of reference infrastructure.

Why

Validates our own designs by building the canonical pattern. Spec 3.0-compliant on the wire, 3.1-ready in architecture and schema.

Cross-references

• RFC: docs/proposals/v3-identity-bundle-design.md
• Tier 1 (merged): PR #345
• Webhook supervisor (merged): PR #348
• ADCP spec issue: adcp#3690
• JS parity tracker: adcp-client#1249

Depends on: Tier 2 BuyerAgentRegistry, Tier 3 BrandAuthorizationResolver, AuditSink Protocol, Postgres WebhookDeliverySupervisor, SubdomainTenantRouter middleware, MCP+A2A unified binary.

🤖 Generated with Claude Code

[bokelley]

Triage

Classification: Feature request
Bucket(s): examples, security-sensitive
Status: ready-for-human

What the experts said:

• dx-expert: Epic-shaped; 3–5k LOC as one PR is unreviable; docker-compose + subdomain routing add significant setup friction; adcp#3690 only blocks BrandAuthorizationResolver, not the whole example; a shippable subset (~400–600 LOC: models + SQLite Alembic) could land independently.
• docs-expert: ~30–40% of proposed scope is stubs for unshipped Tier 2/3 interfaces; BrandAuthorizationResolver stub risks misleading readers into shipping without authorization checks; recommend 3-milestone phased delivery, Milestone 3 gated on adcp#3690.
• security-reviewer: 4 blockers before any PR — (1) HTTP-Sig/bearer fallback enables downgrade if required_for isn't populated for spend-committing ops; (2) per-process replay store breaks cross-replica nonce dedup under docker-compose scaling; (3) BrandAuthorizationResolver stub has no eTLD+1 binding, silently skips authorization; (4) admin REST API has no role model, enabling cross-tenant IDOR.

My take: This is a genuinely needed reference that validates the v3 design end-to-end. The four security design questions need written answers before any implementation PR — especially the admin role model and the BrandAuthorizationResolver shipping without authorization enforcement. Recommend converting to an epic with three milestones: (1) models + SQLite Alembic skeleton, (2) docker-compose + HTTP-Sig + tenant routing with a security design doc resolving fallback ordering and replay-store coordination, (3) BrandAuthorizationResolver after adcp#3690.

---

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

---

Generated by Claude Code