@shipfox/api-auth 9.1.0 → 9.2.0

package/src/core/ports.ts

@@ -0,0 +1,7 @@
+export interface SignupPolicy {
+  isSignupAllowed(params: {
+    email: string;
+    emailVerified: boolean;
+    source: string;
+  }): Promise<{allowed: true} | {allowed: false; message?: string}>;
+}

package/src/core/signup-policy.test.ts

@@ -0,0 +1,78 @@
+import {config} from '#config.js';
+import {
+  createEnvironmentSignupPolicy,
+  DEFAULT_SIGNUP_NOT_ALLOWED_MESSAGE,
+} from './signup-policy.js';
+
+vi.mock('#config.js', () => ({
+  config: {
+    AUTH_SIGNUP_GATE_ENABLED: true,
+    AUTH_SIGNUP_ALLOWED_EMAIL_DOMAINS: ' Shipfox.io, acme.com ',
+    AUTH_SIGNUP_ALLOWED_EMAILS: ' Alice@Example.com, ',
+    AUTH_SIGNUP_NOT_ALLOWED_MESSAGE: undefined,
+  },
+}));
+
+describe('createEnvironmentSignupPolicy', () => {
+  afterEach(() => {
+    vi.mocked(config).AUTH_SIGNUP_GATE_ENABLED = true;
+    vi.mocked(config).AUTH_SIGNUP_NOT_ALLOWED_MESSAGE = undefined;
+  });
+
+  test('allows exact addresses and domains after normalization', async () => {
+    const policy = createEnvironmentSignupPolicy();
+
+    await expect(
+      policy.isSignupAllowed({
+        email: ' alice@example.com ',
+        emailVerified: false,
+        source: 'password',
+      }),
+    ).resolves.toEqual({allowed: true});
+    await expect(
+      policy.isSignupAllowed({
+        email: 'member@SHIPFOX.IO',
+        emailVerified: true,
+        source: 'oauth-google',
+      }),
+    ).resolves.toEqual({allowed: true});
+  });
+
+  test('does not match subdomains', async () => {
+    const policy = createEnvironmentSignupPolicy();
+
+    await expect(
+      policy.isSignupAllowed({
+        email: 'member@eu.shipfox.io',
+        emailVerified: true,
+        source: 'oauth-google',
+      }),
+    ).resolves.toEqual({allowed: false, message: DEFAULT_SIGNUP_NOT_ALLOWED_MESSAGE});
+  });
+
+  test('returns the configured denial message for an unmatched address', async () => {
+    vi.mocked(config).AUTH_SIGNUP_NOT_ALLOWED_MESSAGE = 'Ask your administrator for access.';
+    const policy = createEnvironmentSignupPolicy();
+
+    await expect(
+      policy.isSignupAllowed({
+        email: 'member@other.example',
+        emailVerified: true,
+        source: 'oauth-google',
+      }),
+    ).resolves.toEqual({allowed: false, message: 'Ask your administrator for access.'});
+  });
+
+  test('allows every address when the gate is disabled', async () => {
+    vi.mocked(config).AUTH_SIGNUP_GATE_ENABLED = false;
+    const policy = createEnvironmentSignupPolicy();
+
+    await expect(
+      policy.isSignupAllowed({
+        email: 'member@other.example',
+        emailVerified: false,
+        source: 'password',
+      }),
+    ).resolves.toEqual({allowed: true});
+  });
+});

package/src/core/signup-policy.ts

@@ -0,0 +1,42 @@
+import {config} from '#config.js';
+import type {SignupPolicy} from './ports.js';
+
+export const DEFAULT_SIGNUP_NOT_ALLOWED_MESSAGE =
+  'This Shipfox deployment does not accept new accounts right now.';
+
+/**
+ * Builds the default signup policy from the Auth module's environment settings.
+ *
+ * The allowlist is resolved once at startup. Environment values are normalized
+ * before matching, but the configured denial message is returned unchanged.
+ */
+export function createEnvironmentSignupPolicy(): SignupPolicy {
+  const allowedEmails = parseAllowlist(config.AUTH_SIGNUP_ALLOWED_EMAILS);
+  const allowedDomains = parseAllowlist(config.AUTH_SIGNUP_ALLOWED_EMAIL_DOMAINS);
+
+  return {
+    isSignupAllowed({email}) {
+      if (!config.AUTH_SIGNUP_GATE_ENABLED) return Promise.resolve({allowed: true});
+
+      const normalizedEmail = normalize(email);
+      if (allowedEmails.has(normalizedEmail)) return Promise.resolve({allowed: true});
+
+      const atIndex = normalizedEmail.lastIndexOf('@');
+      const domain = atIndex === -1 ? '' : normalizedEmail.slice(atIndex + 1);
+      if (allowedDomains.has(domain)) return Promise.resolve({allowed: true});
+
+      return Promise.resolve({
+        allowed: false,
+        message: config.AUTH_SIGNUP_NOT_ALLOWED_MESSAGE ?? DEFAULT_SIGNUP_NOT_ALLOWED_MESSAGE,
+      });
+    },
+  };
+}
+
+function parseAllowlist(value: string): ReadonlySet<string> {
+  return new Set(value.split(',').map(normalize).filter(Boolean));
+}
+
+function normalize(value: string): string {
+  return value.trim().toLowerCase();
+}

