@shipfox/api-workspaces 11.0.0 → 12.0.0

package/src/db/rate-limits.ts

@@ -0,0 +1,59 @@
+import {
+  type ConsumeRateLimitParams,
+  type ConsumeRateLimitResult,
+  createRateLimitPersistence,
+} from '@shipfox/node-rate-limit';
+import {lt, sql} from 'drizzle-orm';
+import {db} from './db.js';
+import {workspacesRateLimits} from './schema/rate-limits.js';
+
+type WorkspacesRateLimitTransaction = Parameters<
+  Parameters<ReturnType<typeof db>['transaction']>[0]
+>[0];
+
+const persistence = createRateLimitPersistence<WorkspacesRateLimitTransaction>({
+  transaction: (callback) => db().transaction(callback),
+  setStatementTimeout: async (transaction, timeoutMs) => {
+    await transaction.execute(
+      sql`select set_config('statement_timeout', ${`${timeoutMs}ms`}, true)`,
+    );
+  },
+  consume: async (transaction, params) => {
+    const rows = await transaction
+      .insert(workspacesRateLimits)
+      .values({
+        action: params.action,
+        scope: params.scope,
+        identifierHmac: params.identifierHmac,
+        windowStart: params.windowStart,
+        count: 1,
+        expiresAt: params.expiresAt,
+      })
+      .onConflictDoUpdate({
+        target: [
+          workspacesRateLimits.action,
+          workspacesRateLimits.scope,
+          workspacesRateLimits.identifierHmac,
+          workspacesRateLimits.windowStart,
+        ],
+        set: {
+          count: sql`${workspacesRateLimits.count} + 1`,
+          updatedAt: sql`now()`,
+        },
+      })
+      .returning({count: workspacesRateLimits.count, expiresAt: workspacesRateLimits.expiresAt});
+
+    return rows[0];
+  },
+  prune: async (now) => {
+    const result = await db()
+      .delete(workspacesRateLimits)
+      .where(lt(workspacesRateLimits.expiresAt, now));
+    return result.rowCount ?? 0;
+  },
+});
+
+export type ConsumeWorkspacesRateLimitParams = ConsumeRateLimitParams<string, string>;
+export type ConsumeWorkspacesRateLimitResult = ConsumeRateLimitResult;
+export const consumeWorkspacesRateLimit = persistence.consume;
+export const pruneExpiredWorkspacesRateLimits = persistence.prune;

package/src/db/schema/rate-limits.ts

@@ -0,0 +1,27 @@
+import {index, integer, text, timestamp, uniqueIndex} from 'drizzle-orm/pg-core';
+import {pgTable} from './common.js';
+
+export const workspacesRateLimits = pgTable(
+  'rate_limits',
+  {
+    action: text('action').notNull(),
+    scope: text('scope').notNull(),
+    identifierHmac: text('identifier_hmac').notNull(),
+    windowStart: timestamp('window_start', {withTimezone: true}).notNull(),
+    count: integer('count').notNull().default(1),
+    expiresAt: timestamp('expires_at', {withTimezone: true}).notNull(),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('workspaces_rate_limits_window_unique').on(
+      table.action,
+      table.scope,
+      table.identifierHmac,
+      table.windowStart,
+    ),
+    index('workspaces_rate_limits_expires_at_idx').on(table.expiresAt),
+  ],
+);
+
+export type WorkspaceRateLimitDb = typeof workspacesRateLimits.$inferSelect;

package/src/db/schema/workspaces.ts

@@ -1,5 +1,5 @@
 import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
