@shipfox/api-secrets 2.0.0

package/src/core/store-validation.ts

@@ -0,0 +1,43 @@
+import {isSystemNamespace, namespaceSchema, secretKeySchema} from '@shipfox/api-secrets-dto';
+import {config, MAX_VALUE_BYTES} from '#config.js';
+import {countWorkspaceEntries, type Tx} from '#db/index.js';
+import {
+  NamespaceValidationError,
+  SecretKeyValidationError,
+  SecretValueTooLargeError,
+  WorkspaceSecretCapExceededError,
+} from './errors.js';
+
+export function validateNamespace(namespace: string): void {
+  if (namespaceSchema.safeParse(namespace).success) return;
+  throw new NamespaceValidationError(namespace);
+}
+
+export function validateSecretKeys(keys: Iterable<string>): void {
+  for (const key of keys) {
+    if (!secretKeySchema.safeParse(key).success) throw new SecretKeyValidationError(key);
+  }
+}
+
+export function validateValueBytes(values: Iterable<string>): void {
+  for (const value of values) {
+    if (Buffer.byteLength(value, 'utf8') > MAX_VALUE_BYTES) {
+      throw new SecretValueTooLargeError(MAX_VALUE_BYTES);
+    }
+  }
+}
+
+export async function assertWorkspaceCap(params: {
+  workspaceId: string;
+  namespace: string;
+  incomingEntries: number;
+  tx: Tx;
+}): Promise<void> {
+  // System namespaces are internal-only; public management routes do not accept a namespace.
+  if (isSystemNamespace(params.namespace)) return;
+
+  const count = await countWorkspaceEntries(params.workspaceId, params.tx);
+  if (count + params.incomingEntries > config.SECRETS_MAX_PER_WORKSPACE) {
+    throw new WorkspaceSecretCapExceededError(params.workspaceId, config.SECRETS_MAX_PER_WORKSPACE);
+  }
+}

package/src/core/value-cipher.ts

@@ -0,0 +1,26 @@
+import {aadForValue, aesGcmOpen, aesGcmSeal, type SecretValueAadParams} from './crypto.js';
+import {SecretDecryptionError} from './errors.js';
+
+export function encryptSecretValue(
+  params: SecretValueAadParams & {dek: Buffer; value: string},
+): string {
+  return aesGcmSeal({
+    key: params.dek,
+    plaintext: Buffer.from(params.value, 'utf8'),
+    aad: aadForValue(params),
+  });
+}
+
+export function decryptSecretValue(
+  params: SecretValueAadParams & {dek: Buffer; ciphertext: string},
+): string {
+  try {
+    return aesGcmOpen({
+      key: params.dek,
+      encoded: params.ciphertext,
+      aad: aadForValue(params),
+    }).toString('utf8');
+  } catch {
+    throw new SecretDecryptionError();
+  }
+}

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

