@shipfox/api-secrets 14.0.0 → 17.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-secrets",
   "license": "MIT",
-  "version": "14.0.0",
+  "version": "17.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -24,17 +24,18 @@
   "dependencies": {
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
-    "@shipfox/api-auth-context": "12.2.0",
-    "@shipfox/api-projects-dto": "14.0.0",
+    "@shipfox/api-auth-context": "17.0.0",
+    "@shipfox/api-projects-dto": "15.0.0",
     "@shipfox/api-secrets-dto": "12.0.0",
     "@shipfox/config": "1.2.4",
     "@shipfox/inter-module": "0.2.3",
     "@shipfox/node-drizzle": "0.3.5",
-    "@shipfox/node-fastify": "0.4.2",
-    "@shipfox/node-module": "1.0.6",
-    "@shipfox/node-opentelemetry": "0.6.4",
+    "@shipfox/node-envelope-encryption": "0.2.0",
+    "@shipfox/node-fastify": "0.4.3",
+    "@shipfox/node-module": "1.0.7",
+    "@shipfox/node-opentelemetry": "0.6.5",
     "@shipfox/node-outbox": "0.2.6",
-    "@shipfox/node-postgres": "0.5.0"
+    "@shipfox/node-postgres": "0.5.1"
   },
   "imports": {
     "#*": "./dist/*"

package/src/config.ts

@@ -6,7 +6,7 @@ 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.',
+    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. Do not reuse AGENT_SESSION_ENCRYPTION_KEK. 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.',

package/src/core/crypto.ts

@@ -1,14 +1,11 @@
-import crypto from 'node:crypto';
+import {
+  decodeBase64Key as decodeEnvelopeKey,
+  KeyConfigurationError,
+  openEnvelopeText,
+  sealEnvelopeText,
+} from '@shipfox/node-envelope-encryption';
 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;
@@ -33,61 +30,24 @@ export interface SecretValueAadParams {
 }
 
 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')}`;
+  return sealEnvelopeText(params);
 }
 
 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;