package/src/db/admin-grants.test.ts

@@ -0,0 +1,57 @@
+import {eq} from 'drizzle-orm';
+import {LastAdminOwnerError} from '#core/errors.js';
+import {userFactory} from '#test/index.js';
+import {
+  createAdminGrant,
+  findCurrentAdminRole,
+  listAdminGrants,
+  revokeAdminGrant,
+} from './admin-grants.js';
+import {db} from './db.js';
+import {users} from './schema/users.js';
+
+describe('admin grants db', () => {
+  test('evaluates the highest active grant independently of workspace roles', async () => {
+    const user = await userFactory.create({emailVerifiedAt: new Date()});
+    const observer = await createAdminGrant({userId: user.id, role: 'admin-observer'});
+    await createAdminGrant({userId: user.id, role: 'admin-operator'});
+
+    expect(observer.userId).toBe(user.id);
+    expect(await findCurrentAdminRole({userId: user.id})).toBe('admin-operator');
+    expect((await listAdminGrants()).filter((grant) => grant.userId === user.id)).toHaveLength(2);
+  });
+
+  test('does not evaluate revoked grants or grants for suspended users', async () => {
+    const user = await userFactory.create({emailVerifiedAt: new Date()});
+    const grant = await createAdminGrant({userId: user.id, role: 'admin-owner'});
+
+    await expect(revokeAdminGrant({grantId: grant.id})).rejects.toBeInstanceOf(LastAdminOwnerError);
+    expect(await findCurrentAdminRole({userId: user.id})).toBe('admin-owner');
+
+    await db().update(users).set({status: 'suspended'}).where(eq(users.id, user.id));
+    expect(await findCurrentAdminRole({userId: user.id})).toBeNull();
+  });
+
+  test('prevents revoking the final active owner but permits replacement first', async () => {
+    const firstOwner = await userFactory.create({emailVerifiedAt: new Date()});
+    const secondOwner = await userFactory.create({emailVerifiedAt: new Date()});
+    const firstGrant = await createAdminGrant({userId: firstOwner.id, role: 'admin-owner'});
+    const secondGrant = await createAdminGrant({userId: secondOwner.id, role: 'admin-owner'});
+
+    await expect(revokeAdminGrant({grantId: firstGrant.id})).resolves.toMatchObject({
+      id: firstGrant.id,
+      revokedAt: expect.any(Date),
+    });
+    await expect(revokeAdminGrant({grantId: secondGrant.id})).rejects.toBeInstanceOf(
+      LastAdminOwnerError,
+    );
+    expect(await findCurrentAdminRole({userId: secondOwner.id})).toBe('admin-owner');
+  });
+
+  test('enforces one active grant of each fixed role per user', async () => {
+    const user = await userFactory.create({emailVerifiedAt: new Date()});
+    await createAdminGrant({userId: user.id, role: 'admin-observer'});
+
+    await expect(createAdminGrant({userId: user.id, role: 'admin-observer'})).rejects.toThrow();
+  });
+});

package/src/db/admin-grants.ts

