AdCP 3.3 agent identity: Web Bot Auth profile, trust.json, grants, onboarding posture, relationship status #1500

Summary

AdCP 3.3 adds a new way for agents to sign and be identified, and the WG ratified it on 2026-10-12. This issue tracks what this SDK needs to support it.

Spec and decisions

• Umbrella: RFC: agent identity and buyer self-onboarding (3.3 umbrella) adcp#8118.
• Design: specs/agent-identity-3-3.md, merged in docs(specs): propose agent identity and buyer self-onboarding for 3.3 adcp#8119.
• Decision records: DR-0023 (agent identity) and DR-0025 (demand-side grants).
• Migration guide: docs/reference/migration/agent-identity-3-3.mdx (docs: buyer agent self-onboarding walkthrough and agent identity migration guide (P8, P9) adcp#8172).

What changes on the wire

Also new (experimental):

• demand-side grants in trust.json, with the grant_absent reason on PERMISSION_DENIED;
• account.agent_onboarding on capabilities;
• buyer onboarding posture in trust.json;
• relationship on get_principal, with the principal.changed reasons relationship_changed and relationship_expiring;
• optional RFC 5280 revocation_details (reason, invalidity_date) on revocation lists.

Not in 3.3: JWS document signing (governance context iss, designated-task response signing, rights attestations) stays on the RFC 9421 chain until 3.4.

Does this wait for the 3.3 release?

No. Ship behind flags or experimental options, as the 3.3 agent-resolution alignment did (it shipped right after the spec merged, while the wire pin stayed 3.2). The real dependencies:

• Web Bot Auth wire rules and vectors come from docs(security): add the Web Bot Auth request-signing profile (illustrates #7878) adcp#7894 (the WBA profile page and test-vectors/wba-profile/). It is being rebased onto feat(schema): trust.json v1 identifies agents by origin and carries no keys adcp#8121.
• Generated types for the new schemas need the 3.3 beta.0 schema bundle, or a pull from source schemas. The PRs:
  • feat(schema): trust.json v1 identifies agents by origin and carries no keys adcp#8121: trust.json v1 without keys;
  • feat(protocol): first-contact binding and relationship status (agent identity P4) adcp#8168: principal-relationship;
  • feat(protocol): demand-side grants in trust.json and grant_absent (agent identity P5) adcp#8169: grant_absent;
  • feat(schema): seller onboarding posture in get_adcp_capabilities (agent identity P6) adcp#8170: agent_onboarding;
  • docs(security): Web Bot Auth identities and RFC 9421 deprecation (agent identity P3) adcp#8162: revocation details.
• Normative text: security.mdx §Web Bot Auth identities (docs(security): Web Bot Auth identities and RFC 9421 deprecation (agent identity P3) adcp#8162), and accounts-and-agents.mdx §First contact and binding and §Grants in trust.json (#8168, #8169).
• Rollout order across SDKs: the Go verifier currently rejects any extra covered component. Go must ship header tolerance before any SDK's signer covers Signature-Agent by default. Until then, header emission stays opt-in everywhere.

Common work items

Verifier

• Web Bot Auth verification. Parse the covered Signature-Agent member, fetch the directory at that origin (WBA fetch rules; validate the signed directory response, WBA Appendix B.1), and look the key up by (origin, thumbprint kid). Enforce nonce replay, the created/expires window, and tag="web-bot-auth". The result is the verified canonical origin.
• Profile selection. A message carrying Signature-Agent or the web-bot-auth tag is verified under Web Bot Auth only. An uncovered Signature-Agent member is never attributed.
• A resolver for many signers, keyed by the header, so a seller with many buyers needs no hand-written keyid → agent dispatch.
• Revocation at the origin. Read /.well-known/governance-revocations.json (adcp-gov-revocation+jws), parse revocation_details (RFC 5280 reason, invalidity_date), keep the most severe detail ever seen, and never un-revoke.
• Errors as WBA status and headers. Keep the request_signature_* codes for the RFC 9421 profile.

Trust record, binding, grants

• Canonical origin helper. Scheme and authority after URL canonicalization steps 1–4; reuse the existing canonicalization code.
• Trust-record evaluator, called only at binding, grant evaluation, and open onboarding:
  • derive https://{eTLD+1}/.well-known/trust.json with a pinned PSL snapshot (ICANN and PRIVATE sections);
  • SSRF rules, 2 MiB cap, strict parse, one authoritative_location hop;
  • exactly one agents[] match by canonical origin with the required role;
  • freshness cache bounded by the revocation polling interval;
  • fail closed for spend on a fetch failure.
• Binding hooks. An identity-established signer gets no authority. Provide a hook to bind an origin to a principal (one principal per origin). Binding onto an existing RFC 9421 principal needs explicit approval. No downgrade to RFC 9421 for a bound origin.
• Grant evaluation at sync_accounts (DR-0025):
  • the brand's record authorizes;
  • implicit authority when operator, brand, and signer's operator share a registrable domain;
  • otherwise a chain reaching the signer's operator with account.operator on it;
  • intersection along the chain, and exclusive_grants;
  • trust.json 200 disables authorized_operators;
  • PERMISSION_DENIED with { scope: "agent", reason: "grant_absent" }.

Signer and publishing

• Web Bot Auth signer (opt-in): set and cover Signature-Agent with the agent's origin, tag="web-bot-auth", a nonce, and a thumbprint kid.
• Key directory tooling: generate the directory, sign it per key, and re-sign before expires (CLI or helper).
• trust.json authoring/validation helper: one agent per origin, no keys.

Types and surfaces

• Types for the new schemas: account.agent_onboarding (+ tier, requirement, enums), buyer onboarding posture, get_principal relationship, the new principal.changed reasons, grant_absent, revocation_details, and trust.json v1 without jwks_uri.
• Deprecation warning on RFC 9421-profile signing and verification configuration. It keeps working through 3.x.

Docs and tests

• Migration note in this SDK, linked from the spec's migration guide SDK table.
• Conformance: pass the wba-profile vectors once docs(security): add the Web Bot Auth request-signing profile (illustrates #7878) adcp#7894 lands, plus the grant-chain and trust-record vectors (spec P7).

adcp-client-python specifics

• SignerKeyResolver: the protocol needs a signer-origin parameter. Add a DiscoveredSignerKeys resolver keyed by the covered Signature-Agent and wire it into server/signed_requests.py. This also covers Inbound verification accepts one expected agent_url, but brand.json declares agents[] as a list #1214 (more than one expected agent). Size M.
• async_resolve_agent and verify_from_agent_url: keep them for the RFC 9421 profile. The Web Bot Auth path doesn't call capabilities. Size M–L.
• SigningConfig: add the agent origin and header emission. Size S.
• Trust records: move BrandJsonJwksResolver, brand_authz, and governance helpers toward the trust-record type where grants are evaluated. Governance JWS stays on the RFC 9421 chain in 3.3. Size M.
• Timing: 9.0 is still in beta, so any breaking defaults should land before 9.0 GA. COMPATIBLE_ADCP_VERSIONS gains "3.3" when 3.3 is cut.

Rough size overall: M–L.

Refs adcontextprotocol/adcp#8118