Skip to main content

ADR-015: BYOK Cryptography and Key Rotation

  • Status: Accepted
  • Date: 2026-02-04

Context​

BYOK credentials (OpenAI API keys and Ollama endpoints/keys) must be encrypted at rest ADR-007. We also need operationally safe key rotation.

Constraints:

  • Store encrypted payload + metadata in D1 (tn-sessions).
  • KEK is stored as a Cloudflare Secret.
  • Never log secrets; never return plaintext keys to clients.
  • CLI daemon must authenticate via OAuth device flow to access user's BYOK credentials.

Decision​

Envelope encryption model​

  • Generate a per-credential DEK (random bytes).
  • Encrypt the credential payload with the DEK.
  • Wrap (encrypt) the DEK with the KEK.
  • Store:
    • encrypted payload
    • wrapped DEK
    • algorithm metadata
    • KEK version id

KEK versioning and rotation​

  • KEKs are versioned (e.g., BYOK_KEK_V1, BYOK_KEK_V2).
  • Each stored credential records kek_version.
  • Rotation strategy:
    • New writes use the latest KEK.
    • Existing credentials are re-wrapped lazily on successful use and/or via a background job.

Credential payload shape​

  • Store payload as a small JSON object, then encrypt.
  • Payload contains provider-specific fields, e.g.:
    • OpenAI: { "apiKey": "..." }
    • Ollama: { "baseUrl": "http://...", "apiKey": "..." }

CLI authentication for BYOK​

  • CLI daemon authenticates via OAuth device flow ADR-013.
  • Authenticated CLI can access user's BYOK credentials.
  • CLI never receives plaintext keys; it receives encrypted blobs.
  • CLI must call API to use credentials (API decrypts on-the-fly).

Consequences​

  • Crypto implementation must be correct and testable in Workers.
  • We need migration utilities for re-wrapping DEKs.
  • Access control must ensure only the owning user can use the credential.
  • CLI must proxy all BYOK usage through API (cannot decrypt locally).

Alternatives considered​

  • Plaintext storage in D1: unacceptable.
  • One global DEK: weakens compartmentalization.

Implementation notes​

  • Recommended algorithms: AES-256-GCM for payload, RSA-OAEP for DEK wrapping.
  • Store a non-reversible fingerprint (hash) for duplicate detection.
  • BYOK keys are per-user (not per-session) for simplicity.