@shipfox/api-secrets 2.0.0

package/src/core/errors.ts

@@ -0,0 +1,100 @@
+export class SecretDecryptionError extends Error {
+  constructor() {
+    super('Secret value could not be decrypted.');
+    this.name = 'SecretDecryptionError';
+  }
+}
+
+export class DekWrapError extends Error {
+  constructor() {
+    super('Data encryption key could not be wrapped.');
+    this.name = 'DekWrapError';
+  }
+}
+
+export class DekUnwrapError extends Error {
+  constructor() {
+    super('Data encryption key could not be unwrapped.');
+    this.name = 'DekUnwrapError';
+  }
+}
+
+export class KekConfigurationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'KekConfigurationError';
+  }
+}
+
+export class SecretKeyValidationError extends Error {
+  constructor(public readonly key: string) {
+    super(`Invalid secret key: ${key}`);
+    this.name = 'SecretKeyValidationError';
+  }
+}
+
+export class NamespaceValidationError extends Error {
+  constructor(public readonly namespace: string) {
+    super(`Invalid secret namespace: ${namespace}`);
+    this.name = 'NamespaceValidationError';
+  }
+}
+
+export class WorkspaceSecretCapExceededError extends Error {
+  constructor(
+    public readonly workspaceId: string,
+    public readonly cap: number,
+  ) {
+    super(`Workspace ${workspaceId} exceeds the secret and variable cap of ${cap}.`);
+    this.name = 'WorkspaceSecretCapExceededError';
+  }
+}
+
+export class SecretValueTooLargeError extends Error {
+  constructor(public readonly maxBytes: number) {
+    super(`Secret and variable values must not exceed ${maxBytes} bytes.`);
+    this.name = 'SecretValueTooLargeError';
+  }
+}
+
+export class SecretBatchScopeMismatchError extends Error {
+  constructor() {
+    super('Secret and variable batches must target a single project scope.');
+    this.name = 'SecretBatchScopeMismatchError';
+  }
+}
+
+export class SecretBatchDuplicateKeyError extends Error {
+  constructor(public readonly key: string) {
+    super(`Duplicate secret or variable key in batch: ${key}`);
+    this.name = 'SecretBatchDuplicateKeyError';
+  }
+}
+
+export class SecretNotFoundError extends Error {
+  constructor(public readonly key: string) {
+    super(`Secret not found: ${key}`);
+    this.name = 'SecretNotFoundError';
+  }
+}
+
+export class VariableNotFoundError extends Error {
+  constructor(public readonly key: string) {
+    super(`Variable not found: ${key}`);
+    this.name = 'VariableNotFoundError';
+  }
+}
+
+export class UnknownSecretStoreError extends Error {
+  constructor(public readonly store: string) {
+    super(`Unknown secret store: ${store.slice(0, 64)}`);
+    this.name = 'UnknownSecretStoreError';
+  }
+}
+
+export class KekVersionStrandedError extends Error {
+  constructor(public readonly kekVersion: string) {
+    super(`Data key is stranded on unknown KEK version: ${kekVersion}`);
+    this.name = 'KekVersionStrandedError';
+  }
+}

package/src/core/fingerprint.test.ts

@@ -0,0 +1,27 @@
+import {describe, expect, it} from '@shipfox/vitest/vi';
+import {fingerprintSecretValue} from './fingerprint.js';
+
+const HMAC_FINGERPRINT_PATTERN = /^hmac-sha256:[A-Za-z0-9_-]{43}$/;
+
+describe('fingerprintSecretValue', () => {
+  it('returns a keyed non-reversible fingerprint', () => {
+    const key = Buffer.alloc(32, 1);
+
+    const result = fingerprintSecretValue('abcdefghijklmnopqrstuvwxyz', key);
+
+    expect(result).toMatch(HMAC_FINGERPRINT_PATTERN);
+    expect(result).not.toContain('wxyz');
+  });
+
+  it('is stable for the same key and value and changes with the key', () => {
+    const firstKey = Buffer.alloc(32, 1);
+    const secondKey = Buffer.alloc(32, 2);
+
+    const first = fingerprintSecretValue('secret-value', firstKey);
+    const same = fingerprintSecretValue('secret-value', firstKey);
+    const differentKey = fingerprintSecretValue('secret-value', secondKey);
+
+    expect(same).toBe(first);
+    expect(differentKey).not.toBe(first);
+  });
+});

package/src/core/fingerprint.ts

