feat(decisioning): BuyerAgentRegistry Protocol + AuthInfo discrimination + billing_capability enforcement (Tier 2)

[bokelley]

Summary

Tier 2 of the v3-identity / round-2 SDK roadmap. Implements the round-2 spine: a BuyerAgentRegistry Protocol that resolves an authenticated agent identity to a registered BuyerAgent record, kind-discriminated Credential union, and billing_capability enforcement on sync_accounts.

Implements the Python side of adcp-client#1269 (JS BuyerAgentRegistry design).

Design

Full design lives in the RFC — see docs/proposals/v3-identity-bundle-design.md, section "Tier 2 — BuyerAgentRegistry (the round-2 spine, per #1269)".

Surface

• BuyerAgent frozen dataclass: agent_url, display_name, status, billing_capability, default_account_terms, allowed_brands, ext
• BuyerAgentRegistry Protocol with factory pattern (signing_only / bearer_only / mixed) per Python feedback at adcp-client#1269 comment
• Kind-discriminated Credential union: ApiKeyCredential | OAuthCredential | HttpSigCredential
• AuthInfo migration with one-minor deprecation cycle (tracked separately in companion issue)
• Dispatch wire-up: registry call after auth verification, before accounts.resolve
• RequestContext.buyer_agent field
• sync_accounts enforcement of billing_capability (reject mismatched billing with INVALID_BILLING_MODEL)
• New error codes: REQUEST_AUTH_UNRECOGNIZED_AGENT, AGENT_SUSPENDED, AGENT_BLOCKED
• Reference: examples/buyer_agent_registry_sqlalchemy.py

Cross-references

• RFC: docs/proposals/v3-identity-bundle-design.md
• JS design issue: adcp-client#1269
• JS parity tracker: adcp-client#1249
• Tier 1 (merged): PR #345
• Companion: AuthInfo migration cycle (filed separately)
• Spec 3.1 alignment: adcp#3690

Notes

Designed against 3.1 shapes — wire types stay 3.0 compliant; data model + Protocols anticipate 3.1's #3690 verifier chain.

🤖 Generated with Claude Code

[bokelley]

Triage

Classification: Feature request — protocol-level auth dispatch
Bucket(s): client, handlers, signing (no matching repo labels exist; gap noted in run summary)
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: approved billing enforcement semantics and dispatch order; concern — HttpSigCredential.agent_url trust comes from the brand.json walk (Tier 1 chain), not from a JWK claim, and the RFC must be explicit about this; concern — mTLS is missing from the Credential union despite appearing in current AuthInfo.kind docs, creating a regression for existing mTLS adopters.
• security-reviewer: BLOCKER — ExplicitAccounts.resolve discards auth_info entirely and resolves off the wire account_id; any caller with a valid credential can request a different tenant's account after passing the registry check (confused-deputy cross-tenant read). Also: billing enforcement must fire on every dispatch, not only sync_accounts, because create_media_buy and other spend-committing tools don't re-run the registry.
• code-reviewer: BLOCKER ×3 — _auth_info_to_dict and dispatch.py access .kind/.principal/.scopes directly on the old AuthInfo shape and must be updated in the same PR; resolve_by_credential silently excludes HttpSigCredential (type hole in the Credential union); dict fields in BuyerAgentDefaultTerms violate the frozen immutability contract. Also: keyid vs key_id naming inconsistency across the union.
• adtech-product-expert: billing binary (passthrough_only | agent_billable) misses the advertiser-billed-with-agent-guarantee case (common at holdco DSPs like TTD/DV360); default_account_terms per-agent is the wrong granularity for enterprise buyers with per-account rate cards; missing seat_ids field will force SSPs to free-form programmatic seat mappings into ext.

My take: Two security blockers and three type-safety blockers block execution. Flagging for @bokelley to resolve: (1) ExplicitAccounts cross-tenant fix strategy, (2) billing ternary vs binary, (3) mTLS credential inclusion, (4) seat_ids field, (5) _auth_info_to_dict migration scope in the same PR.

---

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

---

Generated by Claude Code

[bokelley]

Tier 2 fully landed across four PRs:

• feat(decisioning): Tier 2 — BuyerAgentRegistry + dispatch wire-up + AuthInfo v3 fields (#349) #359 — BuyerAgentRegistry Protocol + dispatch wire-up + AuthInfo v3 fields (data model + factory + enforcement helper)
• chore(decisioning): AuthInfo flat-field synthesis emits DeprecationWarning (#358) #363 — AuthInfo flat-field synthesis DeprecationWarning (closes chore(decisioning): AuthInfo migration to kind-discriminated credential variant #358 sub-task)
• feat(decisioning): PgBuyerAgentRegistry — durable Tier 2 commercial-identity store #364 — PgBuyerAgentRegistry — durable Tier 2 commercial-identity store
• feat(decisioning): AuthInfo.from_verified_signer — bridge to RFC 9421 verifier #365 — AuthInfo.from_verified_signer — RFC 9421 verifier bridge

RequestContext.buyer_agent field, kind-discriminated Credential union (with one-minor deprecation cycle for the flat-field shape), sync_accounts billing_capability enforcement, and Postgres-backed reference store all shipped. Closing.