@shipfox/api-auth 9.1.0 → 9.3.0

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,32 @@ import {
 } from './errors.js';
 import {signUserToken} from './jwt.js';
 import {hashPassword, verifyPassword} from './password.js';
+import type {SignupPolicy} from './ports.js';
+import {createEnvironmentSignupPolicy} from './signup-policy.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 = createEnvironmentSignupPolicy();
+
+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 +139,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 +182,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 +196,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 +218,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 +236,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 +336,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 +375,7 @@ export interface LoginResult {
   token: string;
   refreshToken: string;
   user: User;
+  adminRole: AdminRole | null;
 }
 
 export async function login(params: LoginParams): Promise<LoginResult> {
@@ -351,9 +399,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 +414,7 @@ export interface CreateSessionForUserResult {
   token: string;
   refreshToken: string;
   user: User;
+  adminRole: AdminRole | null;
 }
 
 export type CreateSessionForUserError =
@@ -393,9 +442,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 +452,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 +472,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 +480,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 +504,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 +543,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 +592,7 @@ export interface ConfirmPasswordResetResult {
   token: string;
   refreshToken: string;
   user: User;
+  adminRole: AdminRole | null;
 }
 
 export async function confirmPasswordReset(params: {
@@ -562,9 +618,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,58 @@ 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 AdminGrantNotFoundError extends Error {
+  constructor() {
+    super('Administrator grant not found');
+    this.name = 'AdminGrantNotFoundError';
+  }
+}
+
+export class AdminGrantAlreadyExistsError extends Error {
+  constructor() {
+    super('Administrator grant already exists');
+    this.name = 'AdminGrantAlreadyExistsError';
+  }
+}
+
+export class AdminBootstrapClosedError extends Error {
+  constructor() {
+    super('First administrator owner has already been created');
+    this.name = 'AdminBootstrapClosedError';
+  }
+}
+
+export class InvalidAdminBootstrapTokenError extends Error {
+  constructor() {
+    super('Bootstrap token is invalid');
+    this.name = 'InvalidAdminBootstrapTokenError';
+  }
+}
+
+export class AdminIdempotencyKeyReuseError extends Error {
+  constructor() {
+    super('Idempotency key was already used for a different command');
+    this.name = 'AdminIdempotencyKeyReuseError';
+  }
+}
+
 export class TokenInvalidError extends Error {
   constructor(reason?: string) {
     super(reason ? `Invalid token: ${reason}` : 'Invalid token');

package/src/core/jwt.test.ts

@@ -30,6 +30,7 @@ describe('jwt', () => {
     expect(claims.email).toBe(email);
     expect(claims.name).toBe('Token User');
     expect(claims.memberships).toEqual(memberships);
+    expect(claims).not.toHaveProperty('adminRole');
     expect(claims.iat).toBeTypeOf('number');
     expect(claims.exp).toBeGreaterThan(claims.iat);
   });

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