@shipfox/api-workspaces 10.1.0 → 10.2.0

package/src/presentation/routes/admin-workspaces.test.ts

@@ -3,17 +3,30 @@ import {
   type AuthInterModuleClient,
   authInterModuleContract,
 } from '@shipfox/api-auth-dto/inter-module';
+import {ADMINISTRATION_ACTION_PERFORMED} from '@shipfox/api-common-dto';
 import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module';
 import type {RunnersInterModuleClient} from '@shipfox/api-runners-dto/inter-module';
 import {createInterModuleKnownError} from '@shipfox/inter-module';
 import {type AuthMethod, closeApp, createApp} from '@shipfox/node-fastify';
+import {eq, sql} from 'drizzle-orm';
 import type {FastifyInstance, FastifyRequest} from 'fastify';
-import {createMembership} from '#db/memberships.js';
-import {createWorkspace} from '#db/workspaces.js';
+import {db} from '#db/db.js';
+import {createInvitation, listOpenInvitationsByWorkspace} from '#db/invitations.js';
+import {createMembership, listMembershipsByWorkspace} from '#db/memberships.js';
+import {workspacesAdminCommandResults} from '#db/schema/admin-command-results.js';
+import {workspacesOutbox} from '#db/schema/outbox.js';
+import {createWorkspace, getWorkspaceById, updateWorkspace} from '#db/workspaces.js';
 import {createAdminWorkspacesRoutes} from './admin-workspaces.js';
 
 const USER_ID = '11111111-1111-4111-8111-111111111111';
 