@@ -0,0 +1,106 @@
+import crypto from 'node:crypto';
+import {describe, expect, it} from '@shipfox/vitest/vi';
+import {eq} from 'drizzle-orm';
+import {db, secretVariables, upsertSecretVariableRows} from '#db/index.js';
+import {SecretBatchScopeMismatchError, WorkspaceSecretCapExceededError} from './errors.js';
+import {
+  deleteVariables,
+  getVariable,
+  getVariablesByNamespace,
+  setVariables,
+} from './variable-store.js';
+
+describe('variable store', () => {
+  it('stores plaintext variables and applies scope precedence', async () => {
+    const workspaceId = crypto.randomUUID();
+    const projectId = crypto.randomUUID();
+
+    await setVariables({workspaceId, values: {REGION: 'us-east-1'}});
+    await setVariables({workspaceId, projectId, values: {REGION: 'eu-west-1'}});
+    const projectValue = await getVariable({workspaceId, projectId, key: 'REGION'});
+    const values = await getVariablesByNamespace({workspaceId, projectId});
+    const rows = await db().select().from(secretVariables);
+
+    expect(projectValue).toBe('eu-west-1');
+    expect(values).toEqual({REGION: 'eu-west-1'});
+    expect(rows.map((row) => row.value).sort()).toEqual(['eu-west-1', 'us-east-1']);
+  });
+
+  it('normalizes an empty project id to workspace scope', async () => {
+    const workspaceId = crypto.randomUUID();
+
+    await setVariables({workspaceId, projectId: '', values: {REGION: 'us-east-1'}});
+    const value = await getVariable({workspaceId, key: 'REGION'});
+    const rows = await db()
+      .select()
+      .from(secretVariables)
+      .where(eq(secretVariables.workspaceId, workspaceId));
+
+    expect(value).toBe('us-east-1');
+    expect(rows[0]?.projectId).toBeNull();
+  });
+
+  it('treats an empty delete key list as a no-op', async () => {
+    const workspaceId = crypto.randomUUID();
+    await setVariables({workspaceId, values: {REGION: 'us-east-1'}});
+
+    const deleted = await deleteVariables({workspaceId, keys: []});
+    const value = await getVariable({workspaceId, key: 'REGION'});
+
+    expect(deleted).toBe(0);
+    expect(value).toBe('us-east-1');
+  });
+
+  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(setVariables({workspaceId, values})).rejects.toThrow(
+      WorkspaceSecretCapExceededError,
+    );
+  });
+
+  it('rejects mixed project scopes in one variable upsert batch', async () => {
+    const workspaceId = crypto.randomUUID();
+
+    await expect(
+      db().transaction((tx) =>
+        upsertSecretVariableRows(
+          [
+            {
+              workspaceId,
+              projectId: null,
+              namespace: '',
+              key: 'REGION',
+              value: 'us-east-1',
+            },
+            {
+              workspaceId,
+              projectId: crypto.randomUUID(),
+              namespace: '',
+              key: 'OTHER_REGION',
+              value: 'eu-west-1',
+            },
+          ],
+          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(secretVariables).values({
+        workspaceId,
+        projectId: null,
+        namespace: 'Bad/Namespace',
+        key: 'REGION',
+        value: 'us-east-1',
+      }),
+    ).rejects.toThrow();
+  });
+});

package/src/core/variable-store.ts

