docs: add RFC 9421 request signing guide

.changeset/docs-rfc9421-signing-guide.md

@@ -0,0 +1,4 @@
+---
+---
+
+Add RFC 9421 request signing guide: new `docs/building/implementation/request-signing.mdx` covering key generation, JWKS/brand.json publication, buyer-side signing, seller-side verification with `requireAuthenticatedOrSigned` + `mcpToolNameResolver`, webhook signing, key rotation, and conformance testing (39 vectors: 12 positive, 27 negative). Adds a Request Signing section to `build-an-agent.mdx` and cross-links from the `security.mdx` quickstart. Ported from adcontextprotocol/adcp-client#914.

docs.json

@@ -149,6 +149,7 @@
                       "docs/building/implementation/mcp-response-extraction",
                       "docs/building/implementation/a2a-response-extraction",
                       "docs/building/implementation/security",
+                      "docs/building/implementation/request-signing",
                       "docs/building/implementation/webhook-verifier-tuning",
                       "docs/building/implementation/seller-integration",
                       "docs/building/implementation/storyboard-troubleshooting",

docs/building/build-an-agent.mdx

@@ -188,6 +188,50 @@ Each skill includes variant storyboards for different business models — non-gu
 
 See **[Validate Your Agent](/docs/building/validate-your-agent)** for the full testing workflow — debugging failing steps, running compliance checks, and validating interactively through Addie.
 
+## Request signing
+
+If your seller agent receives signed requests from buyers, use `requireAuthenticatedOrSigned` to compose signature verification with existing bearer or API key auth. It handles the full matrix: signature-only when headers are present, fallback-only when absent, and `request_signature_required` 401 for unsigned requests on operations listed in `requiredFor`.
+
+```typescript
+import { createAdcpServer, serve } from '@adcp/client';
+import {
+  verifyApiKey,
+  verifySignatureAsAuthenticator,
+  requireAuthenticatedOrSigned,
+  mcpToolNameResolver,
+  MUTATING_TASKS,
+} from '@adcp/client/server';
+import { BrandJsonJwksResolver, InMemoryReplayStore, InMemoryRevocationStore } from '@adcp/client/signing/server';
+
+serve(() => createAdcpServer({ name: 'My Seller', version: '1.0.0', mediaBuy: { /* ... */ } }), {
+  authenticate: requireAuthenticatedOrSigned({
+    signature: verifySignatureAsAuthenticator({
+      capability: { supported: true, required_for: ['create_media_buy'], covers_content_digest: 'either' },
+      jwks: new BrandJsonJwksResolver(),
+      replayStore: new InMemoryReplayStore(),
+      revocationStore: new InMemoryRevocationStore(),
+      resolveOperation: mcpToolNameResolver,
+    }),
+    fallback: verifyApiKey({ keys: { /* ... */ } }),
+    requiredFor: [...MUTATING_TASKS],
+    resolveOperation: mcpToolNameResolver,
+  }),
+});
+```
+
+For outbound webhook signing, pass a `signerKey` to `createAdcpServer`:
+
+```typescript
+createAdcpServer({
+  webhooks: {
+    signerKey: { keyid: 'my-webhook-key-2026', alg: 'ed25519', privateKey: webhookPrivateJwk },
+  },
+  // ...
+});
+```
+
+See **[Request Signing Guide](/docs/building/implementation/request-signing)** for the full walkthrough: key generation, JWKS publication, brand.json setup, buyer-side signing, and conformance testing.
+
 ## Additional resources
 
 The JS/TS SDK includes documentation designed for both humans and coding agents: