@shipfox/api-auth 9.1.0 → 9.3.0

package/src/presentation/dto/user.ts

@@ -1,4 +1,4 @@
-import type {LoginResponseDto, UserDto} from '@shipfox/api-auth-dto';
+import type {AdminRole, LoginResponseDto, UserDto} from '@shipfox/api-auth-dto';
 import type {User} from '#core/entities/user.js';
 
 export function toUserDto(user: User): UserDto {
@@ -13,9 +13,14 @@ export function toUserDto(user: User): UserDto {
   };
 }
 
-export function toAuthSessionDto(result: {token: string; user: User}): LoginResponseDto {
+export function toAuthSessionDto(result: {
+  token: string;
+  user: User;
+  adminRole?: AdminRole | null;
+}): LoginResponseDto {
   return {
     token: result.token,
     user: toUserDto(result.user),
+    admin_role: result.adminRole ?? null,
   };
 }

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

@@ -14,6 +14,7 @@ describe('auth E2E routes', () => {
           preflightInvitationAcceptance: vi.fn(),
           acceptInvitation: vi.fn(),
           requireActiveMembership: vi.fn(),
+          getWorkspaceOperatingState: vi.fn(),
         }),
       ],
       swagger: false,

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

@@ -0,0 +1,47 @@
+import {authInterModuleContract} from '@shipfox/api-auth-dto/inter-module';
+import {isInterModuleKnownError} from '@shipfox/inter-module';
+import {createInMemoryInterModuleTransport} from '@shipfox/node-module/inter-module';
+import {createAdminGrant} from '#db/admin-grants.js';
+import {userFactory} from '#test/index.js';
+import {createAuthInterModulePresentation} from './inter-module.js';
+
+function createClient() {
+  const transport = createInMemoryInterModuleTransport();
+  const client = transport.createClient(authInterModuleContract);
+  transport.register(createAuthInterModulePresentation());
+  transport.seal();
+  return client;
+}
+
+describe('Auth inter-module administration role presentation', () => {
+  test('returns the current role from Auth storage', async () => {
+    const client = createClient();
+    const user = await userFactory.create({emailVerifiedAt: new Date()});
+    await createAdminGrant({userId: user.id, role: 'admin-owner'});
+
+    await expect(client.getCurrentAdminRole({userId: user.id})).resolves.toEqual({
+      role: 'admin-owner',
+    });
+    await expect(
+      client.requireAdminRole({userId: user.id, minimumRole: 'admin-operator'}),
+    ).resolves.toEqual({role: 'admin-owner'});
+  });
+
+  test('maps an insufficient current role to the declared known error', async () => {
+    const client = createClient();
+    const user = await userFactory.create({emailVerifiedAt: new Date()});
+    await createAdminGrant({userId: user.id, role: 'admin-observer'});
+
+    const error = await client
+      .requireAdminRole({userId: user.id, minimumRole: 'admin-owner'})
+      .catch((caught: unknown) => caught);
+
+    expect(isInterModuleKnownError(authInterModuleContract.methods.requireAdminRole, error)).toBe(
+      true,
+    );
+    if (isInterModuleKnownError(authInterModuleContract.methods.requireAdminRole, error)) {
+      expect(error.code).toBe('admin-role-required');
+      expect(error.details).toEqual({requiredRole: 'admin-owner'});
+    }
+  });
+});

package/src/presentation/inter-module.ts

@@ -1,5 +1,11 @@
 import {authInterModuleContract} from '@shipfox/api-auth-dto/inter-module';
-import {defineInterModulePresentation, type InterModulePresentation} from '@shipfox/inter-module';
+import {
+  createInterModuleKnownError,
+  defineInterModulePresentation,
+  type InterModulePresentation,
+} from '@shipfox/inter-module';
+import {getCurrentAdminRole, requireAdminRole} from '#core/admin-role.js';
+import {AdminRoleRequiredError} from '#core/errors.js';
 import {issueJobLeaseToken} from '#core/job-lease-token.js';
 import {issueRunnerSessionToken} from '#core/runner-session-token.js';
 
