@shipfox/api-secrets 2.0.0

package/src/core/rotate-kek.ts

@@ -0,0 +1,100 @@
+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;
+}
+
+export interface RotateWorkspaceDataKeysOptions {
+  workspaceIds?: string[] | undefined;
+}
+
+export async 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';
+}

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

@@ -0,0 +1,301 @@
+import crypto from 'node:crypto';
+import {describe, expect, it} from '@shipfox/vitest/vi';
+import {eq, sql} from 'drizzle-orm';
+import {db, secretDataKeys, secretValues, upsertSecretValueRows} from '#db/index.js';
+import {
+  NamespaceValidationError,
+  SecretBatchScopeMismatchError,
+  SecretDecryptionError,
+  SecretKeyValidationError,
+  SecretValueTooLargeError,
+  WorkspaceSecretCapExceededError,
+} from './errors.js';
+import {dekManager, deleteSecrets, getSecret, getSecretsByNamespace, setSecrets} from './index.js';
+
+const V1_PREFIX_PATTERN = /^v1:/;
+const HMAC_FINGERPRINT_PATTERN = /^hmac-sha256:[A-Za-z0-9_-]{43}$/;
+
+describe('secret store', () => {
+  it('sets, encrypts, and reads secrets by namespace', async () => {
+    const workspaceId = crypto.randomUUID();
+
+    await setSecrets({
+      workspaceId,
+      namespace: 'system/agent/model-provider/openai',
+      values: {API_KEY: 'sk-live-value'},
+    });
+
+    const value = await getSecret({
+      workspaceId,
+      namespace: 'system/agent/model-provider/openai',
+      key: 'API_KEY',
+    });
+    const values = await getSecretsByNamespace({
+      workspaceId,
+      namespace: 'system/agent/model-provider/openai',
+    });
+    const rows = await db()
+      .select()
+      .from(secretValues)
+      .where(eq(secretValues.workspaceId, workspaceId));
+
+    expect(value).toBe('sk-live-value');
+    expect(values).toEqual({API_KEY: 'sk-live-value'});
+    expect(rows[0]?.ciphertext).toMatch(V1_PREFIX_PATTERN);
+    expect(rows[0]?.ciphertext).not.toBe('sk-live-value');
+    expect(rows[0]?.fingerprint).toMatch(HMAC_FINGERPRINT_PATTERN);
+    expect(rows[0]?.fingerprint).not.toContain('alue');
+  });
+
+  it('prefers project scope over workspace scope and deletes only exact project scope', async () => {
+    const workspaceId = crypto.randomUUID();
+    const projectId = crypto.randomUUID();
+
+    await setSecrets({workspaceId, values: {TOKEN: 'workspace-token'}});
+    await setSecrets({workspaceId, projectId, values: {TOKEN: 'project-token'}});
+    const projectValue = await getSecret({workspaceId, projectId, key: 'TOKEN'});
+    const workspaceValue = await getSecret({workspaceId, key: 'TOKEN'});
+    await deleteSecrets({workspaceId, projectId});
+    const inheritedValue = await getSecret({workspaceId, projectId, key: 'TOKEN'});
+
+    expect(projectValue).toBe('project-token');
+    expect(workspaceValue).toBe('workspace-token');
+    expect(inheritedValue).toBe('workspace-token');
+  });
+
+  it('normalizes an empty project id to workspace scope', async () => {
+    const workspaceId = crypto.randomUUID();
+
+    await setSecrets({workspaceId, projectId: '', values: {TOKEN: 'workspace-token'}});
+    const value = await getSecret({workspaceId, key: 'TOKEN'});
+    const rows = await db()
+      .select()
+      .from(secretValues)
+      .where(eq(secretValues.workspaceId, workspaceId));
+
+    expect(value).toBe('workspace-token');
+    expect(rows[0]?.projectId).toBeNull();
+  });
+
+  it('treats an empty delete key list as a no-op', async () => {
+    const workspaceId = crypto.randomUUID();
+    await setSecrets({workspaceId, values: {TOKEN: 'keep-me'}});
+
+    const deleted = await deleteSecrets({workspaceId, keys: []});
+    const value = await getSecret({workspaceId, key: 'TOKEN'});
+
+    expect(deleted).toBe(0);
+    expect(value).toBe('keep-me');
+  });
+
+  it('rejects invalid keys and namespaces before writing', async () => {
+    const workspaceId = crypto.randomUUID();
+
+    await expect(setSecrets({workspaceId, values: {'bad-key': 'value'}})).rejects.toThrow(
+      SecretKeyValidationError,
+    );
+    await expect(
+      setSecrets({workspaceId, namespace: 'Bad/Namespace', values: {TOKEN: 'value'}}),
+    ).rejects.toThrow(NamespaceValidationError);
+  });
+
+  it('rejects oversized values with a typed domain error', async () => {
+    const workspaceId = crypto.randomUUID();
+
+    await expect(
+      setSecrets({workspaceId, values: {TOKEN: 'a'.repeat(64 * 1024 + 1)}}),
+    ).rejects.toThrow(SecretValueTooLargeError);
+  });
+
+  it('enforces the workspace cap', async () => {
+    const workspaceId = crypto.randomUUID();
+    const values = Object.fromEntries(
+      Array.from({length: 10_001}, (_, index) => [`KEY_${index}`, 'value']),
+    );
+
+    await expect(setSecrets({workspaceId, values})).rejects.toThrow(
+      WorkspaceSecretCapExceededError,
+    );
+  });
+
+  it('does not count system namespace entries against the workspace cap', async () => {
+    const workspaceId = crypto.randomUUID();
+    await db()
+      .insert(secretValues)
+      .values(
+        Array.from({length: 10_000}, (_, index) => ({
+          workspaceId,
+          projectId: null,
+          namespace: 'system/github/installation-token/1',
+          key: `KEY_${index}`,
+          ciphertext: 'v1:test',
+          fingerprint: null,
+        })),
+      );
+
+    await setSecrets({workspaceId, values: {TOKEN: 'user-value'}});
+    const value = await getSecret({workspaceId, key: 'TOKEN'});
+
+    expect(value).toBe('user-value');
+  });
+
+  it('allows system namespace writes when user entries are at the workspace cap', async () => {
+    const workspaceId = crypto.randomUUID();
+    await db()
+      .insert(secretValues)
+      .values(
+        Array.from({length: 10_000}, (_, index) => ({
+          workspaceId,
+          projectId: null,
+          namespace: '',
+          key: `KEY_${index}`,
+          ciphertext: 'v1:test',
+          fingerprint: null,
+        })),
+      );
+
+    await setSecrets({
+      workspaceId,
+      namespace: 'system/github/installation-token/1',
+      values: {TOKEN: 'system-value'},
+    });
+    const value = await getSecret({
+      workspaceId,
+      namespace: 'system/github/installation-token/1',
+      key: 'TOKEN',
+    });
+
+    expect(value).toBe('system-value');
+  });
+
+  it('allows updating an existing secret at the workspace cap', async () => {
+    const workspaceId = crypto.randomUUID();
+    await setSecrets({workspaceId, values: {TOKEN: 'old-value'}});
+    await db()
+      .insert(secretValues)
+      .values(
+        Array.from({length: 9_999}, (_, index) => ({
+          workspaceId,
+          projectId: null,
+          namespace: '',
+          key: `KEY_${index}`,
+          ciphertext: 'v1:test',
+          fingerprint: null,
+        })),
+      );
+
+    await setSecrets({workspaceId, values: {TOKEN: 'new-value'}});
+    const value = await getSecret({workspaceId, key: 'TOKEN'});
+
+    expect(value).toBe('new-value');
+  });
+
+  it('does not mint a data key for an empty batch', async () => {
+    const workspaceId = crypto.randomUUID();
+
+    await setSecrets({workspaceId, values: {}});
+    const rows = await db()
+      .select()
+      .from(secretDataKeys)
+      .where(eq(secretDataKeys.workspaceId, workspaceId));
+
+    expect(rows).toHaveLength(0);
+  });
+
+  it('rolls back value rows when the write transaction fails', async () => {
+    const workspaceId = crypto.randomUUID();
+
+    await expect(
+      db().transaction(async (tx) => {
+        await upsertSecretValueRows(
+          [
+            {
+              workspaceId,
+              projectId: null,
+              namespace: '',
+              key: 'TOKEN',
+              ciphertext: 'v1:test',
+              fingerprint: null,
+            },
+          ],
+          tx,
+        );
+        throw new Error('rollback');
+      }),
+    ).rejects.toThrow('rollback');
+    const rows = await db()
+      .select()
+      .from(secretValues)
+      .where(eq(secretValues.workspaceId, workspaceId));
+
+    expect(rows).toHaveLength(0);
+  });
+
+  it('rejects mixed project scopes in one value upsert batch', async () => {
+    const workspaceId = crypto.randomUUID();
+
+    await expect(
+      db().transaction((tx) =>
+        upsertSecretValueRows(
+          [
+            {
+              workspaceId,
+              projectId: null,
+              namespace: '',
+              key: 'TOKEN',
+              ciphertext: 'v1:test',
+              fingerprint: null,
+            },
+            {
+              workspaceId,
+              projectId: crypto.randomUUID(),
+              namespace: '',
+              key: 'OTHER_TOKEN',
+              ciphertext: 'v1:test',
+              fingerprint: null,
+            },
+          ],
+          tx,
+        ),
+      ),
+    ).rejects.toThrow(SecretBatchScopeMismatchError);
+  });
+
+  it('keeps the database namespace check in parity with the DTO pattern', async () => {
+    const workspaceId = crypto.randomUUID();
+
+    await expect(
+      db().insert(secretValues).values({
+        workspaceId,
+        projectId: null,
+        namespace: 'Bad/Namespace',
+        key: 'TOKEN',
+        ciphertext: 'v1:test',
+        fingerprint: null,
+      }),
+    ).rejects.toThrow();
+  });
+
+  it('fails closed when the workspace data key is removed', async () => {
+    const workspaceId = crypto.randomUUID();
+    await setSecrets({workspaceId, values: {TOKEN: 'recover-me'}});
+    dekManager().invalidate(workspaceId);
+    await db().delete(secretDataKeys).where(eq(secretDataKeys.workspaceId, workspaceId));
+
+    await expect(getSecret({workspaceId, key: 'TOKEN'})).rejects.toThrow(SecretDecryptionError);
+  });
+
+  it('keeps the database key-pattern check in parity with the DTO pattern', async () => {
+    const accepted = await db().execute(sql`
+      SELECT bool_and(value ~ '^[A-Z_][A-Z0-9_]*$') AS ok
+      FROM (VALUES ('A_B1'), ('_A')) accepted(value)
+    `);
+    const rejected = await db().execute(sql`
+      SELECT bool_or(value ~ '^[A-Z_][A-Z0-9_]*$') AS ok
+      FROM (VALUES ('A-B'), ('1A'), ('a')) rejected(value)
+    `);
+
+    expect(accepted.rows[0]?.ok).toBe(true);
+    expect(rejected.rows[0]?.ok).toBe(false);
+  });
+});