@@ -0,0 +1,83 @@
+import type {AdminRole} from '@shipfox/api-auth-dto';
+import {and, asc, eq, isNull, sql} from 'drizzle-orm';
+import {highestAdminRole} from '#core/admin-role-model.js';
+import type {AdminGrant} from '#core/entities/admin-grant.js';
+import {LastAdminOwnerError} from '#core/errors.js';
+import {db} from './db.js';
+import {adminGrants, toAdminGrant} from './schema/admin-grants.js';
+import {users} from './schema/users.js';
+
+export interface CreateAdminGrantParams {
+  userId: string;
+  role: AdminRole;
+}
+
+export async function createAdminGrant(params: CreateAdminGrantParams): Promise<AdminGrant> {
+  const rows = await db()
+    .insert(adminGrants)
+    .values({userId: params.userId, role: params.role})
+    .returning();
+  const row = rows[0];
+  if (!row) throw new Error('Insert returned no rows');
+  return toAdminGrant(row);
+}
+
+export async function listAdminGrants(): Promise<AdminGrant[]> {
+  const rows = await db().select().from(adminGrants).orderBy(asc(adminGrants.createdAt));
+  return rows.map(toAdminGrant);
+}
+
+export async function findCurrentAdminRole(params: {userId: string}): Promise<AdminRole | null> {
+  const rows = await db()
+    .select({role: adminGrants.role})
+    .from(adminGrants)
+    .innerJoin(users, eq(adminGrants.userId, users.id))
+    .where(
+      and(
+        eq(adminGrants.userId, params.userId),
+        isNull(adminGrants.revokedAt),
+        eq(users.status, 'active'),
+      ),
+    );
+
+  return highestAdminRole(rows.map(({role}) => role));
+}
+
+export async function revokeAdminGrant(params: {grantId: string}): Promise<AdminGrant | undefined> {
+  return await db().transaction(async (tx) => {
+    // All owner grant changes share one lock so concurrent revocations cannot
+    // both observe the same final owner and leave the instance ownerless.
+    await tx.execute(sql`select pg_advisory_xact_lock(hashtext('auth_admin_owner_grants'))`);
+
+    const rows = await tx
+      .select()
+      .from(adminGrants)
+      .where(and(eq(adminGrants.id, params.grantId), isNull(adminGrants.revokedAt)))
+      .limit(1);
+    const grant = rows[0];
+    if (!grant) return undefined;
+
+    if (grant.role === 'admin-owner') {
+      const activeOwners = await tx
+        .select({id: adminGrants.id})
+        .from(adminGrants)
+        .innerJoin(users, eq(adminGrants.userId, users.id))
+        .where(
+          and(
+            eq(adminGrants.role, 'admin-owner'),
+            isNull(adminGrants.revokedAt),
+            eq(users.status, 'active'),
+          ),
+        );
+      if (activeOwners.length <= 1) throw new LastAdminOwnerError();
+    }
+
+    const updated = await tx
+      .update(adminGrants)
+      .set({revokedAt: new Date(), updatedAt: new Date()})
+      .where(and(eq(adminGrants.id, grant.id), isNull(adminGrants.revokedAt)))
+      .returning();
+    const row = updated[0];
+    return row ? toAdminGrant(row) : undefined;
+  });
+}

package/src/db/db.ts

@@ -1,5 +1,6 @@
 import {drizzle, type NodePgDatabase} from '@shipfox/node-drizzle';
 import {pgClient} from '@shipfox/node-postgres';
+import {adminGrants} from './schema/admin-grants.js';
 import {authOutbox} from './schema/outbox.js';
 import {passwordResets} from './schema/password-resets.js';
 import {authRateLimits} from './schema/rate-limits.js';