@@ -9,5 +15,20 @@ export function createAuthInterModulePresentation(): InterModulePresentation<
   return defineInterModulePresentation(authInterModuleContract, {
     mintRunnerSessionToken: async (claims) => ({token: await issueRunnerSessionToken(claims)}),
     mintJobLeaseToken: async (claims) => ({token: await issueJobLeaseToken(claims)}),
+    getCurrentAdminRole: async ({userId}) => ({role: await getCurrentAdminRole({userId})}),
+    requireAdminRole: async ({userId, minimumRole}) => {
+      try {
+        return {role: await requireAdminRole({userId, minimumRole})};
+      } catch (error) {
+        if (error instanceof AdminRoleRequiredError) {
+          throw createInterModuleKnownError(
+            authInterModuleContract.methods.requireAdminRole,
+            'admin-role-required',
+            {requiredRole: error.minimumRole},
+          );
+        }
+        throw error;
+      }
+    },
   });
 }

package/src/presentation/routes/administration.test.ts

@@ -0,0 +1,253 @@
+import {ADMINISTRATION_ACTION_PERFORMED} from '@shipfox/api-common-dto';
+import {sql} from 'drizzle-orm';
+import type {FastifyInstance} from 'fastify';
+import {db} from '#db/db.js';
+import {authOutbox} from '#db/schema/outbox.js';
+import {createAuthTestApp, createVerifiedSession, resetCapturedMail} from '#test/routes.js';
+
+const BOOTSTRAP_TOKEN = 'test-bootstrap-token';
+
+async function resetAdministrationState(): Promise<void> {
+  await db().execute(
+    sql`TRUNCATE auth_admin_command_results, auth_admin_grants, auth_outbox, auth_rate_limits CASCADE`,
+  );
+}
+
+function authHeaders(token: string, idempotencyKey: string) {
+  return {
+    authorization: `Bearer ${token}`,
+    'idempotency-key': idempotencyKey,
+  };
+}
+
+describe('Auth administration routes', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createAuthTestApp();
+  });
+
+  beforeEach(async () => {
+    resetCapturedMail();
+    await resetAdministrationState();
+  });
+
+  afterAll(async () => {
+    await resetAdministrationState();
+    await app.close();
+  });
+
+  test('requires an authenticated session for bootstrap', async () => {
+    const response = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants/bootstrap',
+      headers: {'idempotency-key': 'anonymous-bootstrap'},
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+
+    expect(response.statusCode).toBe(401);
+  });
+
+  test('rejects an invalid bootstrap token without writing a grant or event', async () => {
+    const account = await createVerifiedSession('admin-bootstrap-invalid');
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants/bootstrap',
+      headers: authHeaders(account.token, 'invalid-bootstrap'),
+      payload: {bootstrap_token: 'wrong-token'},
+    });
+
+    expect(response.statusCode).toBe(403);
+    expect(response.json().code).toBe('bootstrap-token-invalid');
+    await expect(db().select().from(authOutbox)).resolves.toHaveLength(0);
+  });
+
+  test('rate-limits repeated bootstrap attempts by source IP', async () => {
+    const account = await createVerifiedSession('admin-bootstrap-rate-limit');
+
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+      const response = await app.inject({
+        method: 'POST',
+        url: '/admin/v1/auth/admin-grants/bootstrap',
+        headers: authHeaders(account.token, `bootstrap-rate-limit-${attempt}`),
+        payload: {bootstrap_token: 'wrong-token'},
+      });
+      expect(response.statusCode).toBe(403);
+    }
+
+    const blocked = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants/bootstrap',
+      headers: authHeaders(account.token, 'bootstrap-rate-limit-blocked'),
+      payload: {bootstrap_token: 'wrong-token'},
+    });
+    expect(blocked.statusCode).toBe(429);
+    expect(blocked.json().code).toBe('rate-limited');
+  });
+
+  test('bootstraps exactly one owner and permanently closes bootstrap', async () => {
+    const first = await createVerifiedSession('admin-bootstrap-first');
+    const second = await createVerifiedSession('admin-bootstrap-second');
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants/bootstrap',
+      headers: authHeaders(first.token, 'bootstrap-first'),
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+
+    expect(response.statusCode).toBe(201);
+    expect(response.json()).toMatchObject({user_id: first.userId, role: 'admin-owner'});
+
+    const repeated = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants/bootstrap',
+      headers: authHeaders(first.token, 'bootstrap-first'),
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+    expect(repeated.statusCode).toBe(201);
+    expect(repeated.json().id).toBe(response.json().id);
+
+    const secondAttempt = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants/bootstrap',
+      headers: authHeaders(second.token, 'bootstrap-second'),
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+    expect(secondAttempt.statusCode).toBe(409);
+    expect(secondAttempt.json().code).toBe('bootstrap-closed');
+
+    const events = await db().select().from(authOutbox);
+    expect(events).toHaveLength(1);
+    expect(events[0]?.eventType).toBe(ADMINISTRATION_ACTION_PERFORMED);
+    expect(events[0]?.payload).toMatchObject({
+      actorId: first.userId,
+      actorRole: 'admin-owner',
+      requiredRole: 'admin-owner',
+      command: 'auth.admin_grant.bootstrap',
+      result: 'succeeded',
+    });
+    expect(JSON.stringify(events[0]?.payload)).not.toContain(BOOTSTRAP_TOKEN);
+  });
+
+  test('lets an owner list, grant, and revoke roles with idempotent audited mutations', async () => {
+    const owner = await createVerifiedSession('admin-grant-owner');
+    const target = await createVerifiedSession('admin-grant-target');
+
+    const bootstrap = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants/bootstrap',
+      headers: authHeaders(owner.token, 'grant-bootstrap'),
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+    expect(bootstrap.statusCode).toBe(201);
+
+    const grant = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants',
+      headers: authHeaders(owner.token, 'grant-observer'),
+      payload: {
+        user_id: target.userId,
+        role: 'admin-observer',
+        reason: 'Support investigation',
+      },
+    });
+    expect(grant.statusCode).toBe(201);
+
+    const repeatedGrant = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants',
+      headers: authHeaders(owner.token, 'grant-observer'),
+      payload: {
+        user_id: target.userId,
+        role: 'admin-observer',
+        reason: 'Support investigation',
+      },
+    });
+    expect(repeatedGrant.statusCode).toBe(201);
+    expect(repeatedGrant.json().id).toBe(grant.json().id);
+
+    const grants = await app.inject({
+      method: 'GET',
+      url: '/admin/v1/auth/admin-grants',
+      headers: {authorization: `Bearer ${owner.token}`},
+    });
+    expect(grants.statusCode).toBe(200);
+    expect(grants.json().grants).toEqual(
+      expect.arrayContaining([expect.objectContaining({user_id: target.userId})]),
+    );
+
+    const revoked = await app.inject({
+      method: 'DELETE',
+      url: `/admin/v1/auth/admin-grants/${grant.json().id}`,
+      headers: authHeaders(owner.token, 'revoke-observer'),
+      payload: {reason: 'Support investigation complete'},
+    });
+    expect(revoked.statusCode).toBe(200);
+    expect(revoked.json()).toMatchObject({id: grant.json().id, revoked_at: expect.any(String)});
+
+    const repeatedRevoke = await app.inject({
+      method: 'DELETE',
+      url: `/admin/v1/auth/admin-grants/${grant.json().id}`,
+      headers: authHeaders(owner.token, 'revoke-observer'),
+      payload: {reason: 'Support investigation complete'},
+    });
+    expect(repeatedRevoke.statusCode).toBe(200);
+    expect(repeatedRevoke.json().revoked_at).toBe(revoked.json().revoked_at);
+
+    const events = await db().select().from(authOutbox);
+    expect(events).toHaveLength(3);
+    expect(events.map((event) => event.eventType)).toEqual(
+      Array(3).fill(ADMINISTRATION_ACTION_PERFORMED),
+    );
+  });
+
+  test('protects the final active owner and rejects idempotency-key reuse', async () => {
+    const owner = await createVerifiedSession('admin-final-owner');
+    const target = await createVerifiedSession('admin-final-target');
+
+    await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants/bootstrap',
+      headers: authHeaders(owner.token, 'final-bootstrap'),
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+
+    const firstGrant = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants',
+      headers: authHeaders(owner.token, 'role-key'),
+      payload: {user_id: target.userId, role: 'admin-observer', reason: 'Initial review'},
+    });
+    expect(firstGrant.statusCode).toBe(201);
+
+    const reusedKey = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants',
+      headers: authHeaders(owner.token, 'role-key'),
+      payload: {user_id: target.userId, role: 'admin-operator', reason: 'Different command'},
+    });
+    expect(reusedKey.statusCode).toBe(409);
+    expect(reusedKey.json().code).toBe('idempotency-key-reused');
+
+    const finalOwnerRevoke = await app.inject({
+      method: 'DELETE',
+      url: `/admin/v1/auth/admin-grants/${
+        (
+          await app.inject({
+            method: 'GET',
+            url: '/admin/v1/auth/admin-grants',
+            headers: {authorization: `Bearer ${owner.token}`},
+          })
+        )
+          .json()
+          .grants.find((grant: {user_id: string}) => grant.user_id === owner.userId).id
+      }`,
+      headers: authHeaders(owner.token, 'revoke-final-owner'),
+      payload: {reason: 'Attempt to remove final owner'},
+    });
+    expect(finalOwnerRevoke.statusCode).toBe(409);
+    expect(finalOwnerRevoke.json().code).toBe('last-owner');
+  });
+});

