@shipfox/api-secrets 2.0.0

package/src/presentation/e2eRoutes/index.test.ts

@@ -0,0 +1,94 @@
+import {closeApp, createApp} from '@shipfox/node-fastify';
+import {eq} from 'drizzle-orm';
+import {getSecret} from '#core/index.js';
+import {db, secretValues, secretVariables} from '#db/index.js';
+import {secretsE2eRoutes} from './index.js';
+
+const ACTOR_ID = '11111111-1111-4111-8111-111111111111';
+
+describe('secrets e2e routes', () => {
+  let app: Awaited<ReturnType<typeof createApp>>;
+  let workspaceId: string;
+
+  beforeEach(async () => {
+    await closeApp();
+    workspaceId = crypto.randomUUID();
+    app = await createApp({routes: [secretsE2eRoutes], swagger: false});
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    await db().delete(secretValues).where(eq(secretValues.workspaceId, workspaceId));
+    await db().delete(secretVariables).where(eq(secretVariables.workspaceId, workspaceId));
+    await closeApp();
+  });
+
+  it('creates a secret setup row without exposing plaintext', async () => {
+    const value = 'seeded-secret-value';
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/secrets/secret',
+      payload: {
+        workspace_id: workspaceId,
+        actor_id: ACTOR_ID,
+        key: 'API_TOKEN',
+        value,
+      },
+    });
+    const stored = await getSecret({workspaceId, key: 'API_TOKEN'});
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).toMatchObject({
+      key: 'API_TOKEN',
+      project_id: null,
+      last_edited_by: ACTOR_ID,
+    });
+    expect(stored).toBe(value);
+    expect(res.body).not.toContain(value);
+  });
+
+  it('creates a variable setup row with its readable value', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/secrets/variable',
+      payload: {
+        workspace_id: workspaceId,
+        actor_id: ACTOR_ID,
+        key: 'REGION',
+        value: 'eu-west-1',
+      },
+    });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).toMatchObject({
+      key: 'REGION',
+      project_id: null,
+      value: 'eu-west-1',
+      last_edited_by: ACTOR_ID,
+    });
+  });
+
+  it('rejects invalid setup keys through route validation', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/secrets/secret',
+      payload: {
+        workspace_id: workspaceId,
+        actor_id: ACTOR_ID,
+        key: 'bad-key',
+        value: 'seeded-secret-value',
+      },
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json()).toMatchObject({code: 'validation-error'});
+  });
+
+  it('registers e2e setup routes without user auth', () => {
+    expect(secretsE2eRoutes.prefix).toBe('/secrets');
+    for (const route of secretsE2eRoutes.routes) {
+      expect(route.auth).toBeUndefined();
+    }
+  });
+});

package/src/presentation/e2eRoutes/index.ts

@@ -0,0 +1,8 @@
+import type {RouteGroup} from '@shipfox/node-fastify';
+import {createE2eSecretRoute} from './create-secret.js';
+import {createE2eVariableRoute} from './create-variable.js';
+
+export const secretsE2eRoutes: RouteGroup = {
+  prefix: '/secrets',
+  routes: [createE2eSecretRoute, createE2eVariableRoute],
+};

package/src/presentation/routes/auth.ts

@@ -0,0 +1,50 @@
+import {requireWorkspaceAccess} from '@shipfox/api-auth-context';
+import {requireProjectForWorkspace} from '@shipfox/api-projects';
+import {ClientError} from '@shipfox/node-fastify';
+import type {FastifyRequest} from 'fastify';
+
+export interface ManagementAccess {
+  workspaceId: string;
+  userId: string;
+}
+
+export async function requireManagementRead(params: {
+  request: FastifyRequest;
+  workspaceId: string;
+  projectId?: string | undefined;
+}): Promise<ManagementAccess> {
+  const membership = requireWorkspaceAccess({
+    request: params.request,
+    workspaceId: params.workspaceId,
+  });
+  if (params.projectId) {
+    await requireProjectForWorkspace({
+      workspaceId: params.workspaceId,
+      projectId: params.projectId,
+    });
+  }
+
+  return {workspaceId: params.workspaceId, userId: membership.userId};
+}
+
+export async function requireManagementWrite(params: {
+  request: FastifyRequest;
+  workspaceId: string;
+  projectId?: string | undefined;
+}): Promise<ManagementAccess> {
+  const membership = requireWorkspaceAccess({
+    request: params.request,
+    workspaceId: params.workspaceId,
+  });
+  if (membership.role !== 'admin') {
+    throw new ClientError('Workspace admin role required', 'forbidden', {status: 403});
+  }
+  if (params.projectId) {
+    await requireProjectForWorkspace({
+      workspaceId: params.workspaceId,
+      projectId: params.projectId,
+    });
+  }
+
+  return {workspaceId: params.workspaceId, userId: membership.userId};
+}

