@shipfox/api-auth 9.0.3 → 9.2.0

package/drizzle/meta/_journal.json

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-auth",
   "license": "MIT",
-  "version": "9.0.3",
+  "version": "9.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -26,17 +26,17 @@
     "@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.2",
-    "@shipfox/api-workspaces-dto": "9.0.2",
+    "@shipfox/api-auth-context": "9.2.0",
+    "@shipfox/api-auth-dto": "9.2.0",
+    "@shipfox/api-email-challenges": "1.1.4",
+    "@shipfox/api-workspaces-dto": "9.2.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-jwt": "0.3.2",
-    "@shipfox/node-email": "0.3.3",
+    "@shipfox/node-email": "0.3.4",
     "@shipfox/node-mailer": "0.2.3",
     "@shipfox/node-module": "1.0.2",
     "@shipfox/node-opentelemetry": "0.6.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

@@ -29,8 +29,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/auth.test.ts

@@ -160,6 +160,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 +240,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 +267,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 () => {

package/src/core/auth.ts

@@ -1,4 +1,4 @@
-import {emailSchema} from '@shipfox/api-auth-dto';
+import {type AdminRole, emailSchema} from '@shipfox/api-auth-dto';
 import {
   confirmEmailChallenge,
   consumeEmailChallengeProof,
@@ -31,6 +31,7 @@ import {
   updateUserPassword,
 } from '#db/users.js';
 import {type AuthTokenRefreshOutcome, recordTokenRefreshed} from '#metrics/index.js';
+import {getCurrentAdminRole} from './admin-role.js';
 import type {RefreshToken} from './entities/refresh-token.js';
 import type {User} from './entities/user.js';
 import {
@@ -39,6 +40,7 @@ import {
   EmailTakenError,
   InvalidCredentialsError,
   InvitationEmailMismatchError,
+  SignupNotAllowedError,
   TokenAlreadyUsedError,
   TokenExpiredError,
   TokenInvalidError,
@@ -46,9 +48,33 @@ import {
 } from './errors.js';
 import {signUserToken} from './jwt.js';
 import {hashPassword, verifyPassword} from './password.js';
+import type {SignupPolicy} from './ports.js';
 
 const RESET_TTL_HOURS = 1;
 const PASSWORD_VERIFICATION_PURPOSE = 'password-verification';
+const DEFAULT_SIGNUP_NOT_ALLOWED_MESSAGE =
+  'This Shipfox deployment does not accept new accounts right now.';
+
+const defaultSignupPolicy: SignupPolicy = {
+  isSignupAllowed: async () => ({allowed: true}),
+};
+
+async function assertSignupAllowed(params: {
+  signupPolicy?: SignupPolicy | undefined;
+  email: string;
+  emailVerified: boolean;
+  source: string;
+}): Promise<void> {
+  const result = await (params.signupPolicy ?? defaultSignupPolicy).isSignupAllowed({
+    email: params.email,
+    emailVerified: params.emailVerified,
+    source: params.source,
+  });
+
+  if (!result.allowed) {
+    throw new SignupNotAllowedError(result.message ?? DEFAULT_SIGNUP_NOT_ALLOWED_MESSAGE);
+  }
+}
 
 let dummyHashCache: string | undefined;
 async function getDummyHash(): Promise<string> {
@@ -114,11 +140,12 @@ async function createRefreshSession(
 async function createSessionTokens(
   user: User,
   workspaces: WorkspacesInterModuleClient,
-): Promise<{token: string; refreshToken: string}> {
+): Promise<{token: string; refreshToken: string; adminRole: AdminRole | null}> {
   const refreshSessionId = crypto.randomUUID();
   const token = await signAccessToken(user, workspaces, refreshSessionId);
+  const adminRole = await getCurrentAdminRole({userId: user.id});
   const {refreshToken} = await createRefreshSession(user, refreshSessionId);
-  return {token, refreshToken};
+  return {token, refreshToken, adminRole};
 }
 
 function passwordResetLink(rawToken: string): string {
@@ -156,11 +183,13 @@ export interface SignupParams {
   email: string;
   password: string;
   name?: string | undefined;
+  signupPolicy?: SignupPolicy | undefined;
 }
 
 export interface ProvisionUserParams {
   email: string;
   name?: string | null | undefined;
+  signupPolicy?: SignupPolicy | undefined;
 }
 
 /**
@@ -168,8 +197,19 @@ export interface ProvisionUserParams {
  * Existing users are returned unchanged, including their password and profile.
  */
 export async function provisionUser(params: ProvisionUserParams): Promise<User> {
+  const email = emailSchema.parse(params.email);
+  const existing = await findUserByEmail({email});
+  if (existing) return existing;
+
+  await assertSignupAllowed({
+    signupPolicy: params.signupPolicy,
+    email,
+    emailVerified: true,
+    source: 'external-identity',
+  });
+
   return await provisionDbUser({
-    email: emailSchema.parse(params.email),
+    email,
     name: params.name ?? null,
   });
 }
@@ -179,7 +219,8 @@ export type SignupResult = User & {
 };
 
 export async function signup(params: SignupParams & {sourceIp?: string}): Promise<SignupResult> {
-  const existing = await findUserByEmail({email: params.email});
+  const email = emailSchema.parse(params.email);
+  const existing = await findUserByEmail({email});
   if (existing) {
     const canResumeVerification =
       existing.status === 'active' &&
@@ -196,12 +237,19 @@ export async function signup(params: SignupParams & {sourceIp?: string}): Promis
       });
       return {...existing, emailChallenge};
     }
-    throw new EmailTakenError(params.email);
+    throw new EmailTakenError(email);
   }
 
+  await assertSignupAllowed({
+    signupPolicy: params.signupPolicy,
+    email,
+    emailVerified: false,
+    source: 'password',
+  });
+
   const hashedPassword = await hashPassword({password: params.password});
   const user = await createDbUser({
-    email: params.email,
+    email,
     hashedPassword,
     name: params.name ?? null,
     signedUp: {viaInvitation: false},
@@ -289,12 +337,12 @@ export async function signupWithInvitation(
 
   // Step 4: Issue session. signAccessToken reads memberships through the
   // workspaces module API, so a successful accept is reflected in the JWT.
-  const {token, refreshToken} = await createSessionTokens(user, params.workspaces);
+  const {token, refreshToken, adminRole} = await createSessionTokens(user, params.workspaces);
 
   if (acceptError) {
-    return {token, refreshToken, user, membership, acceptError};
+    return {token, refreshToken, user, membership, acceptError, adminRole};
   }
-  return {token, refreshToken, user, membership};
+  return {token, refreshToken, user, membership, adminRole};
 }
 
 export interface CreateUserParams extends SignupParams {
@@ -328,6 +376,7 @@ export interface LoginResult {
   token: string;
   refreshToken: string;
   user: User;
+  adminRole: AdminRole | null;
 }
 
 export async function login(params: LoginParams): Promise<LoginResult> {
@@ -351,9 +400,9 @@ export async function login(params: LoginParams): Promise<LoginResult> {
     throw new EmailNotVerifiedError();
   }
 
-  const {token, refreshToken} = await createSessionTokens(user, params.workspaces);
+  const {token, refreshToken, adminRole} = await createSessionTokens(user, params.workspaces);
 
-  return {token, refreshToken, user};
+  return {token, refreshToken, user, adminRole};
 }
 
 export interface CreateSessionForUserParams {
@@ -366,6 +415,7 @@ export interface CreateSessionForUserResult {
   token: string;
   refreshToken: string;
   user: User;
+  adminRole: AdminRole | null;
 }
 
 export type CreateSessionForUserError =
@@ -393,9 +443,9 @@ export async function createSessionForUser(
     throw new InvalidCredentialsError();
   }
 
-  const {token, refreshToken} = await createSessionTokens(user, params.workspaces);
+  const {token, refreshToken, adminRole} = await createSessionTokens(user, params.workspaces);
 
-  return {token, refreshToken, user};
+  return {token, refreshToken, user, adminRole};
 }
 
 export interface RefreshAccessTokenResult {
@@ -403,6 +453,7 @@ export interface RefreshAccessTokenResult {
   /** Undefined on a grace-window hit: keep the existing cookie instead of rotating it. */
   refreshToken: string | undefined;
   user: User;
+  adminRole: AdminRole | null;
 }
 
 export async function refreshAccessToken(params: {
@@ -422,6 +473,7 @@ export async function refreshAccessToken(params: {
     recordRefreshOutcome('rejected');
     throw new TokenInvalidError('Refresh token is invalid or expired');
   }
+  const adminRole = await getCurrentAdminRole({userId: user.id});
 
   // Within the grace window a rotated token means a concurrent refresh (e.g. a
   // second tab); past it, reuse of a retired token means a compromised session.
@@ -429,7 +481,7 @@ export async function refreshAccessToken(params: {
     if (isWithinRotationGrace(current)) {
       const token = await signAccessToken(user, params.workspaces, current.sessionId);
       recordRefreshOutcome('grace');
-      return {token, refreshToken: undefined, user};
+      return {token, refreshToken: undefined, user, adminRole};
     }
     await revokeRefreshTokensForUser({userId: user.id});
     recordRefreshOutcome('rejected');
@@ -453,18 +505,19 @@ export async function refreshAccessToken(params: {
     }
     const token = await signAccessToken(user, params.workspaces, latest.sessionId);
     recordRefreshOutcome('grace');
-    return {token, refreshToken: undefined, user};
+    return {token, refreshToken: undefined, user, adminRole};
   }
 
   const token = await signAccessToken(user, params.workspaces, current.sessionId);
   recordRefreshOutcome('rotated');
-  return {token, refreshToken: nextRefreshToken, user};
+  return {token, refreshToken: nextRefreshToken, user, adminRole};
 }
 
 export interface ConfirmEmailVerificationResult {
   token: string;
   refreshToken: string;
   user: User;
+  adminRole: AdminRole | null;
 }
 
 export interface ResendEmailVerificationResult {
@@ -491,9 +544,12 @@ export async function confirmEmailVerification(params: {
     throw new TokenInvalidError('Verification code is invalid or expired');
   }
 
-  const {token, refreshToken} = await createSessionTokens(verifiedUser, params.workspaces);
+  const {token, refreshToken, adminRole} = await createSessionTokens(
+    verifiedUser,
+    params.workspaces,
+  );
 
-  return {token, refreshToken, user: verifiedUser};
+  return {token, refreshToken, user: verifiedUser, adminRole};
 }
 
 export async function resendEmailVerification(params: {
@@ -537,6 +593,7 @@ export interface ConfirmPasswordResetResult {
   token: string;
   refreshToken: string;
   user: User;
+  adminRole: AdminRole | null;
 }
 
 export async function confirmPasswordReset(params: {
@@ -562,9 +619,9 @@ export async function confirmPasswordReset(params: {
 
   await revokeRefreshTokensForUser({userId: consumed.userId});
 
-  const {token, refreshToken} = await createSessionTokens(user, params.workspaces);
+  const {token, refreshToken, adminRole} = await createSessionTokens(user, params.workspaces);
 
-  return {token, refreshToken, user};
+  return {token, refreshToken, user, adminRole};
 }
 
 export async function changePassword(params: {

package/src/core/entities/admin-grant.ts

@@ -0,0 +1,10 @@
+import type {AdminRole} from '@shipfox/api-auth-dto';
+
+export interface AdminGrant {
+  id: string;
+  userId: string;
+  role: AdminRole;
+  revokedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}

package/src/core/errors.ts

@@ -47,6 +47,13 @@ export class EmailTakenError extends Error {
   }
 }
 
+export class SignupNotAllowedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SignupNotAllowedError';
+  }
+}
+
 export class InvalidCredentialsError extends Error {
   constructor() {
     super('Invalid credentials');
@@ -73,6 +80,23 @@ export class AuthDependencyUnavailableError extends Error {
   }
 }
 
+export class AdminRoleRequiredError extends Error {
+  readonly minimumRole: import('@shipfox/api-auth-dto').AdminRole;
+
+  constructor(minimumRole: import('@shipfox/api-auth-dto').AdminRole) {
+    super(`Administrator role required: ${minimumRole}`);
+    this.name = 'AdminRoleRequiredError';
+    this.minimumRole = minimumRole;
+  }
+}
+
+export class LastAdminOwnerError extends Error {
+  constructor() {
+    super('Cannot remove the final active administrator owner');
+    this.name = 'LastAdminOwnerError';
+  }
+}
+
 export class TokenInvalidError extends Error {
   constructor(reason?: string) {
     super(reason ? `Invalid token: ${reason}` : 'Invalid token');