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.

Proposal

Add a SigningProvider Protocol with an async sign() operation. The in-memory path stays the default for testing. External providers (KMS / HSM / Vault) plug in by implementing the Protocol.

from typing import Protocol, Literal

class SigningProvider(Protocol):
    async def sign(self, payload: bytes) -> bytes: ...
    def key_id(self) -> str: ...
    def algorithm(self) -> Literal["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 boto3 is the obvious starter)

Notes

• Interface must be async from the start — KMS sign latency is typically 10–50ms and isn't free in retry/backoff math.
• 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
Bucket(s): signing
Status: ready-for-human

What the experts said:

• security-reviewer: Algorithm/key binding has no construction-time check; key_id() embeds unsanitized into Structured Field serialization (injection risk); async sign() opens SSRF/timing surfaces for network-calling providers — human sign-off required before merge.
• ad-tech-protocol-expert: Sound intent but three concrete defects: sign() docstring must clarify raw-base vs. pre-hashed input (ECDSA double-hash risk on KMS paths), Literal uses wrong casing ("ECDSA-P256" / "Ed25519" ≠ "ecdsa-p256-sha256" / "ed25519" used throughout ALLOWED_ALGS), and RSA-PSS is not in the AdCP signing profile.
• code-reviewer: Three blockers — algorithm literal mismatch with ALLOWED_ALGS, unresolved sync/async split (sign_request() is sync; SigningProvider.sign() is async — design decision needed), and test_public_api_surface_matches_snapshot will need regeneration. KMS example should be deferred to docs rather than shipped as importable code with a new boto3 dep.

My take: The direction is right — closing the KMS gap before 3.1 is the correct window — but there are design-level decisions that need to be locked before a PR is opened: algorithm literal casing fix, sync→async strategy for sign_request(), RSA-PSS scoped out, and key_id() sanitized before embedding in Structured Field output. Flagging to @bokelley to resolve these design questions first.

---

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

---

Generated by Claude Code