+function adminHeaders(idempotencyKey: string) {
+  return {
+    authorization: 'Bearer user',
+    'idempotency-key': idempotencyKey,
+  };
+}
+
 const fakeUserAuth: AuthMethod = {
   name: AUTH_USER,
   authenticate: (request: FastifyRequest) => {
@@ -33,8 +46,13 @@ describe('GET /admin/workspaces', () => {
 
   beforeEach(async () => {
     await closeApp();
+    await db().execute(
+      sql`TRUNCATE workspaces_admin_command_results, workspaces_outbox, workspaces_workspaces CASCADE`,
+    );
     auth = {
-      requireAdminRole: vi.fn().mockResolvedValue({role: 'admin-observer'}),
+      requireAdminRole: vi
+        .fn()
+        .mockImplementation(({minimumRole}) => Promise.resolve({role: minimumRole})),
     } as unknown as AuthInterModuleClient;
     projects = {
       getWorkspaceProjectCounts: vi.fn().mockResolvedValue({counts: []}),
@@ -92,6 +110,258 @@ describe('GET /admin/workspaces', () => {
     });
   });
 
+  test('suspends a workspace without deleting its data and writes one redacted event', async () => {
+    const workspace = await createWorkspace({name: `Suspend ${crypto.randomUUID()}`});
+    await updateWorkspace({id: workspace.id, settings: {retained: true}});
+    await createMembership({userId: crypto.randomUUID(), workspaceId: workspace.id});
+    await createInvitation({
+      workspaceId: workspace.id,
+      email: `pending-${crypto.randomUUID()}@example.com`,
+      hashedToken: crypto.randomUUID(),
+      expiresAt: new Date(Date.now() + 60_000),
+      invitedByUserId: USER_ID,
+      skipEmail: true,
+    });
+
+    const response = await app.inject({
+      method: 'POST',
+      url: `/admin/workspaces/${workspace.id}/suspend`,
+      headers: adminHeaders('suspend-workspace'),
+      payload: {reason: 'Requested by support'},
+    });
+
+    expect(response.statusCode).toBe(200);
+    const body = response.json();
+    expect(body).toMatchObject({workspace_id: workspace.id, status: 'suspended'});
+    expect(body.correlation_id).toEqual(expect.any(String));
+    await expect(getWorkspaceById(workspace.id)).resolves.toMatchObject({
+      id: workspace.id,
+      status: 'suspended',
+      settings: {retained: true},
+    });
+    await expect(listMembershipsByWorkspace({workspaceId: workspace.id})).resolves.toHaveLength(1);
+    await expect(listOpenInvitationsByWorkspace({workspaceId: workspace.id})).resolves.toHaveLength(
+      1,
+    );
+
+    const events = await db()
+      .select()
+      .from(workspacesOutbox)
+      .where(eq(workspacesOutbox.eventType, ADMINISTRATION_ACTION_PERFORMED));
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      eventType: ADMINISTRATION_ACTION_PERFORMED,
+      payload: {
+        actorId: USER_ID,
+        actorRole: 'admin-operator',
+        requiredRole: 'admin-operator',
+        command: 'workspace.suspend',
+        targetType: 'workspace',
+        targetId: workspace.id,
+        reason: 'Requested by support',
+        result: 'succeeded',
+        correlationId: body.correlation_id,
+      },
+    });
+    expect(events[0]?.payload).not.toHaveProperty('idempotencyKey');
+    await expect(
+      db()
+        .select()
+        .from(workspacesAdminCommandResults)
+        .where(eq(workspacesAdminCommandResults.actorId, USER_ID)),
+    ).resolves.toHaveLength(1);
+  });
+
+  test('returns the committed suspension result on an idempotent retry', async () => {
+    const workspace = await createWorkspace({name: `Retry ${crypto.randomUUID()}`});
+    const first = await app.inject({
+      method: 'POST',
+      url: `/admin/workspaces/${workspace.id}/suspend`,
+      headers: adminHeaders('retry-workspace-suspend'),
+      payload: {reason: 'Retry test'},
+    });
+    const retry = await app.inject({
+      method: 'POST',
+      url: `/admin/workspaces/${workspace.id}/suspend`,
+      headers: adminHeaders('retry-workspace-suspend'),
+      payload: {reason: 'Retry test'},
+    });
+
+    expect(first.statusCode).toBe(200);
+    expect(retry.statusCode).toBe(200);
+    expect(retry.json()).toEqual(first.json());
+    await expect(
+      db()
+        .select()
+        .from(workspacesAdminCommandResults)
+        .where(eq(workspacesAdminCommandResults.actorId, USER_ID)),
+    ).resolves.toHaveLength(1);
+    await expect(
+      db()
+        .select()
+        .from(workspacesOutbox)
+        .where(eq(workspacesOutbox.eventType, ADMINISTRATION_ACTION_PERFORMED)),
+    ).resolves.toHaveLength(1);
+  });
+
+  test('reactivates a suspended workspace while preserving its membership', async () => {
+    const workspace = await createWorkspace({name: `Reactivate ${crypto.randomUUID()}`});
+    await createMembership({userId: crypto.randomUUID(), workspaceId: workspace.id});
+
+    const suspended = await app.inject({
+      method: 'POST',
+      url: `/admin/workspaces/${workspace.id}/suspend`,
+      headers: adminHeaders('reactivation-suspend'),
+      payload: {reason: 'Temporary suspension'},
+    });
+    const reactivated = await app.inject({
+      method: 'POST',
+      url: `/admin/workspaces/${workspace.id}/reactivate`,
+      headers: adminHeaders('reactivation-reactivate'),
+      payload: {reason: 'Issue resolved'},
+    });
+
+    expect(suspended.statusCode).toBe(200);
+    expect(reactivated.statusCode).toBe(200);
+    expect(reactivated.json()).toMatchObject({workspace_id: workspace.id, status: 'active'});
+    await expect(getWorkspaceById(workspace.id)).resolves.toMatchObject({status: 'active'});
+    await expect(listMembershipsByWorkspace({workspaceId: workspace.id})).resolves.toHaveLength(1);
+    await expect(
+      db()
+        .select()
+        .from(workspacesOutbox)
+        .where(eq(workspacesOutbox.eventType, ADMINISTRATION_ACTION_PERFORMED)),
+    ).resolves.toHaveLength(2);
+  });
+
+  test('rejects reusing an idempotency key for another workspace command', async () => {
+    const workspace = await createWorkspace({name: `Reuse ${crypto.randomUUID()}`});
+    const suspended = await app.inject({
+      method: 'POST',
+      url: `/admin/workspaces/${workspace.id}/suspend`,
+      headers: adminHeaders('reused-workspace-key'),
+      payload: {reason: 'Reuse test'},
+    });
+    const reused = await app.inject({
+      method: 'POST',
+      url: `/admin/workspaces/${workspace.id}/reactivate`,
+      headers: adminHeaders('reused-workspace-key'),
+      payload: {reason: 'Reuse test'},
+    });
+
+    expect(suspended.statusCode).toBe(200);
+    expect(reused.statusCode).toBe(409);
+    expect(reused.json()).toMatchObject({code: 'idempotency-key-reused'});
+    await expect(getWorkspaceById(workspace.id)).resolves.toMatchObject({status: 'suspended'});
+  });
+
+  test.each([
+    ['missing', undefined],
+    ['blank', '   '],
+    ['oversized', 'x'.repeat(257)],
+  ])('requires an idempotency key when it is %s', async (_case, idempotencyKey) => {
+    const workspace = await createWorkspace({name: `Key ${crypto.randomUUID()}`});
+    const response = await app.inject({
+      method: 'POST',
+      url: `/admin/workspaces/${workspace.id}/suspend`,
+      headers: {
+        authorization: 'Bearer user',
+        ...(idempotencyKey === undefined ? {} : {'idempotency-key': idempotencyKey}),
+      },
+      payload: {reason: 'Missing key test'},
+    });
+
+    expect(response.statusCode).toBe(400);
+    expect(response.json().code).toBe('idempotency-key-required');
+  });
+
+  test.each([
+    ['empty', ''],
+    ['oversized', 'x'.repeat(513)],
+    ['control character', 'Reason\nwith control'],
+    ['format character', 'Reason\u202ewith format character'],
+  ])('rejects a %s administration reason', async (_case, reason) => {
+    const workspace = await createWorkspace({name: `Reason ${crypto.randomUUID()}`});
+    const response = await app.inject({
+      method: 'POST',
+      url: `/admin/workspaces/${workspace.id}/suspend`,
+      headers: adminHeaders(`invalid-reason-${crypto.randomUUID()}`),
+      payload: {reason},
+    });
+
+    expect(response.statusCode).toBe(400);
+  });
+
+  test('returns not found for an unknown workspace', async () => {
+    const response = await app.inject({
+      method: 'POST',
+      url: `/admin/workspaces/${crypto.randomUUID()}/suspend`,
+      headers: adminHeaders('unknown-workspace'),
+      payload: {reason: 'Unknown workspace test'},
+    });
+
+    expect(response.statusCode).toBe(404);
+    expect(response.json().code).toBe('workspace-not-found');
+  });
+
+  test('rejects suspending an already suspended workspace with a fresh key', async () => {
+    const workspace = await createWorkspace({name: `Already suspended ${crypto.randomUUID()}`});
+    const first = await app.inject({
+      method: 'POST',
+      url: `/admin/workspaces/${workspace.id}/suspend`,
+      headers: adminHeaders('already-suspended-first'),
+      payload: {reason: 'First suspension'},
+    });
+    const second = await app.inject({
+      method: 'POST',
+      url: `/admin/workspaces/${workspace.id}/suspend`,
+      headers: adminHeaders('already-suspended-second'),
+      payload: {reason: 'Second suspension'},
+    });
+
+    expect(first.statusCode).toBe(200);
+    expect(second.statusCode).toBe(409);
+    expect(second.json().code).toBe('workspace-already-suspended');
+  });
+
+  test('rejects reactivating an active workspace', async () => {
+    const workspace = await createWorkspace({name: `Already active ${crypto.randomUUID()}`});
+    const response = await app.inject({
+      method: 'POST',
+      url: `/admin/workspaces/${workspace.id}/reactivate`,
+      headers: adminHeaders('already-active-reactivate'),
+      payload: {reason: 'Already active test'},
+    });
+
+    expect(response.statusCode).toBe(409);
+    expect(response.json().code).toBe('workspace-not-suspended');
+  });
+
+  test('rejects mutating a deleted workspace', async () => {
+    const workspace = await createWorkspace({name: `Deleted ${crypto.randomUUID()}`});
+    await updateWorkspace({id: workspace.id, status: 'deleted'});
+    const response = await app.inject({
+      method: 'POST',
+      url: `/admin/workspaces/${workspace.id}/suspend`,
+      headers: adminHeaders('deleted-workspace'),
+      payload: {reason: 'Deleted workspace test'},
+    });
+
+    expect(response.statusCode).toBe(409);
+    expect(response.json().code).toBe('workspace-deleted');
+  });
+
+  test('does not expose a versioned administration namespace', async () => {
+    const response = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/workspaces/00000000-0000-4000-8000-000000000001/suspend',
+      headers: adminHeaders('versioned-route'),
+      payload: {reason: 'Should not route'},
+    });
+
+    expect(response.statusCode).toBe(404);
+  });
+
   test('returns explicit unknown job counts when the supporting lookup fails', async () => {
     const workspace = await createWorkspace({name: `Unknown jobs ${crypto.randomUUID()}`});
     vi.mocked(projects.getWorkspaceProjectCounts).mockResolvedValue({

package/src/presentation/routes/admin-workspaces.ts

@@ -7,15 +7,107 @@ import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module'
 import type {RunnersInterModuleClient} from '@shipfox/api-runners-dto/inter-module';
 import {
   listWorkspaceAdminSummariesResponseSchema,
+  workspaceAdministrationMutationBodySchema,
+  workspaceAdministrationMutationResponseSchema,
   workspaceAdminLookupQuerySchema,
 } from '@shipfox/api-workspaces-dto';
 import {isInterModuleKnownError} from '@shipfox/inter-module';
 import {decodeStringIdCursor, encodeStringIdCursor} from '@shipfox/node-drizzle';
 import {ClientError, defineRoute, type RouteGroup} from '@shipfox/node-fastify';
+import type {FastifyRequest} from 'fastify';
+import {z} from 'zod';
 import {
   listWorkspaceAdministratorSummaries,
+  reactivateWorkspace,
+  suspendWorkspace,
+  type WorkspaceAdministrationMutationContext,
   type WorkspaceAdministratorSummary,
 } from '#core/admin-workspaces.js';
+import {
+  WorkspaceAdminIdempotencyKeyReuseError,
+  WorkspaceAlreadySuspendedError,
+  WorkspaceDeletedError,
+  WorkspaceNotFoundError,
+  WorkspaceNotSuspendedError,
+} from '#core/errors.js';
+
+const idempotencyKeyMaxLength = 256;
+
+function requireActorId(request: FastifyRequest): string {
+  const client = getUserContext(request);
+  if (!client) {
+    throw new ClientError('Authentication required', 'unauthorized', {status: 401});
+  }
+  return client.userId;
+}
+
+function requireIdempotencyKey(request: FastifyRequest): string {
+  const value = request.headers['idempotency-key'];
+  const key = Array.isArray(value) ? value[0] : value;
+  if (!key || key.trim().length === 0 || key.length > idempotencyKeyMaxLength) {
+    throw new ClientError('Idempotency-Key header is required', 'idempotency-key-required', {
+      status: 400,
+    });
+  }
+  return key;
+}
+
+function translateAdminRoleError(error: unknown, message: string): void {
+  if (
+    isInterModuleKnownError(authInterModuleContract.methods.requireAdminRole, error) &&
+    error.code === 'admin-role-required'
+  ) {
+    throw new ClientError(message, 'forbidden', {
+      status: 403,
+      details: {required_role: error.details.requiredRole},
+    });
+  }
+}
+
+function translateAdministrationError(error: unknown): never {
+  translateAdminRoleError(error, 'Administrator operator role required');
+  if (error instanceof WorkspaceNotFoundError) {
+    throw new ClientError('Workspace not found', 'workspace-not-found', {status: 404});
+  }
+  if (error instanceof WorkspaceDeletedError) {
+    throw new ClientError('Workspace is deleted', 'workspace-deleted', {status: 409});
+  }
+  if (error instanceof WorkspaceAlreadySuspendedError) {
+    throw new ClientError('Workspace is already suspended', 'workspace-already-suspended', {
+      status: 409,
+    });
+  }
+  if (error instanceof WorkspaceNotSuspendedError) {
+    throw new ClientError('Workspace is not suspended', 'workspace-not-suspended', {
+      status: 409,
+    });
+  }
+  if (error instanceof WorkspaceAdminIdempotencyKeyReuseError) {
+    throw new ClientError(
+      'Idempotency-Key was already used for a different workspace command',
+      'idempotency-key-reused',
+      {status: 409},
+    );
+  }
+  throw error;
+}
+
+function translateObserverAdministrationError(error: unknown): never {
+  translateAdminRoleError(error, 'Administrator observer role required');
+  throw error;
+}
+
+function toWorkspaceAdministrationMutationDto(result: {
+  workspaceId: string;
+  status: 'active' | 'suspended';
+  correlationId: string;
+}) {
+  return {
+    workspace_id: result.workspaceId,
+    status: result.status,
+    correlation_id: result.correlationId,
+  };
+}
 
 function toWorkspaceAdministratorSummaryDto(summary: WorkspaceAdministratorSummary) {
   return {
@@ -44,18 +136,7 @@ export function createAdminWorkspacesRoutes(params: {
       querystring: workspaceAdminLookupQuerySchema,
       response: {200: listWorkspaceAdminSummariesResponseSchema},
     },
-    errorHandler: (error) => {
-      if (
-        isInterModuleKnownError(authInterModuleContract.methods.requireAdminRole, error) &&
-        error.code === 'admin-role-required'
-      ) {
-        throw new ClientError('Administrator observer role required', 'forbidden', {
-          status: 403,
-          details: {required_role: error.details.requiredRole},
-        });
-      }
-      throw error;
-    },
+    errorHandler: translateObserverAdministrationError,
     handler: async (request) => {
       const client = getUserContext(request);
       if (!client) {
@@ -89,5 +170,54 @@ export function createAdminWorkspacesRoutes(params: {
     },
   });
 
-  return {prefix: '/admin/workspaces', routes: [listRoute]};
+  const createMutationRoute = (routeParams: {
+    action: 'suspend' | 'reactivate';
+    description: string;
+    execute: (context: WorkspaceAdministrationMutationContext) => Promise<{
+      workspaceId: string;
+      status: 'active' | 'suspended';
+      correlationId: string;
+    }>;
+  }) =>
+    defineRoute({
+      method: 'POST',
+      path: `/:workspaceId/${routeParams.action}`,
+      description: routeParams.description,
+      auth: AUTH_USER,
+      schema: {
+        params: z.object({workspaceId: z.string().uuid()}),
+        body: workspaceAdministrationMutationBodySchema,
+        response: {200: workspaceAdministrationMutationResponseSchema},
+      },
+      errorHandler: translateAdministrationError,
+      handler: async (request) => {
+        const actorId = requireActorId(request);
+        const actorRole = (
+          await params.auth.requireAdminRole({userId: actorId, minimumRole: 'admin-operator'})
+        ).role;
+        return toWorkspaceAdministrationMutationDto(
+          await routeParams.execute({
+            actorId,
+            actorRole,
+            workspaceId: request.params.workspaceId,
+            reason: request.body.reason,
+            idempotencyKey: requireIdempotencyKey(request),
+            correlationId: request.id,
+          }),
+        );
+      },
+    });
+
+  const suspendRoute = createMutationRoute({
+    action: 'suspend',
+    description: 'Suspend a workspace for reversible administrator moderation.',
+    execute: suspendWorkspace,
+  });
+  const reactivateRoute = createMutationRoute({
+    action: 'reactivate',
+    description: 'Reactivate a suspended workspace.',
+    execute: reactivateWorkspace,
+  });
+
+  return {prefix: '/admin/workspaces', routes: [listRoute, suspendRoute, reactivateRoute]};
 }

package/test/globalSetup.ts

@@ -8,7 +8,9 @@ export async function setup() {
   createPostgresClient();
 
   await runMigrations(db(), migrationsPath, '__drizzle_migrations_workspaces');
-  await db().execute(sql`TRUNCATE workspaces_outbox, workspaces_workspaces CASCADE`);
+  await db().execute(
+    sql`TRUNCATE workspaces_admin_command_results, workspaces_outbox, workspaces_workspaces CASCADE`,
+  );
 
   closeDb();
   await closePostgresClient();