@shipfox/api-secrets 2.0.0

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@shipfox/api-secrets",
+  "license": "MIT",
+  "version": "2.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
+    "directory": "libs/api/secrets"
+  },
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "imports": {
+    "#test/*": "./test/*",
+    "#*": {
+      "workspace-source": "./src/*",
+      "development": "./src/*",
+      "default": "./dist/*"
+    }
+  },
+  "exports": {
+    ".": {
+      "development": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./core/errors": {
+      "development": {
+        "types": "./src/core/errors.ts",
+        "default": "./src/core/errors.ts"
+      },
+      "default": {
+        "types": "./dist/core/errors.d.ts",
+        "default": "./dist/core/errors.js"
+      }
+    }
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.45.2",
+    "zod": "^4.4.3",
+    "@shipfox/api-auth-context": "2.0.0",
+    "@shipfox/config": "1.2.1",
+    "@shipfox/api-projects": "2.0.0",
+    "@shipfox/api-secrets-dto": "2.0.0",
+    "@shipfox/node-drizzle": "0.2.1",
+    "@shipfox/node-fastify": "0.2.1",
+    "@shipfox/node-module": "0.2.0",
+    "@shipfox/node-opentelemetry": "0.5.0",
+    "@shipfox/node-outbox": "0.2.1",
+    "@shipfox/node-postgres": "0.4.1"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.15.5",
+    "drizzle-kit": "^0.31.10",
+    "fastify": "^5.3.3",
+    "@shipfox/biome": "1.8.1",
+    "@shipfox/swc": "1.2.5",
+    "@shipfox/typescript": "1.1.6",
+    "@shipfox/vitest": "1.2.2",
+    "@shipfox/ts-config": "1.3.8"
+  },
+  "scripts": {
+    "build": "shipfox-swc",
+    "check": "shipfox-biome-check",
+    "check:fix": "shipfox-biome-check --write",
+    "test": "shipfox-vitest-run",
+    "test:watch": "shipfox-vitest-watch",
+    "type": "shipfox-tsc-check",
+    "type:emit": "shipfox-tsc-emit"
+  }
+}

package/src/config.test.ts

@@ -0,0 +1,41 @@
+import {vi} from '@shipfox/vitest/vi';
+
+const VALID_KEY = 'MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY=';
+
+describe('secrets config', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  it.each(['not-base64', `${VALID_KEY}\n`])('rejects malformed KEKs: %s', async (value) => {
+    vi.stubEnv('SECRETS_ENCRYPTION_KEK', value);
+    vi.resetModules();
+
+    await expect(import('./config.js')).rejects.toThrow('SECRETS_ENCRYPTION_KEK');
+  });
+
+  it('accepts current and previous KEKs', async () => {
+    vi.stubEnv('SECRETS_ENCRYPTION_KEK', VALID_KEY);
+    vi.stubEnv('SECRETS_ENCRYPTION_KEK_PREVIOUS', 'MTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWY=');
+    vi.resetModules();
+
+    const {config} = await import('./config.js');
+
+    expect(config.SECRETS_ENCRYPTION_KEK).toBe(VALID_KEY);
+    expect(config.SECRETS_ENCRYPTION_KEK_PREVIOUS).toBe(
+      'MTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWY=',
+    );
+  });
+
+  it.each([
+    ['SECRETS_MAX_PER_WORKSPACE', '0'],
+    ['SECRETS_SHORT_VALUE_WARN_LENGTH', '0'],
+  ])('rejects invalid numeric config %s=%s', async (name, value) => {
+    vi.stubEnv('SECRETS_ENCRYPTION_KEK', VALID_KEY);
+    vi.stubEnv(name, value);
+    vi.resetModules();
+
+    await expect(import('./config.js')).rejects.toThrow(name);
+  });
+});

package/src/config.ts