package/src/core/secret-store.ts

@@ -0,0 +1,251 @@
+import {
+  countSecretValueRows,
+  db,
+  deleteSecretValueRows,
+  lockWorkspaceEntries,
+  type StoreScope,
+  upsertSecretValueRows,
+} from '#db/index.js';
+import {normalizedProjectId} from '#db/scope.js';
+import {
+  classifySecretsOperationError,
+  operationScope,
+  recordSecretsEntriesMutated,
+  recordSecretsOperation,
+} from '#metrics/instance.js';
+import type {DekManager} from './dek-manager.js';
+import {fingerprintSecretValue} from './fingerprint.js';
+import type {SecretStoreProvider} from './store-resolver.js';
+import {
+  assertWorkspaceCap,
+  validateNamespace,
+  validateSecretKeys,
+  validateValueBytes,
+} from './store-validation.js';
+import {encryptSecretValue} from './value-cipher.js';
+
+export interface SetSecretsParams extends StoreScope {
+  workspaceId: string;
+  namespace?: string | undefined;
+  values: Record<string, string>;
+  editedBy?: string | null | undefined;
+}
+
+export interface DeleteSecretsParams extends StoreScope {
+  workspaceId: string;
+  namespace?: string | undefined;
+  keys?: string[] | undefined;
+}
+
+export function createSecretStoreApi(params: {
+  dekManager: DekManager;
+  resolveSecretStore: (name?: string | undefined) => SecretStoreProvider;
+}) {
+  return {
+    async getSecret(
+      input: StoreScope & {
+        workspaceId: string;
+        namespace?: string | undefined;
+        key: string;
+        store?: string;
+      },
+    ) {
+      const startedAt = Date.now();
+      const scope = operationScope(input);
+      try {
+        const namespace = input.namespace ?? '';
+        validateNamespace(namespace);
+        validateSecretKeys([input.key]);
+        const value = await params.resolveSecretStore(input.store).getSecret({...input, namespace});
+        recordSecretsOperation({
+          resource: 'secret',
+          operation: 'get',
+          surface: 'internal',
+          scope,
+          outcome: value === null ? 'not_found' : 'success',
+          durationMs: Date.now() - startedAt,
+        });
+        return value;
+      } catch (error) {
+        recordSecretsOperation({
+          resource: 'secret',
+          operation: 'get',
+          surface: 'internal',
+          scope,
+          outcome: classifySecretsOperationError(error),
+          durationMs: Date.now() - startedAt,
+        });
+        throw error;
+      }
+    },
+    async getSecretsByNamespace(
+      input: StoreScope & {workspaceId: string; namespace?: string | undefined; store?: string},
+    ) {
+      const startedAt = Date.now();
+      const scope = operationScope(input);
+      try {
+        const namespace = input.namespace ?? '';
+        validateNamespace(namespace);
+        const values = await params
+          .resolveSecretStore(input.store)
+          .getSecretsByNamespace({...input, namespace});
+        recordSecretsOperation({
+          resource: 'secret',
+          operation: 'get_namespace',
+          surface: 'internal',
+          scope,
+          outcome: 'success',
+          durationMs: Date.now() - startedAt,
+        });
+        return values;
+      } catch (error) {
+        recordSecretsOperation({
+          resource: 'secret',
+          operation: 'get_namespace',
+          surface: 'internal',
+          scope,
+          outcome: classifySecretsOperationError(error),
+          durationMs: Date.now() - startedAt,
+        });
+        throw error;
+      }
+    },
+    async setSecrets(input: SetSecretsParams): Promise<void> {
+      const startedAt = Date.now();
+      const scope = operationScope(input);
+      try {
+        const namespace = input.namespace ?? '';
+        const entries = Object.entries(input.values);
+        validateNamespace(namespace);
+        validateSecretKeys(entries.map(([key]) => key));
+        validateValueBytes(entries.map(([, value]) => value));
+        if (entries.length === 0) {
+          recordSecretsOperation({
+            resource: 'secret',
+            operation: 'set',
+            surface: 'internal',
+            scope,
+            outcome: 'success',
+            durationMs: Date.now() - startedAt,
+          });
+          return;
+        }
+
+        const dek = await params.dekManager.getPlaintextDek(input.workspaceId);
+        const projectId = normalizedProjectId(input);
+        const rows = entries.map(([key, value]) => ({
+          workspaceId: input.workspaceId,
+          projectId,
+          namespace,
+          key,
+          ciphertext: encryptSecretValue({
+            dek,
+            workspaceId: input.workspaceId,
+            scope: {projectId},
+            namespace,
+            key,
+            value,
+          }),
+          fingerprint: fingerprintSecretValue(value, dek),
+          lastEditedBy: input.editedBy ?? null,
+        }));
+
+        let existingEntries = 0;
+        await db().transaction(async (tx) => {
+          await lockWorkspaceEntries(input.workspaceId, tx);
+          existingEntries = await countSecretValueRows(
+            {
+              workspaceId: input.workspaceId,
+              projectId,
+              namespace,
+              keys: entries.map(([key]) => key),
+            },
+            tx,
+          );
+          await assertWorkspaceCap({
+            workspaceId: input.workspaceId,
+            namespace,
+            incomingEntries: entries.length - existingEntries,
+            tx,
+          });
+          await upsertSecretValueRows(rows, tx);
+        });
+
+        recordSecretsEntriesMutated({
+          resource: 'secret',
+          operation: 'set',
+          effect: 'created',
+          surface: 'internal',
+          count: entries.length - existingEntries,
+        });
+        recordSecretsEntriesMutated({
+          resource: 'secret',
+          operation: 'set',
+          effect: 'updated',
+          surface: 'internal',
+          count: existingEntries,
+        });
+        recordSecretsOperation({
+          resource: 'secret',
+          operation: 'set',
+          surface: 'internal',
+          scope,
+          outcome: 'success',
+          durationMs: Date.now() - startedAt,
+        });
+      } catch (error) {
+        recordSecretsOperation({
+          resource: 'secret',
+          operation: 'set',
+          surface: 'internal',
+          scope,
+          outcome: classifySecretsOperationError(error),
+          durationMs: Date.now() - startedAt,
+        });
+        throw error;
+      }
+    },
+    async deleteSecrets(input: DeleteSecretsParams): Promise<number> {
+      const startedAt = Date.now();
+      const scope = operationScope(input);
+      try {
+        const namespace = input.namespace ?? '';
+        validateNamespace(namespace);
+        if (input.keys) validateSecretKeys(input.keys);
+
+        const deleted = await deleteSecretValueRows({
+          workspaceId: input.workspaceId,
+          projectId: normalizedProjectId(input),
+          namespace,
+          keys: input.keys,
+        });
+        recordSecretsEntriesMutated({
+          resource: 'secret',
+          operation: 'delete',
+          effect: 'deleted',
+          surface: 'internal',
+          count: deleted,
+        });
+        recordSecretsOperation({
+          resource: 'secret',
+          operation: 'delete',
+          surface: 'internal',
+          scope,
+          outcome: 'success',
+          durationMs: Date.now() - startedAt,
+        });
+        return deleted;
+      } catch (error) {
+        recordSecretsOperation({
+          resource: 'secret',
+          operation: 'delete',
+          surface: 'internal',
+          scope,
+          outcome: classifySecretsOperationError(error),
+          durationMs: Date.now() - startedAt,
+        });
+        throw error;
+      }
+    },
+  };
+}