@@ -7,6 +8,7 @@ import {refreshTokens} from './schema/refresh-tokens.js';
 import {users} from './schema/users.js';
 
 export const schema = {
+  adminGrants,
   users,
   passwordResets,
   refreshTokens,

package/src/db/schema/admin-grants.ts

@@ -0,0 +1,49 @@
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {sql} from 'drizzle-orm';
+import {index, pgEnum, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
+import type {AdminGrant} from '#core/entities/admin-grant.js';
+import {pgTable} from './common.js';
+import {users} from './users.js';
+
+export const adminRoleEnum = pgEnum('auth_admin_role', [
+  'admin-observer',
+  'admin-operator',
+  'admin-owner',
+]);
+
+export const adminGrants = pgTable(
+  'admin_grants',
+  {
+    id: uuidv7PrimaryKey(),
+    userId: uuid('user_id')
+      .notNull()
+      .references(() => users.id, {onDelete: 'cascade'}),
+    role: adminRoleEnum('role').notNull(),
+    revokedAt: timestamp('revoked_at', {withTimezone: true}),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [
+    index('auth_admin_grants_user_id_idx').on(table.userId),
+    index('auth_admin_grants_active_owners_idx')
+      .on(table.userId)
+      .where(sql`${table.role} = 'admin-owner' AND ${table.revokedAt} IS NULL`),
+    uniqueIndex('auth_admin_grants_active_user_role_unique')
+      .on(table.userId, table.role)
+      .where(sql`${table.revokedAt} IS NULL`),
+  ],
+);
+
+export type AdminGrantDb = typeof adminGrants.$inferSelect;
+export type AdminGrantCreateDb = typeof adminGrants.$inferInsert;
+
+export function toAdminGrant(row: AdminGrantDb): AdminGrant {
+  return {
+    id: row.id,
+    userId: row.userId,
+    role: row.role,
+    revokedAt: row.revokedAt,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}

package/src/index.test.ts

@@ -6,6 +6,22 @@ import {
 import {createAuthModule} from './index.js';
 import {passwordLoginMethods} from './login-methods.js';
 
+type SignupPolicyLike = {
+  isSignupAllowed(params: {
+    email: string;
+    emailVerified: boolean;
+    source: string;
+  }): Promise<{allowed: true} | {allowed: false; message?: string}>;
+};
+
+const buildAuthRoutes = vi.hoisted(() =>
+  vi.fn((_passwordEnabled: boolean, _workspaces: unknown, _signupPolicy?: SignupPolicyLike) => ({
+    prefix: '/auth',
+    plugins: [],
+    routes: [],
+  })),
+);
+
 vi.mock('#config.js', () => ({
   config: {
     AUTH_JWT_EXPIRES_IN: '15m',
@@ -14,15 +30,24 @@ vi.mock('#config.js', () => ({
     AUTH_REFRESH_ROTATION_GRACE_SECONDS: 30,
     AUTH_REFRESH_COOKIE_NAME: 'shipfox_refresh_token',
     AUTH_PASSWORD_ENABLED: true,
+    AUTH_SIGNUP_GATE_ENABLED: true,
+    AUTH_SIGNUP_ALLOWED_EMAIL_DOMAINS: 'example.com',
+    AUTH_SIGNUP_ALLOWED_EMAILS: '',
+    AUTH_SIGNUP_NOT_ALLOWED_MESSAGE: undefined,
     CLIENT_BASE_URL: 'https://app.example.test',
   },
 }));
 
+vi.mock('#presentation/routes/index.js', () => ({buildAuthRoutes}));
+
 vi.mock('@shipfox/node-mailer', () => ({
   mailer: {send: vi.fn()},
 }));
 
 describe('authModule', () => {
+  const signupPolicy = {
+    isSignupAllowed: async () => ({allowed: true as const}),
+  };
   const authModule = createAuthModule({
     workspaces: {
       listMembershipsForTokenClaims: vi.fn(),
@@ -31,6 +56,7 @@ describe('authModule', () => {
       acceptInvitation: vi.fn(),
       requireActiveMembership: vi.fn(),
     },
+    signupPolicy,
   });
   test('declares password login only when password login is enabled', () => {
     expect(passwordLoginMethods(true)).toEqual([{id: 'password'}]);
@@ -38,6 +64,33 @@ describe('authModule', () => {
     expect(authModule.loginMethods).toEqual([{id: 'password'}]);
   });
 
+  test('uses the environment signup policy when none is provided', async () => {
+    buildAuthRoutes.mockClear();
+    const module = createAuthModule({
+      workspaces: {
+        listMembershipsForTokenClaims: vi.fn(),
+        getWorkspaceCreator: vi.fn(),
+        preflightInvitationAcceptance: vi.fn(),
+        acceptInvitation: vi.fn(),
+        requireActiveMembership: vi.fn(),
+      },
+    });
+    expect(module.routes).toHaveLength(1);
+    const signupPolicy = buildAuthRoutes.mock.calls[0]?.[2];
+
+    expect(signupPolicy).toEqual(expect.objectContaining({isSignupAllowed: expect.any(Function)}));
+    await expect(
+      signupPolicy?.isSignupAllowed({
+        email: 'person@other.example',
+        emailVerified: false,
+        source: 'password',
+      }),
+    ).resolves.toEqual({
+      allowed: false,
+      message: 'This Shipfox deployment does not accept new accounts right now.',
+    });
+  });
+
   test('registers auth email outbox publisher and subscribers', () => {
     const publisher = authModule.publishers?.find((pub) => pub.name === 'auth');
     const events = authModule.subscribers?.map((subscriber) => subscriber.event);

package/src/index.ts

@@ -6,6 +6,8 @@ import {
 import type {ShipfoxModule} from '@shipfox/node-module';
 import {subscriberFactory} from '@shipfox/node-module';
 import {config} from '#config.js';
+import type {SignupPolicy} from '#core/ports.js';
+import {createEnvironmentSignupPolicy} from '#core/signup-policy.js';
 import {db} from '#db/db.js';
 import {migrationsPath} from '#db/migrations.js';
 import {authOutbox} from '#db/schema/outbox.js';
@@ -18,7 +20,15 @@ import {buildAuthRoutes} from '#presentation/routes/index.js';
 import {onPasswordResetSendRequested} from '#presentation/subscribers/index.js';
 import {passwordLoginMethods} from './login-methods.js';
 
-export type {JobLeaseTokenClaims, RunnerSessionTokenClaims} from '@shipfox/api-auth-dto';
+export type {AdminRole, JobLeaseTokenClaims, RunnerSessionTokenClaims} from '@shipfox/api-auth-dto';
+export {
+  ADMIN_ROLES,
+  getCurrentAdminRole,
+  hasMinimumAdminRole,
+  highestAdminRole,
+  requireAdminRole,
+  revokeAdminGrant,
+} from '#core/admin-role.js';
 export type {
   CreateSessionForUserError,
   CreateSessionForUserParams,
@@ -28,11 +38,15 @@ export type {
 export {createSessionForUser, provisionUser} from '#core/auth.js';
 export type {EmailOwner, FindUserByEmailParams} from '#core/email-owner.js';
 export {findUserByEmail} from '#core/email-owner.js';
+export type {AdminGrant} from '#core/entities/admin-grant.js';
 export type {User, UserStatus} from '#core/entities/user.js';
 export {
+  AdminRoleRequiredError,
   AuthDependencyUnavailableError,
   EmailNotVerifiedError,
   InvalidCredentialsError,
+  LastAdminOwnerError,
+  SignupNotAllowedError,
   UserNotFoundError,
 } from '#core/errors.js';
 export {
@@ -40,10 +54,15 @@ export {
   jobLeaseParamsFrom,
   verifyJobLeaseToken,
 } from '#core/job-lease-token.js';
+export type {SignupPolicy} from '#core/ports.js';
 export {
   issueRunnerSessionToken,
   verifyRunnerSessionToken,
 } from '#core/runner-session-token.js';
+export {
+  createEnvironmentSignupPolicy,
+  DEFAULT_SIGNUP_NOT_ALLOWED_MESSAGE,
+} from '#core/signup-policy.js';
 export {
   type AuthenticatedSessionContext,
   createJwtAuthMethod,
@@ -62,17 +81,21 @@ export {createRunnerSessionAuthMethod} from '#presentation/auth/runner-session-a
 
 const subscriber = subscriberFactory<AuthEventMap>();
 
+export interface CreateAuthModuleOptions {
+  workspaces: import('@shipfox/api-workspaces-dto/inter-module').WorkspacesInterModuleClient;
+  signupPolicy?: SignupPolicy;
+}
+
 export function createAuthModule({
   workspaces,
-}: {
-  workspaces: import('@shipfox/api-workspaces-dto/inter-module').WorkspacesInterModuleClient;
-}): ShipfoxModule {
+  signupPolicy = createEnvironmentSignupPolicy(),
+}: CreateAuthModuleOptions): ShipfoxModule {
   return {
     name: 'auth',
     database: {db, migrationsPath, databaseNamespace: 'auth'},
     auth: [createJwtAuthMethod(), createLeaseTokenAuthMethod(), createRunnerSessionAuthMethod()],
     loginMethods: passwordLoginMethods(config.AUTH_PASSWORD_ENABLED),
-    routes: [buildAuthRoutes(config.AUTH_PASSWORD_ENABLED, workspaces)],
+    routes: [buildAuthRoutes(config.AUTH_PASSWORD_ENABLED, workspaces, signupPolicy)],
     e2eRoutes: [createAuthE2eRoutes(workspaces)],
     publishers: [{name: 'auth', table: authOutbox, db, eventSchemas: authEventSchemas}],
     subscribers: [subscriber(AUTH_PASSWORD_RESET_SEND_REQUESTED, onPasswordResetSendRequested)],

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/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/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/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();
   });