@@ -0,0 +1,41 @@
+import {SECRETS_MAX_LIST_LIMIT} from '@shipfox/api-secrets-dto';
+import {createConfig, num, str} from '@shipfox/config';
+import {decodeBase64Key} from '#core/crypto.js';
+
+export const MAX_VALUE_BYTES = 64 * 1024;
+
+export const config = createConfig({
+  SECRETS_ENCRYPTION_KEK: str({
+    desc: 'Master key used to protect all stored secrets. Required. Generate a unique value per environment with openssl rand -base64 32 and provide it from a secret manager. The committed .env value is only for local development. Losing this key makes stored secrets unrecoverable. To rotate it, set SECRETS_ENCRYPTION_KEK_PREVIOUS to the old value during the rotation window.',
+  }),
+  SECRETS_ENCRYPTION_KEK_PREVIOUS: str({
+    desc: 'Previous master key used only while rotating stored secret data keys. Optional. Set it to the old SECRETS_ENCRYPTION_KEK value until rotation has completed.',
+    default: undefined,
+  }),
+  SECRETS_MAX_PER_WORKSPACE: num({
+    desc: 'Maximum number of secrets and variables allowed per workspace across all project scopes and namespaces.',
+    default: 10000,
+  }),
+  SECRETS_SHORT_VALUE_WARN_LENGTH: num({
+    desc: 'Secret values shorter than this many characters are classified for a write warning by management routes.',
+    default: 12,
+  }),
+});
+
+decodeBase64Key(config.SECRETS_ENCRYPTION_KEK, 'SECRETS_ENCRYPTION_KEK');
+if (config.SECRETS_ENCRYPTION_KEK_PREVIOUS) {
+  decodeBase64Key(config.SECRETS_ENCRYPTION_KEK_PREVIOUS, 'SECRETS_ENCRYPTION_KEK_PREVIOUS');
+}
+if (config.SECRETS_MAX_PER_WORKSPACE < 1) {
+  throw new Error('SECRETS_MAX_PER_WORKSPACE must be greater than 0.');
+}
+if (config.SECRETS_MAX_PER_WORKSPACE > SECRETS_MAX_LIST_LIMIT) {
+  // The settings UI lists the whole bounded set in one call (limit = SECRETS_MAX_LIST_LIMIT).
+  // A cap above that would let the list silently truncate, so fail fast instead.
+  throw new Error(
+    `SECRETS_MAX_PER_WORKSPACE (${config.SECRETS_MAX_PER_WORKSPACE}) cannot exceed SECRETS_MAX_LIST_LIMIT (${SECRETS_MAX_LIST_LIMIT}).`,
+  );
+}
+if (config.SECRETS_SHORT_VALUE_WARN_LENGTH < 1) {
+  throw new Error('SECRETS_SHORT_VALUE_WARN_LENGTH must be greater than 0.');
+}

package/src/core/crypto.test.ts

