@shipfox/api-auth 9.1.0 → 9.3.0

package/drizzle/meta/_journal.json

@@ -8,6 +8,20 @@
       "when": 1784102113104,
       "tag": "0000_initial",
       "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1785065259979,
+      "tag": "0001_brainy_shriek",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1785075183023,
+      "tag": "0002_burly_whizzer",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-auth",
   "license": "MIT",
-  "version": "9.1.0",
+  "version": "9.3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -26,20 +26,21 @@
     "@node-rs/argon2": "^2.0.2",
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
-    "@shipfox/api-auth-context": "9.0.3",
-    "@shipfox/api-auth-dto": "9.0.2",
-    "@shipfox/api-email-challenges": "1.1.3",
-    "@shipfox/api-workspaces-dto": "9.0.2",
+    "@shipfox/api-common-dto": "9.2.0",
+    "@shipfox/api-auth-context": "9.3.0",
+    "@shipfox/api-auth-dto": "9.3.0",
+    "@shipfox/api-email-challenges": "1.1.5",
+    "@shipfox/api-workspaces-dto": "9.3.0",
     "@shipfox/inter-module": "0.2.2",
     "@shipfox/config": "1.2.4",
     "@shipfox/node-drizzle": "0.3.4",
     "@shipfox/node-auth-root-key": "0.2.3",
-    "@shipfox/node-fastify": "0.3.3",
+    "@shipfox/node-fastify": "0.3.4",
     "@shipfox/node-jwt": "0.3.2",
     "@shipfox/node-email": "0.3.4",
-    "@shipfox/node-mailer": "0.2.3",
-    "@shipfox/node-module": "1.0.2",
-    "@shipfox/node-opentelemetry": "0.6.2",
+    "@shipfox/node-mailer": "0.2.4",
+    "@shipfox/node-module": "1.0.3",
+    "@shipfox/node-opentelemetry": "0.6.3",
     "@shipfox/node-outbox": "0.2.6",
     "@shipfox/node-postgres": "0.4.4",
     "@shipfox/node-rate-limit": "0.3.2",

package/src/config.test.ts

@@ -0,0 +1,39 @@
+describe('signup gate configuration', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  test('uses the Auth-prefixed defaults', async () => {
+    vi.resetModules();
+
+    const {config} = await import('#config.js');
+
+    expect(config.AUTH_SIGNUP_GATE_ENABLED).toBe(false);
+    expect(config.AUTH_SIGNUP_ALLOWED_EMAIL_DOMAINS).toBe('');
+    expect(config.AUTH_SIGNUP_ALLOWED_EMAILS).toBe('');
+    expect(config.AUTH_SIGNUP_NOT_ALLOWED_MESSAGE).toBeUndefined();
+  });
+
+  test('fails startup when the enabled gate has no allowlist', async () => {
+    vi.stubEnv('AUTH_SIGNUP_GATE_ENABLED', 'true');
+    vi.stubEnv('AUTH_SIGNUP_ALLOWED_EMAIL_DOMAINS', ',  ');
+    vi.stubEnv('AUTH_SIGNUP_ALLOWED_EMAILS', ' , ');
+    vi.resetModules();
+
+    await expect(import('#config.js')).rejects.toThrow(
+      'AUTH_SIGNUP_GATE_ENABLED requires AUTH_SIGNUP_ALLOWED_EMAIL_DOMAINS or AUTH_SIGNUP_ALLOWED_EMAILS',
+    );
+  });
+
+  test('accepts an enabled gate with either allowlist', async () => {
+    vi.stubEnv('AUTH_SIGNUP_GATE_ENABLED', 'true');
+    vi.stubEnv('AUTH_SIGNUP_ALLOWED_EMAIL_DOMAINS', 'shipfox.io');
+    vi.resetModules();
+
+    const {config} = await import('#config.js');
+
+    expect(config.AUTH_SIGNUP_GATE_ENABLED).toBe(true);
+    expect(config.AUTH_SIGNUP_ALLOWED_EMAIL_DOMAINS).toBe('shipfox.io');
+  });
+});

