@shipfox/api-auth 9.2.0 → 10.0.0

package/drizzle/meta/_journal.json

@@ -15,6 +15,13 @@
       "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.2.0",
+  "version": "10.0.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.2.0",
-    "@shipfox/api-auth-dto": "9.2.0",
-    "@shipfox/api-email-challenges": "1.1.4",
-    "@shipfox/api-workspaces-dto": "9.2.0",
+    "@shipfox/api-common-dto": "9.2.0",
+    "@shipfox/api-auth-context": "10.0.0",
+    "@shipfox/api-auth-dto": "10.0.0",
+    "@shipfox/api-email-challenges": "1.1.6",
+    "@shipfox/api-workspaces-dto": "10.0.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.4.0",
     "@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.4",
+    "@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.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',

package/src/core/administration.ts

@@ -0,0 +1,213 @@
+import {createHash, timingSafeEqual} from 'node:crypto';
+import type {AdminRole} from '@shipfox/api-auth-dto';
+import {createAdministrationActionEvent} from '@shipfox/api-common-dto';
+import type {TimestampIdCursor} from '@shipfox/node-drizzle';
+import {config} from '#config.js';
+import {
+  bootstrapFirstAdminOwner as bootstrapFirstAdminOwnerInDb,
+  grantAdminRoleWithAudit,
+  listAdminGrantSummaries,
+  revokeAdminGrantWithAudit,
+} from '#db/admin-grants.js';
+import {findAdministratorUser as findAdministratorUserInDb} from '#db/admin-users.js';
+import {requireAdminRole} from './admin-role.js';
+import type {AdminGrant} from './entities/admin-grant.js';
+import type {
+  AdministratorGrantSummary,
+  AdministratorUserSummary,
+} from './entities/administrator-read-model.js';
+import {
+  AdminBootstrapClosedError,
+  AdminGrantAlreadyExistsError,
+  AdminGrantNotFoundError,
+  AdminIdempotencyKeyReuseError,
+  InvalidAdminBootstrapTokenError,
+  LastAdminOwnerError,
+  UserNotFoundError,
+} from './errors.js';
+
+const ADMIN_OWNER_ROLE: AdminRole = 'admin-owner';
+const ADMIN_OBSERVER_ROLE: AdminRole = 'admin-observer';
+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 findAdministratorUserSummary(
+  params: {actorId: string} & ({id: string; email?: never} | {email: string; id?: never}),
+): Promise<AdministratorUserSummary | undefined> {
+  await requireAdminRole({userId: params.actorId, minimumRole: ADMIN_OBSERVER_ROLE});
+
+  const user = await findAdministratorUserInDb(
+    'id' in params ? {id: params.id} : {email: params.email},
+  );
+  if (!user) return undefined;
+
+  return user;
+}
+
+export async function listAdministratorGrantSummaries(params: {
+  actorId: string;
+  limit: number;
+  cursor?: TimestampIdCursor;
+}): Promise<{
+  grants: AdministratorGrantSummary[];
+  nextCursor: TimestampIdCursor | null;
+}> {
+  await requireAdminRole({userId: params.actorId, minimumRole: ADMIN_OBSERVER_ROLE});
+
+  const result = await listAdminGrantSummaries({
+    limit: params.limit,
+    ...(params.cursor ? {cursor: params.cursor} : {}),
+  });
+  return {
+    grants: result.rows.map((row) => ({
+      grantId: row.id,
+      role: row.role,
+      createdAt: row.createdAt,
+      revokedAt: row.revokedAt,
+      user: row.user,
+    })),
+    nextCursor: result.nextCursor,
+  };
+}
+
+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});

package/src/core/auth.ts

@@ -49,15 +49,14 @@ import {
 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 = {
-  isSignupAllowed: async () => ({allowed: true}),
-};
+const defaultSignupPolicy: SignupPolicy = createEnvironmentSignupPolicy();
 
 async function assertSignupAllowed(params: {
   signupPolicy?: SignupPolicy | undefined;

package/src/core/entities/administrator-read-model.ts

@@ -0,0 +1,23 @@
+import type {AdminRole} from '@shipfox/api-auth-dto';
+import type {UserStatus} from './user.js';
+
+export interface AdministratorUserIdentity {
+  id: string;
+  email: string;
+  name: string | null;
+  status: UserStatus;
+}
+
+export interface AdministratorUserSummary extends AdministratorUserIdentity {
+  emailVerifiedAt: Date | null;
+  createdAt: Date;
+  adminRole: AdminRole | null;
+}
+
+export interface AdministratorGrantSummary {
+  grantId: string;
+  role: AdminRole;
+  createdAt: Date;
+  revokedAt: Date | null;
+  user: AdministratorUserIdentity;
+}

package/src/core/errors.ts

@@ -97,6 +97,41 @@ export class LastAdminOwnerError extends Error {
   }
 }
 
+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/db/admin-grants.test.ts

@@ -1,12 +1,7 @@
 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 {createAdminGrant, findCurrentAdminRole, revokeAdminGrant} from './admin-grants.js';
 import {db} from './db.js';
 import {users} from './schema/users.js';
 
@@ -18,7 +13,6 @@ describe('admin grants db', () => {
 
     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 () => {