@@ -0,0 +1,115 @@
+import crypto from 'node:crypto';
+import {describe, expect, it} from '@shipfox/vitest/vi';
+import {aadForValue, aesGcmOpen, aesGcmSeal, decodeBase64Key} from './crypto.js';
+import {SecretDecryptionError} from './errors.js';
+
+const V1_PREFIX_PATTERN = /^v1:/;
+const STRIP_WHITESPACE_PATTERN = /Strip whitespace/;
+const BASE64_PADDING_SUFFIX = /=+$/;
+
+describe('AES-GCM secret crypto', () => {
+  it('round-trips with non-deterministic ciphertext', () => {
+    const key = crypto.randomBytes(32);
+    const aad = aadForValue({
+      workspaceId: crypto.randomUUID(),
+      scope: {projectId: null},
+      namespace: '',
+      key: 'API_KEY',
+    });
+
+    const first = aesGcmSeal({key, plaintext: Buffer.from('secret'), aad});
+    const second = aesGcmSeal({key, plaintext: Buffer.from('secret'), aad});
+    const opened = aesGcmOpen({key, encoded: first, aad});
+
+    expect(first).toMatch(V1_PREFIX_PATTERN);
+    expect(first).not.toContain('secret');
+    expect(first).not.toBe(second);
+    expect(opened.toString('utf8')).toBe('secret');
+  });
+
+  it('rejects tampered ciphertext and wrong AAD', () => {
+    const key = crypto.randomBytes(32);
+    const aad = aadForValue({
+      workspaceId: crypto.randomUUID(),
+      scope: {projectId: '2df9f89a-98a0-4a4a-8d7d-8f356207b449'},
+      namespace: 'system/agent/model-provider/openai',
+      key: 'API_KEY',
+    });
+    const encoded = aesGcmSeal({key, plaintext: Buffer.from('secret'), aad});
+
+    expect(() => aesGcmOpen({key, encoded: `${encoded.slice(0, -1)}A`, aad})).toThrow(
+      SecretDecryptionError,
+    );
+    expect(() =>
+      aesGcmOpen({
+        key,
+        encoded,
+        aad: aadForValue({
+          workspaceId: crypto.randomUUID(),
+          scope: {projectId: '2df9f89a-98a0-4a4a-8d7d-8f356207b449'},
+          namespace: 'system/agent/model-provider/openai',
+          key: 'API_KEY',
+        }),
+      }),
+    ).toThrow(SecretDecryptionError);
+  });
+
+  it('binds ciphertext to namespace and key', () => {
+    const key = crypto.randomBytes(32);
+    const workspaceId = crypto.randomUUID();
+    const scope = {projectId: crypto.randomUUID()};
+    const aad = aadForValue({
+      workspaceId,
+      scope,
+      namespace: 'system/agent/model-provider/openai',
+      key: 'API_KEY',
+    });
+    const encoded = aesGcmSeal({key, plaintext: Buffer.from('secret'), aad});
+
+    expect(() =>
+      aesGcmOpen({
+        key,
+        encoded,
+        aad: aadForValue({
+          workspaceId,
+          scope,
+          namespace: 'system/agent/model-provider/anthropic',
+          key: 'API_KEY',
+        }),
+      }),
+    ).toThrow(SecretDecryptionError);
+    expect(() =>
+      aesGcmOpen({
+        key,
+        encoded,
+        aad: aadForValue({
+          workspaceId,
+          scope,
+          namespace: 'system/agent/model-provider/openai',
+          key: 'OTHER_KEY',
+        }),
+      }),
+    ).toThrow(SecretDecryptionError);
+  });
+
+  it('rejects too-short and non-canonical encodings', () => {
+    const key = crypto.randomBytes(32);
+
+    expect(() => aesGcmOpen({key, encoded: 'v1:AA==', aad: 'aad'})).toThrow(SecretDecryptionError);
+    expect(() => aesGcmOpen({key, encoded: 'v1:AA==\n', aad: 'aad'})).toThrow(
+      SecretDecryptionError,
+    );
+  });
+
+  it('strictly validates base64 keys', () => {
+    const encoded = Buffer.alloc(32, 1).toString('base64');
+    const key = decodeBase64Key(encoded, 'TEST_KEY');
+
+    expect(key).toHaveLength(32);
+    expect(() => decodeBase64Key(encoded.replace(BASE64_PADDING_SUFFIX, ''), 'TEST_KEY')).toThrow(
+      STRIP_WHITESPACE_PATTERN,
+    );
+    expect(() => decodeBase64Key(`${encoded}=`, 'TEST_KEY')).toThrow(STRIP_WHITESPACE_PATTERN);
+    expect(() => decodeBase64Key(`${encoded}\n`, 'TEST_KEY')).toThrow(STRIP_WHITESPACE_PATTERN);
+  });
+});

package/src/core/crypto.ts