@@ -0,0 +1,14 @@
+import crypto from 'node:crypto';
+
+const FINGERPRINT_PREFIX = 'hmac-sha256:';
+const FINGERPRINT_DOMAIN = 'shipfox:secrets:value-fingerprint:v1';
+
+export function fingerprintSecretValue(value: string, key: Buffer): string {
+  const digest = crypto
+    .createHmac('sha256', key)
+    .update(FINGERPRINT_DOMAIN)
+    .update('\0')
+    .update(value)
+    .digest('base64url');
+  return `${FINGERPRINT_PREFIX}${digest}`;
+}

package/src/core/index.ts

@@ -0,0 +1,153 @@
+import {config} from '#config.js';
+import {decodeBase64Key} from './crypto.js';
+import {DekManager} from './dek-manager.js';
+import {createLocalKeyProvider, type KeyProvider} from './key-provider.js';
+import {createLocalSecretStore} from './local-secret-store.js';
+import {createSecretsManagementApi} from './management.js';
+import {rotateWorkspaceDataKeysWithProvider} from './rotate-kek.js';
+import {createSecretStoreApi} from './secret-store.js';
+import {
+  BUILTIN_LOCAL_STORE,
+  createSecretStoreResolver,
+  type SecretStoreProvider,
+} from './store-resolver.js';
+
+export * from './errors.js';
+export type {
+  ManagementEntry,
+  ManagementKeyParams,
+  ManagementListParams,
+  ManagementWriteParams,
+} from './management.js';
+export type {DeleteSecretsParams, SetSecretsParams} from './secret-store.js';
+export type {DeleteVariablesParams, SetVariablesParams} from './variable-store.js';
+export {
+  deleteVariables,
+  getVariable,
+  getVariablesByNamespace,
+  setVariables,
+} from './variable-store.js';
+export {BUILTIN_LOCAL_STORE, type SecretStoreProvider};
+
+let memoizedKeyProvider: KeyProvider | undefined;
+let memoizedDekManager: DekManager | undefined;
+let memoizedLocalStore: SecretStoreProvider | undefined;
+let memoizedSecretApi: ReturnType<typeof createSecretStoreApi> | undefined;
+let memoizedManagementApi: ReturnType<typeof createSecretsManagementApi> | undefined;
+
+export function keyProvider(): KeyProvider {
+  if (memoizedKeyProvider) return memoizedKeyProvider;
+  memoizedKeyProvider = createLocalKeyProvider({
+    currentKek: decodeBase64Key(config.SECRETS_ENCRYPTION_KEK, 'SECRETS_ENCRYPTION_KEK'),
+    previousKek: config.SECRETS_ENCRYPTION_KEK_PREVIOUS
+      ? decodeBase64Key(config.SECRETS_ENCRYPTION_KEK_PREVIOUS, 'SECRETS_ENCRYPTION_KEK_PREVIOUS')
+      : undefined,
+  });
+  return memoizedKeyProvider;
+}
+
+export function dekManager(): DekManager {
+  if (memoizedDekManager) return memoizedDekManager;
+  memoizedDekManager = new DekManager(keyProvider(), {
+    maxEntries: 1000,
+    ttlMs: 5 * 60 * 1000,
+  });
+  return memoizedDekManager;
+}
+
+export function localSecretStore(): SecretStoreProvider {
+  if (memoizedLocalStore) return memoizedLocalStore;
+  memoizedLocalStore = createLocalSecretStore({dekManager: dekManager()});
+  return memoizedLocalStore;
+}
+
+export function resolveSecretStore(name?: string | undefined): SecretStoreProvider {
+  return createSecretStoreResolver(localSecretStore())(name);
+}
+
+function secretApi(): ReturnType<typeof createSecretStoreApi> {
+  if (memoizedSecretApi) return memoizedSecretApi;
+  memoizedSecretApi = createSecretStoreApi({
+    dekManager: dekManager(),
+    resolveSecretStore,
+  });
+  return memoizedSecretApi;
+}
+
+function managementApi(): ReturnType<typeof createSecretsManagementApi> {
+  if (memoizedManagementApi) return memoizedManagementApi;
+  memoizedManagementApi = createSecretsManagementApi({dekManager: dekManager()});
+  return memoizedManagementApi;
+}
+
+export function getSecret(
+  ...args: Parameters<ReturnType<typeof createSecretStoreApi>['getSecret']>
+) {
+  return secretApi().getSecret(...args);
+}
+
+export function getSecretsByNamespace(
+  ...args: Parameters<ReturnType<typeof createSecretStoreApi>['getSecretsByNamespace']>
+) {
+  return secretApi().getSecretsByNamespace(...args);
+}
+
+export function setSecrets(
+  ...args: Parameters<ReturnType<typeof createSecretStoreApi>['setSecrets']>
+) {
+  return secretApi().setSecrets(...args);
+}
+
+export function deleteSecrets(
+  ...args: Parameters<ReturnType<typeof createSecretStoreApi>['deleteSecrets']>
+) {
+  return secretApi().deleteSecrets(...args);
+}
+
+export function listManagedSecrets(
+  ...args: Parameters<ReturnType<typeof createSecretsManagementApi>['listSecrets']>
+) {
+  return managementApi().listSecrets(...args);
+}
+
+export function listManagedVariables(
+  ...args: Parameters<ReturnType<typeof createSecretsManagementApi>['listVariables']>
+) {
+  return managementApi().listVariables(...args);
+}
+
+export function getManagedVariable(
+  ...args: Parameters<ReturnType<typeof createSecretsManagementApi>['getVariable']>
+) {
+  return managementApi().getVariable(...args);
+}
+
+export function setManagedSecrets(
+  ...args: Parameters<ReturnType<typeof createSecretsManagementApi>['setSecrets']>
+) {
+  return managementApi().setSecrets(...args);
+}
+
+export function setManagedVariables(
+  ...args: Parameters<ReturnType<typeof createSecretsManagementApi>['setVariables']>
+) {
+  return managementApi().setVariables(...args);
+}
+
+export function deleteManagedSecret(
+  ...args: Parameters<ReturnType<typeof createSecretsManagementApi>['deleteSecret']>
+) {
+  return managementApi().deleteSecret(...args);
+}
+
+export function deleteManagedVariable(
+  ...args: Parameters<ReturnType<typeof createSecretsManagementApi>['deleteVariable']>
+) {
+  return managementApi().deleteVariable(...args);
+}
+
+export function rotateWorkspaceDataKeys() {
+  return rotateWorkspaceDataKeysWithProvider(keyProvider());
+}
+
+export {rotateWorkspaceDataKeysWithProvider};