package/src/presentation/routes/administration.ts

@@ -0,0 +1,195 @@
+import {AUTH_USER} from '@shipfox/api-auth-context';
+import {
+  bootstrapAdminOwnerBodySchema,
+  bootstrapAdminOwnerResponseSchema,
+  grantAdminRoleBodySchema,
+  grantAdminRoleResponseSchema,
+  listAdminGrantsResponseSchema,
+  revokeAdminGrantBodySchema,
+  revokeAdminGrantResponseSchema,
+} from '@shipfox/api-auth-dto';
+import {ClientError, defineRoute, type RouteGroup} from '@shipfox/node-fastify';
+import type {FastifyRequest} from 'fastify';
+import {z} from 'zod';
+import {
+  bootstrapFirstAdminOwner,
+  grantAdministratorRole,
+  listAdministratorGrants,
+  revokeAdministratorGrant,
+} from '#core/administration.js';
+import type {AdminGrant} from '#core/entities/admin-grant.js';
+import {
+  AdminBootstrapClosedError,
+  AdminGrantAlreadyExistsError,
+  AdminGrantNotFoundError,
+  AdminIdempotencyKeyReuseError,
+  AdminRoleRequiredError,
+  InvalidAdminBootstrapTokenError,
+  LastAdminOwnerError,
+  UserNotFoundError,
+} from '#core/errors.js';
+import {getClientContext} from '#presentation/auth/jwt-auth.js';
+import {createAuthIpRateLimitPreHandler} from './rate-limit.js';
+
+const idempotencyKeyMaxLength = 256;
+
+function requireActorId(request: FastifyRequest): string {
+  const client = getClientContext(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 toAdminGrantDto(grant: AdminGrant) {
+  return {
+    id: grant.id,
+    user_id: grant.userId,
+    role: grant.role,
+    revoked_at: grant.revokedAt?.toISOString() ?? null,
+    created_at: grant.createdAt.toISOString(),
+    updated_at: grant.updatedAt.toISOString(),
+  };
+}
+
+function translateAdministrationError(error: unknown): never {
+  if (error instanceof AdminRoleRequiredError) {
+    throw new ClientError('Administrator owner role required', 'forbidden', {
+      status: 403,
+      details: {required_role: error.minimumRole},
+    });
+  }
+  if (error instanceof InvalidAdminBootstrapTokenError) {
+    throw new ClientError('Bootstrap token is invalid', 'bootstrap-token-invalid', {
+      status: 403,
+    });
+  }
+  if (error instanceof AdminBootstrapClosedError) {
+    throw new ClientError('First administrator owner already exists', 'bootstrap-closed', {
+      status: 409,
+    });
+  }
+  if (error instanceof AdminGrantAlreadyExistsError) {
+    throw new ClientError('Administrator grant already exists', 'grant-already-exists', {
+      status: 409,
+    });
+  }
+  if (error instanceof AdminGrantNotFoundError) {
+    throw new ClientError('Administrator grant not found', 'not-found', {status: 404});
+  }
+  if (error instanceof UserNotFoundError) {
+    throw new ClientError('User not found', 'not-found', {status: 404});
+  }
+  if (error instanceof LastAdminOwnerError) {
+    throw new ClientError('Cannot remove the final active administrator owner', 'last-owner', {
+      status: 409,
+    });
+  }
+  if (error instanceof AdminIdempotencyKeyReuseError) {
+    throw new ClientError(
+      'Idempotency-Key was already used for a different command',
+      'idempotency-key-reused',
+      {status: 409},
+    );
+  }
+  throw error;
+}
+
+const bootstrapRoute = defineRoute({
+  method: 'POST',
+  path: '/bootstrap',
+  description: 'Claim the first administrator owner role with the deployment bootstrap token.',
+  schema: {
+    body: bootstrapAdminOwnerBodySchema,
+    response: {201: bootstrapAdminOwnerResponseSchema},
+  },
+  preHandler: createAuthIpRateLimitPreHandler('bootstrap'),
+  errorHandler: translateAdministrationError,
+  handler: async (request, reply) => {
+    const actorId = requireActorId(request);
+    const grant = await bootstrapFirstAdminOwner({
+      actorId,
+      bootstrapToken: request.body.bootstrap_token,
+      idempotencyKey: requireIdempotencyKey(request),
+      correlationId: request.id,
+    });
+    reply.code(201);
+    return toAdminGrantDto(grant);
+  },
+});
+
+const listRoute = defineRoute({
+  method: 'GET',
+  path: '/',
+  description: 'List local administrator grants.',
+  schema: {response: {200: listAdminGrantsResponseSchema}},
+  errorHandler: translateAdministrationError,
+  handler: async (request) => ({
+    grants: (await listAdministratorGrants({actorId: requireActorId(request)})).map(
+      toAdminGrantDto,
+    ),
+  }),
+});
+
+const grantRoute = defineRoute({
+  method: 'POST',
+  path: '/',
+  description: 'Grant a local administrator role to an active user.',
+  schema: {
+    body: grantAdminRoleBodySchema,
+    response: {201: grantAdminRoleResponseSchema},
+  },
+  errorHandler: translateAdministrationError,
+  handler: async (request, reply) => {
+    const actorId = requireActorId(request);
+    const grant = await grantAdministratorRole({
+      actorId,
+      userId: request.body.user_id,
+      role: request.body.role,
+      reason: request.body.reason,
+      idempotencyKey: requireIdempotencyKey(request),
+      correlationId: request.id,
+    });
+    reply.code(201);
+    return toAdminGrantDto(grant);
+  },
+});
+
+const revokeRoute = defineRoute({
+  method: 'DELETE',
+  path: '/:grantId',
+  description: 'Revoke a local administrator grant.',
+  schema: {
+    params: z.object({grantId: z.string().uuid()}),
+    body: revokeAdminGrantBodySchema,
+    response: {200: revokeAdminGrantResponseSchema},
+  },
+  errorHandler: translateAdministrationError,
+  handler: async (request) => {
+    const grant = await revokeAdministratorGrant({
+      actorId: requireActorId(request),
+      grantId: request.params.grantId,
+      reason: request.body.reason,
+      idempotencyKey: requireIdempotencyKey(request),
+      correlationId: request.id,
+    });
+    return toAdminGrantDto(grant);
+  },
+});
+
+export const administrationRoutes: RouteGroup = {
+  prefix: '/admin/v1/auth/admin-grants',
+  auth: AUTH_USER,
+  routes: [bootstrapRoute, listRoute, grantRoute, revokeRoute],
+};

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

@@ -8,6 +8,7 @@ const workspaces = {
   preflightInvitationAcceptance: vi.fn(),
   acceptInvitation: vi.fn(),
   requireActiveMembership: vi.fn(),
+  getWorkspaceOperatingState: vi.fn(),
 };
 
 const disabledPasswordPaths = [

package/src/presentation/routes/index.ts

@@ -1,5 +1,6 @@
 import type {WorkspacesInterModuleClient} from '@shipfox/api-workspaces-dto/inter-module';
 import type {RouteGroup} from '@shipfox/node-fastify';
+import type {SignupPolicy} from '#core/ports.js';
 import {authCookiePlugin} from '#presentation/auth/refresh-cookie.js';
 import {createVerifyEmailConfirmRoute} from './email-verification/verify-email-confirm.js';
 import {verifyEmailResendRoute} from './email-verification/verify-email-resend.js';
@@ -15,10 +16,11 @@ import {createRefreshRoute} from './session/refresh.js';
 export function buildAuthRoutes(
   passwordEnabled: boolean,
   workspaces: WorkspacesInterModuleClient,
+  signupPolicy?: SignupPolicy,
 ): RouteGroup {
   const passwordRoutes = passwordEnabled
     ? [
-        createSignupRoute(workspaces),
+        createSignupRoute(workspaces, signupPolicy),
         createVerifyEmailConfirmRoute(workspaces),
         verifyEmailResendRoute,
         createLoginRoute(workspaces),

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

@@ -8,7 +8,10 @@ import {
   checkAuthRateLimit,
 } from '#core/rate-limit.js';
 
-const policies: Record<AuthRateLimitAction, Record<AuthRateLimitScope, AuthRateLimitPolicy>> = {
+const policies: Record<
+  AuthRateLimitAction,
+  Partial<Record<AuthRateLimitScope, AuthRateLimitPolicy>>
+> = {
   login: {
     ip: {limit: 60, windowSeconds: 5 * 60},
     email: {limit: 10, windowSeconds: 15 * 60},
@@ -17,6 +20,9 @@ const policies: Record<AuthRateLimitAction, Record<AuthRateLimitScope, AuthRateL
     ip: {limit: 30, windowSeconds: 60 * 60},
     email: {limit: 3, windowSeconds: 60 * 60},
   },
+  bootstrap: {
+    ip: {limit: 5, windowSeconds: 15 * 60},
+  },
 };
 
 interface EmailBody {
@@ -34,12 +40,15 @@ async function enforceRateLimit(params: {
   scope: AuthRateLimitScope;
   identifier: string;
 }): Promise<void> {
+  const policy = policies[params.action][params.scope];
+  if (!policy) return;
+
   try {
     await checkAuthRateLimit({
       action: params.action,
       scope: params.scope,
       identifier: params.identifier,
-      ...policies[params.action][params.scope],
+      ...policy,
     });
   } catch (error) {
     if (error instanceof AuthRateLimitExceededError) {
@@ -117,3 +126,15 @@ export function createAuthRateLimitPreHandler(action: AuthRateLimitAction) {
     });
   };
 }
+
+export function createAuthIpRateLimitPreHandler(action: AuthRateLimitAction) {
+  return async (request: FastifyRequest, reply: FastifyReply): Promise<void> => {
+    await enforceRateLimit({
+      request,
+      reply,
+      action,
+      scope: 'ip',
+      identifier: request.ip,
+    });
+  };
+}

package/src/presentation/routes/registration/signup.test.ts

@@ -1,6 +1,9 @@
+import type {WorkspacesInterModuleClient} from '@shipfox/api-workspaces-dto/inter-module';
 import {workspacesInterModuleContract} from '@shipfox/api-workspaces-dto/inter-module';
 import {createInterModuleKnownError} from '@shipfox/inter-module';
+import {ClientError} from '@shipfox/node-fastify';
 import type {FastifyInstance} from 'fastify';
+import {SignupNotAllowedError} from '#core/errors.js';
 import {verifyUserToken} from '#core/jwt.js';
 import {
   acceptWorkspaceInvitationMock,
@@ -14,6 +17,7 @@ import {
   signup,
   uniqueEmail,
 } from '#test/routes.js';
+import {createSignupRoute} from './signup.js';
 
 describe('POST /auth/signup', () => {
   let app: FastifyInstance;
@@ -27,6 +31,28 @@ describe('POST /auth/signup', () => {
     resetCapturedMail();
   });
 
+  test('maps a denied signup to a bounded client error', () => {
+    const errorHandler = createSignupRoute({} as WorkspacesInterModuleClient).errorHandler as (
+      error: unknown,
+    ) => never;
+    const message = 'x'.repeat(501);
+    let mapped: unknown;
+
+    try {
+      errorHandler(new SignupNotAllowedError(message));
+    } catch (error) {
+      mapped = error;
+    }
+
+    expect(mapped).toBeInstanceOf(ClientError);
+    expect(mapped).toMatchObject({
+      message: 'x'.repeat(500),
+      status: 403,
+      code: 'signup-not-allowed',
+      details: {message: 'x'.repeat(500)},
+    });
+  });
+
   afterAll(async () => {
     await app.close();
   });