@shipfox/api-secrets 2.0.0

package/src/db/management.ts

@@ -0,0 +1,252 @@
+import {and, asc, eq, gt, inArray, isNull, type SQL, sql} from 'drizzle-orm';
+import type {AnyPgColumn} from 'drizzle-orm/pg-core';
+import type {Tx} from './db.js';
+import {db} from './db.js';
+import {type SecretValue, secretValues} from './schema/values.js';
+import {type SecretVariable, secretVariables, toSecretVariable} from './schema/variables.js';
+import {normalizedProjectId, type StoreScope} from './scope.js';
+
+export interface ManagementListParams extends StoreScope {
+  workspaceId: string;
+  limit: number;
+  cursor?: string | undefined;
+}
+
+export type SecretManagementRow = Omit<SecretValue, 'ciphertext' | 'fingerprint'>;
+
+// Values can be large and multi-line, so the list returns only a bounded, single-line
+// preview (the value's first line, capped at this many characters). The full value is
+// fetched on demand via getVariableManagementRow. This keeps a single-call list of the
+// whole bounded set from materializing hundreds of MB server-side.
+export const VARIABLE_LIST_VALUE_PREVIEW_LENGTH = 256;
+
+/** A variable list row whose `value` is a preview; `valueTruncated` flags that more exists. */
+export interface VariableManagementListRow extends SecretVariable {
+  valueTruncated: boolean;
+}
+
+export interface SecretManagementListResult {
+  secrets: SecretManagementRow[];
+  nextCursor: string | null;
+}
+
+export interface VariableManagementListResult {
+  variables: VariableManagementListRow[];
+  nextCursor: string | null;
+}
+
+export async function listSecretManagementRows(
+  params: ManagementListParams,
+  tx?: Tx,
+): Promise<SecretManagementListResult> {
+  const executor = tx ?? db();
+  const rows = await executor
+    .select(secretManagementColumns)
+    .from(secretValues)
+    .where(and(...managementFilters(secretValues, params)))
+    .orderBy(asc(secretValues.key))
+    .limit(params.limit + 1);
+
+  const hasMore = rows.length > params.limit;
+  const pageRows = hasMore ? rows.slice(0, params.limit) : rows;
+  const last = pageRows.at(-1);
+
+  return {
+    secrets: pageRows.map(toSecretManagementRow),
+    nextCursor: hasMore && last ? last.key : null,
+  };
+}
+
+export async function listVariableManagementRows(
+  params: ManagementListParams,
+  tx?: Tx,
+): Promise<VariableManagementListResult> {
+  const executor = tx ?? db();
+  // Preview = the value's first line, capped at the preview length. `valueTruncated`
+  // is true whenever the stored value differs from that preview (longer, or multi-line).
+  const valuePreview = sql<string>`left(split_part(${secretVariables.value}, chr(10), 1), ${VARIABLE_LIST_VALUE_PREVIEW_LENGTH})`;
+  const rows = await executor
+    .select({
+      id: secretVariables.id,
+      workspaceId: secretVariables.workspaceId,
+      projectId: secretVariables.projectId,
+      namespace: secretVariables.namespace,
+      key: secretVariables.key,
+      createdAt: secretVariables.createdAt,
+      updatedAt: secretVariables.updatedAt,
+      lastEditedBy: secretVariables.lastEditedBy,
+      valuePreview,
+      valueTruncated: sql<boolean>`${secretVariables.value} <> ${valuePreview}`,
+    })
+    .from(secretVariables)
+    .where(and(...managementFilters(secretVariables, params)))
+    .orderBy(asc(secretVariables.key))
+    .limit(params.limit + 1);
+
+  const hasMore = rows.length > params.limit;
+  const pageRows = hasMore ? rows.slice(0, params.limit) : rows;
+  const last = pageRows.at(-1);
+
+  return {
+    variables: pageRows.map((row) => ({
+      id: row.id,
+      workspaceId: row.workspaceId,
+      projectId: row.projectId,
+      namespace: row.namespace,
+      key: row.key,
+      value: row.valuePreview,
+      valueTruncated: row.valueTruncated,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+      lastEditedBy: row.lastEditedBy,
+    })),
+    nextCursor: hasMore && last ? last.key : null,
+  };
+}
+
+export async function getSecretManagementRow(
+  params: StoreScope & {workspaceId: string; key: string},
+  tx?: Tx,
+): Promise<SecretManagementRow | undefined> {
+  const executor = tx ?? db();
+  const rows = await executor
+    .select(secretManagementColumns)
+    .from(secretValues)
+    .where(and(...managementFilters(secretValues, params), eq(secretValues.key, params.key)))
+    .limit(1);
+
+  const row = rows[0];
+  return row ? toSecretManagementRow(row) : undefined;
+}
+
+export async function getVariableManagementRow(
+  params: StoreScope & {workspaceId: string; key: string},
+  tx?: Tx,
+): Promise<SecretVariable | undefined> {
+  const executor = tx ?? db();
+  const rows = await executor
+    .select()
+    .from(secretVariables)
+    .where(and(...managementFilters(secretVariables, params), eq(secretVariables.key, params.key)))
+    .limit(1);
+
+  const row = rows[0];
+  return row ? toSecretVariable(row) : undefined;
+}
+
+export async function listExistingSecretManagementKeys(
+  params: StoreScope & {workspaceId: string; keys: string[]},
+  tx: Tx,
+): Promise<Set<string>> {
+  if (params.keys.length === 0) return new Set();
+
+  const rows = await tx
+    .select({key: secretValues.key})
+    .from(secretValues)
+    .where(and(...managementFilters(secretValues, params), inArray(secretValues.key, params.keys)));
+
+  return new Set(rows.map((row) => row.key));
+}
+
+export async function listExistingVariableManagementKeys(
+  params: StoreScope & {workspaceId: string; keys: string[]},
+  tx: Tx,
+): Promise<Set<string>> {
+  if (params.keys.length === 0) return new Set();
+
+  const rows = await tx
+    .select({key: secretVariables.key})
+    .from(secretVariables)
+    .where(
+      and(...managementFilters(secretVariables, params), inArray(secretVariables.key, params.keys)),
+    );
+
+  return new Set(rows.map((row) => row.key));
+}
+
+export async function deleteSecretManagementRows(
+  params: StoreScope & {workspaceId: string; keys: string[]},
+  tx: Tx,
+): Promise<SecretManagementRow[]> {
+  if (params.keys.length === 0) return [];
+
+  const rows = await tx
+    .delete(secretValues)
+    .where(and(...managementFilters(secretValues, params), inArray(secretValues.key, params.keys)))
+    .returning(secretManagementColumns);
+
+  return rows.map(toSecretManagementRow);
+}
+
+const secretManagementColumns = {
+  id: secretValues.id,
+  workspaceId: secretValues.workspaceId,
+  projectId: secretValues.projectId,
+  namespace: secretValues.namespace,
+  key: secretValues.key,
+  createdAt: secretValues.createdAt,
+  updatedAt: secretValues.updatedAt,
+  lastEditedBy: secretValues.lastEditedBy,
+};
+
+type SecretManagementDbRow =
+  typeof secretManagementColumns extends Record<string, infer _Column>
+    ? {
+        id: string;
+        workspaceId: string;
+        projectId: string | null;
+        namespace: string;
+        key: string;
+        createdAt: Date;
+        updatedAt: Date;
+        lastEditedBy: string | null;
+      }
+    : never;
+
+function toSecretManagementRow(row: SecretManagementDbRow): SecretManagementRow {
+  return {
+    id: row.id,
+    workspaceId: row.workspaceId,
+    projectId: row.projectId,
+    namespace: row.namespace,
+    key: row.key,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+    lastEditedBy: row.lastEditedBy,
+  };
+}
+
+export async function deleteVariableManagementRows(
+  params: StoreScope & {workspaceId: string; keys: string[]},
+  tx: Tx,
+): Promise<SecretVariable[]> {
+  if (params.keys.length === 0) return [];
+
+  const rows = await tx
+    .delete(secretVariables)
+    .where(
+      and(...managementFilters(secretVariables, params), inArray(secretVariables.key, params.keys)),
+    )
+    .returning();
+
+  return rows.map(toSecretVariable);
+}
+
+function managementFilters(
+  table: {
+    workspaceId: AnyPgColumn;
+    projectId: AnyPgColumn;
+    namespace: AnyPgColumn;
+    key: AnyPgColumn;
+  },
+  params: StoreScope & {workspaceId: string; cursor?: string | undefined},
+): SQL[] {
+  const projectId = normalizedProjectId(params);
+  const filters = [
+    eq(table.workspaceId, params.workspaceId),
+    eq(table.namespace, ''),
+    projectId ? eq(table.projectId, projectId) : isNull(table.projectId),
+  ];
+  if (params.cursor) filters.push(gt(table.key, params.cursor));
+  return filters;
+}

