Add SigningProvider abstraction for external key management (KMS/HSM/Vault)

[bokelley]

Problem

The current signer requires the private JWK to live in process memory. The AdCP spec is explicitly key-storage-agnostic and recommends KMS/HSM ("Store keys in HSM or KMS rather than on disk" — docs/building/implementation/security.mdx), but the SDK forces in-memory storage in practice.

For production deployments this is real friction: operators who want to keep private keys in AWS KMS / GCP KMS / Azure Key Vault / Vault Transit have to either fork the signer or pull the key out of KMS into memory at boot — which defeats the point of using a managed key store. This is especially relevant for the Go SDK since Go is the common choice for production agent surfaces (e.g. agentic-api) where KMS-backed signing is table stakes.

Proposal

Add a SigningProvider interface with a context-aware Sign() operation. The in-memory path stays the default for testing. External providers (KMS / HSM / Vault) plug in by implementing the interface.

type SigningProvider interface {
    Sign(ctx context.Context, payload []byte) ([]byte, error)
    KeyID() string
    Algorithm() string // "Ed25519" | "ECDSA-P256" | "RSA-PSS"
}

Built-ins to ship:

• InMemorySigningProvider (current behavior, default, used in tests)
• Documentation/example for at least one cloud KMS (AWS KMS via aws-sdk-go-v2/service/kms is the obvious starter; GCP KMS via cloud.google.com/go/kms is a close second given common Go deployment targets)

Notes

• The interface takes context.Context from the start — KMS sign latency is typically 10–50ms, calls can fail or deadline, and retries / backoff need cancellation.
• This is purely an SDK concern; no spec change needed. The spec already permits any signing path that produces a verifiable RFC 9421 signature against the keys published at jwks_uri.
• RFC 9421 signing is recommended in 3.0, required for mutating/financial operations in 3.1+, and fully required at 4.0 (early 2027 target). Closing the KMS gap before 3.1 makes adoption a lot easier for serious deployments.

Context: came up while reviewing a buyer-side production deployment where KMS was the desired storage path; verifier side has the same issue if an operator wants to cache verified keys behind a managed store.

[bokelley]

Triage

Classification: Feature request — SDK abstraction
Bucket(s): tmpclient (signing SDK surface) — note: no tmpclient repo label exists; flagged in run summary
Status: ready-for-human — design blockers must be resolved before implementation

What the experts said:

• code-reviewer: two blockers — Algorithm() string conflicts with the existing Algorithm typed const (RFC 9421 wire values), and NewSigner/NewSignedHTTPClient hard-require PrivateKey != nil, so the integration path needs a precise opt-in
• ad-tech-protocol-expert: blocker — Algorithm() returning "Ed25519" / "ECDSA-P256" instead of "ed25519" / "ecdsa-p256-sha256" would produce signatures that fail the verifier's alg.Allowed() check; RSA-PSS is not in the current AdCP profile and is scope creep for this issue
• security-reviewer: two blockers — KMS error strings (ARN paths, resource names, permission-denied detail) flow verbatim into the fmt.Errorf("signing: sign: %w", err) chain and could surface in HTTP responses, violating AGENTS.md "never echo err.Error()"; additionally Algorithm() as string allows a misconfigured provider to inject an arbitrary alg value with no validation against the allowlist; also flags that Sign() must document that it is stateless with respect to payload (no caching of signed bases — nonce reuse risk)

My take: The direction is correct and well-motivated — the sub-module pattern (adcp/signing/awskms/ etc.) is the right home for cloud deps and keeps the root module clean. However, the interface as written has two wire-breaking design errors (Algorithm type and error surface) that all three experts flagged as blockers; the interface should not be implemented until those are resolved in the issue.

---

Specific design constraints for the refined proposal:

1. Algorithm() must return signing.Algorithm, not string. The existing Algorithm type ("ed25519", "ecdsa-p256-sha256") is the RFC 9421 wire value written directly into alg= sig-params by formatSigParams. The return value must be validated against Algorithm.Allowed() at provider construction time (not per-request). A provider returning a non-allowed value should be rejected by NewSignerFromProvider.