package/src/core/key-provider.test.ts

@@ -0,0 +1,44 @@
+import crypto from 'node:crypto';
+import {describe, expect, it} from '@shipfox/vitest/vi';
+import {DekUnwrapError} from './errors.js';
+import {createLocalKeyProvider} from './key-provider.js';
+
+describe('local key provider', () => {
+  it('wraps with the current KEK and unwraps with current or previous KEK', () => {
+    const currentKek = crypto.randomBytes(32);
+    const previousKek = crypto.randomBytes(32);
+    const provider = createLocalKeyProvider({currentKek, previousKek});
+    const previousProvider = createLocalKeyProvider({currentKek: previousKek});
+    const workspaceId = crypto.randomUUID();
+    const dek = crypto.randomBytes(32);
+
+    const previousWrapped = previousProvider.wrapDek(workspaceId, dek);
+    const unwrappedPrevious = provider.unwrapDek(
+      workspaceId,
+      previousWrapped.wrappedDek,
+      previousWrapped.kekVersion,
+    );
+    const currentWrapped = provider.wrapDek(workspaceId, unwrappedPrevious);
+    const unwrappedCurrent = provider.unwrapDek(
+      workspaceId,
+      currentWrapped.wrappedDek,
+      currentWrapped.kekVersion,
+    );
+
+    expect(currentWrapped.kekVersion).toBe(provider.currentKeyVersion);
+    expect(previousWrapped.kekVersion).toBe(provider.previousKeyVersion);
+    expect(unwrappedCurrent.equals(dek)).toBe(true);
+  });
+
+  it('rejects unknown versions and wrong workspace AAD', () => {
+    const provider = createLocalKeyProvider({currentKek: crypto.randomBytes(32)});
+    const wrapped = provider.wrapDek(crypto.randomUUID(), crypto.randomBytes(32));
+
+    expect(() =>
+      provider.unwrapDek(crypto.randomUUID(), wrapped.wrappedDek, wrapped.kekVersion),
+    ).toThrow(DekUnwrapError);
+    expect(() =>
+      provider.unwrapDek(crypto.randomUUID(), wrapped.wrappedDek, 'local:unknown'),
+    ).toThrow(DekUnwrapError);
+  });
+});

package/src/core/key-provider.ts

