@shipfox/api-workspaces 11.0.0 → 12.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-workspaces",
   "license": "MIT",
-  "version": "11.0.0",
+  "version": "12.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -24,22 +24,24 @@
   "dependencies": {
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
-    "@shipfox/api-common-dto": "9.2.0",
-    "@shipfox/api-auth-context": "11.0.0",
-    "@shipfox/api-auth-dto": "10.2.0",
-    "@shipfox/api-projects-dto": "10.1.0",
-    "@shipfox/api-runners-dto": "10.2.0",
-    "@shipfox/api-workspaces-dto": "11.0.0",
+    "@shipfox/api-common-dto": "12.0.0",
+    "@shipfox/api-auth-dto": "12.0.0",
+    "@shipfox/api-projects-dto": "12.2.0",
+    "@shipfox/api-auth-context": "12.2.0",
+    "@shipfox/api-runners-dto": "12.2.0",
     "@shipfox/config": "1.2.4",
-    "@shipfox/inter-module": "0.2.2",
-    "@shipfox/node-drizzle": "0.3.4",
-    "@shipfox/node-fastify": "0.4.0",
+    "@shipfox/inter-module": "0.2.3",
+    "@shipfox/api-workspaces-dto": "12.0.0",
+    "@shipfox/node-auth-root-key": "0.2.3",
+    "@shipfox/node-drizzle": "0.3.5",
+    "@shipfox/node-fastify": "0.4.2",
     "@shipfox/node-email": "0.3.4",
-    "@shipfox/node-mailer": "0.2.4",
-    "@shipfox/node-module": "1.0.4",
-    "@shipfox/node-opentelemetry": "0.6.3",
-    "@shipfox/node-postgres": "0.4.4",
+    "@shipfox/node-mailer": "0.2.5",
+    "@shipfox/node-module": "1.0.6",
+    "@shipfox/node-opentelemetry": "0.6.4",
     "@shipfox/node-outbox": "0.2.6",
+    "@shipfox/node-postgres": "0.5.0",
+    "@shipfox/node-rate-limit": "0.4.0",
     "@shipfox/node-tokens": "0.3.2"
   },
   "imports": {

package/src/core/entities/workspace.ts

@@ -3,6 +3,7 @@ export type WorkspaceStatus = 'active' | 'suspended' | 'deleted';
 export interface Workspace {
   id: string;
   name: string;
+  slug: string;
   status: WorkspaceStatus;
   settings: Record<string, unknown>;
   createdBy: string | null;

package/src/core/errors.ts

@@ -5,6 +5,13 @@ export class WorkspaceNotFoundError extends Error {
   }
 }
 
+export class WorkspaceSlugConflictError extends Error {
+  constructor(slug: string) {
+    super(`Workspace slug is already taken: ${slug}`);
+    this.name = 'WorkspaceSlugConflictError';
+  }
+}
+
 export class WorkspaceInactiveError extends Error {
   constructor(workspaceId: string) {
     super(`Workspace is not active: ${workspaceId}`);

package/src/core/index.ts

@@ -27,6 +27,7 @@ export {
   WorkspaceDeletedError,
   WorkspaceNotFoundError,
   WorkspaceNotSuspendedError,
+  WorkspaceSlugConflictError,
 } from './errors.js';
 export {
   acceptWorkspaceInvitation,
@@ -38,6 +39,7 @@ export {
 } from './invitations.js';
 export {type EnsureMembershipParams, ensureMembership} from './memberships.js';
 export {
+  checkWorkspaceSlugAvailability,
   createWorkspaceForUser,
   getWorkspace,
   listUserWorkspaceMemberships,
@@ -46,4 +48,5 @@ export {
   type RequireWorkspaceMembershipResult,
   removeWorkspaceMember,
   requireWorkspaceMembership,
+  updateWorkspaceDetails,
 } from './workspaces.js';

package/src/core/invitations.ts

@@ -100,7 +100,7 @@ export async function previewInvitation(params: {token: string}): Promise<Previe
 
   const workspace = await getWorkspaceById(invitation.workspaceId);
   if (!workspace) {
-    // Workspace cascade-deleted — the invitation row is orphaned. Treat as invalid.
+    // Workspace cascade-deleted: the invitation row is orphaned. Treat as invalid.
     return {status: 'invalid'};
   }
 

package/src/core/rate-limit.test.ts

@@ -0,0 +1,113 @@
+import {eq, sql} from 'drizzle-orm';
+import {db} from '#db/db.js';
+import {workspacesRateLimits} from '#db/schema/rate-limits.js';
+import {
+  checkWorkspacesRateLimit,
+  hashWorkspacesRateLimitIdentifier,
+  WorkspacesRateLimitUnavailableError,
+} from './rate-limit.js';
+
+const HMAC_HEX_PATTERN = /^[a-f0-9]{64}$/;
+
+describe('checkWorkspacesRateLimit', () => {
+  it('hashes identifiers without storing the raw identifier', async () => {
+    const identifier = `ip-${crypto.randomUUID()}`;
+    const identifierHmac = hashWorkspacesRateLimitIdentifier({
+      action: 'slug-availability',
+      scope: 'ip',
+      identifier,
+    });
+
+    await checkWorkspacesRateLimit({
+      action: 'slug-availability',
+      scope: 'ip',
+      identifier,
+      limit: 1,
+      windowSeconds: 60,
+      now: new Date('2026-06-23T00:00:10Z'),
+    });
+
+    const rows = await db()
+      .select({identifierHmac: workspacesRateLimits.identifierHmac})
+      .from(workspacesRateLimits)
+      .where(eq(workspacesRateLimits.identifierHmac, identifierHmac));
+
+    expect(identifierHmac).toMatch(HMAC_HEX_PATTERN);
+    expect(identifierHmac).not.toContain(identifier);
+    expect(rows).toEqual([{identifierHmac}]);
+  });
+
+  it('rejects the first over-limit attempt with retry-after seconds', async () => {
+    const identifier = `ip-${crypto.randomUUID()}`;
+    const now = new Date('2026-06-23T00:00:10Z');
+
+    await checkWorkspacesRateLimit({
+      action: 'slug-availability',
+      scope: 'ip',
+      identifier,
+      limit: 2,
+      windowSeconds: 60,
+      now,
+    });
+    await checkWorkspacesRateLimit({
+      action: 'slug-availability',
+      scope: 'ip',
+      identifier,
+      limit: 2,
+      windowSeconds: 60,
+      now,
+    });
+    const result = checkWorkspacesRateLimit({
+      action: 'slug-availability',
+      scope: 'ip',
+      identifier,
+      limit: 2,
+      windowSeconds: 60,
+      now,
+    });
+
+    await expect(result).rejects.toMatchObject({
+      name: 'WorkspacesRateLimitExceededError',
+      retryAfterSeconds: 50,
+    });
+  });
+
+  it('fails closed when the limiter query times out', async () => {
+    const identifier = `ip-${crypto.randomUUID()}`;
+    const identifierHmac = hashWorkspacesRateLimitIdentifier({
+      action: 'slug-availability',
+      scope: 'ip',
+      identifier,
+    });
+    await db()
+      .insert(workspacesRateLimits)
+      .values({
+        action: 'slug-availability',
+        scope: 'ip',
+        identifierHmac,
+        windowStart: new Date('2026-06-23T00:03:00Z'),
+        count: 1,
+        expiresAt: new Date('2026-06-23T00:04:00Z'),
+      });
+
+    await db().transaction(async (tx) => {
+      await tx.execute(sql`
+        SELECT 1
+        FROM workspaces_rate_limits
+        WHERE identifier_hmac = ${identifierHmac}
+        FOR UPDATE
+      `);
+      const result = checkWorkspacesRateLimit({
+        action: 'slug-availability',
+        scope: 'ip',
+        identifier,
+        limit: 1,
+        windowSeconds: 60,
+        now: new Date('2026-06-23T00:03:30Z'),
+        timeoutMs: 10,
+      });
+
+      await expect(result).rejects.toBeInstanceOf(WorkspacesRateLimitUnavailableError);
+    });
+  });
+});

package/src/core/rate-limit.ts

@@ -0,0 +1,119 @@
+import {rateLimitIdentifierKey} from '@shipfox/node-auth-root-key';
+import {
+  checkRateLimit,
+  hashRateLimitIdentifier,
+  RateLimitExceededError,
+  type RateLimitOutcome,
+  type RateLimitPolicy,
+  RateLimitUnavailableError,
+} from '@shipfox/node-rate-limit';
+import {consumeWorkspacesRateLimit, pruneExpiredWorkspacesRateLimits} from '#db/rate-limits.js';
+import {
+  recordWorkspaceRateLimitCheck,
+  recordWorkspaceRateLimitPruneFailure,
+} from '#metrics/instance.js';
+
+export type WorkspacesRateLimitAction = 'slug-availability';
+export type WorkspacesRateLimitScope = 'ip';
+export type WorkspacesRateLimitOutcome = RateLimitOutcome;
+export type WorkspacesRateLimitPolicy = RateLimitPolicy;
+
+export interface CheckWorkspacesRateLimitParams extends WorkspacesRateLimitPolicy {
+  action: WorkspacesRateLimitAction;
+  scope: WorkspacesRateLimitScope;
+  identifier: string;
+  now?: Date | undefined;
+  timeoutMs?: number | undefined;
+}
+
+export class WorkspacesRateLimitExceededError extends RateLimitExceededError<
+  WorkspacesRateLimitAction,
+  WorkspacesRateLimitScope
+> {
+  constructor(params: {
+    action: WorkspacesRateLimitAction;
+    scope: WorkspacesRateLimitScope;
+    retryAfterSeconds: number;
+    identifierHmacPrefix: string;
+  }) {
+    super(params);
+    this.name = 'WorkspacesRateLimitExceededError';
+  }
+}
+
+export class WorkspacesRateLimitUnavailableError extends RateLimitUnavailableError<
+  WorkspacesRateLimitAction,
+  WorkspacesRateLimitScope
+> {
+  constructor(params: {
+    action: WorkspacesRateLimitAction;
+    scope: WorkspacesRateLimitScope;
+    identifierHmacPrefix: string;
+    cause: unknown;
+  }) {
+    super(params);
+    this.name = 'WorkspacesRateLimitUnavailableError';
+  }
+}
+
+export const WORKSPACE_SLUG_AVAILABILITY_RATE_LIMIT = {
+  limit: 60,
+  windowSeconds: 5 * 60,
+} as const;
+
+const RATE_LIMIT_TIMEOUT_MS = 250;
+const IDENTIFIER_HASH_DOMAIN = 'shipfox.workspaces.rate-limit.identifier.v1';
+
+export function hashWorkspacesRateLimitIdentifier(params: {
+  action: WorkspacesRateLimitAction;
+  scope: WorkspacesRateLimitScope;
+  identifier: string;
+}): string {
+  return hashRateLimitIdentifier({
+    action: params.action,
+    scope: params.scope,
+    identifier: params.identifier,
+    secret: rateLimitIdentifierKey(),
+    domain: IDENTIFIER_HASH_DOMAIN,
+  });
+}
+
+export async function checkWorkspacesRateLimit(
+  params: CheckWorkspacesRateLimitParams,
+): Promise<void> {
+  try {
+    await checkRateLimit({
+      action: params.action,
+      scope: params.scope,
+      identifier: params.identifier,
+      limit: params.limit,
+      windowSeconds: params.windowSeconds,
+      identifierSecret: rateLimitIdentifierKey(),
+      identifierHashDomain: IDENTIFIER_HASH_DOMAIN,
+      consume: consumeWorkspacesRateLimit,
+      prune: pruneExpiredWorkspacesRateLimits,
+      onCheck: recordWorkspaceRateLimitCheck,
+      onPruneFailure: recordWorkspaceRateLimitPruneFailure,
+      now: params.now,
+      timeoutMs: params.timeoutMs ?? RATE_LIMIT_TIMEOUT_MS,
+    });
+  } catch (error) {
+    if (error instanceof RateLimitExceededError) {
+      throw new WorkspacesRateLimitExceededError({
+        action: error.action,
+        scope: error.scope,
+        retryAfterSeconds: error.retryAfterSeconds,
+        identifierHmacPrefix: error.identifierHmacPrefix,
+      });
+    }
+    if (error instanceof RateLimitUnavailableError) {
+      throw new WorkspacesRateLimitUnavailableError({
+        action: error.action,
+        scope: error.scope,
+        identifierHmacPrefix: error.identifierHmacPrefix,
+        cause: error.cause,
+      });
+    }
+    throw error;
+  }
+}

package/src/core/workspaces.test.ts

@@ -15,9 +15,11 @@ import {
 describe('workspaces core', () => {
   test('createWorkspaceForUser creates a workspace and membership for the user', async () => {
     const user = userFactory.build();
+    const slug = `core-${crypto.randomUUID().slice(0, 8)}`;
 
     const workspace = await createWorkspaceForUser({
       name: 'Core Workspace',
+      slug,
       userId: user.userId,
       userEmail: user.email,
       userName: user.name,
@@ -25,6 +27,7 @@ describe('workspaces core', () => {
     const membership = await findMembership({userId: user.userId, workspaceId: workspace.id});
 
     expect(workspace.name).toBe('Core Workspace');
+    expect(workspace.slug).toBe(slug);
     expect(membership).toBeDefined();
   });
 
@@ -33,6 +36,7 @@ describe('workspaces core', () => {
 
     const workspace = await createWorkspaceForUser({
       name: 'Evented Workspace',
+      slug: `evented-${crypto.randomUUID().slice(0, 8)}`,
       userId: user.userId,
       userEmail: user.email,
       userName: user.name,
@@ -47,6 +51,7 @@ describe('workspaces core', () => {
       payload: {
         workspaceId: workspace.id,
         name: workspace.name,
+        slug: workspace.slug,
         creatorUserId: user.userId,
       },
     });
@@ -56,6 +61,7 @@ describe('workspaces core', () => {
     const user = userFactory.build();
     const workspace = await createWorkspaceForUser({
       name: 'Member Workspace',
+      slug: `member-${crypto.randomUUID().slice(0, 8)}`,
       userId: user.userId,
       userEmail: user.email,
       userName: user.name,
@@ -75,6 +81,7 @@ describe('workspaces core', () => {
   test('getWorkspaceOperatingState returns the current status without workspace details', async () => {
     const workspace = await createWorkspaceForUser({
       name: 'Operating State Workspace',
+      slug: `operating-${crypto.randomUUID().slice(0, 8)}`,
       userId: crypto.randomUUID(),
     });
 
@@ -89,6 +96,7 @@ describe('workspaces core', () => {
     const user = userFactory.build();
     const workspace = await createWorkspaceForUser({
       name: 'Suspended Workspace',
+      slug: `suspended-${crypto.randomUUID().slice(0, 8)}`,
       userId: user.userId,
       userEmail: user.email,
       userName: user.name,
@@ -109,6 +117,7 @@ describe('workspaces core', () => {
     const outsider = userFactory.build();
     const workspace = await createWorkspaceForUser({
       name: 'Private Workspace',
+      slug: `private-${crypto.randomUUID().slice(0, 8)}`,
       userId: owner.userId,
       userEmail: owner.email,
       userName: owner.name,

package/src/core/workspaces.ts

@@ -1,9 +1,11 @@
 import type {UserContextMembership} from '@shipfox/api-auth-context';
 import {
   WORKSPACES_WORKSPACE_CREATED,
+  WORKSPACES_WORKSPACE_UPDATED,
   type WorkspaceRole,
   type WorkspacesEventMap,
 } from '@shipfox/api-workspaces-dto';
+import {isUniqueViolation} from '@shipfox/node-drizzle';
 import {writeOutboxEvent} from '@shipfox/node-outbox';
 import {db} from '#db/db.js';
 import {
@@ -17,7 +19,7 @@ import {
 import {memberships} from '#db/schema/memberships.js';
 import {workspacesOutbox} from '#db/schema/outbox.js';
 import {toWorkspace, workspaces} from '#db/schema/workspaces.js';
-import {getWorkspaceById} from '#db/workspaces.js';
+import {getWorkspaceById, isWorkspaceSlugAvailable, updateWorkspace} from '#db/workspaces.js';
 import type {Workspace} from './entities/workspace.js';
 import {
   MembershipNotFoundError,
@@ -25,6 +27,7 @@ import {
   SelfRemovalNotAllowedError,
   WorkspaceInactiveError,
   WorkspaceNotFoundError,
+  WorkspaceSlugConflictError,
 } from './errors.js';
 
 export interface RequireWorkspaceMembershipParams {
@@ -62,6 +65,7 @@ export async function requireWorkspaceMembership(
 
 export async function createWorkspaceForUser(params: {
   name: string;
+  slug: string;
   userId: string;
   userEmail?: string | undefined;
   userName?: string | null | undefined;
@@ -69,9 +73,12 @@ export async function createWorkspaceForUser(params: {
   return await db().transaction(async (tx) => {
     const [workspaceRow] = await tx
       .insert(workspaces)
-      .values({name: params.name, createdBy: params.userId})
+      .values({name: params.name, slug: params.slug, createdBy: params.userId})
+      .onConflictDoNothing({target: workspaces.slug})
       .returning();
-    if (!workspaceRow) throw new Error('Insert returned no rows');
+    if (!workspaceRow) {
+      throw new WorkspaceSlugConflictError(params.slug);
+    }
     await tx.insert(memberships).values({
       userId: params.userId,
       userEmail: params.userEmail ?? `user-${params.userId}@example.local`,
@@ -85,6 +92,7 @@ export async function createWorkspaceForUser(params: {
       payload: {
         workspaceId: workspace.id,
         name: workspace.name,
+        slug: workspace.slug,
         creatorUserId: params.userId,
       },
     });
@@ -93,6 +101,42 @@ export async function createWorkspaceForUser(params: {
   });
 }
 
+export async function checkWorkspaceSlugAvailability(slug: string): Promise<boolean> {
+  return await isWorkspaceSlugAvailable(slug);
+}
+
+export async function updateWorkspaceDetails(params: {
+  workspaceId: string;
+  name?: string | undefined;
+  slug?: string | undefined;
+}): Promise<Workspace> {
+  try {
+    return await db().transaction(async (tx) => {
+      const workspace = await updateWorkspace(
+        {id: params.workspaceId, name: params.name, slug: params.slug},
+        {tx},
+      );
+      if (!workspace) throw new WorkspaceNotFoundError(params.workspaceId);
+
+      await writeOutboxEvent<WorkspacesEventMap>(tx, workspacesOutbox, {
+        type: WORKSPACES_WORKSPACE_UPDATED,
+        payload: {
+          workspaceId: workspace.id,
+          name: workspace.name,
+          slug: workspace.slug,
+        },
+      });
+
+      return workspace;
+    });
+  } catch (error) {
+    if (isUniqueViolation(error, 'workspaces_slug_unique') && params.slug) {
+      throw new WorkspaceSlugConflictError(params.slug);
+    }
+    throw error;
+  }
+}
+
 export async function getWorkspace(params: {workspaceId: string}): Promise<Workspace> {
   const workspace = await getWorkspaceById(params.workspaceId);
   if (!workspace) {

package/src/db/db.ts

@@ -4,6 +4,7 @@ import {workspacesAdminCommandResults} from './schema/admin-command-results.js';
 import {invitations} from './schema/invitations.js';
 import {memberships} from './schema/memberships.js';
 import {workspacesOutbox} from './schema/outbox.js';
+import {workspacesRateLimits} from './schema/rate-limits.js';
 import {workspaces} from './schema/workspaces.js';
 
 export const schema = {
@@ -12,6 +13,7 @@ export const schema = {
   memberships,
   invitations,
   workspacesOutbox,
+  workspacesRateLimits,
 };
 
 let _db: NodePgDatabase<typeof schema> | undefined;

package/src/db/index.ts

@@ -22,8 +22,17 @@ export {
   listMembershipsByWorkspace,
   removeMembership,
 } from './memberships.js';
+export type {
+  ConsumeWorkspacesRateLimitParams,
+  ConsumeWorkspacesRateLimitResult,
+} from './rate-limits.js';
+export {
+  consumeWorkspacesRateLimit,
+  pruneExpiredWorkspacesRateLimits,
+} from './rate-limits.js';
 export {workspacesAdminCommandResults} from './schema/admin-command-results.js';
 export {workspacesOutbox} from './schema/outbox.js';
+export {workspacesRateLimits} from './schema/rate-limits.js';
 export type {
   AdminWorkspaceRow,
   CreateWorkspaceParams,
@@ -36,6 +45,7 @@ export {
   createWorkspace,
   getWorkspaceById,
   getWorkspaceServiceMetrics,
+  isWorkspaceSlugAvailable,
   listAdminWorkspaces,
   updateWorkspace,
 } from './workspaces.js';

package/src/db/memberships.ts

@@ -59,6 +59,7 @@ export async function ensureMembership(params: EnsureMembershipParams): Promise<
 
 export interface MembershipWithWorkspace extends Membership {
   workspaceName: string;
+  workspaceSlug: string;
   workspaceStatus: Workspace['status'];
 }
 
@@ -69,6 +70,7 @@ export async function listMembershipsByUser(params: {
     .select({
       membership: memberships,
       workspaceName: workspaces.name,
+      workspaceSlug: workspaces.slug,
       workspaceStatus: workspaces.status,
     })
     .from(memberships)
@@ -79,6 +81,7 @@ export async function listMembershipsByUser(params: {
   return rows.map((row) => ({
     ...toMembership(row.membership),
     workspaceName: row.workspaceName,
+    workspaceSlug: row.workspaceSlug,
     workspaceStatus: row.workspaceStatus,
   }));
 }

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

@@ -0,0 +1,74 @@
+import {and, eq, sql} from 'drizzle-orm';
+import {consumeWorkspacesRateLimit, pruneExpiredWorkspacesRateLimits} from '#db/rate-limits.js';
+import {db} from './db.js';
+import {workspacesRateLimits} from './schema/rate-limits.js';
+
+describe('workspaces rate limits db', () => {
+  it('atomically increments one bucket for concurrent attempts', async () => {
+    const identifierHmac = `hmac-${crypto.randomUUID()}`;
+    const params = {
+      action: 'slug-availability',
+      scope: 'ip',
+      identifierHmac,
+      windowStart: new Date('2026-06-23T00:00:00Z'),
+      expiresAt: new Date('2026-06-23T00:01:00Z'),
+      timeoutMs: 5_000,
+    };
+
+    await Promise.all(Array.from({length: 20}, () => consumeWorkspacesRateLimit(params)));
+
+    const [row] = await db()
+      .select({count: workspacesRateLimits.count})
+      .from(workspacesRateLimits)
+      .where(eq(workspacesRateLimits.identifierHmac, identifierHmac));
+    expect(row?.count).toBe(20);
+  });
+
+  it('prunes expired counters and keeps active counters', async () => {
+    const expiredIdentifierHmac = `expired-${crypto.randomUUID()}`;
+    const activeIdentifierHmac = `active-${crypto.randomUUID()}`;
+    await db()
+      .insert(workspacesRateLimits)
+      .values([
+        {
+          action: 'slug-availability',
+          scope: 'ip',
+          identifierHmac: expiredIdentifierHmac,
+          windowStart: new Date('2026-06-23T00:00:00Z'),
+          count: 1,
+          expiresAt: new Date('2026-06-23T00:01:00Z'),
+        },
+        {
+          action: 'slug-availability',
+          scope: 'ip',
+          identifierHmac: activeIdentifierHmac,
+          windowStart: new Date('2026-06-23T00:04:00Z'),
+          count: 1,
+          expiresAt: new Date('2026-06-23T00:06:00Z'),
+        },
+      ]);
+
+    const result = await pruneExpiredWorkspacesRateLimits({
+      now: new Date('2026-06-23T00:05:00Z'),
+      minIntervalMs: 0,
+    });
+
+    expect(result).toBeGreaterThanOrEqual(1);
+    expect(await countBucket(expiredIdentifierHmac)).toBe(0);
+    expect(await countBucket(activeIdentifierHmac)).toBe(1);
+  });
+
+  async function countBucket(identifierHmac: string): Promise<number> {
+    const [row] = await db()
+      .select({count: sql<number>`count(*)::int`})
+      .from(workspacesRateLimits)
+      .where(
+        and(
+          eq(workspacesRateLimits.action, 'slug-availability'),
+          eq(workspacesRateLimits.scope, 'ip'),
+          eq(workspacesRateLimits.identifierHmac, identifierHmac),
+        ),
+      );
+    return row?.count ?? 0;
+  }
+});