diff --git a/.changeset/wba-request-signing-profile.md b/.changeset/wba-request-signing-profile.md new file mode 100644 index 00000000000..a8cc172f1eb --- /dev/null +++ b/.changeset/wba-request-signing-profile.md @@ -0,0 +1,13 @@ +--- +"adcontextprotocol": minor +--- + +Add the Web Bot Auth request-signing profile, experimental in 3.3 and adopted by DR-0023, 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, every signing key is an Ed25519 key, `keyid` is the JWK thumbprint, and every signed request carries an RFC 9421 `nonce` of 64 bytes, as unpadded base64url or canonical padded base64, that the seller's verifier MUST check. Signature failures are reported with `400`, `403`, and `429`. A request carries exactly one `web-bot-auth` signature and one `Signature-Agent` member, and a verifier does not read signatures with other tags; a party that signs a request is its signer, and whether it may act for another party is answered by that party's `brand.json` or `trust.json`. A directory response is served with the `application/http-message-signatures-directory+json` media type and signed by each Ed25519 key it holds; a verifier uses each Ed25519 key with a valid signature, ignores every other key, and refuses a directory in which any key carries a private member. Webhooks under the profile are ordinary signed requests from the seller's identity. A governance agent is an identity like any other, on its own origin; JWS artifacts, such as governance tokens, are outside this profile. The profile selects options Web Bot Auth and RFC 9421 already define and adds nothing to the wire. + +Two checks have no Web Bot Auth library behind them, so they live in the AdCP layer, in the `security.mdx` section "AdCP checks after Web Bot Auth verification": the identity's revocation list, signed by a key in the identity's directory with JWS `alg` `EdDSA`, and the `Accept-Signature` hint on a `403` or `429`, which is a SHOULD. + +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, experimental `signing_profile` on every webhook registration (`push-notification-config`, `notification-config`, `agent-notification-config`, `reporting-webhook`, and `artifact_webhook` on `create_media_buy`) lets a webhook subscriber select the profile it verifies; a registration that carries both `signing_profile` and `authentication` fails schema validation. `reporting_webhook` and `artifact_webhook` still require `authentication`, so `signing_profile` is usable there once adcontextprotocol/adcp#8177 makes `authentication` optional. Omitting every new field keeps the 3.0 to 3.2 behavior. + +Adds the `wba-profile` conformance vectors: two positive vectors (single signer, signed directory response) and six negative vectors (missing nonce, replayed nonce, uncovered `Signature-Agent`, key absent from the named directory, unparseable header, two signatures on one request), each stating its expected status code. Adds `scenarios.json`, 49 failure scenarios as data that a harness signs at run time, each with its expected outcome and a tier that says whether a Web Bot Auth library alone gives that outcome or only the profile's rules do. diff --git a/docs/building/by-layer/L1/index.mdx b/docs/building/by-layer/L1/index.mdx index c5f661a767a..66307e44329 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)** — experimental in 3.3, adopted by DR-0023: one key-resolution rule from the covered `Signature-Agent` header, identity as an origin, mandatory nonce checks, one signature per request, and status-code error responses. diff --git a/docs/building/by-layer/L1/security.mdx b/docs/building/by-layer/L1/security.mdx index eda07ebdbdc..76aea559779 100644 --- a/docs/building/by-layer/L1/security.mdx +++ b/docs/building/by-layer/L1/security.mdx @@ -1606,6 +1606,37 @@ Operators SHOULD serve a single combined revocation list at the brand.json origi Verifiers accepting request-signed mutations MUST poll the revocation list on the cadence declared in `next_update` (floor 1 min, ceiling 30 min). The fetch-failure safe-default applies with grace = 4× the previous polling interval: verifiers that have not refreshed within `next_update + grace` MUST reject new request-signed mutations with `request_signature_revocation_stale` until the list is refreshed. +#### AdCP checks after Web Bot Auth verification + + +These checks belong to the [Web Bot Auth request-signing profile](/docs/building/by-layer/L1/wba-profile), which is experimental in AdCP 3.3, adopted by [DR-0023](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0023-agent-identity-is-an-origin.md). + + +A Web Bot Auth (WBA) verifier configured with the profile's rules decides whether a request is validly signed and which origin signed it. AdCP adds two checks that run after that verifier returns, each on a different outcome. The revocation-list check runs only after verification succeeds. The `Accept-Signature` field goes only on the verifier's `403` or `429` refusal. A standard WBA library does not perform them, so an implementation runs them in its AdCP layer. The WBA profile's conformance vectors do not grade them. + +**Revocation list.** After WBA verification succeeds, the verifier checks the signing identity's revocation list, the list that [Transport revocation](#transport-revocation) defines. The following rules apply under the profile: + +- The identity's origin serves the list, with the path and media type that Transport revocation uses. The verifier accepts the list only from that origin. +- A key in the identity's key directory signs the list, with the JWS `alg` `EdDSA`. +- Entries in `revoked_kids` are JWK thumbprints. The verifier matches them against the signature's `keyid`. + +[Transport revocation](#transport-revocation) states the polling cadence and what a request gets when its key is revoked or the list is missing or stale. + +The list lives on the same origin as the key directory. An outage that keeps a stale directory in use also leaves the list unrefreshed, so the safe default bounds how long a removed key commits spend during a discovery failure. + +**`Accept-Signature` on a refusal.** When WBA verification refuses a request with `403` or `429`, the verifier SHOULD add an `Accept-Signature` field (RFC 9421 section 5.1). WBA section 5.3 lets an origin request a signature this way. The field names the label, the covered components, and the parameters the profile requires: + +```http +NOTE: '\' line wrapping per RFC 8792 + +HTTP/1.1 403 Forbidden +Accept-Signature: sig1=("@method" "@target-uri" "@authority" "content-type" \ + "content-digest" "signature-agent";key="sig1");created;expires;nonce;ke\ + yid;alg;tag="web-bot-auth" +``` + +On a `429`, the field SHOULD also carry a fresh `nonce` for the signer's next attempt. The verifier SHOULD add the same field to its answer to an unsigned request for an operation in `required_for`. A `400`, a revoked key, and an AdCP authorization error carry no `Accept-Signature`. + #### Transport capability advertisement Verifiers advertise signing support and per-call requirements via the `request_signing` block on `get_adcp_capabilities`: 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..a9d602ce953 --- /dev/null +++ b/docs/building/by-layer/L1/wba-profile.mdx @@ -0,0 +1,287 @@ +--- +title: Web Bot Auth request-signing profile +sidebarTitle: Web Bot Auth profile +description: "Experimental AdCP 3.3 Web Bot Auth profile for request and webhook signing: keys from Signature-Agent, an origin as the identity, and one web-bot-auth signature." +"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: experimental in AdCP 3.3**, adopted by [DR-0023](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0023-agent-identity-is-an-origin.md). The profile is published 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. 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. The member value is exactly the ASCII serialization of an `https` origin (RFC 6454 section 6.2), such as `https://buyer-7k3q.com`: a lowercase host, no default port, no trailing `/`, and no path, query, fragment, or userinfo (sections 5.2.1 and 5.5). A signer sends that canonical origin. A verifier compares the value with it as a string, without normalizing, and refuses any other value, including an `http` origin, with `403`. 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.2.1 defines `type` as a Token, and a verifier accepts `type=directory` as a Token or as a String, as the reference library does. + +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 covers purposes: a governance agent is an agent like any other, on its own origin (see [One agent per purpose](#one-agent-per-purpose)). + +`brand.json`, `adagents.json`, and a seller's onboarding records refer to an identity by its origin. So does [`trust.json`](/docs/reference/trust-json): it lists agent origins with their roles and carries no keys. A multi-tenant vendor gives each tenant its own subdomain, for example `https://7f3a9c.sentinel-governance.example`, which serves that tenant's key directory. + +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 `004-key-not-in-named-directory` grades this rule. + +## One agent per purpose + +Purpose belongs to the agent, not to the key. A governance agent is an identity like any other, on its own origin, with its own key directory, so no key and no directory states a purpose. JWS artifacts, such as governance tokens, are outside this profile. + +## 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 whose value is the ASCII serialization of an `https` origin (RFC 6454 section 6.2), with no path, query, fragment, or userinfo | Sections 5.2, 5.2.1, 5.5 | +| `Signature-Agent` value | Exactly the ASCII serialization of an `https` origin: a lowercase host, no default port, no trailing `/`, and no path, query, fragment, or userinfo. A verifier compares the string without normalizing and refuses any other value with `403` | Sections 5.2.1 and 5.5; RFC 6454 section 6.2 | +| Components, every request | `@method`, `@target-uri`, `@authority`, `"signature-agent";key=