2. KMS errors must be wrapped, not forwarded. Sign(ctx, payload) implementations must map KMS SDK errors to a stable signing.SigningError type (parallel to the verifier's Error) before returning. The interface contract should document this explicitly — raw aws/kms, cloud.google.com/go/kms, or vault error strings must never be returned unwrapped, as they travel up the chain through SignRequest → RoundTrip → caller.

3. NewSigner integration path needs a precise spec. The cleanest non-breaking approach: add an optional Provider SigningProvider field to SignerOptions; NewSigner accepts (Provider != nil) || (PrivateKey != nil) and short-circuits the key-type switch when Provider is set. The InMemorySigningProvider becomes a thin wrapper over the existing sign() logic. Specify this precisely in the issue before implementation.

4. RSA-PSS: out of scope for this issue. The AdCP profile's Algorithm.Allowed() does not include RSA-PSS. Including it in the Algorithm() comment creates a false affordance — operators who provision RSA-PSS KMS keys will see runtime rejections. Remove it; track it as a separate issue if needed.

5. r.Context() threading. The provider path should call provider.Sign(r.Context(), base) from within signingTransport.RoundTrip (where the context is available on the cloned request), not through the existing context-free sign() helper.

6. tmproto/signing.go is out of scope. It is a zero-dep root-module path using a hand-rolled epoch scheme, not RFC 9421. Importing context there would violate the root module's dep posture.

7. KeyID() stability contract. Document that KeyID() must be stable for the lifetime of the provider instance; key rotation requires constructing a new provider after the JWKS has been updated and propagated (verifiers have a ~30s refetch cooldown).

@bokelley — once the interface spec above is incorporated into the issue, this is Execute-eligible (non-breaking additive interface + InMemorySigningProvider + sub-module for KMS examples). Happy to re-triage on /triage execute once the proposal is updated.

---

Triaged by Claude Code. Session: https://claude.ai/code/cse_016r4rTRCuRr9TkzZxLkxFpv

---

Generated by Claude Code

[bokelley]

Reference implementation status (2026-04-28)

The JS reference (@adcp/client) shipped the full SigningProvider abstraction over a multi-version arc this week. Final state at 5.21.1:

• 5.20.0 — SigningProvider interface for outbound request signing (sync/async parity, in-memory + GCP KMS reference adapter, DER → IEEE P1363 ECDSA conversion helper).
• 5.21.0 — signerProvider option on createWebhookEmitter, PostgresReplayStore (adcp-client#1018) for distributed verifier deployments, pemToAdcpJwk JWKS-publication helper, assertProviderPublicKeyMatches tripwire helper, createGcpKmsSigningProviderLazy lifecycle helper.
• 5.21.1 — grader IP-pin fix against Cloudflare-fronted endpoints. (adcp-go doesn't ship a CLI grader so this doesn't translate directly; noted for completeness.)

Six learnings from the first KMS adopter rollout

Filed against @adcp/client as adcp-client#1022 (closed). Worth carrying over to Go's SigningProvider design:

1. Lifecycle: lazy init, not eager. Calling KMS GetPublicKey (or any warm-up) before binding the listener has a dangerous failure mode: gRPC retries inside the KMS client block indefinitely, the process never opens its port, and the infrastructure health-check times out without surfacing the underlying KMS error. Lazy init on first sign with retry-on-failure (cache success only, never errors) and in-flight-call coalescing (Go: sync.Once is wrong here — use a mutex with cached result + retry on miss) is the right pattern. We took down our prod deploy with eager init in adcp#3283 and had to revert.
2. Tripwire: assert public key at init. Managed key stores can silently rotate. Commit the expected SPKI bytes alongside code; assert at init that KMS returns the same bytes. Mismatch fails loudly rather than silently emitting signatures verifiers reject.
3. JWKS-publication helper. Every KMS adopter needs to publish a JWK for the verifier side. Easy to mis-implement (wrong alg value, missing adcp_use, wrong key_ops). A helper that takes the PEM + kid + algorithm + adcp_use and emits the right shape prevents drift.
4. Distinct key material per adcp_use — spec-required. AdCP spec (docs/guides/SIGNING-GUIDE.md § Key separation) requires distinct cryptoKeyVersions per signing purpose, not just RFC 9421 tag isolation. Receivers enforce purpose at the JWK's adcp_use field per adcp#2423. The SigningProvider design should make this discoverable — at minimum, docstring warning; ideally, the JWKS-publication helper takes adcp_use as a required parameter.
5. Fingerprint logging caveat. GCP KMS resource names embed project IDs. If the SigningProvider exposes a Fingerprint field for cache disambiguation, the docstring should warn against logging it raw.
6. Test surface awareness. When a regression report comes in, confirm which test surface produced it before forming a theory. Each runs code in different environments — DB pool availability, env vars, KMS credentials.

Adjacent gaps Go may want as separate issues

JS landed two pieces of infrastructure beyond the core SigningProvider interface that have no Go equivalent yet:

• PostgresReplayStore parity — adcp/signing/replay.go ships only an in-memory ReplayStore. Multi-instance deployments (≥2 verifier processes behind a load balancer) lose replay protection across the pool: a captured signature replayed against a sibling process whose memory cache hasn't seen the nonce gets accepted. The JS SDK closed this in adcp-client#1018 with a Postgres-backed ReplayStore using (keyid, scope, nonce) as the primary key with ON CONFLICT DO NOTHING for atomic replay rejection. Worth filing as a separate issue if it's not already in scope here.
• Conformance grader — JS ships adcp grade request-signing <url> as a CLI smoke test for any verifier. adcp-go ships internal conformance_test.go that exercises the spec vectors against in-package code, but no external-target grader. Different shape; may be intentional (Go tests are package-scoped; the JS grader's value is "test someone else's deployment"). Worth confirming this is by design.

Reference adoption

agenticadvertising.org (TypeScript app) shipped the JS-side rollout. Now signs all outbound AdCP requests via GCP KMS Ed25519 + RFC 9421; webhook emission on a separate cryptoKeyVersion. JWKS at https://agenticadvertising.org/.well-known/jwks.json. 33/33 graded vectors pass.

If a Go adopter shows up with the same KMS-backed pattern, the API design should match this surface. Happy to send a draft PR if there's appetite.

[bokelley]

Triage

Classification: Feature request — SDK abstraction (update)
Bucket(s): tmpclient
Status: ready-for-human — awaiting @bokelley's draft PR

What the experts said:

• code-reviewer: all 7 prior blockers confirmed still stand; raises latent interface stability risk — SigningProvider needs a PublicKey(ctx context.Context) (crypto.PublicKey, error) method before the interface is frozen; both the JWKS helper and SPKI tripwire require it, and adding it post-freeze is a breaking change
• dx-expert: design is now unblocked; await @bokelley's draft rather than bot-executing — production KMS rollout experience is better suited to the adapter API shape than a bot implementation; JWKS helper (NewPublicJWKFromProvider) and SPKI tripwire belong in the same issue scope
• security-reviewer: prior blockers Schema-driven type generation from JSON Schema #1–Router: production hardening #3 and TMP client library for publishers #7 confirmed; blocker Publish v0.1.0 as a proper Go module #2 is extended — GCP KMS resource names embed project IDs, SigningError.Detail must never be populated from kmsErr.Error(); JWKS helper is a blocker-if-shipped without full conformance test coverage against the existing negative vectors; cross-process ReplayStore gap is out of scope (pre-existing, separate issue)

My take: Accept the PR offer — the design is unblocked. The one new thing to decide before freezing the interface is whether PublicKey() goes on SigningProvider; resolve that in the PR description (or here first) and the rest follows.

---

Updated design constraints

All seven constraints from the 2026-04-25 comment stand. Updates from the JS production learnings:

• Blocker Publish v0.1.0 as a proper Go module #2 extended: SigningError.Detail must never be populated from kmsErr.Error(). GCP KMS error strings embed resource names of the form projects/<id>/locations/<region>/keyRings/<ring>/cryptoKeyVersions/<n>. Only caller-controlled detail strings are safe.
• New — PublicKey() method decision (resolve before PR): Decide whether SigningProvider includes PublicKey(ctx context.Context) (crypto.PublicKey, error). Both NewPublicJWKFromProvider and AssertProviderPublicKeyMatchesSPKI require it. If omitted now, adding it later is a breaking change to the interface.
• Lazy-init (nit): sync.Once is wrong for KMS adapters — it permanently caches errors. The interface docstring should document the correct pattern: mutex + cached-result + retry on miss (cache success only). Adapter implementations shipped in adcp/signing/awskms/ or adcp/signing/gcpkms/ must follow this; the production incident at adcp#3283 was caused by eager init.
• SPKI tripwire: In scope for the KMS sub-module. AssertProviderPublicKeyMatchesSPKI(ctx, provider, expectedSPKI []byte) error at construction time prevents silent rotation failures. Requires PublicKey() on the interface.
• JWKS helper: In scope if PublicKey() is on the interface. NewPublicJWKFromProvider(ctx, provider, kid, adcpUse string) (JWK, error) must take adcp_use as a required parameter (spec-required key separation per adcp#2423) and must pass the existing negative conformance vectors — at minimum 025-jwk-alg-crv-mismatch and 008-wrong-adcp-use.

Out of scope for this issue (file separately):

• PostgresReplayStore — multi-instance replay protection gap is real but pre-existing and verifier-side; file separately
• Conformance grader CLI parity — may be intentional (package-scoped conformance_test.go vs. external-target CLI); confirm by-design or file separately
• Webhook SigningProvider support (signerProvider on createWebhookEmitter equivalent) — two-line change to PublisherOptions but should be a separate, legible PR

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code