@adcp/sdk 16.0.0-beta.1 → 16.0.0-beta.2

package/docs/migration-agent-identity-3.3.md

@@ -113,7 +113,7 @@ const client = new SingleAgentClient({
   experimentalIdentity33: true,
   webhookSigningProfile: 'web-bot-auth',
   webhookVerification: {
-    webBotAuth: { directory, isRevoked: (origin, kid) => revocations.isRevoked(origin, kid) },
+    webBotAuth: { directory, revocation: revocations },
   },
 });
 ```
@@ -149,8 +149,22 @@ to sign a list of revoked key thumbprints and optional reasons/dates.
 `createSignedOriginRevocationList` provides the same authoring API. The SDK
 supports Ed25519 and P-256 identity keys. Observed key revocations are permanent;
 refresh failures use the last verified list only within the published grace
-window. First-contact identity reads may proceed when no list is available;
-mutating operations fail closed without a current or grace-valid signed list.
+window. Staleness follows the list's signed `next_update`, never the polling
+interval: the verifier re-polls at least every polling interval (at most 30
+minutes) and fails closed only after `next_update` plus four polling
+intervals. Publishers MUST NOT declare `next_update` more than 30 minutes ahead
+(the authoring helper refuses it), but a verifier tolerates a longer cadence
+from other implementations: each successful fetch of such a list stays valid
+for at most 30 minutes plus grace, so an outage cannot extend acceptance past
+that. A list whose `updated` is more than 60 seconds ahead of the verifier
+clock, or whose `next_update` has passed, is refused. `OriginRevocationResolver.status()` reports `revoked`, `current`
+(including within grace), `absent` (the origin answers 404/410: the identity is
+established but cannot be bound for spend) or `unknown` (no verifiable list and
+grace has passed: the identity is not established, so the request is handled as
+unverified). History-store failures throw `revocation_persistence_failed`, an
+infrastructure outage handled by the application layer. `isRevoked()` remains as
+a compatibility wrapper that throws `revocation_unavailable` for `absent` and
+`unknown`.
 
 For positively negotiated 3.3 sellers advertising signed webhooks, experimental
 clients omit injected reporting/task webhook HMAC authentication even when a
@@ -220,8 +234,8 @@ const server = createAdcpServerFromPlatform(platform, {
     assertLegacyOriginAllowed: url => lifecycle.assertLegacyAllowed(url),
     webBotAuth: {
       directory,
-      isRevoked: (origin, kid) => revocations.isRevoked(origin, kid),
-      resolvePrincipal: createIdentity33PrincipalResolver({ lifecycle }),
+      // Revocation and binding run after verification, in the identity layer.
+      resolvePrincipal: createIdentity33PrincipalResolver({ lifecycle, revocation: revocations }),
     },
   },
 });
@@ -268,17 +282,58 @@ redirects, 2 MiB, depth 32, and no duplicate JSON keys. Exactly one canonical
 origin must carry the required role. Cache lifetime is the configured revocation
 poll interval (60–1800 seconds), negatives at most 60 seconds. Failures are not
 absence. Share authoritative-history state when retaining legacy fallback.
+Fetches to an operator's own hosts are rate-limited per (operator, host);
+`authoritative_location` hops to hosts outside the operator's registrable domain
+share one separate per-host budget. A hop therefore never spends the target
+operator's own budget, and many operators cannot multiply fetches to one host.
+A host-rate refusal is a retryable outage that is not cached as the operator's
+failure.
+
+A record that cannot be read (transport error, outage, rate, invalid content)
+raises `TrustRecordUnavailableError`; a current record that does not list the
+origin with the required role raises `TrustMembershipError`. Both extend
+`IdentityAuthorizationError`. For a bound origin:
+
+- **Delisted:** the last record read does not list the origin with the role
+  (operators retire agents by publishing an empty `agents[]`). The origin is
+  identity-established for every request, task polling and cancellation
+  included: the principal resolver demotes it to the per-origin anonymous
+  scope with no credential and no registry-resolved `ctx.agent`, and it gets
+  the anonymous tool policy plus `get_principal` (which reports
+  `unconfigured`). The binding is kept: `open` onboarding cannot re-bind it and
+  RFC 9421 stays refused for the origin. Spend gets `PERMISSION_DENIED` with no
+  details. A known delisting stays a delisting through a later failed refresh.
+- **Unreachable:** a record that cannot be read, including a 404/410 after a
+  record was read (or for any bound origin, on every replica), is a discovery
+  failure, never a removal; the last record read stays authoritative.
+  Spend-committing calls get a retryable `SERVICE_UNAVAILABLE`. As seller
+  policy, reads and identity configuration continue under the binding while
+  the last record read listed the origin and is within
+  `TrustEvaluator({ maxOutageContinuationSeconds })` (default four polling
+  intervals) of its freshness; after that nothing is served (`503`).
+
+After every signature verifies, authorization outcomes use the standard AdCP
+error envelope, never a 403 with `Accept-Signature`. That includes a principal
+resolver that throws: a transient (or uncoded) error is an outage answered
+`503 SERVICE_UNAVAILABLE` by the server, and any other coded error is
+`PERMISSION_DENIED`, delivered on the tool call (other requests are refused with
+that envelope and no challenge).
 
 Demand grants come from the verified brand or house record. Implicit authority
 requires brand, account operator, and signer operator to share a registrable
 domain. Otherwise only a direct grant with the account operator equal to the
-signer, or a two-link chain through the account operator, is accepted. The
+signer, a direct grant from a self-operated brand (the brand is its own account
+operator) to the signer's operator, or a two-link chain through the account
+operator, is accepted. The
 intersection must cover the actual brand IDs, countries, scope, signer-origin
 narrowing and temporal window. A restrictive published grant cannot be
 superseded by seller fallback. A trust 200 disables brand.json authority;
 authoritative absence alone permits explicit legacy policy. An established
 identity lacking a grant gets `PERMISSION_DENIED` with
 `{ scope: 'agent', reason: 'grant_absent' }`. No account or live buy is changed.
+A grantor that once served trust.json and is now unreachable (404/410
+included) never falls back to brand.json `authorized_operators[]`, and it is
+not a grant removal: spend gets a retryable `SERVICE_UNAVAILABLE`.
 
 Origin key revocations use `/.well-known/governance-revocations.json`, signed
 with `typ: adcp-gov-revocation+jws`, as ratified R3 specifies. This origin key
@@ -291,9 +346,10 @@ Permanent revocation storage reserves separate bounded capacity for audited boun
 origins and anonymous/self-service origins, so first-contact traffic cannot exhaust the bound
 pool. Storage failures deny reads and mutations without outage grace; inspect the
 non-enumerable error cause and raise `createIdentity33StateStores.revocationLimits`
-when capacity is exhausted. Existing facts must remain stored. Outage grace is
-available only after that origin's fetch fails, never merely because the global
-fetch limiter is full.
+when capacity is exhausted. Existing facts must remain stored. When the shared
+refresh limiter is full (attacker-selected origins can occupy it), an origin
+whose last verified list is still inside `next_update` plus grace keeps that
+status, exactly as if its own fetch had failed; past grace it fails closed.
 
 ## Authoring and pinned sources
 
@@ -324,12 +380,55 @@ released schemas:
 
 Ratified R2 defaults replay to 429. Older vector negative/002 expects 403;
 `replayStatus: 403` is an explicit compatibility test option, not the default.
+
+Verifier outcomes follow DR-0023 and WBA §5.5/§6.10. `verifyWebBotAuth` needs
+only key discovery and a replay store and returns the verified origins;
+revocation, bindings and the origin-binding fence run afterwards in the
+identity layer (`createIdentity33PrincipalResolver({ lifecycle, revocation })`),
+so verification can run in a CDN or middleware in front of the AdCP server.
+
+- Signature-path errors are WBA statuses and headers only: 400 for a field that
+  does not parse, 403 with `Accept-Signature` for a signature that does not
+  verify, 429 for a replayed nonce. Any AdCP body is the generic authentication
+  error (`AUTH_INVALID`); the specific reason is logged, never sent.
+- A key-directory fetch failure (transport error or any non-200, 404/410/5xx
+  included) is a discovery failure. It never evicts a cached, unexpired
+  directory, which keeps verifying. Without one the request is unverified and
+  answered 403 with `Accept-Signature` (the SDK's default unverified-request
+  policy). A fetched directory without the key is a signature failure.
+- Plain JWKS directories without Appendix B signatures are accepted, with every
+  key checked against its RFC 7638 thumbprint; pass
+  `requireSignedDirectories: true` to the resolver to refuse them. An unsigned
+  directory keeps verifying through failed refreshes for at most
+  `maxUnsignedDirectoryAgeSeconds` (default one day).
+- A revoked key is 403 with the generic authentication error and no
+  `Accept-Signature`: the signer must stop using that key. Revocation status
+  `unknown` (stale past grace) leaves the identity unverified (403 with
+  `Accept-Signature`). An origin that serves no revocation list (`absent`) is
+  identity-established and cannot be bound for spend.
+- Replay-store and revocation-history-store failures are infrastructure
+  outages, raised as `WebBotAuthUnavailableError`. The server integrations
+  answer them at the application layer with 503 `SERVICE_UNAVAILABLE` and
+  `Retry-After`, never as a signature outcome.
+- `webBotAuth.isRevoked`, `requireFreshRevocation` and `deferAuthorizationErrors`
+  are deprecated. A server needs either a revocation-aware principal resolver or
+  the deprecated `isRevoked`, and the webhook receiver either `revocation` or
+  `isRevoked`. The deprecated path cannot express "established but not
+  bindable", so it refuses an origin that serves no list (unverified).
+- Clients act on the HTTP status and `Accept-Signature`, not the generic body:
+  re-sign on 403 with `Accept-Signature`, stop using the key on 403 without it,
+  back off on 429 or 503.
+- `@target-uri` and `@authority` are taken from the target URI as received
+  (RFC 9421 §2.2.2), never canonicalized; canonical origins identify the signer
+  only. Default nonces are 64 bytes (draft §4.2). Ed25519, ECDSA P-256 and
+  RSA-PSS-SHA512 keys are supported. `test/fixtures/wba-interop/` holds fixtures
+  verified in both directions against Cloudflare's `web-bot-auth`.
 Older #7894 governance vectors propose a superseded migration and are retained
 with their non-applicability recorded in `test/fixtures/wba-profile/PINNED.json`.
 The buyer default onboarding field is `profiles.adcp.onboarding`, matching the
 schema; the design's `record_profiles` wording names the schema definition.
 
-The process-local trust evaluator bounds authority history and conservatively disables legacy fallback after history eviction. Production sellers should supply `authorityHistory` from the shared state stores so history survives restarts and cache eviction.
+Process-local authority history is bounded and never evicts remembered operators. Public deployments must supply `authorityHistory` from the shared state stores so history survives restarts and cache eviction. See [Public deployment limits](#public-deployment-limits) for admission and legacy-fallback behavior.
 
 Open `sync_principal` commits the newly approved origin binding before the caller notification-configuration handler runs. A later configuration failure does not undo that binding; retry applies configuration to the same principal. This allocation never grants spend authority: every mutating request still passes tier, relationship and grant checks before provisioning or idempotency.
 
@@ -350,6 +449,46 @@ The standard principal resolver automatically fences RFC signatures for already-
 
 Signing capabilities include the experimental `wba_draft_revision` field next to `profiles`, identifying `draft-ietf-webbotauth-httpsig-protocol-00` as required by ratified R2. Reporting and artifact callback choices are persisted by destination before dispatch, including update calls; their receivers pass the trusted request URL and `taskType` (`media_buy_delivery` or `artifact_delivery`) to `verifyAndParseWebhook`. These deliveries preserve the original payload in `result` after authentication and schema validation; `envelope` adds SDK routing/status metadata. PostgreSQL migrations also add optional `delivery_kind`.
 
-Revocation stores allocate no permanent row for an empty list. Each audited/unbound pool reserves a tenant-wide CAS budget (10,000 origins and 100,000 keys; each operator is limited to 256 origins and 16,384 keys per pool). Audited bindings promote existing facts without deleting them; self-service `openAccess` bindings stay in the unbound pool. Failed writes may conservatively reserve capacity; facts are never evicted to regain it. Store/quota failures return `SERVICE_UNAVAILABLE` for every operation. In-memory revocation storage is for development/tests; production sellers use shared persistent stores.
+Revocation stores allocate no permanent row for an empty list. Each audited/unbound pool reserves a tenant-wide CAS budget (10,000 origins and 100,000 keys; each operator is limited to 256 origins and 16,384 keys per pool). Audited bindings promote existing facts without deleting them; self-service `openAccess` bindings stay in the unbound pool. Failed writes may conservatively reserve capacity; facts are never evicted to regain it. Store/quota failures return `SERVICE_UNAVAILABLE` for every operation. In-memory revocation storage is for development/tests and is bounded per origin, per operator (registrable domain, default 16,384 keys) and in total, so wildcard subdomains of one operator cannot fill it alone (several operators still can, and a refused merge fails closed); production sellers use shared persistent stores.
 
 Unbound callers use an internal per-origin anonymous scope to isolate task/proposal state; this is not a durable principal and is never returned by `get_principal`. Only the explicit anonymous tool policy is allowed.
+
+### Public deployment limits
+
+- **Durable authority history is required for public deployments.** Without
+  `authorityHistory`, the trust evaluator remembers which operators have served
+  a trust record only in process memory. Nothing is evicted, so no operator's
+  legacy `authorized_operators[]` fallback changes because of others, but the
+  memory is bounded: `maxEntries` (default 1,000) in total, at most half of
+  that (`maxPrivateAuthoritativeOperators`) for PSL PRIVATE-section names, and
+  `maxAuthoritativeOperatorsPerPrivateSuffix` (default 32) per hosting provider
+  (the provider's ICANN registrable domain, so every `*.vercel.app`,
+  `*.s3.<region>.amazonaws.com` or `*.<project>.platformsh.site` operator
+  shares one budget). An operator over budget cannot have its trust record
+  accepted in that process: 32 subdomains under one provider block later operators on that
+  provider, and a full `maxEntries` refuses every new trust record publisher.
+  When an operator fits its budget, a history slot is reserved on any 200,
+  before the body is validated, so a removed or invalid record still prevents
+  a legacy downgrade for that remembered operator. An operator refused for
+  lack of budget is not remembered: its trust record remains unavailable,
+  but a later 404/410 is treated as absence and may invoke explicit legacy
+  authorization, as after a process restart. With durable `authorityHistory`,
+  every 200 is recorded, the in-memory set is only a cache, and none of these
+  admission limits refuse records.
+- **The unbound revocation pool can fill.** With the default CAS limits
+  (100,000 keys per pool, 16,384 per operator), about seven registrable domains,
+  including free PSL PRIVATE-section names, can exhaust the unbound pool. New
+  unbound origins with revoked keys then fail closed with `SERVICE_UNAVAILABLE`
+  until capacity is raised; the bound pool is unaffected.
+- **Delisted origins have no exception.** A bound origin whose operator
+  delists it is identity-established for every request, including polling and
+  cancelling tasks it created while it was listed.
+- **Duplicate structured-field keys are rejected.** Signature-Input,
+  Signature and Signature-Agent with a duplicated dictionary member or a
+  duplicated parameter (for example `created=1;created=2`) are malformed: 400
+  under Web Bot Auth, `request_signature_header_malformed` under RFC 9421. RFC
+  8941 parsers keep the last value, which other implementations may not.
+- **`createExpressVerifier` does not implement Web Bot Auth.** It answers a
+  request carrying `Signature-Agent` or the `web-bot-auth` tag with 403 (no
+  challenge) instead of verifying it under RFC 9421. Use `createAdcpServer`
+  `signedRequests.webBotAuth` or `verifySignatureAsAuthenticator({ webBotAuth })`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "16.0.0-beta.1",
+  "version": "16.0.0-beta.2",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",
@@ -859,6 +859,7 @@
     "esbuild": "^0.28.2",
     "esbuild-fix-imports-plugin": "^1.0.23",
     "eslint": "^10.9.1",
+    "http-message-sig": "0.3.0",
     "json-schema-to-typescript": "^15.0.4",
     "json-schema-to-zod": "^2.8.1",
     "openapi-typescript": "^7.13.0",
@@ -873,6 +874,7 @@
     "typedoc-plugin-markdown": "^4.13.0",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.68.0",
+    "web-bot-auth": "0.2.0",
     "zod": "^4.4.3",
     "zod-openapi": "^5.4.3"
   },