Virtual Key Vault: BYOK with AES-256-GCM Encryption and Zero-Downtime Rotation

2026-02-22

virtual-keysprovider-crud

LOCKSTEP TRACEABILITY MATRIX --- api_endpoints: [ "GET /v1/providers/catalog", "POST /v1/providers/test", "POST /v1/providers", "GET /v1/providers", "DELETE /v1/providers/:providerId", ] sdk_methods_updated: [ "client.providers.list()", "client.providers.create()", "client.providers.test()", "client.providers.delete()", ] mcp_tools_updated: ["none"] ---

What We Built

The Virtual Key Vault is BrainstormRouter's BYOK (Bring Your Own Key) system. Enterprise customers store their provider API keys (OpenAI, Anthropic, Google, etc.) in BrainstormRouter's encrypted vault. Each real key is encrypted with AES-256-GCM and mapped to a virtual key ID (vk_<32-char-hex>). The virtual key is what gets used internally — the real key is never exposed after storage.

The vault enforces per-key rate limits (RPM with a 60-second sliding window), daily budget limits (tracked in BigInt microcents for exact aggregation), and model allowlists. Keys can be rotated with zero downtime — the old key is deactivated and the new key is encrypted in a single atomic operation. An audit log tracks every action (created, used, rotated, revoked, budget_exceeded, rate_limited) with a 10,000-entry circular buffer.

The Provider CRUD API (providers.ts, 359 LOC) is the REST surface for key management. It supports provider discovery (GET /v1/providers/catalog), key validation with lightweight live requests (POST /v1/providers/test), encrypted key storage with automatic rotation (POST /v1/providers), key listing with masking (GET /v1/providers), and deactivation (DELETE /v1/providers/:providerId).

Why It Matters

Enterprise customers cannot share their API keys with a third-party gateway unless they trust the encryption, rotation, and access control. The Virtual Key Vault gives enterprises three things: (1) their keys are encrypted at rest with AES-256-GCM, (2) they can rotate keys without any code changes or downtime, and (3) every key usage is audited with per-key rate and budget enforcement.

This is the foundation of enterprise trust. Without it, BrainstormRouter is just a proxy. With it, BrainstormRouter is a managed service that enterprises can adopt without security review friction.

How It Works

Key Storage Flow:

POST /v1/providers { provider: "openai", key: "sk-..." }
  → resolveProvider("openai")
  → testKey("openai", "sk-...") with 10s timeout
  → vault.create({ tenantId, provider, realKey, label })
  → AES-256-GCM encrypt → store encrypted blob
  → return { id: "vk_a1b2c3...", provider, masked_key: "sk-...xyz1" }

Enforcement Checks (on every resolve):

const realKey = vault.resolve(virtualKeyId, requestedModel);
// 1. Check active status
// 2. Check model allowlist (if configured)
// 3. Check RPM rate limit (60s sliding window)
// 4. Check daily budget (BigInt microcents, keyed by YYYY-MM-DD)
// Throws VaultEnforcementError on violation

Zero-Downtime Rotation:

vault.rotate(virtualKeyId, newRealKey, actor);
// 1. Deactivate old encrypted key
// 2. Encrypt new key with AES-256-GCM
// 3. Store new encrypted blob
// 4. Audit log: { action: "rotated", actor, timestamp }
// Virtual key ID unchanged — no downstream code changes needed

Key Validation (per provider):

OpenAI: GET /v1/models (list models)
Anthropic: OPTIONS /v1/messages (auth check without body)
Google: GET /v1beta/models?key=...
Ollama: GET /api/tags

10-second timeout. 401/403 = auth failed. 429 = key valid (rate limited). 405 = key valid (Anthropic OPTIONS).

The Numbers

AES-256-GCM encryption for all stored provider keys
vk_<32-char-hex> virtual key format
60-second sliding window for RPM rate limiting
BigInt microcents for exact daily budget tracking (no floating-point drift)
10,000-entry circular audit buffer per vault instance
10-second timeout on key validation requests
Zero-downtime rotation — virtual key ID unchanged, old key atomically replaced

Competitive Edge

Portkey stores provider keys but does not offer per-key budget limits, model allowlists, or audited rotation. OpenRouter requires users to manage their own keys. BrainstormRouter's Virtual Key Vault is the only system that combines AES-256-GCM encryption, per-key RPM and budget enforcement, zero-downtime rotation, and a full audit trail — making it the answer to "how do we safely give a third-party gateway our API keys?"

Lockstep Checklist

[x] API Routes: Full CRUD at /v1/providers/* including catalog, test, store, list, and delete.
[x] TS SDK: client.providers.list(), .create(), .test(), .delete() implemented in packages/sdk-ts/src/resources/providers.ts.
[x] Python SDK: Matching implementation in packages/sdk-py/src/brainstormrouter/resources/providers.py.
[ ] MCP Schemas: Not applicable.
[x] Master Record: Listed under "Financial & Key Governance" in master-capability-record.md.