package/src/db/schema/common.ts

@@ -0,0 +1,8 @@
+import {sql} from 'drizzle-orm';
+import {pgTableCreator} from 'drizzle-orm/pg-core';
+
+export const pgTable = pgTableCreator((name) => `secrets_${name}`);
+
+export function sqlStringLiteral(value: string) {
+  return sql.raw(`'${value.replaceAll("'", "''")}'`);
+}

package/src/db/schema/data-keys.ts

@@ -0,0 +1,31 @@
+import {text, timestamp, uuid} from 'drizzle-orm/pg-core';
+import {pgTable} from './common.js';
+
+export interface DataKey {
+  workspaceId: string;
+  wrappedDek: string;
+  kekVersion: string;
+  createdAt: Date;
+  rotatedAt: Date | null;
+}
+
+export const secretDataKeys = pgTable('data_keys', {
+  workspaceId: uuid('workspace_id').primaryKey(),
+  wrappedDek: text('wrapped_dek').notNull(),
+  kekVersion: text('kek_version').notNull(),
+  createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+  rotatedAt: timestamp('rotated_at', {withTimezone: true}),
+});
+
+export type DataKeyDb = typeof secretDataKeys.$inferSelect;
+export type DataKeyCreateDb = typeof secretDataKeys.$inferInsert;
+
+export function toDataKey(row: DataKeyDb): DataKey {
+  return {
+    workspaceId: row.workspaceId,
+    wrappedDek: row.wrappedDek,
+    kekVersion: row.kekVersion,
+    createdAt: row.createdAt,
+    rotatedAt: row.rotatedAt,
+  };
+}