package/src/core/store-resolver.test.ts

@@ -0,0 +1,20 @@
+import {describe, expect, it} from '@shipfox/vitest/vi';
+import {UnknownSecretStoreError} from './errors.js';
+import {
+  BUILTIN_LOCAL_STORE,
+  createSecretStoreResolver,
+  type SecretStoreProvider,
+} from './store-resolver.js';
+
+describe('secret store resolver', () => {
+  it('resolves the local provider and rejects unknown stores', () => {
+    const provider: SecretStoreProvider = {
+      getSecret: async () => null,
+      getSecretsByNamespace: async () => ({}),
+    };
+    const resolveSecretStore = createSecretStoreResolver(provider);
+
+    expect(resolveSecretStore(BUILTIN_LOCAL_STORE)).toBe(provider);
+    expect(() => resolveSecretStore('remote')).toThrow(UnknownSecretStoreError);
+  });
+});

package/src/core/store-resolver.ts

@@ -0,0 +1,28 @@
+import {UnknownSecretStoreError} from './errors.js';
+
+export const BUILTIN_LOCAL_STORE = 'local';
+
+export interface GetSecretParams {
+  workspaceId: string;
+  projectId?: string | null | undefined;
+  namespace: string;
+  key: string;
+}
+
+export interface GetSecretsByNamespaceParams {
+  workspaceId: string;
+  projectId?: string | null | undefined;
+  namespace: string;
+}
+
+export interface SecretStoreProvider {
+  getSecret(params: GetSecretParams): Promise<string | null>;
+  getSecretsByNamespace(params: GetSecretsByNamespaceParams): Promise<Record<string, string>>;
+}
+
+export function createSecretStoreResolver(localProvider: SecretStoreProvider) {
+  return function resolveSecretStore(name = BUILTIN_LOCAL_STORE): SecretStoreProvider {
+    if (name === BUILTIN_LOCAL_STORE) return localProvider;
+    throw new UnknownSecretStoreError(name);
+  };
+}