package/src/presentation/routes/batch-secrets.ts

@@ -0,0 +1,33 @@
+import {batchSecretsBodySchema, batchSecretsResponseSchema} from '@shipfox/api-secrets-dto';
+import {defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {setManagedSecrets} from '#core/index.js';
+import {toSecretDto} from '#presentation/dto/index.js';
+import {requireManagementWrite} from './auth.js';
+import {translateManagementError} from './errors.js';
+import {secretWarnings} from './warnings.js';
+
+export const batchSecretsRoute = defineRoute({
+  method: 'POST',
+  path: '/secrets::batch',
+  description: 'Create or update multiple user-managed secrets in one scope.',
+  schema: {
+    params: z.object({workspaceId: z.string().uuid()}),
+    body: batchSecretsBodySchema,
+    response: {200: batchSecretsResponseSchema},
+  },
+  errorHandler: translateManagementError,
+  handler: async (request) => {
+    const {workspaceId} = request.params;
+    const {project_id: projectId, entries} = request.body;
+    const access = await requireManagementWrite({request, workspaceId, projectId});
+    const secrets = await setManagedSecrets({
+      workspaceId,
+      projectId,
+      actorId: access.userId,
+      entries,
+    });
+
+    return {secrets: secrets.map(toSecretDto), warnings: secretWarnings(entries)};
+  },
+});

package/src/presentation/routes/batch-variables.ts

@@ -0,0 +1,33 @@
+import {batchVariablesBodySchema, batchVariablesResponseSchema} from '@shipfox/api-secrets-dto';
+import {defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {setManagedVariables} from '#core/index.js';
+import {toVariableDto} from '#presentation/dto/index.js';
+import {requireManagementWrite} from './auth.js';
+import {translateManagementError} from './errors.js';
+import {variableWarnings} from './warnings.js';
+
+export const batchVariablesRoute = defineRoute({
+  method: 'POST',
+  path: '/variables::batch',
+  description: 'Create or update multiple user-managed variables in one scope.',
+  schema: {
+    params: z.object({workspaceId: z.string().uuid()}),
+    body: batchVariablesBodySchema,
+    response: {200: batchVariablesResponseSchema},
+  },
+  errorHandler: translateManagementError,
+  handler: async (request) => {
+    const {workspaceId} = request.params;
+    const {project_id: projectId, entries} = request.body;
+    const access = await requireManagementWrite({request, workspaceId, projectId});
+    const variables = await setManagedVariables({
+      workspaceId,
+      projectId,
+      actorId: access.userId,
+      entries,
+    });
+
+    return {variables: variables.map(toVariableDto), warnings: variableWarnings(entries)};
+  },
+});

package/src/presentation/routes/cursor.ts

@@ -0,0 +1,23 @@
+interface ManagementCursor {
+  key: string;
+}
+
+export function encodeManagementCursor(cursor: string): string {
+  return Buffer.from(JSON.stringify({key: cursor} satisfies ManagementCursor), 'utf8').toString(
+    'base64url',
+  );
+}
+
+export function decodeManagementCursor(cursor: string | undefined): string | undefined {
+  if (!cursor) return undefined;
+
+  try {
+    const parsed: unknown = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return undefined;
+    const {key} = parsed as Partial<ManagementCursor>;
+    if (typeof key !== 'string' || key.length === 0) return undefined;
+    return key;
+  } catch {
+    return undefined;
+  }
+}

package/src/presentation/routes/delete-secret.ts

@@ -0,0 +1,26 @@
+import {secretKeySchema, secretScopeQuerySchema} from '@shipfox/api-secrets-dto';
+import {defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {deleteManagedSecret} from '#core/index.js';
+import {requireManagementWrite} from './auth.js';
+import {translateManagementError} from './errors.js';
+
+export const deleteSecretRoute = defineRoute({
+  method: 'DELETE',
+  path: '/secrets/:key',
+  description: 'Delete a user-managed secret.',
+  schema: {
+    params: z.object({workspaceId: z.string().uuid(), key: secretKeySchema}),
+    querystring: secretScopeQuerySchema,
+    response: {204: z.void()},
+  },
+  errorHandler: translateManagementError,
+  handler: async (request, reply) => {
+    const {workspaceId, key} = request.params;
+    const {project_id: projectId} = request.query;
+    const access = await requireManagementWrite({request, workspaceId, projectId});
+
+    await deleteManagedSecret({workspaceId, projectId, key, actorId: access.userId});
+    return reply.status(204).send();
+  },
+});

package/src/presentation/routes/delete-variable.ts

@@ -0,0 +1,26 @@
+import {secretKeySchema, secretScopeQuerySchema} from '@shipfox/api-secrets-dto';
+import {defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {deleteManagedVariable} from '#core/index.js';
+import {requireManagementWrite} from './auth.js';
+import {translateManagementError} from './errors.js';
+
+export const deleteVariableRoute = defineRoute({
+  method: 'DELETE',
+  path: '/variables/:key',
+  description: 'Delete a user-managed variable.',
+  schema: {
+    params: z.object({workspaceId: z.string().uuid(), key: secretKeySchema}),
+    querystring: secretScopeQuerySchema,
+    response: {204: z.void()},
+  },
+  errorHandler: translateManagementError,
+  handler: async (request, reply) => {
+    const {workspaceId, key} = request.params;
+    const {project_id: projectId} = request.query;
+    const access = await requireManagementWrite({request, workspaceId, projectId});
+
+    await deleteManagedVariable({workspaceId, projectId, key, actorId: access.userId});
+    return reply.status(204).send();
+  },
+});

package/src/presentation/routes/errors.ts

@@ -0,0 +1,63 @@
+import {ProjectNotFoundError} from '@shipfox/api-projects';
+import {ClientError} from '@shipfox/node-fastify';
+import {
+  NamespaceValidationError,
+  SecretBatchDuplicateKeyError,
+  SecretBatchScopeMismatchError,
+  SecretKeyValidationError,
+  SecretNotFoundError,
+  SecretValueTooLargeError,
+  UnknownSecretStoreError,
+  VariableNotFoundError,
+  WorkspaceSecretCapExceededError,
+} from '#core/errors.js';
+
+export function translateManagementError(error: unknown): never {
+  if (error instanceof SecretKeyValidationError) {
+    throw new ClientError('Invalid secret key', 'invalid-key', {
+      status: 400,
+      details: {key: error.key},
+    });
+  }
+  if (error instanceof NamespaceValidationError) {
+    throw new ClientError('Invalid namespace', 'invalid-namespace', {
+      status: 400,
+      details: {namespace: error.namespace},
+    });
+  }
+  if (error instanceof SecretValueTooLargeError) {
+    throw new ClientError(error.message, 'value-too-large', {
+      status: 413,
+      details: {max_bytes: error.maxBytes},
+    });
+  }
+  if (error instanceof WorkspaceSecretCapExceededError) {
+    throw new ClientError('Workspace secret cap exceeded', 'workspace-secret-cap-exceeded', {
+      status: 409,
+      details: {cap: error.cap},
+    });
+  }
+  if (error instanceof SecretBatchScopeMismatchError) {
+    throw new ClientError(error.message, 'batch-scope-mismatch', {status: 400});
+  }
+  if (error instanceof SecretBatchDuplicateKeyError) {
+    throw new ClientError('Duplicate batch key', 'duplicate-key', {
+      status: 400,
+      details: {key: error.key},
+    });
+  }
+  if (error instanceof SecretNotFoundError) {
+    throw new ClientError('Secret not found', 'secret-not-found', {status: 404});
+  }
+  if (error instanceof VariableNotFoundError) {
+    throw new ClientError('Variable not found', 'variable-not-found', {status: 404});
+  }
+  if (error instanceof UnknownSecretStoreError) {
+    throw new ClientError('Unknown secret store', 'unknown-secret-store', {status: 400});
+  }
+  if (error instanceof ProjectNotFoundError) {
+    throw new ClientError('Project not found', 'project-not-found', {status: 404});
+  }
+
+  throw error;
+}

package/src/presentation/routes/get-variable.ts

@@ -0,0 +1,32 @@
+import {
+  getVariableResponseSchema,
+  secretKeySchema,
+  secretScopeQuerySchema,
+} from '@shipfox/api-secrets-dto';
+import {defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {getManagedVariable} from '#core/index.js';
+import {toVariableDto} from '#presentation/dto/index.js';
+import {requireManagementRead} from './auth.js';
+import {translateManagementError} from './errors.js';
+
+export const getVariableRoute = defineRoute({
+  method: 'GET',
+  path: '/variables/:key',
+  description: 'Read a user-managed variable.',
+  schema: {
+    params: z.object({workspaceId: z.string().uuid(), key: secretKeySchema}),
+    querystring: secretScopeQuerySchema,
+    response: {200: getVariableResponseSchema},
+  },
+  errorHandler: translateManagementError,
+  handler: async (request) => {
+    const {workspaceId, key} = request.params;
+    const {project_id: projectId} = request.query;
+
+    await requireManagementRead({request, workspaceId, projectId});
+    const variable = await getManagedVariable({workspaceId, projectId, key});
+
+    return {variable: toVariableDto(variable)};
+  },
+});

package/src/presentation/routes/index.ts

@@ -0,0 +1,29 @@
+import {AUTH_USER} from '@shipfox/api-auth-context';
+import type {RouteGroup} from '@shipfox/node-fastify';
+import {batchSecretsRoute} from './batch-secrets.js';
+import {batchVariablesRoute} from './batch-variables.js';
+import {deleteSecretRoute} from './delete-secret.js';
+import {deleteVariableRoute} from './delete-variable.js';
+import {getVariableRoute} from './get-variable.js';
+import {listSecretsRoute} from './list-secrets.js';
+import {listVariablesRoute} from './list-variables.js';
+import {putSecretRoute} from './put-secret.js';
+import {putVariableRoute} from './put-variable.js';
+
+export const secretsRoutes: RouteGroup[] = [
+  {
+    prefix: '/workspaces/:workspaceId',
+    auth: AUTH_USER,
+    routes: [
+      listSecretsRoute,
+      putSecretRoute,
+      batchSecretsRoute,
+      deleteSecretRoute,
+      listVariablesRoute,
+      getVariableRoute,
+      putVariableRoute,
+      batchVariablesRoute,
+      deleteVariableRoute,
+    ],
+  },
+];

package/src/presentation/routes/list-secrets.ts

@@ -0,0 +1,41 @@
+import {listSecretsQuerySchema, listSecretsResponseSchema} from '@shipfox/api-secrets-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {listManagedSecrets} from '#core/index.js';
+import {toSecretDto} from '#presentation/dto/index.js';
+import {requireManagementRead} from './auth.js';
+import {decodeManagementCursor, encodeManagementCursor} from './cursor.js';
+import {translateManagementError} from './errors.js';
+
+export const listSecretsRoute = defineRoute({
+  method: 'GET',
+  path: '/secrets',
+  description: 'List user-managed secrets for a workspace or project scope.',
+  schema: {
+    params: z.object({workspaceId: z.string().uuid()}),
+    querystring: listSecretsQuerySchema,
+    response: {200: listSecretsResponseSchema},
+  },
+  errorHandler: translateManagementError,
+  handler: async (request) => {
+    const {workspaceId} = request.params;
+    const {project_id: projectId, limit, cursor} = request.query;
+    const decodedCursor = decodeManagementCursor(cursor);
+    if (cursor && !decodedCursor) {
+      throw new ClientError('Invalid cursor', 'invalid-cursor', {status: 400});
+    }
+
+    await requireManagementRead({request, workspaceId, projectId});
+    const result = await listManagedSecrets({
+      workspaceId,
+      projectId,
+      limit,
+      cursor: decodedCursor ?? undefined,
+    });
+
+    return {
+      secrets: result.secrets.map(toSecretDto),
+      next_cursor: result.nextCursor ? encodeManagementCursor(result.nextCursor) : null,
+    };
+  },
+});

package/src/presentation/routes/list-variables.ts

@@ -0,0 +1,41 @@
+import {listVariablesQuerySchema, listVariablesResponseSchema} from '@shipfox/api-secrets-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {listManagedVariables} from '#core/index.js';
+import {toVariableListItemDto} from '#presentation/dto/index.js';
+import {requireManagementRead} from './auth.js';
+import {decodeManagementCursor, encodeManagementCursor} from './cursor.js';
+import {translateManagementError} from './errors.js';
+
+export const listVariablesRoute = defineRoute({
+  method: 'GET',
+  path: '/variables',
+  description: 'List user-managed variables for a workspace or project scope.',
+  schema: {
+    params: z.object({workspaceId: z.string().uuid()}),
+    querystring: listVariablesQuerySchema,
+    response: {200: listVariablesResponseSchema},
+  },
+  errorHandler: translateManagementError,
+  handler: async (request) => {
+    const {workspaceId} = request.params;
+    const {project_id: projectId, limit, cursor} = request.query;
+    const decodedCursor = decodeManagementCursor(cursor);
+    if (cursor && !decodedCursor) {
+      throw new ClientError('Invalid cursor', 'invalid-cursor', {status: 400});
+    }
+
+    await requireManagementRead({request, workspaceId, projectId});
+    const result = await listManagedVariables({
+      workspaceId,
+      projectId,
+      limit,
+      cursor: decodedCursor ?? undefined,
+    });
+
+    return {
+      variables: result.variables.map(toVariableListItemDto),
+      next_cursor: result.nextCursor ? encodeManagementCursor(result.nextCursor) : null,
+    };
+  },
+});