@@ -0,0 +1,105 @@
+import crypto from 'node:crypto';
+import {KekConfigurationError, SecretDecryptionError} from './errors.js';
+
+const CIPHER = 'aes-256-gcm';
+const ENCODED_PREFIX = 'v1:';
+const IV_BYTES = 12;
+const AUTH_TAG_BYTES = 16;
+const KEY_BYTES = 32;
+const BASE64_KEY_PATTERN = /^[A-Za-z0-9+/]+={0,2}$/;
+const BASE64_PADDING_SUFFIX = /=+$/;
+
+export interface AesGcmSealParams {
+  key: Buffer;
+  plaintext: Buffer;
+  aad: string;
+}
+
+export interface AesGcmOpenParams {
+  key: Buffer;
+  encoded: string;
+  aad: string;
+}
+
+export interface SecretScope {
+  projectId?: string | null | undefined;
+}
+
+export interface SecretValueAadParams {
+  workspaceId: string;
+  scope?: SecretScope | undefined;
+  namespace: string;
+  key: string;
+}
+
+export function aesGcmSeal(params: AesGcmSealParams): string {
+  const iv = crypto.randomBytes(IV_BYTES);
+  const cipher = crypto.createCipheriv(CIPHER, params.key, iv);
+  cipher.setAAD(Buffer.from(params.aad, 'utf8'));
+
+  const ciphertext = Buffer.concat([cipher.update(params.plaintext), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+
+  return `${ENCODED_PREFIX}${Buffer.concat([iv, authTag, ciphertext]).toString('base64')}`;
+}
+
+export function aesGcmOpen(params: AesGcmOpenParams): Buffer {
+  if (!params.encoded.startsWith(ENCODED_PREFIX)) throw new SecretDecryptionError();
+
+  const encodedPayload = params.encoded.slice(ENCODED_PREFIX.length);
+  const payload = Buffer.from(encodedPayload, 'base64');
+  const canonical = payload.toString('base64');
+  if (
+    !BASE64_KEY_PATTERN.test(encodedPayload) ||
+    canonical.replace(BASE64_PADDING_SUFFIX, '') !==
+      encodedPayload.replace(BASE64_PADDING_SUFFIX, '')
+  ) {
+    throw new SecretDecryptionError();
+  }
+  if (payload.length < IV_BYTES + AUTH_TAG_BYTES) throw new SecretDecryptionError();
+
+  try {
+    const iv = payload.subarray(0, IV_BYTES);
+    const authTag = payload.subarray(IV_BYTES, IV_BYTES + AUTH_TAG_BYTES);
+    const ciphertext = payload.subarray(IV_BYTES + AUTH_TAG_BYTES);
+    const decipher = crypto.createDecipheriv(CIPHER, params.key, iv);
+    decipher.setAAD(Buffer.from(params.aad, 'utf8'));
+    decipher.setAuthTag(authTag);
+
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  } catch (error) {
+    if (error instanceof SecretDecryptionError) throw error;
+    throw new SecretDecryptionError();
+  }
+}
+
+export function decodeBase64Key(encoded: string | undefined, label: string): Buffer {
+  if (!encoded) {
+    throw new KekConfigurationError(
+      `${label} is required and must be a base64-encoded 32-byte key. Generate one with openssl rand -base64 32.`,
+    );
+  }
+
+  const key = Buffer.from(encoded, 'base64');
+  if (key.length !== KEY_BYTES || !isCanonicalBase64Key(encoded, key)) {
+    throw new KekConfigurationError(
+      `${label} must be a canonical base64-encoded 32-byte key. Strip whitespace and generate a new value with openssl rand -base64 32 if needed.`,
+    );
+  }
+
+  return key;
+}
+
+export function aadForDek(workspaceId: string, kekVersion: string): string {
+  return JSON.stringify([workspaceId, kekVersion]);
+}
+
+export function aadForValue(params: SecretValueAadParams): string {
+  const projectId = params.scope?.projectId ?? null;
+  const scopeTuple = projectId !== null ? ['project', projectId] : ['workspace'];
+  return JSON.stringify([params.workspaceId, scopeTuple, params.namespace, params.key]);
+}
+
+function isCanonicalBase64Key(encoded: string, key: Buffer): boolean {
+  return BASE64_KEY_PATTERN.test(encoded) && key.toString('base64') === encoded;
+}

package/src/core/dek-manager.test.ts

@@ -0,0 +1,120 @@
+import crypto from 'node:crypto';
+import {describe, expect, it} from '@shipfox/vitest/vi';
+import {eq} from 'drizzle-orm';
+import {db, insertDataKeyIfAbsent, secretDataKeys} from '#db/index.js';
+import {DekManager} from './dek-manager.js';
+import {createLocalKeyProvider} from './key-provider.js';
+
+describe('DekManager', () => {
+  it('persists one data key across concurrent first use', async () => {
+    const workspaceId = crypto.randomUUID();
+    const manager = new DekManager(createLocalKeyProvider({currentKek: crypto.randomBytes(32)}), {
+      maxEntries: 10,
+      ttlMs: 60_000,
+    });
+
+    const [first, second] = await Promise.all([
+      manager.getPlaintextDek(workspaceId),
+      manager.getPlaintextDek(workspaceId),
+    ]);
+    const rows = await db()
+      .select()
+      .from(secretDataKeys)
+      .where(eq(secretDataKeys.workspaceId, workspaceId));
+
+    expect(rows).toHaveLength(1);
+    expect(first.equals(second)).toBe(true);
+  });
+
+  it('reports whether a first-use data key insert won the race', async () => {
+    const workspaceId = crypto.randomUUID();
+    const keyProvider = createLocalKeyProvider({currentKek: crypto.randomBytes(32)});
+    const first = keyProvider.wrapDek(workspaceId, crypto.randomBytes(32));
+    const second = keyProvider.wrapDek(workspaceId, crypto.randomBytes(32));
+
+    const inserted = await insertDataKeyIfAbsent({
+      workspaceId,
+      wrappedDek: first.wrappedDek,
+      kekVersion: first.kekVersion,
+    });
+    const skipped = await insertDataKeyIfAbsent({
+      workspaceId,
+      wrappedDek: second.wrappedDek,
+      kekVersion: second.kekVersion,
+    });
+
+    expect(inserted).toBe(true);
+    expect(skipped).toBe(false);
+  });
+
+  it('re-reads persisted data keys on cold start', async () => {
+    const workspaceId = crypto.randomUUID();
+    const keyProvider = createLocalKeyProvider({currentKek: crypto.randomBytes(32)});
+    const firstManager = new DekManager(keyProvider, {maxEntries: 10, ttlMs: 60_000});
+    const secondManager = new DekManager(keyProvider, {maxEntries: 10, ttlMs: 60_000});
+
+    const first = await firstManager.getPlaintextDek(workspaceId);
+    const second = await secondManager.getPlaintextDek(workspaceId);
+
+    expect(second.equals(first)).toBe(true);
+  });
+
+  it('serves cache hits without reading the persisted data key', async () => {
+    const workspaceId = crypto.randomUUID();
+    const manager = new DekManager(createLocalKeyProvider({currentKek: crypto.randomBytes(32)}), {
+      maxEntries: 10,
+      ttlMs: 60_000,
+    });
+
+    const first = await manager.getPlaintextDek(workspaceId);
+    await db().delete(secretDataKeys).where(eq(secretDataKeys.workspaceId, workspaceId));
+    const second = await manager.getPlaintextDek(workspaceId);
+
+    expect(second.equals(first)).toBe(true);
+  });
+
+  it('returns defensive copies of cached data keys', async () => {
+    const workspaceId = crypto.randomUUID();
+    const manager = new DekManager(createLocalKeyProvider({currentKek: crypto.randomBytes(32)}), {
+      maxEntries: 10,
+      ttlMs: 60_000,
+    });
+
+    const first = await manager.getPlaintextDek(workspaceId);
+    const expected = Buffer.from(first);
+    first.fill(0);
+    const second = await manager.getPlaintextDek(workspaceId);
+
+    expect(second.equals(expected)).toBe(true);
+  });
+
+  it('refreshes expired cache entries from storage', async () => {
+    const workspaceId = crypto.randomUUID();
+    const manager = new DekManager(createLocalKeyProvider({currentKek: crypto.randomBytes(32)}), {
+      maxEntries: 10,
+      ttlMs: -1,
+    });
+
+    const first = await manager.getPlaintextDek(workspaceId);
+    await db().delete(secretDataKeys).where(eq(secretDataKeys.workspaceId, workspaceId));
+    const second = await manager.getPlaintextDek(workspaceId);
+
+    expect(second.equals(first)).toBe(false);
+  });
+
+  it('evicts the least recently used cache entry when full', async () => {
+    const evictedWorkspaceId = crypto.randomUUID();
+    const otherWorkspaceId = crypto.randomUUID();
+    const manager = new DekManager(createLocalKeyProvider({currentKek: crypto.randomBytes(32)}), {
+      maxEntries: 1,
+      ttlMs: 60_000,
+    });
+
+    const first = await manager.getPlaintextDek(evictedWorkspaceId);
+    await manager.getPlaintextDek(otherWorkspaceId);
+    await db().delete(secretDataKeys).where(eq(secretDataKeys.workspaceId, evictedWorkspaceId));
+    const second = await manager.getPlaintextDek(evictedWorkspaceId);
+
+    expect(second.equals(first)).toBe(false);
+  });
+});

package/src/core/dek-manager.ts

@@ -0,0 +1,98 @@
+import crypto from 'node:crypto';
+import {getDataKey, insertDataKeyIfAbsent} from '#db/index.js';
+import {classifyDekAccessError, recordSecretsDekAccess} from '#metrics/instance.js';
+import type {KeyProvider} from './key-provider.js';
+
+const DEK_BYTES = 32;
+
+/**
+ * Plaintext DEKs live in memory by design so hot secret reads avoid unwrapping on
+ * every access. Node cannot reliably zeroize Buffers, so residency is bounded by
+ * LRU size and lazy TTL instead of pretending wipes are a complete mitigation.
+ */
+export class DekManager {
+  readonly #cache = new Map<string, {dek: Buffer; expiresAt: number}>();
+  readonly #keyProvider: KeyProvider;
+  readonly #options: {maxEntries: number; ttlMs: number};
+
+  constructor(keyProvider: KeyProvider, options: {maxEntries: number; ttlMs: number}) {
+    this.#keyProvider = keyProvider;
+    this.#options = options;
+  }
+
+  async getPlaintextDek(workspaceId: string): Promise<Buffer> {
+    const startedAt = Date.now();
+    try {
+      const cached = this.#cache.get(workspaceId);
+      if (cached && cached.expiresAt > Date.now()) {
+        this.#cache.delete(workspaceId);
+        this.#cache.set(workspaceId, cached);
+        recordSecretsDekAccess({outcome: 'cache_hit', durationMs: Date.now() - startedAt});
+        return Buffer.from(cached.dek);
+      }
+      const hadExpiredCache = Boolean(cached);
+      if (cached) this.#cache.delete(workspaceId);
+
+      const existing = await getDataKey(workspaceId);
+      if (existing) {
+        const dek = this.#keyProvider.unwrapDek(
+          workspaceId,
+          existing.wrappedDek,
+          existing.kekVersion,
+        );
+        this.#set(workspaceId, dek);
+        recordSecretsDekAccess({
+          outcome: hadExpiredCache ? 'cache_expired' : 'db_unwrapped',
+          durationMs: Date.now() - startedAt,
+        });
+        return Buffer.from(dek);
+      }
+
+      const generatedDek = crypto.randomBytes(DEK_BYTES);
+      const wrapped = this.#keyProvider.wrapDek(workspaceId, generatedDek);
+      const inserted = await insertDataKeyIfAbsent({
+        workspaceId,
+        wrappedDek: wrapped.wrappedDek,
+        kekVersion: wrapped.kekVersion,
+      });
+
+      // The DEK row commits before value writes. If concurrent first-use inserts race,
+      // the primary key decides the winner and every caller re-reads the persisted row.
+      const persisted = await getDataKey(workspaceId);
+      if (!persisted) throw new Error(`Data key was not persisted for workspace ${workspaceId}`);
+      const dek = this.#keyProvider.unwrapDek(
+        workspaceId,
+        persisted.wrappedDek,
+        persisted.kekVersion,
+      );
+      this.#set(workspaceId, dek);
+      recordSecretsDekAccess({
+        outcome: inserted ? 'generated' : 'db_unwrapped',
+        durationMs: Date.now() - startedAt,
+      });
+      return Buffer.from(dek);
+    } catch (error) {
+      recordSecretsDekAccess({
+        outcome: classifyDekAccessError(error),
+        durationMs: Date.now() - startedAt,
+      });
+      throw error;
+    }
+  }
+
+  invalidate(workspaceId: string): void {
+    this.#cache.delete(workspaceId);
+  }
+
+  #set(workspaceId: string, dek: Buffer): void {
+    this.#cache.set(workspaceId, {
+      dek: Buffer.from(dek),
+      expiresAt: Date.now() + this.#options.ttlMs,
+    });
+    while (this.#cache.size > this.#options.maxEntries) {
+      const oldest = this.#cache.keys().next().value as string | undefined;
+      if (!oldest) break;
+      this.#cache.delete(oldest);
+    }
+  }
+}