feat(signing): SigningProvider abstraction for KMS-backed RFC 9421 signing

[bokelley]

What this PR does

Adds a pluggable SigningProvider interface so AdCP RFC 9421 private keys can live in a managed key store (GCP KMS, AWS KMS, Azure Key Vault, HashiCorp Vault Transit) instead of process memory. The async sign(payload) boundary matches RFC 9421 §3.1: the SDK produces the canonical signature base, the provider returns wire-format signature bytes.

Closes #1009. Sibling work tracked in #1015 (distributed ReplayStore for multi-instance verifiers).

Wire format unchanged. No AdCP version bump. SDK minor: 5.19.0 → 5.20.0.

What's worth a second pair of eyes

1. Sync and async share the same canonicalization helpers

signRequest and signRequestAsync go through prepareRequestSignature + finalizeRequestSignature in src/lib/signing/signer.ts. Same for webhook. The only path-difference is whether the bytes go to produceSignature (sync, in-process Node crypto) or await provider.sign (async, KMS round-trip). Canonicalization can't drift between the two paths because there's only one canonicalization. The shared helpers are exported from @adcp/client/signing so other entry points can reuse them.

There's also a property test (fast-check, 50 fuzzed requests per run) asserting byte-identical signatureBase, Signature-Input, and Signature between sync and async for Ed25519 — defense in depth in case anyone reintroduces duplicate code paths in the future.

2. Discriminated AgentRequestSigningConfig on kind

type AgentRequestSigningConfig = AgentRequestSigningConfigInline | AgentRequestSigningConfigProvider;

'inline' is the default (kind optional on the existing shape — current literals work without changes). 'provider' is required on the new shape. The narrowing flows through to agent-context.ts and agent-fetch.ts via the isInlineSigningConfig / isProviderSigningConfig predicates so unsafe field access is caught at compile time.

3. Defensive cache-key hashing for provider-supplied fingerprints

buildAgentSigningContext SHA-256s algorithm + '\0' + keyid + '\0' + fingerprint before composing transport- and capability-cache keys. A buggy adapter that returns kid, '', 'default', or a tenant-controlled string for fingerprint still produces 64-bit collision-resistant output. Two distinct keys with identical raw fingerprints don't collide because algorithm and kid are folded in. This preserves the multi-tenant isolation property that the in-memory path has always provided.

4. Identity snapshot at fetch construction

buildAgentSigningFetch wraps the provider in a frozen-identity view (keyid / algorithm / fingerprint snapshotted once) before passing it to createSigningFetchAsync. Wire keyid/alg cannot drift away from the cache key the connection was bound to even if a downstream adapter mutates fields after construction.

5. Non-UTF-8 byte bodies are rejected explicitly

bodyToString in both fetch.ts and fetch-async.ts uses TextDecoder fatal-mode and throws on invalid UTF-8. Previously Buffer.from(body).toString('utf8') silently replaced invalid bytes with U+FFFD; verification still passed because the wire and the digest agreed on the lossy string, but the seller received mangled content. Real footgun for binary payloads — KMS audience hits this faster than the inline-key audience.

6. InMemorySigningProvider NODE_ENV gate, scoped to the reference impl

Constructor refuses to instantiate when NODE_ENV=production (case-insensitive) unless ADCP_ALLOW_IN_MEMORY_SIGNER=1 is set. Lives under @adcp/client/signing/testing so production imports surface the KMS path first. The interface JSDoc explicitly notes that this gate is a self-discipline aid for the bundled implementation only — the SDK can't (and doesn't try to) enforce hygiene on third-party providers.

7. GCP KMS reference adapter as an example, not a bundled dep

examples/gcp-kms-signing-provider.ts — type-checked under npm run typecheck:examples, demonstrates the DER → IEEE P1363 conversion (via the shared derEcdsaToP1363 helper), pre-flight algorithm validation via one getPublicKey call, and the consumer-side KeyManagementServiceClient wiring. The published package stays free of @google-cloud/kms; users npm i the cloud SDK they need.

Migration

Existing callers passing { kid, alg, private_key, agent_url } continue to work unchanged (no kind field needed). New callers pass { kind: 'provider', provider, agent_url }.