@@ -0,0 +1,232 @@
+import {
+  countSecretVariableRows,
+  db,
+  deleteSecretVariableRows,
+  getSecretVariableRowWithPrecedence,
+  listSecretVariableRowsByNamespace,
+  lockWorkspaceEntries,
+  type StoreScope,
+  upsertSecretVariableRows,
+} from '#db/index.js';
+import {normalizedProjectId} from '#db/scope.js';
+import {
+  classifySecretsOperationError,
+  operationScope,
+  recordSecretsEntriesMutated,
+  recordSecretsOperation,
+} from '#metrics/instance.js';
+import {
+  assertWorkspaceCap,
+  validateNamespace,
+  validateSecretKeys,
+  validateValueBytes,
+} from './store-validation.js';
+
+export interface SetVariablesParams extends StoreScope {
+  workspaceId: string;
+  namespace?: string | undefined;
+  values: Record<string, string>;
+  editedBy?: string | null | undefined;
+}
+
+export interface DeleteVariablesParams extends StoreScope {
+  workspaceId: string;
+  namespace?: string | undefined;
+  keys?: string[] | undefined;
+}
+
+export async function getVariable(
+  input: StoreScope & {workspaceId: string; namespace?: string | undefined; key: string},
+): Promise<string | null> {
+  const startedAt = Date.now();
+  const scope = operationScope(input);
+  try {
+    const namespace = input.namespace ?? '';
+    validateNamespace(namespace);
+    validateSecretKeys([input.key]);
+
+    const row = await getSecretVariableRowWithPrecedence({...input, namespace});
+    recordSecretsOperation({
+      resource: 'variable',
+      operation: 'get',
+      surface: 'internal',
+      scope,
+      outcome: row ? 'success' : 'not_found',
+      durationMs: Date.now() - startedAt,
+    });
+    return row?.value ?? null;
+  } catch (error) {
+    recordSecretsOperation({
+      resource: 'variable',
+      operation: 'get',
+      surface: 'internal',
+      scope,
+      outcome: classifySecretsOperationError(error),
+      durationMs: Date.now() - startedAt,
+    });
+    throw error;
+  }
+}
+
+export async function getVariablesByNamespace(
+  input: StoreScope & {workspaceId: string; namespace?: string | undefined},
+): Promise<Record<string, string>> {
+  const startedAt = Date.now();
+  const scope = operationScope(input);
+  try {
+    const namespace = input.namespace ?? '';
+    validateNamespace(namespace);
+
+    const rows = await listSecretVariableRowsByNamespace({...input, namespace});
+    recordSecretsOperation({
+      resource: 'variable',
+      operation: 'get_namespace',
+      surface: 'internal',
+      scope,
+      outcome: 'success',
+      durationMs: Date.now() - startedAt,
+    });
+    return Object.fromEntries(rows.map((row) => [row.key, row.value]));
+  } catch (error) {
+    recordSecretsOperation({
+      resource: 'variable',
+      operation: 'get_namespace',
+      surface: 'internal',
+      scope,
+      outcome: classifySecretsOperationError(error),
+      durationMs: Date.now() - startedAt,
+    });
+    throw error;
+  }
+}
+
+export async function setVariables(input: SetVariablesParams): 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: 'variable',
+        operation: 'set',
+        surface: 'internal',
+        scope,
+        outcome: 'success',
+        durationMs: Date.now() - startedAt,
+      });
+      return;
+    }
+
+    const projectId = normalizedProjectId(input);
+    let existingEntries = 0;
+    await db().transaction(async (tx) => {
+      await lockWorkspaceEntries(input.workspaceId, tx);
+      existingEntries = await countSecretVariableRows(
+        {
+          workspaceId: input.workspaceId,
+          projectId,
+          namespace,
+          keys: entries.map(([key]) => key),
+        },
+        tx,
+      );
+      await assertWorkspaceCap({
+        workspaceId: input.workspaceId,
+        namespace,
+        incomingEntries: entries.length - existingEntries,
+        tx,
+      });
+      await upsertSecretVariableRows(
+        entries.map(([key, value]) => ({
+          workspaceId: input.workspaceId,
+          projectId,
+          namespace,
+          key,
+          value,
+          lastEditedBy: input.editedBy ?? null,
+        })),
+        tx,
+      );
+    });
+
+    recordSecretsEntriesMutated({
+      resource: 'variable',
+      operation: 'set',
+      effect: 'created',
+      surface: 'internal',
+      count: entries.length - existingEntries,
+    });
+    recordSecretsEntriesMutated({
+      resource: 'variable',
+      operation: 'set',
+      effect: 'updated',
+      surface: 'internal',
+      count: existingEntries,
+    });
+    recordSecretsOperation({
+      resource: 'variable',
+      operation: 'set',
+      surface: 'internal',
+      scope,
+      outcome: 'success',
+      durationMs: Date.now() - startedAt,
+    });
+  } catch (error) {
+    recordSecretsOperation({
+      resource: 'variable',
+      operation: 'set',
+      surface: 'internal',
+      scope,
+      outcome: classifySecretsOperationError(error),
+      durationMs: Date.now() - startedAt,
+    });
+    throw error;
+  }
+}
+
+export async function deleteVariables(input: DeleteVariablesParams): 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 deleteSecretVariableRows({
+      workspaceId: input.workspaceId,
+      projectId: normalizedProjectId(input),
+      namespace,
+      keys: input.keys,
+    });
+    recordSecretsEntriesMutated({
+      resource: 'variable',
+      operation: 'delete',
+      effect: 'deleted',
+      surface: 'internal',
+      count: deleted,
+    });
+    recordSecretsOperation({
+      resource: 'variable',
+      operation: 'delete',
+      surface: 'internal',
+      scope,
+      outcome: 'success',
+      durationMs: Date.now() - startedAt,
+    });
+    return deleted;
+  } catch (error) {
+    recordSecretsOperation({
+      resource: 'variable',
+      operation: 'delete',
+      surface: 'internal',
+      scope,
+      outcome: classifySecretsOperationError(error),
+      durationMs: Date.now() - startedAt,
+    });
+    throw error;
+  }
+}

package/src/db/cap.ts