package/src/db/schema/outbox.ts

@@ -0,0 +1,4 @@
+import {createOutboxTable} from '@shipfox/node-outbox';
+import {pgTable} from './common.js';
+
+export const secretsOutbox = createOutboxTable(pgTable);

package/src/db/schema/values.ts

@@ -0,0 +1,74 @@
+import {NAMESPACE_PATTERN_SOURCE, SECRET_KEY_PATTERN_SOURCE} from '@shipfox/api-secrets-dto';
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {sql} from 'drizzle-orm';
+import {check, index, text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
+import {pgTable, sqlStringLiteral} from './common.js';
+
+export interface SecretValue {
+  id: string;
+  workspaceId: string;
+  projectId: string | null;
+  namespace: string;
+  key: string;
+  ciphertext: string;
+  fingerprint: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+  lastEditedBy: string | null;
+}
+
+export const secretValues = pgTable(
+  'values',
+  {
+    id: uuidv7PrimaryKey(),
+    workspaceId: uuid('workspace_id').notNull(),
+    projectId: uuid('project_id'),
+    namespace: text('namespace').notNull(),
+    key: text('key').notNull(),
+    ciphertext: text('ciphertext').notNull(),
+    fingerprint: text('fingerprint'),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
+    lastEditedBy: uuid('last_edited_by'),
+  },
+  (table) => [
+    uniqueIndex('secrets_values_ws_scope_unique')
+      .on(table.workspaceId, table.namespace, table.key)
+      .where(sql`"project_id" IS NULL`),
+    uniqueIndex('secrets_values_project_scope_unique')
+      .on(table.workspaceId, table.projectId, table.namespace, table.key)
+      .where(sql`"project_id" IS NOT NULL`),
+    index('secrets_values_lookup_idx').on(
+      table.workspaceId,
+      table.namespace,
+      table.projectId,
+      table.key,
+    ),
+    check(
+      'secrets_values_key_ck',
+      sql`${table.key} ~ ${sqlStringLiteral(SECRET_KEY_PATTERN_SOURCE)}`,
+    ),
+    check(
+      'secrets_values_namespace_ck',
+      sql`char_length(${table.namespace}) <= 128 AND (${table.namespace} = '' OR ${table.namespace} ~ ${sqlStringLiteral(NAMESPACE_PATTERN_SOURCE)})`,
+    ),
+  ],
+);
+
+export type SecretValueDb = typeof secretValues.$inferSelect;
+export type SecretValueCreateDb = typeof secretValues.$inferInsert;
+
+export function toSecretValue(row: SecretValueDb): SecretValue {
+  return {
+    id: row.id,
+    workspaceId: row.workspaceId,
+    projectId: row.projectId,
+    namespace: row.namespace,
+    key: row.key,
+    ciphertext: row.ciphertext,
+    fingerprint: row.fingerprint,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+    lastEditedBy: row.lastEditedBy,
+  };
+}

package/src/db/schema/variables.ts

@@ -0,0 +1,71 @@
+import {NAMESPACE_PATTERN_SOURCE, SECRET_KEY_PATTERN_SOURCE} from '@shipfox/api-secrets-dto';
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {sql} from 'drizzle-orm';
+import {check, index, text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
+import {pgTable, sqlStringLiteral} from './common.js';
+
+export interface SecretVariable {
+  id: string;
+  workspaceId: string;
+  projectId: string | null;
+  namespace: string;
+  key: string;
+  value: string;
+  createdAt: Date;
+  updatedAt: Date;
+  lastEditedBy: string | null;
+}
+
+export const secretVariables = pgTable(
+  'variables',
+  {
+    id: uuidv7PrimaryKey(),
+    workspaceId: uuid('workspace_id').notNull(),
+    projectId: uuid('project_id'),
+    namespace: text('namespace').notNull(),
+    key: text('key').notNull(),
+    value: text('value').notNull(),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
+    lastEditedBy: uuid('last_edited_by'),
+  },
+  (table) => [
+    uniqueIndex('secrets_variables_ws_scope_unique')
+      .on(table.workspaceId, table.namespace, table.key)
+      .where(sql`"project_id" IS NULL`),
+    uniqueIndex('secrets_variables_project_scope_unique')
+      .on(table.workspaceId, table.projectId, table.namespace, table.key)
+      .where(sql`"project_id" IS NOT NULL`),
+    index('secrets_variables_lookup_idx').on(
+      table.workspaceId,
+      table.namespace,
+      table.projectId,
+      table.key,
+    ),
+    check(
+      'secrets_variables_key_ck',
+      sql`${table.key} ~ ${sqlStringLiteral(SECRET_KEY_PATTERN_SOURCE)}`,
+    ),
+    check(
+      'secrets_variables_namespace_ck',
+      sql`char_length(${table.namespace}) <= 128 AND (${table.namespace} = '' OR ${table.namespace} ~ ${sqlStringLiteral(NAMESPACE_PATTERN_SOURCE)})`,
+    ),
+  ],
+);
+
+export type SecretVariableDb = typeof secretVariables.$inferSelect;
+export type SecretVariableCreateDb = typeof secretVariables.$inferInsert;
+
+export function toSecretVariable(row: SecretVariableDb): SecretVariable {
+  return {
+    id: row.id,
+    workspaceId: row.workspaceId,
+    projectId: row.projectId,
+    namespace: row.namespace,
+    key: row.key,
+    value: row.value,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+    lastEditedBy: row.lastEditedBy,
+  };
+}

package/src/db/scope.ts

@@ -0,0 +1,42 @@
+import {and, eq, isNull, or, type SQL, sql} from 'drizzle-orm';
+import type {PgColumn} from 'drizzle-orm/pg-core';
+
+export interface StoreScope {
+  projectId?: string | null | undefined;
+}
+
+export interface ScopeColumns {
+  workspaceId: PgColumn;
+  projectId: PgColumn;
+  namespace: PgColumn;
+  key: PgColumn;
+}
+
+export function normalizedProjectId(scope?: StoreScope | undefined): string | null {
+  return scope?.projectId || null;
+}
+
+export function scopeConflictTargetWhere(scope?: StoreScope | undefined): SQL {
+  return normalizedProjectId(scope) !== null
+    ? sql`"project_id" IS NOT NULL`
+    : sql`"project_id" IS NULL`;
+}
+
+export function scopeExactWhere(columns: ScopeColumns, params: StoreScope): SQL | undefined {
+  const projectId = normalizedProjectId(params);
+  return projectId !== null ? eq(columns.projectId, projectId) : isNull(columns.projectId);
+}
+
+export function lookupWithPrecedenceWhere(
+  columns: ScopeColumns,
+  params: StoreScope & {workspaceId: string; namespace: string; key: string},
+): SQL | undefined {
+  const base = and(
+    eq(columns.workspaceId, params.workspaceId),
+    eq(columns.namespace, params.namespace),
+    eq(columns.key, params.key),
+  );
+  const projectId = normalizedProjectId(params);
+  if (projectId === null) return and(base, isNull(columns.projectId));
+  return and(base, or(eq(columns.projectId, projectId), isNull(columns.projectId)));
+}

package/src/db/values.ts

@@ -0,0 +1,191 @@
+import {and, eq, inArray, isNull, sql} from 'drizzle-orm';
+import {SecretBatchScopeMismatchError} from '#core/errors.js';
+import {db, type Tx} from './db.js';
+import {type SecretValue, secretValues, toSecretValue} from './schema/values.js';
+import {
+  lookupWithPrecedenceWhere,
+  normalizedProjectId,
+  type StoreScope,
+  scopeConflictTargetWhere,
+  scopeExactWhere,
+} from './scope.js';
+
+export interface SecretValueWrite {
+  workspaceId: string;
+  projectId: string | null;
+  namespace: string;
+  key: string;
+  ciphertext: string;
+  fingerprint: string | null;
+  lastEditedBy?: string | null | undefined;
+}
+
+export async function getSecretValueRowWithPrecedence(
+  params: StoreScope & {workspaceId: string; namespace: string; key: string},
+  tx?: Tx,
+): Promise<SecretValue | undefined> {
+  const executor = tx ?? db();
+  const rows = await executor
+    .select()
+    .from(secretValues)
+    .where(
+      lookupWithPrecedenceWhere(
+        {
+          workspaceId: secretValues.workspaceId,
+          projectId: secretValues.projectId,
+          namespace: secretValues.namespace,
+          key: secretValues.key,
+        },
+        params,
+      ),
+    )
+    .orderBy(sql`${secretValues.projectId} NULLS LAST`)
+    .limit(1);
+  const row = rows[0];
+  return row ? toSecretValue(row) : undefined;
+}
+
+export async function listSecretValueRowsByNamespace(
+  params: StoreScope & {workspaceId: string; namespace: string},
+  tx?: Tx,
+): Promise<SecretValue[]> {
+  const executor = tx ?? db();
+  const rows = await executor.execute<SecretValueRow>(sql`
+    SELECT DISTINCT ON (key)
+      id, workspace_id, project_id, namespace, key, ciphertext, fingerprint,
+      created_at, updated_at, last_edited_by
+    FROM secrets_values
+    WHERE ${listByNamespaceSql(params)}
+    ORDER BY key, project_id NULLS LAST, id
+  `);
+  return rows.rows.map(rowToSecretValue);
+}
+
+export async function upsertSecretValueRows(rows: SecretValueWrite[], tx: Tx): Promise<void> {
+  if (rows.length === 0) return;
+  const projectId = batchProjectId(rows);
+  await tx
+    .insert(secretValues)
+    .values(rows)
+    .onConflictDoUpdate({
+      target: projectId
+        ? [
+            secretValues.workspaceId,
+            secretValues.projectId,
+            secretValues.namespace,
+            secretValues.key,
+          ]
+        : [secretValues.workspaceId, secretValues.namespace, secretValues.key],
+      targetWhere: scopeConflictTargetWhere({projectId}),
+      set: {
+        ciphertext: sql`excluded.ciphertext`,
+        fingerprint: sql`excluded.fingerprint`,
+        lastEditedBy: sql`excluded.last_edited_by`,
+        updatedAt: sql`NOW()`,
+      },
+    });
+}
+
+export async function countSecretValueRows(
+  params: StoreScope & {workspaceId: string; namespace: string; keys: string[]},
+  tx: Tx,
+): Promise<number> {
+  if (params.keys.length === 0) return 0;
+
+  const rows = await tx
+    .select({count: sql<string | number>`COUNT(*)`})
+    .from(secretValues)
+    .where(
+      and(
+        eq(secretValues.workspaceId, params.workspaceId),
+        eq(secretValues.namespace, params.namespace),
+        scopeExactWhere(
+          {
+            workspaceId: secretValues.workspaceId,
+            projectId: secretValues.projectId,
+            namespace: secretValues.namespace,
+            key: secretValues.key,
+          },
+          params,
+        ) ?? isNull(secretValues.projectId),
+        inArray(secretValues.key, params.keys),
+      ),
+    );
+
+  return Number(rows[0]?.count ?? 0);
+}
+
+export async function deleteSecretValueRows(
+  params: StoreScope & {workspaceId: string; namespace: string; keys?: string[] | undefined},
+  tx?: Tx,
+): Promise<number> {
+  if (params.keys && params.keys.length === 0) return 0;
+
+  const executor = tx ?? db();
+  const filters = [
+    eq(secretValues.workspaceId, params.workspaceId),
+    eq(secretValues.namespace, params.namespace),
+    scopeExactWhere(
+      {
+        workspaceId: secretValues.workspaceId,
+        projectId: secretValues.projectId,
+        namespace: secretValues.namespace,
+        key: secretValues.key,
+      },
+      params,
+    ) ?? isNull(secretValues.projectId),
+  ];
+  if (params.keys && params.keys.length > 0) {
+    filters.push(inArray(secretValues.key, params.keys));
+  }
+  const deleted = await executor
+    .delete(secretValues)
+    .where(and(...filters))
+    .returning({id: secretValues.id});
+  return deleted.length;
+}
+
+function batchProjectId(rows: SecretValueWrite[]): string | null {
+  const projectId = normalizedProjectId({projectId: rows[0]?.projectId});
+  const mixedScope = rows.some(
+    (row) => normalizedProjectId({projectId: row.projectId}) !== projectId,
+  );
+  if (mixedScope) throw new SecretBatchScopeMismatchError();
+  return projectId;
+}
+
+function listByNamespaceSql(params: StoreScope & {workspaceId: string; namespace: string}) {
+  const projectId = normalizedProjectId(params);
+  if (!projectId) {
+    return sql`workspace_id = ${params.workspaceId} AND namespace = ${params.namespace} AND project_id IS NULL`;
+  }
+  return sql`workspace_id = ${params.workspaceId} AND namespace = ${params.namespace} AND (project_id = ${projectId} OR project_id IS NULL)`;
+}
+
+interface SecretValueRow extends Record<string, unknown> {
+  id: string;
+  workspace_id: string;
+  project_id: string | null;
+  namespace: string;
+  key: string;
+  ciphertext: string;
+  fingerprint: string | null;
+  created_at: Date;
+  updated_at: Date;
+  last_edited_by: string | null;
+}
+
+function rowToSecretValue(row: SecretValueRow): SecretValue {
+  return {
+    id: row.id,
+    workspaceId: row.workspace_id,
+    projectId: row.project_id,
+    namespace: row.namespace,
+    key: row.key,
+    ciphertext: row.ciphertext,
+    fingerprint: row.fingerprint,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    lastEditedBy: row.last_edited_by,
+  };
+}