In-process cache-key shape changed for inline configs (sha256(alg + kid + sha256(kid + d).slice(16)) vs old sha256(kid + d).slice(16)). Cache is in-process with a 5-minute TTL, no persistence boundary — entries become unreachable on upgrade and re-prime within seconds. Verified call sites (protocols/mcp.ts, protocols/a2a.ts, capability-priming.ts) consume cacheKey opaquely.

Test plan

• npm run typecheck — clean
• npm run typecheck:examples — clean
• npm run format:check — clean
• npm run build:lib — clean
• 25 new tests in test/request-signing-provider.test.js
• Existing 188 signing tests pass — no regressions
• Property test (fast-check, 50 runs) asserts sync/async equivalence

Deferred follow-ups

• Distributed ReplayStore adapter (Redis) for multi-instance verifiers — filed as Distributed ReplayStore adapter (Redis) for multi-instance verifier deployments #1015, no dependency on this PR.
• AWS KMS / Azure Key Vault example adapters — pattern is identical to the GCP example; ship if/when there's demand.
• @google-cloud/kms's crc32c integrity field on asymmetricSign — defensive, not required by the spec.
• InMemorySigningProvider.sign re-imports createPrivateKey per call — testing-only path, perf optimization not correctness.

🤖 Generated with Claude Code

[bokelley]

Pushed c61b1a80 addressing the substantive items.

Two big ones, fixed properly:

1. Sync/async share canonicalization. Took the refactor route over the test-only route. prepareRequestSignature / prepareWebhookSignature / finalizeRequestSignature live in signer.ts; both sync and async paths consume them. The only difference between paths is now produceSignature vs await provider.sign. Added a fast-check property test (50 fuzzed requests per run) that asserts byte-identical Ed25519 sync/async output as belt-and-suspenders — if anyone reintroduces duplicate canonicalization in the future, the property fails.

2. Non-UTF-8 byte bodies — fixed in both wrappers, not deferred. bodyToString in fetch.ts and fetch-async.ts now uses TextDecoder fatal-mode and throws a clear TypeError on invalid UTF-8. Previous lossy Buffer.toString('utf8') behavior is gone from both paths. Added a regression test for the rejection path.

Smaller items:

• AgentRequestSigningConfigProvider.provider is now a top-level import type rather than inline import(). Verified there's no cycle — signing/provider.ts imports AdcpSignAlg from signing/types.ts, and signing/types.ts doesn't import from types/adcp.ts.
• derEcdsaToP1363 now parses the SEQUENCE total content length and validates against buffer end (in addition to per-INTEGER bounds checks already there).
• SigningProvider JSDoc explicitly notes the NODE_ENV gate scope: it's a self-discipline aid for the bundled InMemorySigningProvider only; the SDK can't enforce hygiene on third-party providers.
• GCP example usage block now shows the consumer-side KeyManagementServiceClient construction and explicit client parameter.

Publish state confirmed: npm view @adcp/client@5.19.0 shows the currently-published version (without SigningProvider). The changeset is minor, so this PR ships 5.20.0 on merge. The package.json 5.19.0 you're seeing locally is just the most recent release — no skew with what's on npm.

PR description rewritten to lead with the seven substantive items rather than the review-cleared framing. Reviewers can now see what they're actually being asked to look at.

Test totals: 25 provider tests (was 23) + 188 existing signing tests, all green.

[bokelley]

Pushed 38a35271:

• Changeset note added. New paragraph calls out the behavior change for non-UTF-8 byte bodies (was silent U+FFFD; now TypeError), names the escape hatch, gives anyone whose CI starts failing a finder.
• ECDSA property test added. Same fast-check arbitrary, asserts identical signatureBase + Signature-Input across sync/async (50 runs). Skips comparing Signature bytes since ECDSA is non-deterministic. The canonicalization invariant now holds for both algs.

Skipping the DER trailing-bytes nit and the SigningProviderErrorCode single-member-union per your "won't push / no objection." Will revisit the union if/when a second code joins it.

Thanks for the careful read — the prepare/finalize helpers being reusable for future signers (sigstore, custom HSM) is a good framing; I hadn't named that benefit explicitly but it's exactly why I picked the refactor over the test-only path.

Ready when you are.