@@ -0,0 +1,58 @@
+import {and, count, eq, notLike, sql} from 'drizzle-orm';
+import {db, type Tx} from './db.js';
+import {secretValues} from './schema/values.js';
+import {secretVariables} from './schema/variables.js';
+
+export async function countWorkspaceEntries(workspaceId: string, tx?: Tx): Promise<number> {
+  const executor = tx ?? db();
+  const valueCount = executor
+    .select({count: count().as('value_count')})
+    .from(secretValues)
+    .where(
+      and(eq(secretValues.workspaceId, workspaceId), notLike(secretValues.namespace, 'system/%')),
+    )
+    .as('value_count');
+  const variableCount = executor
+    .select({count: count().as('variable_count')})
+    .from(secretVariables)
+    .where(
+      and(
+        eq(secretVariables.workspaceId, workspaceId),
+        notLike(secretVariables.namespace, 'system/%'),
+      ),
+    )
+    .as('variable_count');
+  const [row] = await executor
+    .select({value: sql<number>`${valueCount.count} + ${variableCount.count}`})
+    .from(valueCount)
+    .crossJoin(variableCount);
+
+  return Number(row?.value ?? 0);
+}
+
+export async function countPublicEntriesByResource(
+  tx?: Tx,
+): Promise<{secrets: number; variables: number}> {
+  const executor = tx ?? db();
+  const [secretCount, variableCount] = await Promise.all([
+    executor
+      .select({count: count().as('secret_count')})
+      .from(secretValues)
+      .where(notLike(secretValues.namespace, 'system/%')),
+    executor
+      .select({count: count().as('variable_count')})
+      .from(secretVariables)
+      .where(notLike(secretVariables.namespace, 'system/%')),
+  ]);
+
+  return {
+    secrets: Number(secretCount[0]?.count ?? 0),
+    variables: Number(variableCount[0]?.count ?? 0),
+  };
+}
+
+export async function lockWorkspaceEntries(workspaceId: string, tx: Tx): Promise<void> {
+  await tx.execute(sql`
+    SELECT pg_advisory_xact_lock(hashtext('shipfox_secrets_workspace_cap'), hashtext(${workspaceId}))
+  `);
+}

package/src/db/data-keys.ts

@@ -0,0 +1,99 @@
+import {and, eq, gt, inArray, notInArray, type SQL, sql} from 'drizzle-orm';
+import {db, type Tx} from './db.js';
+import {type DataKey, secretDataKeys, toDataKey} from './schema/data-keys.js';
+
+export async function getDataKey(workspaceId: string, tx?: Tx): Promise<DataKey | undefined> {
+  const executor = tx ?? db();
+  const rows = await executor
+    .select()
+    .from(secretDataKeys)
+    .where(eq(secretDataKeys.workspaceId, workspaceId))
+    .limit(1);
+  const row = rows[0];
+  return row ? toDataKey(row) : undefined;
+}
+
+export async function insertDataKeyIfAbsent(
+  dataKey: {workspaceId: string; wrappedDek: string; kekVersion: string},
+  tx?: Tx,
+): Promise<boolean> {
+  const executor = tx ?? db();
+  const rows = await executor
+    .insert(secretDataKeys)
+    .values(dataKey)
+    .onConflictDoNothing({
+      target: secretDataKeys.workspaceId,
+    })
+    .returning({workspaceId: secretDataKeys.workspaceId});
+  return rows.length > 0;
+}
+
+export async function updateDataKeyWrapCas(
+  params: {workspaceId: string; oldKekVersion: string; wrappedDek: string; kekVersion: string},
+  tx?: Tx,
+): Promise<boolean> {
+  const executor = tx ?? db();
+  const rows = await executor
+    .update(secretDataKeys)
+    .set({
+      wrappedDek: params.wrappedDek,
+      kekVersion: params.kekVersion,
+      rotatedAt: sql`NOW()`,
+    })
+    .where(
+      and(
+        eq(secretDataKeys.workspaceId, params.workspaceId),
+        eq(secretDataKeys.kekVersion, params.oldKekVersion),
+      ),
+    )
+    .returning({workspaceId: secretDataKeys.workspaceId});
+  return rows.length > 0;
+}
+
+export async function listDataKeyVersions(
+  knownVersions: string[],
+  params: {workspaceIds?: string[] | undefined} = {},
+): Promise<string[]> {
+  if (params.workspaceIds?.length === 0) return [];
+
+  const filters: SQL[] = [];
+  if (knownVersions.length > 0) {
+    filters.push(notInArray(secretDataKeys.kekVersion, knownVersions));
+  }
+  if (params.workspaceIds) {
+    filters.push(inArray(secretDataKeys.workspaceId, params.workspaceIds));
+  }
+  const rows = await db()
+    .selectDistinct({kekVersion: secretDataKeys.kekVersion})
+    .from(secretDataKeys)
+    .where(filters.length > 0 ? and(...filters) : undefined);
+  return rows.map((row) => row.kekVersion);
+}
+
+export async function listDataKeysPage(params: {
+  afterWorkspaceId?: string | undefined;
+  limit: number;
+  versions?: string[] | undefined;
+  workspaceIds?: string[] | undefined;
+}): Promise<DataKey[]> {
+  if (params.versions && params.versions.length === 0) return [];
+  if (params.workspaceIds?.length === 0) return [];
+
+  const filters: SQL[] = [];
+  if (params.afterWorkspaceId) {
+    filters.push(gt(secretDataKeys.workspaceId, params.afterWorkspaceId));
+  }
+  if (params.versions) {
+    filters.push(inArray(secretDataKeys.kekVersion, params.versions));
+  }
+  if (params.workspaceIds) {
+    filters.push(inArray(secretDataKeys.workspaceId, params.workspaceIds));
+  }
+  const rows = await db()
+    .select()
+    .from(secretDataKeys)
+    .where(filters.length > 0 ? and(...filters) : undefined)
+    .orderBy(secretDataKeys.workspaceId)
+    .limit(params.limit);
+  return rows.map(toDataKey);
+}