package/src/config.ts

@@ -1,6 +1,10 @@
 import {bool, createConfig, num, str} from '@shipfox/config';
 
 export const config = createConfig({
+  ADMIN_BOOTSTRAP_TOKEN: str({
+    desc: 'Deployment secret accepted once to create the first administrator owner. Set it before bootstrap and remove or rotate it after successful bootstrap.',
+    default: undefined,
+  }),
   AUTH_JWT_EXPIRES_IN: str({
     desc: 'How long an access token stays valid. Accepts a duration string such as 15m, 1h, or 7d.',
     default: '15m',
@@ -29,8 +33,38 @@ export const config = createConfig({
     desc: 'Whether password login is available. Use true or false. Defaults to true. When false, password and email-verification routes are not registered, and server startup requires another module to contribute a login method.',
     default: true,
   }),
+  AUTH_SIGNUP_GATE_ENABLED: bool({
+    desc: 'Whether new account creation is restricted to the configured signup email allowlist. Defaults to false, which allows every signup.',
+    default: false,
+  }),
+  AUTH_SIGNUP_ALLOWED_EMAIL_DOMAINS: str({
+    desc: 'Comma-separated email domains allowed to create accounts, such as shipfox.io,acme.com. Required when AUTH_SIGNUP_GATE_ENABLED is true unless AUTH_SIGNUP_ALLOWED_EMAILS is set.',
+    default: '',
+  }),
+  AUTH_SIGNUP_ALLOWED_EMAILS: str({
+    desc: 'Comma-separated exact email addresses allowed to create accounts. Required when AUTH_SIGNUP_GATE_ENABLED is true unless AUTH_SIGNUP_ALLOWED_EMAIL_DOMAINS is set.',
+    default: '',
+  }),
+  AUTH_SIGNUP_NOT_ALLOWED_MESSAGE: str({
+    desc: 'Description returned when the signup gate blocks an account. Optional. The default is This Shipfox deployment does not accept new accounts right now.',
+    default: undefined,
+  }),
   CLIENT_BASE_URL: str({
     desc: 'Base URL of the client app. Used to build links in emails such as password resets.',
     default: 'http://localhost:5173',
   }),
 });
+
+if (
+  config.AUTH_SIGNUP_GATE_ENABLED &&
+  !hasSignupAllowlistEntry(config.AUTH_SIGNUP_ALLOWED_EMAIL_DOMAINS) &&
+  !hasSignupAllowlistEntry(config.AUTH_SIGNUP_ALLOWED_EMAILS)
+) {
+  throw new Error(
+    'AUTH_SIGNUP_GATE_ENABLED requires AUTH_SIGNUP_ALLOWED_EMAIL_DOMAINS or AUTH_SIGNUP_ALLOWED_EMAILS to be set.',
+  );
+}
+
+function hasSignupAllowlistEntry(value: string): boolean {
+  return value.split(',').some((entry) => entry.trim().length > 0);
+}

package/src/core/admin-role-model.ts

@@ -0,0 +1,25 @@
+import type {AdminRole} from '@shipfox/api-auth-dto';
+
+export const ADMIN_ROLES: readonly AdminRole[] = [
+  'admin-observer',
+  'admin-operator',
+  'admin-owner',
+];
+
+const ADMIN_ROLE_RANK: Record<AdminRole, number> = {
+  'admin-observer': 1,
+  'admin-operator': 2,
+  'admin-owner': 3,
+};
+
+export function hasMinimumAdminRole(role: AdminRole, minimumRole: AdminRole): boolean {
+  return ADMIN_ROLE_RANK[role] >= ADMIN_ROLE_RANK[minimumRole];
+}
+
+export function highestAdminRole(roles: readonly AdminRole[]): AdminRole | null {
+  return roles.reduce<AdminRole | null>(
+    (highest, role) =>
+      highest === null || ADMIN_ROLE_RANK[role] > ADMIN_ROLE_RANK[highest] ? role : highest,
+    null,
+  );
+}

package/src/core/admin-role.test.ts

@@ -0,0 +1,39 @@
+import {createAdminGrant} from '#db/admin-grants.js';
+import {userFactory} from '#test/index.js';
+import {hasMinimumAdminRole, highestAdminRole, requireAdminRole} from './admin-role.js';
+import type {AdminRoleRequiredError} from './errors.js';
+
+describe('admin role policy', () => {
+  test.each([
+    ['admin-observer', 'admin-observer', true],
+    ['admin-observer', 'admin-operator', false],
+    ['admin-operator', 'admin-observer', true],
+    ['admin-operator', 'admin-owner', false],
+    ['admin-owner', 'admin-observer', true],
+    ['admin-owner', 'admin-operator', true],
+    ['admin-owner', 'admin-owner', true],
+  ] as const)('%s satisfies %s: %s', (role, minimumRole, expected) => {
+    expect(hasMinimumAdminRole(role, minimumRole)).toBe(expected);
+  });
+
+  test('selects the highest role from fixed grants', () => {
+    expect(highestAdminRole(['admin-observer', 'admin-owner', 'admin-operator'])).toBe(
+      'admin-owner',
+    );
+    expect(highestAdminRole([])).toBeNull();
+  });
+
+  test('evaluates the current role from Auth storage for every required minimum', async () => {
+    const user = await userFactory.create({emailVerifiedAt: new Date()});
+    await createAdminGrant({userId: user.id, role: 'admin-operator'});
+
+    await expect(requireAdminRole({userId: user.id, minimumRole: 'admin-observer'})).resolves.toBe(
+      'admin-operator',
+    );
+    await expect(requireAdminRole({userId: user.id, minimumRole: 'admin-owner'})).rejects.toEqual(
+      expect.objectContaining<Partial<AdminRoleRequiredError>>({
+        minimumRole: 'admin-owner',
+      }),
+    );
+  });
+});

package/src/core/admin-role.ts

@@ -0,0 +1,25 @@
+import type {AdminRole} from '@shipfox/api-auth-dto';
+import {findCurrentAdminRole, revokeAdminGrant as revokeAdminGrantInDb} from '#db/admin-grants.js';
+import {hasMinimumAdminRole} from './admin-role-model.js';
+import {AdminRoleRequiredError} from './errors.js';
+
+export {ADMIN_ROLES, hasMinimumAdminRole, highestAdminRole} from './admin-role-model.js';
+
+export async function getCurrentAdminRole(params: {userId: string}): Promise<AdminRole | null> {
+  return await findCurrentAdminRole(params);
+}
+
+export async function requireAdminRole(params: {
+  userId: string;
+  minimumRole: AdminRole;
+}): Promise<AdminRole> {
+  const role = await getCurrentAdminRole({userId: params.userId});
+  if (!role || !hasMinimumAdminRole(role, params.minimumRole)) {
+    throw new AdminRoleRequiredError(params.minimumRole);
+  }
+  return role;
+}
+
+export async function revokeAdminGrant(params: {grantId: string}) {
+  return await revokeAdminGrantInDb(params);
+}

package/src/core/administration.ts

@@ -0,0 +1,172 @@
+import {createHash, timingSafeEqual} from 'node:crypto';
+import type {AdminRole} from '@shipfox/api-auth-dto';
+import {createAdministrationActionEvent} from '@shipfox/api-common-dto';
+import {config} from '#config.js';
+import {
+  bootstrapFirstAdminOwner as bootstrapFirstAdminOwnerInDb,
+  grantAdminRoleWithAudit,
+  listAdminGrants,
+  revokeAdminGrantWithAudit,
+} from '#db/admin-grants.js';
+import {requireAdminRole} from './admin-role.js';
+import type {AdminGrant} from './entities/admin-grant.js';
+import {
+  AdminBootstrapClosedError,
+  AdminGrantAlreadyExistsError,
+  AdminGrantNotFoundError,
+  AdminIdempotencyKeyReuseError,
+  InvalidAdminBootstrapTokenError,
+  LastAdminOwnerError,
+  UserNotFoundError,
+} from './errors.js';
+
+const ADMIN_OWNER_ROLE: AdminRole = 'admin-owner';
+const BOOTSTRAP_COMMAND = 'auth.admin_grant.bootstrap';
+const GRANT_COMMAND = 'auth.admin_grant.grant';
+const REVOKE_COMMAND = 'auth.admin_grant.revoke';
+
+export function hashAdministrationValue(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+export function administrationCommandFingerprint(command: string, input: unknown): string {
+  return hashAdministrationValue(`${command}:${JSON.stringify(input)}`);
+}
+
+function bootstrapTokenMatches(candidate: string, expected: string | undefined): boolean {
+  if (!expected) return false;
+  const candidateHash = Buffer.from(hashAdministrationValue(candidate), 'hex');
+  const expectedHash = Buffer.from(hashAdministrationValue(expected), 'hex');
+  return timingSafeEqual(candidateHash, expectedHash);
+}
+
+function administrationEvent(params: {
+  actorId: string;
+  actorRole: AdminRole;
+  command: string;
+  targetType: string;
+  targetId: string;
+  reason: string;
+  correlationId: string;
+  idempotencyKeyFingerprint: string;
+}) {
+  return createAdministrationActionEvent({
+    actorId: params.actorId,
+    actorRole: params.actorRole,
+    requiredRole: ADMIN_OWNER_ROLE,
+    command: params.command,
+    targetType: params.targetType,
+    targetId: params.targetId,
+    reason: params.reason,
+    result: 'succeeded',
+    correlationId: params.correlationId,
+    idempotencyKeyFingerprint: params.idempotencyKeyFingerprint,
+    occurredAt: new Date().toISOString(),
+  });
+}
+
+export interface AdministrationMutationContext {
+  actorId: string;
+  idempotencyKey: string;
+  correlationId: string;
+}
+
+export async function bootstrapFirstAdminOwner(
+  params: AdministrationMutationContext & {bootstrapToken: string},
+): Promise<AdminGrant> {
+  if (!bootstrapTokenMatches(params.bootstrapToken, config.ADMIN_BOOTSTRAP_TOKEN)) {
+    throw new InvalidAdminBootstrapTokenError();
+  }
+
+  return await bootstrapFirstAdminOwnerInDb({
+    userId: params.actorId,
+    actorId: params.actorId,
+    idempotencyKeyFingerprint: hashAdministrationValue(params.idempotencyKey),
+    requestFingerprint: administrationCommandFingerprint(BOOTSTRAP_COMMAND, {
+      actorId: params.actorId,
+    }),
+    event: administrationEvent({
+      actorId: params.actorId,
+      actorRole: ADMIN_OWNER_ROLE,
+      command: BOOTSTRAP_COMMAND,
+      targetType: 'user',
+      targetId: params.actorId,
+      reason: 'Initial administrator owner bootstrap',
+      correlationId: params.correlationId,
+      idempotencyKeyFingerprint: hashAdministrationValue(params.idempotencyKey),
+    }),
+  });
+}
+
+export async function listAdministratorGrants(params: {actorId: string}): Promise<AdminGrant[]> {
+  await requireAdminRole({userId: params.actorId, minimumRole: ADMIN_OWNER_ROLE});
+  return await listAdminGrants();
+}
+
+export async function grantAdministratorRole(
+  params: AdministrationMutationContext & {userId: string; role: AdminRole; reason: string},
+): Promise<AdminGrant> {
+  const actorRole = await requireAdminRole({
+    userId: params.actorId,
+    minimumRole: ADMIN_OWNER_ROLE,
+  });
+  return await grantAdminRoleWithAudit({
+    userId: params.userId,
+    role: params.role,
+    actorId: params.actorId,
+    idempotencyKeyFingerprint: hashAdministrationValue(params.idempotencyKey),
+    requestFingerprint: administrationCommandFingerprint(GRANT_COMMAND, {
+      userId: params.userId,
+      role: params.role,
+      reason: params.reason,
+    }),
+    event: administrationEvent({
+      actorId: params.actorId,
+      actorRole,
+      command: GRANT_COMMAND,
+      targetType: 'user',
+      targetId: params.userId,
+      reason: params.reason,
+      correlationId: params.correlationId,
+      idempotencyKeyFingerprint: hashAdministrationValue(params.idempotencyKey),
+    }),
+  });
+}
+
+export async function revokeAdministratorGrant(
+  params: AdministrationMutationContext & {grantId: string; reason: string},
+): Promise<AdminGrant> {
+  const actorRole = await requireAdminRole({
+    userId: params.actorId,
+    minimumRole: ADMIN_OWNER_ROLE,
+  });
+  return await revokeAdminGrantWithAudit({
+    grantId: params.grantId,
+    actorId: params.actorId,
+    idempotencyKeyFingerprint: hashAdministrationValue(params.idempotencyKey),
+    requestFingerprint: administrationCommandFingerprint(REVOKE_COMMAND, {
+      grantId: params.grantId,
+      reason: params.reason,
+    }),
+    event: administrationEvent({
+      actorId: params.actorId,
+      actorRole,
+      command: REVOKE_COMMAND,
+      targetType: 'admin-grant',
+      targetId: params.grantId,
+      reason: params.reason,
+      correlationId: params.correlationId,
+      idempotencyKeyFingerprint: hashAdministrationValue(params.idempotencyKey),
+    }),
+  });
+}
+
+export {
+  AdminBootstrapClosedError,
+  AdminGrantAlreadyExistsError,
+  AdminGrantNotFoundError,
+  AdminIdempotencyKeyReuseError,
+  InvalidAdminBootstrapTokenError,
+  LastAdminOwnerError,
+  UserNotFoundError,
+};

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

@@ -0,0 +1,65 @@
+import {provisionUser, signup} from '#core/auth.js';
+
+const testConfig = vi.hoisted(() => ({
+  AUTH_JWT_EXPIRES_IN: '15m',
+  AUTH_REFRESH_TOKEN_EXPIRES_IN_DAYS: 14,
+  AUTH_REFRESH_ROTATION_GRACE_SECONDS: 30,
+  AUTH_REFRESH_COOKIE_NAME: 'shipfox_refresh_token',
+  AUTH_SIGNUP_GATE_ENABLED: true,
+  AUTH_SIGNUP_ALLOWED_EMAIL_DOMAINS: 'allowed.example',
+  AUTH_SIGNUP_ALLOWED_EMAILS: '',
+  AUTH_SIGNUP_NOT_ALLOWED_MESSAGE: undefined as string | undefined,
+  CLIENT_BASE_URL: 'https://app.example.test',
+}));
+
+vi.mock('#config.js', () => ({config: testConfig}));
+
+describe('low-level account creation defaults', () => {
+  test('signup uses the environment policy when no policy is supplied', async () => {
+    const email = `signup-default-${crypto.randomUUID()}@allowed.example`;
+
+    const user = await signup({email, password: 'correct horse battery staple'});
+
+    expect(user.email).toBe(email);
+  });
+
+  test('signup rejects an unlisted email when no policy is supplied', async () => {
+    const email = `signup-default-${crypto.randomUUID()}@blocked.example`;
+
+    await expect(signup({email, password: 'correct horse battery staple'})).rejects.toMatchObject({
+      name: 'SignupNotAllowedError',
+    });
+  });
+
+  test('provisionUser uses the environment policy when no policy is supplied', async () => {
+    const email = `provision-default-${crypto.randomUUID()}@allowed.example`;
+
+    const user = await provisionUser({email});
+
+    expect(user.email).toBe(email);
+  });
+
+  test('provisionUser rejects an unlisted email when no policy is supplied', async () => {
+    const email = `provision-default-${crypto.randomUUID()}@blocked.example`;
+
+    await expect(provisionUser({email})).rejects.toMatchObject({
+      name: 'SignupNotAllowedError',
+    });
+  });
+
+  test('an explicit policy overrides the environment policy for both paths', async () => {
+    const signupEmail = `signup-override-${crypto.randomUUID()}@blocked.example`;
+    const provisionEmail = `provision-override-${crypto.randomUUID()}@blocked.example`;
+    const isSignupAllowed = vi.fn().mockResolvedValue({allowed: true});
+    const signupPolicy = {isSignupAllowed};
+
+    await signup({
+      email: signupEmail,
+      password: 'correct horse battery staple',
+      signupPolicy,
+    });
+    await provisionUser({email: provisionEmail, signupPolicy});
+
+    expect(isSignupAllowed).toHaveBeenCalledTimes(2);
+  });
+});

package/src/core/auth.test.ts

@@ -61,6 +61,10 @@ vi.mock('#config.js', () => ({
     AUTH_REFRESH_TOKEN_EXPIRES_IN_DAYS: 14,
     AUTH_REFRESH_ROTATION_GRACE_SECONDS: 30,
     AUTH_REFRESH_COOKIE_NAME: 'shipfox_refresh_token',
+    AUTH_SIGNUP_GATE_ENABLED: false,
+    AUTH_SIGNUP_ALLOWED_EMAIL_DOMAINS: '',
+    AUTH_SIGNUP_ALLOWED_EMAILS: '',
+    AUTH_SIGNUP_NOT_ALLOWED_MESSAGE: undefined,
     CLIENT_BASE_URL: testConfig.clientBaseUrl,
   },
   mailer: testConfig.mailer,
@@ -77,6 +81,7 @@ const workspaces = {
   preflightInvitationAcceptance: vi.fn(),
   acceptInvitation: vi.fn(),
   requireActiveMembership: vi.fn(),
+  getWorkspaceOperatingState: vi.fn(),
 };
 
 const login = (params: {email: string; password: string}) => coreLogin({...params, workspaces});
@@ -160,6 +165,71 @@ describe('auth core', () => {
     await expect(promise).rejects.toBeInstanceOf(EmailTakenError);
   });
 
+  test('signup normalizes the email before checking the policy', async () => {
+    const email = `signup-policy-${crypto.randomUUID()}@example.com`;
+    const isSignupAllowed = vi.fn().mockResolvedValue({allowed: true});
+
+    await signup({
+      email: `  ${email.toUpperCase()}  `,
+      password: 'correct horse battery staple',
+      signupPolicy: {isSignupAllowed},
+    });
+
+    expect(isSignupAllowed).toHaveBeenCalledWith({
+      email,
+      emailVerified: false,
+      source: 'password',
+    });
+  });
+
+  test('signup denies a new user when the policy does not allow it', async () => {
+    const email = `signup-policy-denied-${crypto.randomUUID()}@example.com`;
+    const isSignupAllowed = vi.fn().mockResolvedValue({allowed: false});
+
+    await expect(
+      signup({
+        email,
+        password: 'correct horse battery staple',
+        signupPolicy: {isSignupAllowed},
+      }),
+    ).rejects.toEqual(
+      expect.objectContaining({
+        name: 'SignupNotAllowedError',
+        message: 'This Shipfox deployment does not accept new accounts right now.',
+      }),
+    );
+    expect(await findUserByEmail({email})).toBeUndefined();
+  });
+
+  test('signup fails closed when the policy throws', async () => {
+    const email = `signup-policy-error-${crypto.randomUUID()}@example.com`;
+    const policyError = new Error('policy unavailable');
+    const isSignupAllowed = vi.fn().mockRejectedValue(policyError);
+
+    await expect(
+      signup({
+        email,
+        password: 'correct horse battery staple',
+        signupPolicy: {isSignupAllowed},
+      }),
+    ).rejects.toBe(policyError);
+    expect(await findUserByEmail({email})).toBeUndefined();
+  });
+
+  test('signup does not check the policy for an existing user', async () => {
+    const existing = await userFactory.create({emailVerifiedAt: new Date()});
+    const isSignupAllowed = vi.fn().mockResolvedValue({allowed: false});
+
+    await expect(
+      signup({
+        email: `  ${existing.email.toUpperCase()}  `,
+        password: 'correct horse battery staple',
+        signupPolicy: {isSignupAllowed},
+      }),
+    ).rejects.toBeInstanceOf(EmailTakenError);
+    expect(isSignupAllowed).not.toHaveBeenCalled();
+  });
+
   test('signup with an invitation writes the signed-up event with its user insert', async () => {
     const email = `signup-invitation-${crypto.randomUUID()}@example.com`;
     const userId = crypto.randomUUID();
@@ -175,6 +245,9 @@ describe('auth core', () => {
       name: 'Invited User',
       invitationToken: `invite-${crypto.randomUUID()}`,
       workspaces,
+      signupPolicy: {
+        isSignupAllowed: vi.fn().mockRejectedValue(new Error('policy unavailable')),
+      },
     });
 
     const events = await outboxEventsTo(email, AUTH_USER_SIGNED_UP);
@@ -199,24 +272,66 @@ describe('auth core', () => {
     expect(user.status).toBe('active');
   });
 
+  test('provisionUser normalizes the email before checking the policy', async () => {
+    const email = `provision-policy-${crypto.randomUUID()}@example.com`;
+    const isSignupAllowed = vi.fn().mockResolvedValue({allowed: true});
+
+    await provisionUser({
+      email: `  ${email.toUpperCase()}  `,
+      signupPolicy: {isSignupAllowed},
+    });
+
+    expect(isSignupAllowed).toHaveBeenCalledWith({
+      email,
+      emailVerified: true,
+      source: 'external-identity',
+    });
+  });
+
+  test('provisionUser denies a new user when the policy does not allow it', async () => {
+    const email = `provision-policy-denied-${crypto.randomUUID()}@example.com`;
+    const isSignupAllowed = vi.fn().mockResolvedValue({allowed: false, message: 'Closed beta'});
+
+    await expect(provisionUser({email, signupPolicy: {isSignupAllowed}})).rejects.toEqual(
+      expect.objectContaining({
+        name: 'SignupNotAllowedError',
+        message: 'Closed beta',
+      }),
+    );
+    expect(await findUserByEmail({email})).toBeUndefined();
+  });
+
+  test('provisionUser fails closed when the policy throws', async () => {
+    const email = `provision-policy-error-${crypto.randomUUID()}@example.com`;
+    const policyError = new Error('policy unavailable');
+    const isSignupAllowed = vi.fn().mockRejectedValue(policyError);
+
+    await expect(provisionUser({email, signupPolicy: {isSignupAllowed}})).rejects.toBe(policyError);
+    expect(await findUserByEmail({email})).toBeUndefined();
+  });
+
   test('provisionUser returns existing unverified and suspended users unchanged', async () => {
     const unverified = await userFactory.create();
     const suspended = await userFactory.create({emailVerifiedAt: new Date()});
     await db().update(users).set({status: 'suspended'}).where(eq(users.id, suspended.id));
     const storedUnverified = await findUserById({id: unverified.id});
     const storedSuspended = await findUserById({id: suspended.id});
+    const isSignupAllowed = vi.fn().mockResolvedValue({allowed: false});
 
     const existingUnverified = await provisionUser({
       email: `  ${unverified.email.toUpperCase()}  `,
       name: 'Replacement Name',
+      signupPolicy: {isSignupAllowed},
     });
     const existingSuspended = await provisionUser({
       email: `  ${suspended.email.toUpperCase()}  `,
       name: 'Replacement Name',
+      signupPolicy: {isSignupAllowed},
     });
 
     expect(existingUnverified).toEqual(storedUnverified);
     expect(existingSuspended).toEqual(storedSuspended);
+    expect(isSignupAllowed).not.toHaveBeenCalled();
   });
 
   test('provisionUser returns one unchanged user for concurrent callbacks', async () => {