+    return openEnvelopeText(params);
+  } catch {
     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.`,
-    );
+  try {
+    return decodeEnvelopeKey(encoded, label);
+  } catch (error) {
+    if (error instanceof KeyConfigurationError) throw new KekConfigurationError(error.message);
+    throw error;
   }
-
-  return key;
 }
 
 export function aadForDek(workspaceId: string, kekVersion: string): string {
@@ -99,7 +59,3 @@ export function aadForValue(params: SecretValueAadParams): string {
   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.ts

@@ -1,76 +1,37 @@
-import crypto from 'node:crypto';
+import {DataKeyManager} from '@shipfox/node-envelope-encryption';
 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};
+  readonly #manager: DataKeyManager;
 
   constructor(keyProvider: KeyProvider, options: {maxEntries: number; ttlMs: number}) {
-    this.#keyProvider = keyProvider;
-    this.#options = options;
+    this.#manager = new DataKeyManager(
+      keyProvider,
+      {
+        async get(workspaceId) {
+          const record = await getDataKey(workspaceId);
+          return record ? {keyId: workspaceId, ...record} : undefined;
+        },
+        insertIfAbsent(record) {
+          return insertDataKeyIfAbsent({
+            workspaceId: record.keyId,
+            wrappedDek: record.wrappedDek,
+            kekVersion: record.kekVersion,
+          });
+        },
+      },
+      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);
+      const result = await this.#manager.getPlaintextDataKey(workspaceId);
+      recordSecretsDekAccess({outcome: result.outcome, durationMs: Date.now() - startedAt});
+      return result.dek;
     } catch (error) {
       recordSecretsDekAccess({
         outcome: classifyDekAccessError(error),
@@ -81,18 +42,6 @@ export class DekManager {
   }
 
   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);
-    }
+    this.#manager.invalidate(workspaceId);
   }
 }

package/src/core/key-provider.ts

@@ -1,5 +1,9 @@
-import crypto from 'node:crypto';
-import {aadForDek, aesGcmOpen, aesGcmSeal} from './crypto.js';
+import {
+  createLocalKeyProvider as createEnvelopeKeyProvider,
+  DataKeyUnwrapError,
+  DataKeyWrapError,
+  deriveLocalKeyVersion,
+} from '@shipfox/node-envelope-encryption';
 import {DekUnwrapError, DekWrapError} from './errors.js';
 
 const KEK_VERSION_DOMAIN = 'shipfox-secrets-kek-version';
@@ -22,49 +26,29 @@ export interface LocalKeyProviderParams {
 }
 
 export function createLocalKeyProvider(params: LocalKeyProviderParams): KeyProvider {
-  const currentKeyVersion = deriveLocalKekVersion(params.currentKek);
-  const previousKeyVersion = params.previousKek ? deriveLocalKekVersion(params.previousKek) : null;
-
+  const provider = createEnvelopeKeyProvider({...params, keyVersionDomain: KEK_VERSION_DOMAIN});
   return {
-    currentKeyVersion,
-    previousKeyVersion,
+    currentKeyVersion: provider.currentKeyVersion,
+    previousKeyVersion: provider.previousKeyVersion,
     wrapDek(workspaceId, plaintextDek) {
       try {
-        return {
-          wrappedDek: aesGcmSeal({
-            key: params.currentKek,
-            plaintext: plaintextDek,
-            aad: aadForDek(workspaceId, currentKeyVersion),
-          }),
-          kekVersion: currentKeyVersion,
-        };
-      } catch {
-        throw new DekWrapError();
+        return provider.wrapDek(workspaceId, plaintextDek);
+      } catch (error) {
+        if (error instanceof DataKeyWrapError) throw new DekWrapError();
+        throw error;
       }
     },
     unwrapDek(workspaceId, wrappedDek, kekVersion) {
-      const key =
-        kekVersion === currentKeyVersion
-          ? params.currentKek
-          : kekVersion === previousKeyVersion
-            ? params.previousKek
-            : undefined;
-      if (!key) throw new DekUnwrapError();
-
       try {
-        return aesGcmOpen({
-          key,
-          encoded: wrappedDek,
-          aad: aadForDek(workspaceId, kekVersion),
-        });
-      } catch {
-        throw new DekUnwrapError();
+        return provider.unwrapDek(workspaceId, wrappedDek, kekVersion);
+      } catch (error) {
+        if (error instanceof DataKeyUnwrapError) throw new DekUnwrapError();
+        throw error;
       }
     },
   };
 }
 
 export function deriveLocalKekVersion(kek: Buffer): string {
-  const hash = crypto.createHash('sha256').update(KEK_VERSION_DOMAIN).update(kek).digest('hex');
-  return `local:${hash.slice(0, 16)}`;
+  return deriveLocalKeyVersion(kek, KEK_VERSION_DOMAIN);
 }

package/src/core/rotate-kek.ts

@@ -1,10 +1,9 @@
+import {rotateDataKeysWithTelemetry} from '@shipfox/node-envelope-encryption';
 import {listDataKeysPage, listDataKeyVersions, updateDataKeyWrapCas} from '#db/index.js';
 import {classifyKekRotationError, recordSecretsKekRotation} from '#metrics/instance.js';
 import {KekVersionStrandedError} from './errors.js';
 import type {KeyProvider} from './key-provider.js';
 
-const PAGE_SIZE = 100;
-
 export interface RotateWorkspaceDataKeysResult {
   rotated: number;
   skipped: number;
@@ -14,87 +13,35 @@ export interface RotateWorkspaceDataKeysOptions {
   workspaceIds?: string[] | undefined;
 }
 
-export async function rotateWorkspaceDataKeysWithProvider(
+export function rotateWorkspaceDataKeysWithProvider(
   keyProvider: KeyProvider,
   options: RotateWorkspaceDataKeysOptions = {},
 ): Promise<RotateWorkspaceDataKeysResult> {
-  const startedAt = Date.now();
-  try {
-    const knownVersions = [keyProvider.currentKeyVersion, keyProvider.previousKeyVersion].filter(
-      (version): version is string => Boolean(version),
-    );
-    const unknownVersions = await listDataKeyVersions(knownVersions, {
-      workspaceIds: options.workspaceIds,
-    });
-    if (unknownVersions.length > 0) throw new KekVersionStrandedError(unknownVersions[0] as string);
-
-    let rotated = 0;
-    let skipped = 0;
-    let skippedCurrent = 0;
-    let skippedRace = 0;
-    let afterWorkspaceId: string | undefined;
-
-    while (true) {
-      const page = await listDataKeysPage({
-        afterWorkspaceId,
-        limit: PAGE_SIZE,
-        workspaceIds: options.workspaceIds,
-      });
-      if (page.length === 0) break;
-
-      for (const row of page) {
-        afterWorkspaceId = row.workspaceId;
-        if (row.kekVersion === keyProvider.currentKeyVersion) {
-          skipped += 1;
-          skippedCurrent += 1;
-          continue;
-        }
-
-        const plaintextDek = keyProvider.unwrapDek(row.workspaceId, row.wrappedDek, row.kekVersion);
-        try {
-          const wrapped = keyProvider.wrapDek(row.workspaceId, plaintextDek);
-          const updated = await updateDataKeyWrapCas({
-            workspaceId: row.workspaceId,
-            oldKekVersion: row.kekVersion,
-            wrappedDek: wrapped.wrappedDek,
-            kekVersion: wrapped.kekVersion,
-          });
-          if (updated) rotated += 1;
-          else {
-            skipped += 1;
-            skippedRace += 1;
-          }
-        } finally {
-          plaintextDek.fill(0);
-        }
-      }
-    }
-
-    recordSecretsKekRotation({outcome: 'rotated', count: rotated});
-    recordSecretsKekRotation({outcome: 'skipped_current', count: skippedCurrent});
-    recordSecretsKekRotation({outcome: 'skipped_race', count: skippedRace});
-    recordSecretsKekRotation({
-      outcome: rotationDurationOutcome({rotated, skippedCurrent, skippedRace}),
-      count: 0,
-      durationMs: Date.now() - startedAt,
-    });
-    return {rotated, skipped};
-  } catch (error) {
-    recordSecretsKekRotation({
-      outcome: classifyKekRotationError(error),
-      durationMs: Date.now() - startedAt,
-    });
-    throw error;
-  }
-}
-
-function rotationDurationOutcome(params: {
-  rotated: number;
-  skippedCurrent: number;
-  skippedRace: number;
-}) {
-  if (params.rotated > 0) return 'rotated';
-  if (params.skippedRace > 0) return 'skipped_race';
-  if (params.skippedCurrent === 0) return 'none';
-  return 'skipped_current';
+  return rotateDataKeysWithTelemetry({
+    keyProvider,
+    repository: {
+      listUnknownKeyVersions(knownVersions) {
+        return listDataKeyVersions(knownVersions, {workspaceIds: options.workspaceIds});
+      },
+      async listPage(params) {
+        const rows = await listDataKeysPage({
+          afterWorkspaceId: params.afterKeyId,
+          limit: params.limit,
+          workspaceIds: options.workspaceIds,
+        });
+        return rows.map((row) => ({keyId: row.workspaceId, ...row}));
+      },
+      updateWrapCas(params) {
+        return updateDataKeyWrapCas({
+          workspaceId: params.keyId,
+          oldKekVersion: params.oldKekVersion,
+          wrappedDek: params.wrappedDek,
+          kekVersion: params.kekVersion,
+        });
+      },
+    },
+    record: recordSecretsKekRotation,
+    classifyError: classifyKekRotationError,
+    strandedError: (keyVersion) => new KekVersionStrandedError(keyVersion),
+  });
 }