@@ -0,0 +1,70 @@
+import crypto from 'node:crypto';
+import {aadForDek, aesGcmOpen, aesGcmSeal} from './crypto.js';
+import {DekUnwrapError, DekWrapError} from './errors.js';
+
+const KEK_VERSION_DOMAIN = 'shipfox-secrets-kek-version';
+
+export interface WrappedDek {
+  wrappedDek: string;
+  kekVersion: string;
+}
+
+export interface KeyProvider {
+  readonly currentKeyVersion: string;
+  readonly previousKeyVersion: string | null;
+  wrapDek(workspaceId: string, plaintextDek: Buffer): WrappedDek;
+  unwrapDek(workspaceId: string, wrappedDek: string, kekVersion: string): Buffer;
+}
+
+export interface LocalKeyProviderParams {
+  currentKek: Buffer;
+  previousKek?: Buffer | undefined;
+}
+
+export function createLocalKeyProvider(params: LocalKeyProviderParams): KeyProvider {
+  const currentKeyVersion = deriveLocalKekVersion(params.currentKek);
+  const previousKeyVersion = params.previousKek ? deriveLocalKekVersion(params.previousKek) : null;
+
+  return {
+    currentKeyVersion,
+    previousKeyVersion,
+    wrapDek(workspaceId, plaintextDek) {
+      try {
+        return {
+          wrappedDek: aesGcmSeal({
+            key: params.currentKek,
+            plaintext: plaintextDek,
+            aad: aadForDek(workspaceId, currentKeyVersion),
+          }),
+          kekVersion: currentKeyVersion,
+        };
+      } catch {
+        throw new DekWrapError();
+      }
+    },
+    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();
+      }
+    },
+  };
+}
+
+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)}`;
+}

package/src/core/local-secret-store.ts

@@ -0,0 +1,49 @@
+import {
+  getSecretValueRowWithPrecedence,
+  listSecretValueRowsByNamespace,
+  type StoreScope,
+} from '#db/index.js';
+import type {DekManager} from './dek-manager.js';
+import {decryptSecretValue} from './value-cipher.js';
+
+export interface LocalSecretStoreParams {
+  dekManager: DekManager;
+}
+
+export function createLocalSecretStore(params: LocalSecretStoreParams) {
+  return {
+    async getSecret(input: StoreScope & {workspaceId: string; namespace: string; key: string}) {
+      const row = await getSecretValueRowWithPrecedence(input);
+      if (!row) return null;
+
+      const dek = await params.dekManager.getPlaintextDek(input.workspaceId);
+      return decryptSecretValue({
+        dek,
+        workspaceId: row.workspaceId,
+        scope: {projectId: row.projectId},
+        namespace: row.namespace,
+        key: row.key,
+        ciphertext: row.ciphertext,
+      });
+    },
+    async getSecretsByNamespace(input: StoreScope & {workspaceId: string; namespace: string}) {
+      const rows = await listSecretValueRowsByNamespace(input);
+      const dek =
+        rows.length > 0 ? await params.dekManager.getPlaintextDek(input.workspaceId) : null;
+
+      return Object.fromEntries(
+        rows.map((row) => [
+          row.key,
+          decryptSecretValue({
+            dek: dek as Buffer,
+            workspaceId: row.workspaceId,
+            scope: {projectId: row.projectId},
+            namespace: row.namespace,
+            key: row.key,
+            ciphertext: row.ciphertext,
+          }),
+        ]),
+      );
+    },
+  };
+}

package/src/core/management.test.ts

@@ -0,0 +1,37 @@
+import {eq} from 'drizzle-orm';
+import {db, secretDataKeys, secretVariables} from '#db/index.js';
+import {setManagedSecrets, setManagedVariables} from './index.js';
+
+describe('secrets management core', () => {
+  let workspaceId: string;
+
+  beforeEach(() => {
+    workspaceId = crypto.randomUUID();
+  });
+
+  it('treats empty managed writes as no-ops', async () => {
+    const secretResult = await setManagedSecrets({
+      workspaceId,
+      actorId: crypto.randomUUID(),
+      entries: [],
+    });
+    const variableResult = await setManagedVariables({
+      workspaceId,
+      actorId: crypto.randomUUID(),
+      entries: [],
+    });
+
+    const dataKeys = await db()
+      .select()
+      .from(secretDataKeys)
+      .where(eq(secretDataKeys.workspaceId, workspaceId));
+    const variables = await db()
+      .select()
+      .from(secretVariables)
+      .where(eq(secretVariables.workspaceId, workspaceId));
+    expect(secretResult).toEqual([]);
+    expect(variableResult).toEqual([]);
+    expect(dataKeys).toHaveLength(0);
+    expect(variables).toHaveLength(0);
+  });
+});