-import {index, jsonb, pgEnum, text, timestamp, uuid} from 'drizzle-orm/pg-core';
+import {index, jsonb, pgEnum, text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
 import type {Workspace, WorkspaceStatus} from '#core/entities/workspace.js';
 import {pgTable} from './common.js';
 
@@ -14,13 +14,17 @@ export const workspaces = pgTable(
   {
     id: uuidv7PrimaryKey(),
     name: text('name').notNull(),
+    slug: text('slug').notNull(),
     status: workspaceStatusEnum('status').notNull().default('active'),
     settings: jsonb('settings').notNull().default({}),
     createdBy: uuid('created_by'),
     createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
     updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
   },
-  (table) => [index('workspaces_name_id_idx').on(table.name, table.id)],
+  (table) => [
+    index('workspaces_name_id_idx').on(table.name, table.id),
+    uniqueIndex('workspaces_slug_unique').on(table.slug),
+  ],
 );
 
 export type WorkspaceDb = typeof workspaces.$inferSelect;
@@ -30,6 +34,7 @@ export function toWorkspace(row: WorkspaceDb): Workspace {
   return {
     id: row.id,
     name: row.name,
+    slug: row.slug,
     status: row.status as WorkspaceStatus,
     settings: row.settings as Record<string, unknown>,
     createdBy: row.createdBy,

package/src/db/workspaces.ts

@@ -9,6 +9,8 @@ import {toWorkspace, workspaces} from './schema/workspaces.js';
 
 export interface CreateWorkspaceParams {
   name: string;
+  /** Existing database-only fixtures predate the required API slug. */
+  slug?: string | undefined;
 }
 
 export async function createWorkspace(params: CreateWorkspaceParams): Promise<Workspace> {
@@ -16,6 +18,7 @@ export async function createWorkspace(params: CreateWorkspaceParams): Promise<Wo
     .insert(workspaces)
     .values({
       name: params.name,
+      slug: params.slug ?? `workspace-${crypto.randomUUID().slice(0, 8)}`,
     })
     .returning();
 
@@ -28,19 +31,26 @@ export async function createWorkspace(params: CreateWorkspaceParams): Promise<Wo
 export interface UpdateWorkspaceParams {
   id: string;
   name?: string | undefined;
+  slug?: string | undefined;
   status?: WorkspaceStatus | undefined;
   settings?: Record<string, unknown> | undefined;
 }
 
+type WorkspaceDatabase = ReturnType<typeof db>;
+type WorkspaceTransaction = Parameters<Parameters<WorkspaceDatabase['transaction']>[0]>[0];
+
 export async function updateWorkspace(
   params: UpdateWorkspaceParams,
+  options: {tx?: WorkspaceDatabase | WorkspaceTransaction | undefined} = {},
 ): Promise<Workspace | undefined> {
+  const executor = options.tx ?? db();
   const set: Record<string, unknown> = {updatedAt: sql`NOW()`};
   if (params.name !== undefined) set.name = params.name;
+  if (params.slug !== undefined) set.slug = params.slug;
   if (params.status !== undefined) set.status = params.status;
   if (params.settings !== undefined) set.settings = params.settings;
 
-  const rows = await db()
+  const rows = await executor
     .update(workspaces)
     .set(set)
     .where(eq(workspaces.id, params.id))
@@ -58,6 +68,16 @@ export async function getWorkspaceById(id: string): Promise<Workspace | undefine
   return toWorkspace(row);
 }
 
+export async function isWorkspaceSlugAvailable(slug: string): Promise<boolean> {
+  const rows = await db()
+    .select({id: workspaces.id})
+    .from(workspaces)
+    .where(eq(workspaces.slug, slug))
+    .limit(1);
+
+  return rows.length === 0;
+}
+
 export interface AdminWorkspaceRow extends Workspace {
   memberCount: number;
 }

package/src/index.test.ts

@@ -4,6 +4,7 @@ import {
   WORKSPACES_MEMBER_INVITED,
   WORKSPACES_MEMBER_JOINED,
   WORKSPACES_WORKSPACE_CREATED,
+  WORKSPACES_WORKSPACE_UPDATED,
   workspacesEventSchemas,
 } from '@shipfox/api-workspaces-dto';
 import {workspacesModule} from './index.js';
@@ -27,6 +28,7 @@ describe('workspacesModule', () => {
     expect(Object.keys(publisher?.eventSchemas ?? {})).toEqual([
       WORKSPACES_INVITATION_SEND_REQUESTED,
       WORKSPACES_WORKSPACE_CREATED,
+      WORKSPACES_WORKSPACE_UPDATED,
       WORKSPACES_MEMBER_INVITED,
       WORKSPACES_MEMBER_JOINED,
       ADMINISTRATION_ACTION_PERFORMED,

package/src/index.ts

@@ -25,6 +25,7 @@ export {
   TokenExpiredError,
   TokenInvalidError,
   WorkspaceNotFoundError,
+  WorkspaceSlugConflictError,
 } from '#core/errors.js';
 export {
   acceptWorkspaceInvitation,

package/src/metrics/instance.ts

@@ -3,6 +3,7 @@ import {instanceMetrics} from '@shipfox/node-opentelemetry';
 export type WorkspacesInvitationEmailRequested = 'requested' | 'skipped';
 export type WorkspacesMembershipChangeAction = 'added' | 'removed';
 export type WorkspacesInvitationAcceptOutcome = 'added' | 'already_member';
+export type WorkspacesRateLimitOutcome = 'allowed' | 'blocked' | 'unavailable';
 
 const meter = instanceMetrics.getMeter('workspaces');
 
@@ -28,6 +29,20 @@ const invitationAcceptedCount = meter.createCounter<{
   description: 'Workspace invitations accepted by membership outcome',
 });
 
+const workspaceRateLimitCheckCount = meter.createCounter<{
+  action: 'slug-availability';
+  outcome: WorkspacesRateLimitOutcome;
+}>('workspaces_rate_limit_checks', {
+  description: 'Workspace rate-limit checks by action and outcome',
+});
+
+const workspaceRateLimitPruneFailureCount = meter.createCounter(
+  'workspaces_rate_limit_prune_failures',
+  {
+    description: 'Workspace rate-limit prune failures',
+  },
+);
+
 function recordMetric(record: () => void): void {
   try {
     record();
@@ -55,3 +70,14 @@ export function recordWorkspaceInvitationAccepted(
 ): void {
   recordMetric(() => invitationAcceptedCount.add(1, {outcome}));
 }
+
+export function recordWorkspaceRateLimitCheck(params: {
+  action: 'slug-availability';
+  outcome: WorkspacesRateLimitOutcome;
+}): void {
+  recordMetric(() => workspaceRateLimitCheckCount.add(1, params));
+}
+
+export function recordWorkspaceRateLimitPruneFailure(): void {
+  recordMetric(() => workspaceRateLimitPruneFailureCount.add(1));
+}

package/src/presentation/dto/membership.ts

@@ -9,6 +9,7 @@ export function toMembershipWithWorkspaceDto(
     user_id: membership.userId,
     workspace_id: membership.workspaceId,
     workspace_name: membership.workspaceName,
+    workspace_slug: membership.workspaceSlug,
     workspace_status: membership.workspaceStatus,
     created_at: membership.createdAt.toISOString(),
     updated_at: membership.updatedAt.toISOString(),

package/src/presentation/dto/workspace.ts

@@ -5,6 +5,7 @@ export function toWorkspaceDto(workspace: Workspace): WorkspaceDto {
   return {
     id: workspace.id,
     name: workspace.name,
+    slug: workspace.slug,
     status: workspace.status,
     settings: workspace.settings,
     created_at: workspace.createdAt.toISOString(),

package/src/presentation/e2eRoutes/create-workspace.ts

@@ -2,7 +2,8 @@ import {
   e2eCreateWorkspaceBodySchema,
   e2eCreateWorkspaceResponseSchema,
 } from '@shipfox/api-workspaces-dto';
-import {defineRoute} from '@shipfox/node-fastify';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {WorkspaceSlugConflictError} from '#core/errors.js';
 import {createWorkspaceForUser} from '#core/index.js';
 import {toWorkspaceDto} from '#presentation/dto/index.js';
 
@@ -16,9 +17,16 @@ export const createE2eWorkspaceRoute = defineRoute({
       201: e2eCreateWorkspaceResponseSchema,
     },
   },
+  errorHandler: (error) => {
+    if (error instanceof WorkspaceSlugConflictError) {
+      throw new ClientError('Workspace slug is already taken', 'slug-conflict', {status: 409});
+    }
+    throw error;
+  },
   handler: async (request, reply) => {
     const workspace = await createWorkspaceForUser({
       name: request.body.name,
+      slug: request.body.slug ?? `e2e-workspace-${crypto.randomUUID().slice(0, 8)}`,
       userId: request.body.user_id,
       userEmail: request.body.user_email,
       userName: request.body.user_name,

package/src/presentation/inter-module.test.ts

@@ -21,6 +21,7 @@ describe('Workspaces inter-module presentation', () => {
     const creatorUserId = crypto.randomUUID();
     const workspace = await createWorkspaceForUser({
       name: 'Creator Workspace',
+      slug: `creator-${crypto.randomUUID().slice(0, 8)}`,
       userId: creatorUserId,
     });
     await createMembership({workspaceId: workspace.id, userId: crypto.randomUUID()});
@@ -35,6 +36,7 @@ describe('Workspaces inter-module presentation', () => {
     const creatorUserId = crypto.randomUUID();
     const workspace = await createWorkspaceForUser({
       name: 'Outlasted Creator Workspace',
+      slug: `outlasted-${crypto.randomUUID().slice(0, 8)}`,
       userId: creatorUserId,
     });
     const remainingUserId = crypto.randomUUID();
@@ -58,9 +60,21 @@ describe('Workspaces inter-module presentation', () => {
   test('carries workspace status into token claims', async () => {
     const client = createClient();
     const userId = crypto.randomUUID();
-    const active = await createWorkspaceForUser({name: 'Active Workspace', userId});
-    const suspended = await createWorkspaceForUser({name: 'Suspended Workspace', userId});
-    const deleted = await createWorkspaceForUser({name: 'Deleted Workspace', userId});
+    const active = await createWorkspaceForUser({
+      name: 'Active Workspace',
+      slug: `active-${crypto.randomUUID().slice(0, 8)}`,
+      userId,
+    });
+    const suspended = await createWorkspaceForUser({
+      name: 'Suspended Workspace',
+      slug: `suspended-${crypto.randomUUID().slice(0, 8)}`,
+      userId,
+    });
+    const deleted = await createWorkspaceForUser({
+      name: 'Deleted Workspace',
+      slug: `deleted-${crypto.randomUUID().slice(0, 8)}`,
+      userId,
+    });
     await updateWorkspace({id: suspended.id, status: 'suspended'});
     await updateWorkspace({id: deleted.id, status: 'deleted'});
 
@@ -86,7 +100,11 @@ describe('Workspaces inter-module presentation', () => {
   test('preserves suspended-workspace access errors through the claim boundary', async () => {
     const client = createClient();
     const userId = crypto.randomUUID();
-    const workspace = await createWorkspaceForUser({name: 'Suspended Access Workspace', userId});
+    const workspace = await createWorkspaceForUser({
+      name: 'Suspended Access Workspace',
+      slug: `suspended-access-${crypto.randomUUID().slice(0, 8)}`,
+      userId,
+    });
     await updateWorkspace({id: workspace.id, status: 'suspended'});
 
     const claims = await client.listMembershipsForTokenClaims({userId});

package/src/presentation/routes/index.ts

@@ -5,7 +5,12 @@ import type {RouteGroup} from '@shipfox/node-fastify';
 import {createAdminWorkspacesRoutes} from './admin-workspaces.js';
 import {invitationsAcceptGroup, invitationsWorkspaceScopedRoutes} from './invitations/index.js';
 import {memberRoutes} from './members/index.js';
-import {createWorkspaceRoute, listUserWorkspacesRoute} from './workspaces/index.js';
+import {
+  createWorkspaceRoute,
+  listUserWorkspacesRoute,
+  updateWorkspaceRoute,
+  workspaceSlugAvailabilityRoute,
+} from './workspaces/index.js';
 
 export const workspacesRoutes: RouteGroup[] = [
   invitationsAcceptGroup,
@@ -14,6 +19,8 @@ export const workspacesRoutes: RouteGroup[] = [
     routes: [
       listUserWorkspacesRoute,
       createWorkspaceRoute,
+      workspaceSlugAvailabilityRoute,
+      updateWorkspaceRoute,
       {
         prefix: '/:workspaceId/members',
         routes: memberRoutes,

package/src/presentation/routes/rate-limit.ts

@@ -0,0 +1,45 @@
+import {ClientError, type FastifyReply, type FastifyRequest} from '@shipfox/node-fastify';
+import {enforceRateLimit as enforceSharedRateLimit} from '@shipfox/node-rate-limit';
+import {
+  checkWorkspacesRateLimit,
+  WORKSPACE_SLUG_AVAILABILITY_RATE_LIMIT,
+} from '#core/rate-limit.js';
+
+function routeName(request: FastifyRequest): string {
+  return request.routeOptions.url ?? request.url.split('?')[0] ?? 'unknown';
+}
+
+export function createWorkspaceSlugAvailabilityRateLimitPreHandler() {
+  return async (request: FastifyRequest, reply: FastifyReply): Promise<void> => {
+    await enforceSharedRateLimit({
+      request,
+      reply,
+      check: () =>
+        checkWorkspacesRateLimit({
+          action: 'slug-availability',
+          scope: 'ip',
+          identifier: request.ip,
+          ...WORKSPACE_SLUG_AVAILABILITY_RATE_LIMIT,
+        }),
+      route: routeName(request),
+      unavailableCode: 'workspace-rate-limit-unavailable',
+      unavailableMessage: 'Workspace rate limiter unavailable',
+      setRetryAfter: (reply, retryAfterSeconds) => {
+        reply.header('Retry-After', String(retryAfterSeconds));
+      },
+      logWarn: (request, context) => {
+        request.log.warn(context, 'Workspace rate limit blocked request');
+      },
+      logError: (request, context) => {
+        request.log.error(context, 'Workspace rate limiter unavailable');
+      },
+      createClientError: (presentation, cause) =>
+        new ClientError(presentation.message, presentation.code, {
+          status: presentation.status,
+          ...(presentation.details ? {details: presentation.details} : {}),
+          data: presentation.data,
+          cause,
+        }),
+    });
+  };
+}

package/src/presentation/routes/workspaces/create.test.ts

@@ -47,13 +47,14 @@ describe('POST /workspaces', () => {
     const res = await app.inject({
       method: 'POST',
       url: '/workspaces',
-      payload: {name: '  Test Workspace  '},
+      payload: {name: '  Test Workspace  ', slug: 'test-workspace'},
     });
 
     expect(res.statusCode).toBe(201);
     const body = res.json();
     expect(body.id).toBeDefined();
     expect(body.name).toBe('Test Workspace');
+    expect(body.slug).toBe('test-workspace');
     expect(body.status).toBe('active');
 
     const membership = await findMembership({userId, workspaceId: body.id});
@@ -69,7 +70,7 @@ describe('POST /workspaces', () => {
     const res = await app.inject({
       method: 'POST',
       url: '/workspaces',
-      payload: {name},
+      payload: {name, slug: 'test-workspace'},
     });
 
     expect(res.statusCode).toBe(400);
@@ -79,9 +80,38 @@ describe('POST /workspaces', () => {
     const res = await app.inject({
       method: 'POST',
       url: '/workspaces',
-      payload: {},
+      payload: {slug: 'test-workspace'},
     });
 
     expect(res.statusCode).toBe(400);
   });
+
+  test('accepts a workspace slugged settings', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/workspaces',
+      payload: {name: 'Settings Workspace', slug: 'settings'},
+    });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json().slug).toBe('settings');
+  });
+
+  test('returns slug-conflict for a duplicate slug', async () => {
+    const slug = `duplicate-${crypto.randomUUID().slice(0, 8)}`;
+    const first = await app.inject({
+      method: 'POST',
+      url: '/workspaces',
+      payload: {name: 'First Workspace', slug},
+    });
+    const second = await app.inject({
+      method: 'POST',
+      url: '/workspaces',
+      payload: {name: 'Second Workspace', slug},
+    });
+
+    expect(first.statusCode).toBe(201);
+    expect(second.statusCode).toBe(409);
+    expect(second.json().code).toBe('slug-conflict');
+  });
 });

package/src/presentation/routes/workspaces/create.ts

@@ -1,6 +1,7 @@
 import {AUTH_USER, getUserContext} from '@shipfox/api-auth-context';
 import {createWorkspaceBodySchema, workspaceResponseSchema} from '@shipfox/api-workspaces-dto';
 import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {WorkspaceSlugConflictError} from '#core/errors.js';
 import {createWorkspaceForUser} from '#core/index.js';
 import {toWorkspaceDto} from '#presentation/dto/index.js';
 
@@ -15,16 +16,23 @@ export const createWorkspaceRoute = defineRoute({
       201: workspaceResponseSchema,
     },
   },
+  errorHandler: (error) => {
+    if (error instanceof WorkspaceSlugConflictError) {
+      throw new ClientError('Workspace slug is already taken', 'slug-conflict', {status: 409});
+    }
+    throw error;
+  },
   handler: async (request, reply) => {
     const client = getUserContext(request);
     if (!client) {
       throw new ClientError('Authentication required', 'unauthorized', {status: 401});
     }
 
-    const {name} = request.body;
+    const {name, slug} = request.body;
 
     const workspace = await createWorkspaceForUser({
       name,
+      slug,
       userId: client.userId,
       userEmail: client.email,
       userName: client.name,

package/src/presentation/routes/workspaces/index.ts

@@ -1,2 +1,4 @@
 export {createWorkspaceRoute} from './create.js';
 export {listUserWorkspacesRoute} from './list.js';
+export {workspaceSlugAvailabilityRoute} from './slug-availability.js';
+export {updateWorkspaceRoute} from './update.js';

package/src/presentation/routes/workspaces/list.test.ts

@@ -49,6 +49,7 @@ describe('GET /workspaces', () => {
           user_id: userId,
           workspace_id: workspace.id,
           workspace_name: 'Acme',
+          workspace_slug: workspace.slug,
         },
       ],
     });