From 76b36239ce859e9a1f8da01dcdf2c28b4985eb8a Mon Sep 17 00:00:00 2001 From: Constantine Mirin Date: Fri, 2 Oct 2026 18:44:15 -0400 Subject: [PATCH 01/49] docs(security): add Web Bot Auth request-signing profile (illustrates #7878) Publish the Web Bot Auth request and webhook profile proposed for 3.3 alongside the AdCP RFC 9421 profile, which stays as written. The page defines one key-resolution rule (Signature-Agent -> origin -> well-known directory), identity as an origin, mandatory nonce checks by the seller's verifier, relay chains where each later signature covers the earlier ones, status-code error responses, and webhooks as ordinary signed requests from the seller's identity. Add optional request_signing.profiles and webhook_signing.profiles to the capabilities response, and an optional signing_profile to the three notification configuration schemas, all defaulting to the AdCP profile. Add the wba-profile conformance vectors: three positive vectors (single signer, relay with two signatures, signed directory response) and seven negative vectors, each stating its expected status code. Every positive vector verifies with http-message-sig; the single-signer request also verifies with web-bot-auth. Refs #7878 --- .changeset/wba-request-signing-profile.md | 11 + docs/building/by-layer/L1/index.mdx | 1 + docs/building/by-layer/L1/wba-profile.mdx | 312 ++++++++++++++++++ docs/reference/test-vectors/index.mdx | 1 + .../source/test-vectors/wba-profile/README.md | 136 ++++++++ .../source/test-vectors/wba-profile/keys.json | 35 ++ .../negative/001-missing-nonce.json | 46 +++ .../negative/002-replayed-nonce.json | 57 ++++ .../003-signature-agent-not-covered.json | 46 +++ .../004-relay-omits-inner-signature.json | 52 +++ .../005-relay-inner-signature-altered.json | 52 +++ .../006-key-not-in-named-directory.json | 51 +++ .../007-malformed-signature-agent.json | 31 ++ .../positive/001-single-signer-request.json | 35 ++ .../002-relay-request-two-signatures.json | 42 +++ .../003-signed-directory-response.json | 36 ++ .../core/agent-notification-config.json | 6 + .../source/core/notification-config.json | 6 + .../source/core/push-notification-config.json | 6 + .../get-adcp-capabilities-response.json | 28 ++ 20 files changed, 990 insertions(+) create mode 100644 .changeset/wba-request-signing-profile.md create mode 100644 docs/building/by-layer/L1/wba-profile.mdx create mode 100644 static/compliance/source/test-vectors/wba-profile/README.md create mode 100644 static/compliance/source/test-vectors/wba-profile/keys.json create mode 100644 static/compliance/source/test-vectors/wba-profile/negative/001-missing-nonce.json create mode 100644 static/compliance/source/test-vectors/wba-profile/negative/002-replayed-nonce.json create mode 100644 static/compliance/source/test-vectors/wba-profile/negative/003-signature-agent-not-covered.json create mode 100644 static/compliance/source/test-vectors/wba-profile/negative/004-relay-omits-inner-signature.json create mode 100644 static/compliance/source/test-vectors/wba-profile/negative/005-relay-inner-signature-altered.json create mode 100644 static/compliance/source/test-vectors/wba-profile/negative/006-key-not-in-named-directory.json create mode 100644 static/compliance/source/test-vectors/wba-profile/negative/007-malformed-signature-agent.json create mode 100644 static/compliance/source/test-vectors/wba-profile/positive/001-single-signer-request.json create mode 100644 static/compliance/source/test-vectors/wba-profile/positive/002-relay-request-two-signatures.json create mode 100644 static/compliance/source/test-vectors/wba-profile/positive/003-signed-directory-response.json diff --git a/.changeset/wba-request-signing-profile.md b/.changeset/wba-request-signing-profile.md new file mode 100644 index 00000000000..f50d63541f2 --- /dev/null +++ b/.changeset/wba-request-signing-profile.md @@ -0,0 +1,11 @@ +--- +"adcontextprotocol": minor +--- + +Add the Web Bot Auth request-signing profile proposed for 3.3 in RFC #7878, published alongside the AdCP RFC 9421 profile, which stays as written. The page `docs/building/by-layer/L1/wba-profile.mdx` defines the profile: a signer names its origin in a covered `Signature-Agent` header, and the verifier resolves the signer's keys in one step from that origin's `/.well-known/http-message-signatures-directory`. An identity is an origin with one key directory, `keyid` is the JWK thumbprint, every signed request carries an RFC 9421 `nonce` that the seller's verifier MUST check, and signature failures are reported with `400`, `403` with `Accept-Signature`, and `429`. Several signers add their own signatures, each later signer covering the earlier ones, so a seller verifies every party in a relay chain. Webhooks under the profile are ordinary signed requests from the seller's identity. The profile selects options Web Bot Auth and RFC 9421 already define and adds nothing to the wire. + +A verified identity the seller has not approved gets no account access, reads included. After approval, the identity maps to a principal and the principal to its accounts, so onboarding becomes approving a verified identity instead of issuing a credential. + +Additive schema changes: `request_signing.profiles` and `webhook_signing.profiles` on `get_adcp_capabilities` let a seller say which signing profiles it accepts and emits, and an optional `signing_profile` on `push-notification-config`, `notification-config`, and `agent-notification-config` lets a webhook subscriber select the profile it verifies. Omitting every new field keeps the 3.0 to 3.2 behavior. + +Adds the `wba-profile` conformance vectors: three positive vectors (single signer, relay with two signatures, signed directory response) and seven negative vectors (missing nonce, replayed nonce, uncovered `Signature-Agent`, relay not covering the inner signature, inner signature altered after the relay signed, key absent from the named directory, unparseable header), each stating its expected status code. diff --git a/docs/building/by-layer/L1/index.mdx b/docs/building/by-layer/L1/index.mdx index c5f661a767a..ec007616d2a 100644 --- a/docs/building/by-layer/L1/index.mdx +++ b/docs/building/by-layer/L1/index.mdx @@ -23,3 +23,4 @@ For the cumulative cross-layer story (what L0+L1 buys you), see the [SDK stack r - **[Security implementation profile](/docs/building/by-layer/L1/security)** — RFC 9421 wire details, KMS integration, replay-window tuning. - **[Portable attestations](/docs/building/by-layer/L1/security#portable-attestations)** — reference-first claim credentials, evaluator allowlists, safe resolution, verification outcomes, and action binding. - **[Webhook verifier tuning](/docs/building/by-layer/L1/webhook-verifier-tuning)** — clock-skew handling, key-rotation transitions, signature failure diagnostics. +- **[Web Bot Auth request-signing profile](/docs/building/by-layer/L1/wba-profile)** — proposed for 3.3 (RFC #7878): one key-resolution rule from the covered `Signature-Agent` header, identity as an origin, mandatory nonce checks, relay chains, and status-code error responses. diff --git a/docs/building/by-layer/L1/wba-profile.mdx b/docs/building/by-layer/L1/wba-profile.mdx new file mode 100644 index 00000000000..b0f73f3ecb3 --- /dev/null +++ b/docs/building/by-layer/L1/wba-profile.mdx @@ -0,0 +1,312 @@ +--- +title: Web Bot Auth request-signing profile +sidebarTitle: Web Bot Auth profile +description: "Proposed AdCP 3.3 profile of Web Bot Auth for request and webhook signing: keys resolved from Signature-Agent, identity as an origin, nonce checks, relays." +"og:title": "AdCP — Web Bot Auth request-signing profile" +--- + +This page defines an AdCP profile of Web Bot Auth (WBA), the IETF protocol for identifying automated HTTP clients. Under the profile, a seller identifies a signing agent from the request itself. The signer names its origin in a covered `Signature-Agent` header, and the seller fetches the signer's keys from that origin's key directory. The seller then decides, under AdCP's own rules, what the identified agent may do. + + +**Status: proposed for AdCP 3.3.** This page illustrates the request and webhook profile proposed in [RFC #7878](https://github.com/adcontextprotocol/adcp/issues/7878). The proposal publishes this profile alongside the AdCP RFC 9421 profile in [Signed Requests (Transport Layer)](/docs/building/by-layer/L1/security#signed-requests-transport-layer), which stays as written. Nothing on this page is normative until the working group records a decision on the RFC. Document signing and transparency logs are separate decisions and are not part of this page. + + +The profile selects options that WBA and RFC 9421 already define. It adds no headers, tags, key fields, or error codes to the wire. Any implementation of [draft-ietf-webbotauth-httpsig-protocol-00](https://datatracker.ietf.org/doc/draft-ietf-webbotauth-httpsig-protocol/00/) can therefore sign and verify AdCP requests once it is configured with the rules on this page. Section numbers in this page refer to that draft unless they name RFC 9421. + +## What the profile changes for a seller + +Under the AdCP RFC 9421 profile, a seller verifies a signature only from an agent it has onboarded. The agent's key location comes from onboarding or from a registry the seller trusts. Under this profile, the seller learns the signer's identity from the first signed request. Onboarding becomes approving a verified identity instead of issuing a credential. The seller approves an identity from a domain allowlist, from a commercial agreement, or with one click in its admin interface. After that, every signed request from the identity is authenticated without a bearer token. Until the seller approves the identity, the identity gets no account access, reads included. See [Onboarding](#onboarding). + +## One resolution rule + +A verifier resolves a signer's keys in one step: + +```text +Signature-Agent member -> origin -> https:///.well-known/http-message-signatures-directory +``` + +The verifier reads the `Signature-Agent` member keyed to the signature label and takes the origin it names. It fetches the HTTP Message Signatures Directory at that origin's well-known path (section 5.5). One fetch returns one file, and the verifier reads no other document to find keys. The directory is the only key location the profile recognizes. The verifier ignores a `Signature-Agent` member with a `type` parameter other than `directory`, as section 5.2.1 permits for a type the verifier does not support. + +Section 5.5 explains why the well-known path matters: "TLS authenticates the host but not the path", and "The well-known URI is reserved, so directory additionally names a domain". + +## Identity + +Under the profile, an identity is an origin, for example `https://buyer-7k3q.com`. The identity has one key directory, and every key it signs with is published there. The verifier attributes a verified request to that origin and to nothing else. + +Two agents cannot share an origin. An operator that runs several agents gives each its own origin, for example one subdomain per agent. Section 6.5 recommends this for agents that need to be told apart: "these should use distinct signing keys and signing key directories". The same rule separates signing purposes. A signer whose keys must stay isolated from transport keys is its own identity on its own origin. + +`brand.json`, `adagents.json`, and a seller's onboarding records refer to an identity by its origin. If `trust.json` ([#7809](https://github.com/adcontextprotocol/adcp/issues/7809)) moves agents and grants out of `brand.json`, the same rule applies: `trust.json` lists agent origins with their roles and carries no keys. + +An agent that shares a host with other agents under the AdCP RFC 9421 profile keeps using that profile until it moves to its own origin. When it moves, the seller maps the agent's principal to that origin explicitly. Key discovery therefore never changes who the seller considers the caller to be. + +Key lookup is keyed on the pair of origin and key, never on the key alone (section 5.4). A verifier that indexes keys by thumbprint alone attributes a request to whatever origin the signer claims. Negative vector `006-key-not-in-named-directory` grades this rule. + +## Profile rules + +RFC 9421 section 3.2.1 lets an application impose requirements beyond the base specification. Its examples include "Requiring a specific set of header fields to be signed", "Enforcing a maximum signature age", and "Enforcing uniqueness of the nonce parameter". The profile consists of the following rules. Each rule is a requirement of that kind or a choice among options WBA defines. + +| Rule | Profile choice | Basis | +|---|---|---| +| Signature | RFC 9421 with `tag="web-bot-auth"`, `keyid` set to the key's JWK thumbprint, and a covered `Signature-Agent` member naming an origin | Sections 5.2, 5.2.1, 5.5 | +| Components, every request | `@method`, `@target-uri`, `@authority`, `"signature-agent";key=