package/src/db/db.ts

@@ -0,0 +1,26 @@
+import {drizzle, type NodePgDatabase} from '@shipfox/node-drizzle';
+import {pgClient} from '@shipfox/node-postgres';
+import {secretDataKeys} from './schema/data-keys.js';
+import {secretsOutbox} from './schema/outbox.js';
+import {secretValues} from './schema/values.js';
+import {secretVariables} from './schema/variables.js';
+
+export const schema = {
+  secretDataKeys,
+  secretsOutbox,
+  secretValues,
+  secretVariables,
+};
+
+let _db: NodePgDatabase<typeof schema> | undefined;
+
+export function db() {
+  if (!_db) _db = drizzle(pgClient(), {schema});
+  return _db;
+}
+
+export function closeDb(): void {
+  _db = undefined;
+}
+
+export type Tx = Parameters<Parameters<NodePgDatabase<typeof schema>['transaction']>[0]>[0];

package/src/db/index.ts

@@ -0,0 +1,45 @@
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+export {countPublicEntriesByResource, countWorkspaceEntries, lockWorkspaceEntries} from './cap.js';
+export {
+  getDataKey,
+  insertDataKeyIfAbsent,
+  listDataKeysPage,
+  listDataKeyVersions,
+  updateDataKeyWrapCas,
+} from './data-keys.js';
+export {closeDb, db, schema, type Tx} from './db.js';
+export {
+  deleteSecretManagementRows,
+  deleteVariableManagementRows,
+  getSecretManagementRow,
+  getVariableManagementRow,
+  listExistingSecretManagementKeys,
+  listExistingVariableManagementKeys,
+  listSecretManagementRows,
+  listVariableManagementRows,
+  type SecretManagementRow,
+  type VariableManagementListRow,
+} from './management.js';
+export {secretDataKeys} from './schema/data-keys.js';
+export {secretsOutbox} from './schema/outbox.js';
+export {secretValues} from './schema/values.js';
+export {secretVariables} from './schema/variables.js';
+export type {StoreScope} from './scope.js';
+export {
+  countSecretValueRows,
+  deleteSecretValueRows,
+  getSecretValueRowWithPrecedence,
+  listSecretValueRowsByNamespace,
+  upsertSecretValueRows,
+} from './values.js';
+export {
+  countSecretVariableRows,
+  deleteSecretVariableRows,
+  getSecretVariableRowWithPrecedence,
+  listSecretVariableRowsByNamespace,
+  upsertSecretVariableRows,
+} from './variables.js';
+
+export const migrationsPath = resolve(dirname(fileURLToPath(import.meta.url)), '../../drizzle');