docs: add RFC 9421 request signing guide

[benminer]

Summary

• Adds docs/guides/SIGNING-GUIDE.md — a step-by-step guide covering the full RFC 9421 signing workflow: key generation, JWKS/brand.json publication, client-side signing, server-side verification, webhook signing, capability declaration, key rotation, and conformance testing.
• Updates README.md to link the guide from the "For AI Agents" section and rewrites the Security > Request Signing section with better conceptual framing before code examples.
• Adds a Request Signing section to BUILD-AN-AGENT.md showing verifySignatureAsAuthenticator + requireSignatureWhenPresent composition and webhook signer config.

Test plan

• Verify all relative links resolve correctly on GitHub
• Confirm code examples match current @adcp/client API surface (verified against src/lib/signing/ and src/lib/server/auth-signature.ts)

[bokelley]

Nice guide — picking this up after a walk-through with the existing signing helpers. Two ergonomic improvements would cut Step 4 almost in half without changing the conceptual framing.

1. requireAuthenticatedOrSigned already bundles the composition

The SDK ships requireAuthenticatedOrSigned which wraps signature + fallback + requiredFor + resolveOperation into one call. The three-variable manual composition in Step 4 (signatureAuth, bearerAuth, requireSignatureWhenPresent(...)) collapses to:

import {
  serve,
  verifyApiKey,
  anyOf,
  verifySignatureAsAuthenticator,
  requireAuthenticatedOrSigned,
  MUTATING_TASKS,
} from '@adcp/client/server';

serve(createAgent, {
  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: { 'sk_live_abc': { principal: 'acct_42' } } }),
    requiredFor: [...MUTATING_TASKS],
    resolveOperation: mcpToolNameResolver,
  }),
});

The docstring at src/lib/server/auth-signature.ts:414 spells out the full behavior matrix — same presence-gated semantics you describe, plus requiredFor enforcement for the unsigned-no-credentials path (the spec's request_signature_required 401).

2. mcpToolNameResolver removes the resolveOperation boilerplate

The guide (and BUILD-AN-AGENT.md snippet) hand-writes the same JSON-RPC parser three times:

resolveOperation: req => {
  try {
    const body = JSON.parse(req.rawBody ?? '');
    if (body.method === 'tools/call') return body.params?.name;
  } catch {}
  return undefined;
}

I opened #916 to export this as mcpToolNameResolver from @adcp/client/server, so once it lands adapter authors write resolveOperation: mcpToolNameResolver everywhere. The guide above already assumes that — feel free to wait for #916 to merge before the rewrite, or merge as-is and I'll send a follow-up cleanup.

Minor polish (orthogonal to the above)

• Step 4 of the new guide has verifySignatureAsAuthenticator imported twice on adjacent lines — merge into one import block.
• README rewrite drops the conformance-vector count; the guide correctly cites 39 (12 positive + 27 negative = confirmed against compliance/cache/3.0.0/test-vectors/request-signing/).

Happy to push the rewrite into this branch after #916 merges if that's easier than a follow-up PR — just say the word.

[bokelley]

Quick update — the SDK ergonomics that motivated some of the early review comments here have shipped on main:

• feat(server): add mcpToolNameResolver helper for signature auth #916 — mcpToolNameResolver exported from @adcp/client/server (replaces the inlined JSON-RPC parser).
• feat(signing): default stores + upstream, add createAgentSignedFetch preset #917 — defaults for replayStore / revocationStore on both verifySignatureAsAuthenticator AND createExpressVerifier; default for upstream on buildAgentSigningFetch; new createAgentSignedFetch({ signing, sellerAgentUri }) preset for the single-seller buyer case.

The canonical home for the docs is now adcontextprotocol/adcp#3064 — once that merges and a release of @adcp/client carrying #917 ships, the examples there can drop the explicit new InMemoryReplayStore() / new InMemoryRevocationStore() lines and the verbose buildAgentSigningFetch + CapabilityCache + getCapability setup. I've left a parallel comment on #3064 with the specific spots to tighten.

Closing this one out makes sense at this point unless you want to keep it open for cross-reference.

[bokelley]

Cross-SDK update on the ergonomics work this PR's review surfaced:

• TS (`@adcp/client`): #917 merged.
• Python (`adcp`): adcp-client-python#272 open — default `replay_store` on `VerifyOptions`, new `install_signing_event_hook` + `signing_operation` preset, full migration guide.
• Go (`adcp-go`): adcp-go#88 open — default `Replay` store, new `NewSignedHTTPClient` preset with capability-aware signing.

All three carry the same security-by-default replay-store default and the same single-seller buyer preset shape (idiomatic to each language). Canonical docs PR is adcp#3064 — I left a cross-SDK status comment there.