@shipfox/api-auth 9.2.0 → 10.0.0

package/src/db/admin-grants.ts

@@ -1,12 +1,38 @@
 import type {AdminRole} from '@shipfox/api-auth-dto';
-import {and, asc, eq, isNull, sql} from 'drizzle-orm';
+import type {
+  AdministrationActionEvent,
+  AdministrationActionEventMap,
+} from '@shipfox/api-common-dto';
+import {
+  paginateTimestampIdRows,
+  type TimestampIdCursor,
+  timestampIdCursorWhere,
+} from '@shipfox/node-drizzle';
+import {writeOutboxEvent} from '@shipfox/node-outbox';
+import {and, desc, 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 type {AdministratorGrantSummary} from '#core/entities/administrator-read-model.js';
+import {
+  AdminBootstrapClosedError,
+  AdminGrantAlreadyExistsError,
+  AdminGrantNotFoundError,
+  AdminIdempotencyKeyReuseError,
+  LastAdminOwnerError,
+  UserNotFoundError,
+} from '#core/errors.js';
 import {db} from './db.js';
+import {
+  type AdminCommandResultDb,
+  adminCommandResults,
+  type StoredAdminGrant,
+} from './schema/admin-command-results.js';
 import {adminGrants, toAdminGrant} from './schema/admin-grants.js';
+import {authOutbox} from './schema/outbox.js';
 import {users} from './schema/users.js';
 
+type Tx = Parameters<Parameters<ReturnType<typeof db>['transaction']>[0]>[0];
+
 export interface CreateAdminGrantParams {
   userId: string;
   role: AdminRole;
@@ -22,9 +48,51 @@ export async function createAdminGrant(params: CreateAdminGrantParams): Promise<
   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 interface AdministratorGrantSummaryRecord {
+  id: string;
+  role: AdminRole;
+  createdAt: Date;
+  revokedAt: Date | null;
+  user: AdministratorGrantSummary['user'];
+}
+
+export async function listAdminGrantSummaries(params: {
+  limit: number;
+  cursor?: TimestampIdCursor;
+}): Promise<{
+  rows: AdministratorGrantSummaryRecord[];
+  nextCursor: TimestampIdCursor | null;
+}> {
+  const cursorCondition = timestampIdCursorWhere({
+    timestampColumn: adminGrants.createdAt,
+    idColumn: adminGrants.id,
+    cursor: params.cursor,
+  });
+  const conditions = cursorCondition ? [cursorCondition] : [];
+  const rows = await db()
+    .select({
+      id: adminGrants.id,
+      role: adminGrants.role,
+      createdAt: adminGrants.createdAt,
+      revokedAt: adminGrants.revokedAt,
+      user: {
+        id: users.id,
+        email: users.email,
+        name: users.name,
+        status: users.status,
+      },
+    })
+    .from(adminGrants)
+    .innerJoin(users, eq(adminGrants.userId, users.id))
+    .where(and(...conditions))
+    .orderBy(desc(adminGrants.createdAt), desc(adminGrants.id))
+    .limit(params.limit + 1);
+
+  const page = paginateTimestampIdRows({rows, limit: params.limit, timestampKey: 'createdAt'});
+  return {
+    rows: page.pageRows,
+    nextCursor: page.nextCursor,
+  };
 }
 
 export async function findCurrentAdminRole(params: {userId: string}): Promise<AdminRole | null> {
@@ -81,3 +149,240 @@ export async function revokeAdminGrant(params: {grantId: string}): Promise<Admin
     return row ? toAdminGrant(row) : undefined;
   });
 }
+
+interface AuditedAdminCommandParams {
+  actorId: string;
+  idempotencyKeyFingerprint: string;
+  requestFingerprint: string;
+  event: AdministrationActionEvent;
+}
+
+function toStoredAdminGrant(grant: AdminGrant): StoredAdminGrant {
+  return {
+    id: grant.id,
+    userId: grant.userId,
+    role: grant.role,
+    revokedAt: grant.revokedAt?.toISOString() ?? null,
+    createdAt: grant.createdAt.toISOString(),
+    updatedAt: grant.updatedAt.toISOString(),
+  };
+}
+
+function fromStoredAdminGrant(grant: StoredAdminGrant): AdminGrant {
+  return {
+    id: grant.id,
+    userId: grant.userId,
+    role: grant.role,
+    revokedAt: grant.revokedAt ? new Date(grant.revokedAt) : null,
+    createdAt: new Date(grant.createdAt),
+    updatedAt: new Date(grant.updatedAt),
+  };
+}
+
+async function findCommandResult(
+  tx: Tx,
+  params: Pick<
+    AuditedAdminCommandParams,
+    'actorId' | 'idempotencyKeyFingerprint' | 'requestFingerprint'
+  > & {
+    command: string;
+  },
+): Promise<AdminGrant | undefined> {
+  const rows = await tx
+    .select()
+    .from(adminCommandResults)
+    .where(
+      and(
+        eq(adminCommandResults.actorId, params.actorId),
+        eq(adminCommandResults.idempotencyKeyFingerprint, params.idempotencyKeyFingerprint),
+      ),
+    )
+    .limit(1);
+  const result: AdminCommandResultDb | undefined = rows[0];
+  if (!result) return undefined;
+  if (
+    result.command !== params.command ||
+    result.requestFingerprint !== params.requestFingerprint
+  ) {
+    throw new AdminIdempotencyKeyReuseError();
+  }
+  return fromStoredAdminGrant(result.result.grant);
+}
+
+async function storeCommandResult(
+  tx: Tx,
+  params: AuditedAdminCommandParams,
+  grant: AdminGrant,
+): Promise<void> {
+  await tx.insert(adminCommandResults).values({
+    actorId: params.actorId,
+    idempotencyKeyFingerprint: params.idempotencyKeyFingerprint,
+    command: params.event.command,
+    requestFingerprint: params.requestFingerprint,
+    result: {grant: toStoredAdminGrant(grant)},
+  });
+}
+
+async function writeAdminAction(tx: Tx, event: AdministrationActionEvent): Promise<void> {
+  await writeOutboxEvent<AdministrationActionEventMap>(tx, authOutbox, {
+    type: 'administration.action.performed',
+    payload: event,
+  });
+}
+
+async function lockAdminCommand(
+  tx: Tx,
+  params: {actorId: string; idempotencyKeyFingerprint: string},
+) {
+  await tx.execute(
+    sql`select pg_advisory_xact_lock(hashtext(${`auth_admin_command:${params.actorId}:${params.idempotencyKeyFingerprint}`}))`,
+  );
+}
+
+export async function bootstrapFirstAdminOwner(
+  params: AuditedAdminCommandParams & {userId: string},
+): Promise<AdminGrant> {
+  return await db().transaction(async (tx) => {
+    await lockAdminCommand(tx, params);
+    await tx.execute(sql`select pg_advisory_xact_lock(hashtext('auth_admin_owner_grants'))`);
+
+    const existing = await findCommandResult(tx, {
+      ...params,
+      command: params.event.command,
+    });
+    if (existing) return existing;
+
+    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'),
+        ),
+      )
+      .limit(1);
+    if (activeOwners.length > 0) throw new AdminBootstrapClosedError();
+
+    const userRows = await tx
+      .select({id: users.id, status: users.status})
+      .from(users)
+      .where(eq(users.id, params.userId))
+      .limit(1);
+    const user = userRows[0];
+    if (user?.status !== 'active') throw new UserNotFoundError(params.userId);
+
+    const rows = await tx
+      .insert(adminGrants)
+      .values({userId: params.userId, role: 'admin-owner'})
+      .returning();
+    const row = rows[0];
+    if (!row) throw new Error('Bootstrap grant insert returned no rows');
+
+    const grant = toAdminGrant(row);
+    await writeAdminAction(tx, params.event);
+    await storeCommandResult(tx, params, grant);
+    return grant;
+  });
+}
+
+export async function grantAdminRoleWithAudit(
+  params: AuditedAdminCommandParams & {userId: string; role: AdminRole},
+): Promise<AdminGrant> {
+  return await db().transaction(async (tx) => {
+    await lockAdminCommand(tx, params);
+    await tx.execute(sql`select pg_advisory_xact_lock(hashtext('auth_admin_owner_grants'))`);
+
+    const existing = await findCommandResult(tx, {
+      ...params,
+      command: params.event.command,
+    });
+    if (existing) return existing;
+
+    const userRows = await tx
+      .select({id: users.id, status: users.status})
+      .from(users)
+      .where(eq(users.id, params.userId))
+      .limit(1);
+    const user = userRows[0];
+    if (user?.status !== 'active') throw new UserNotFoundError(params.userId);
+
+    const activeRows = await tx
+      .select({id: adminGrants.id})
+      .from(adminGrants)
+      .where(
+        and(
+          eq(adminGrants.userId, params.userId),
+          eq(adminGrants.role, params.role),
+          isNull(adminGrants.revokedAt),
+        ),
+      )
+      .limit(1);
+    if (activeRows.length > 0) throw new AdminGrantAlreadyExistsError();
+
+    const rows = await tx
+      .insert(adminGrants)
+      .values({userId: params.userId, role: params.role})
+      .returning();
+    const row = rows[0];
+    if (!row) throw new Error('Administrator grant insert returned no rows');
+
+    const grant = toAdminGrant(row);
+    await writeAdminAction(tx, params.event);
+    await storeCommandResult(tx, params, grant);
+    return grant;
+  });
+}
+
+export async function revokeAdminGrantWithAudit(
+  params: AuditedAdminCommandParams & {grantId: string},
+): Promise<AdminGrant> {
+  return await db().transaction(async (tx) => {
+    await lockAdminCommand(tx, params);
+    await tx.execute(sql`select pg_advisory_xact_lock(hashtext('auth_admin_owner_grants'))`);
+
+    const existing = await findCommandResult(tx, {
+      ...params,
+      command: params.event.command,
+    });
+    if (existing) return existing;
+
+    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) throw new AdminGrantNotFoundError();
+
+    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 updatedRow = updated[0];
+    if (!updatedRow) throw new AdminGrantNotFoundError();
+
+    const revoked = toAdminGrant(updatedRow);
+    await writeAdminAction(tx, params.event);
+    await storeCommandResult(tx, params, revoked);
+    return revoked;
+  });
+}

package/src/db/admin-users.ts

@@ -0,0 +1,58 @@
+import type {AdminRole} from '@shipfox/api-auth-dto';
+import {and, eq, isNull} from 'drizzle-orm';
+import {highestAdminRole} from '#core/admin-role-model.js';
+import type {UserStatus} from '#core/entities/user.js';
+import {db} from './db.js';
+import {adminGrants} from './schema/admin-grants.js';
+import {users} from './schema/users.js';
+
+export interface AdministratorUserRecord {
+  id: string;
+  email: string;
+  name: string | null;
+  emailVerifiedAt: Date | null;
+  status: UserStatus;
+  createdAt: Date;
+  adminRole: AdminRole | null;
+}
+
+type AdministratorUserLookup = {id: string; email?: never} | {email: string; id?: never};
+
+export async function findAdministratorUser(
+  params: AdministratorUserLookup,
+): Promise<AdministratorUserRecord | undefined> {
+  const identifier = 'id' in params ? eq(users.id, params.id) : eq(users.email, params.email);
+  const rows = await db()
+    .select({
+      id: users.id,
+      email: users.email,
+      name: users.name,
+      emailVerifiedAt: users.emailVerifiedAt,
+      status: users.status,
+      createdAt: users.createdAt,
+      adminRole: adminGrants.role,
+    })
+    .from(users)
+    .leftJoin(
+      adminGrants,
+      and(
+        eq(adminGrants.userId, users.id),
+        isNull(adminGrants.revokedAt),
+        eq(users.status, 'active'),
+      ),
+    )
+    .where(identifier);
+
+  const first = rows[0];
+  if (!first) return undefined;
+
+  return {
+    id: first.id,
+    email: first.email,
+    name: first.name,
+    emailVerifiedAt: first.emailVerifiedAt,
+    status: first.status,
+    createdAt: first.createdAt,
+    adminRole: highestAdminRole(rows.flatMap(({adminRole}) => (adminRole ? [adminRole] : []))),
+  };
+}

package/src/db/db.ts

@@ -1,5 +1,6 @@
 import {drizzle, type NodePgDatabase} from '@shipfox/node-drizzle';
 import {pgClient} from '@shipfox/node-postgres';
+import {adminCommandResults} from './schema/admin-command-results.js';
 import {adminGrants} from './schema/admin-grants.js';
 import {authOutbox} from './schema/outbox.js';
 import {passwordResets} from './schema/password-resets.js';
@@ -9,6 +10,7 @@ import {users} from './schema/users.js';
 
 export const schema = {
   adminGrants,
+  adminCommandResults,
   users,
   passwordResets,
   refreshTokens,

package/src/db/schema/admin-command-results.ts

@@ -0,0 +1,41 @@
+import type {AdminRole} from '@shipfox/api-auth-dto';
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {jsonb, text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
+import {pgTable} from './common.js';
+import {users} from './users.js';
+
+export interface StoredAdminGrant {
+  id: string;
+  userId: string;
+  role: AdminRole;
+  revokedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface StoredAdminCommandResult {
+  grant: StoredAdminGrant;
+}
+
+export const adminCommandResults = pgTable(
+  'admin_command_results',
+  {
+    id: uuidv7PrimaryKey(),
+    actorId: uuid('actor_id')
+      .notNull()
+      .references(() => users.id, {onDelete: 'cascade'}),
+    idempotencyKeyFingerprint: text('idempotency_key_fingerprint').notNull(),
+    command: text('command').notNull(),
+    requestFingerprint: text('request_fingerprint').notNull(),
+    result: jsonb('result').$type<StoredAdminCommandResult>().notNull(),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('auth_admin_command_results_actor_key_unique').on(
+      table.actorId,
+      table.idempotencyKeyFingerprint,
+    ),
+  ],
+);
+
+export type AdminCommandResultDb = typeof adminCommandResults.$inferSelect;

package/src/index.test.ts

@@ -3,6 +3,7 @@ import {
   AUTH_USER_SIGNED_UP,
   authEventSchemas,
 } from '@shipfox/api-auth-dto';
+import {ADMINISTRATION_ACTION_PERFORMED} from '@shipfox/api-common-dto';
 import {createAuthModule} from './index.js';
 import {passwordLoginMethods} from './login-methods.js';
 
@@ -55,6 +56,7 @@ describe('authModule', () => {
       preflightInvitationAcceptance: vi.fn(),
       acceptInvitation: vi.fn(),
       requireActiveMembership: vi.fn(),
+      getWorkspaceOperatingState: vi.fn(),
     },
     signupPolicy,
   });
@@ -73,9 +75,10 @@ describe('authModule', () => {
         preflightInvitationAcceptance: vi.fn(),
         acceptInvitation: vi.fn(),
         requireActiveMembership: vi.fn(),
+        getWorkspaceOperatingState: vi.fn(),
       },
     });
-    expect(module.routes).toHaveLength(1);
+    expect(module.routes).toHaveLength(3);
     const signupPolicy = buildAuthRoutes.mock.calls[0]?.[2];
 
     expect(signupPolicy).toEqual(expect.objectContaining({isSignupAllowed: expect.any(Function)}));
@@ -95,8 +98,9 @@ describe('authModule', () => {
     const publisher = authModule.publishers?.find((pub) => pub.name === 'auth');
     const events = authModule.subscribers?.map((subscriber) => subscriber.event);
 
-    expect(publisher?.eventSchemas).toBe(authEventSchemas);
+    expect(publisher?.eventSchemas).not.toBe(authEventSchemas);
     expect(Object.keys(publisher?.eventSchemas ?? {}).sort()).toEqual([
+      ADMINISTRATION_ACTION_PERFORMED,
       AUTH_PASSWORD_RESET_SEND_REQUESTED,
       AUTH_USER_SIGNED_UP,
     ]);

package/src/index.ts

@@ -3,6 +3,7 @@ import {
   type AuthEventMap,
   authEventSchemas,
 } from '@shipfox/api-auth-dto';
+import {administrationActionEventSchemas} from '@shipfox/api-common-dto';
 import type {ShipfoxModule} from '@shipfox/node-module';
 import {subscriberFactory} from '@shipfox/node-module';
 import {config} from '#config.js';
@@ -16,10 +17,16 @@ import {createLeaseTokenAuthMethod} from '#presentation/auth/lease-token-auth.js
 import {createRunnerSessionAuthMethod} from '#presentation/auth/runner-session-auth.js';
 import {createAuthE2eRoutes} from '#presentation/e2eRoutes/index.js';
 import {createAuthInterModulePresentation} from '#presentation/inter-module.js';
+import {
+  administrationRoutes,
+  administrationUserRoutes,
+} from '#presentation/routes/administration.js';
 import {buildAuthRoutes} from '#presentation/routes/index.js';
 import {onPasswordResetSendRequested} from '#presentation/subscribers/index.js';
 import {passwordLoginMethods} from './login-methods.js';
 
+const authPublisherEventSchemas = {...authEventSchemas, ...administrationActionEventSchemas};
+
 export type {AdminRole, JobLeaseTokenClaims, RunnerSessionTokenClaims} from '@shipfox/api-auth-dto';
 export {
   ADMIN_ROLES,
@@ -29,6 +36,11 @@ export {
   requireAdminRole,
   revokeAdminGrant,
 } from '#core/admin-role.js';
+export {
+  bootstrapFirstAdminOwner,
+  grantAdministratorRole,
+  revokeAdministratorGrant,
+} from '#core/administration.js';
 export type {
   CreateSessionForUserError,
   CreateSessionForUserParams,
@@ -41,9 +53,14 @@ 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 {
+  AdminBootstrapClosedError,
+  AdminGrantAlreadyExistsError,
+  AdminGrantNotFoundError,
+  AdminIdempotencyKeyReuseError,
   AdminRoleRequiredError,
   AuthDependencyUnavailableError,
   EmailNotVerifiedError,
+  InvalidAdminBootstrapTokenError,
   InvalidCredentialsError,
   LastAdminOwnerError,
   SignupNotAllowedError,
@@ -95,9 +112,13 @@ export function createAuthModule({
     database: {db, migrationsPath, databaseNamespace: 'auth'},
     auth: [createJwtAuthMethod(), createLeaseTokenAuthMethod(), createRunnerSessionAuthMethod()],
     loginMethods: passwordLoginMethods(config.AUTH_PASSWORD_ENABLED),
-    routes: [buildAuthRoutes(config.AUTH_PASSWORD_ENABLED, workspaces, signupPolicy)],
+    routes: [
+      buildAuthRoutes(config.AUTH_PASSWORD_ENABLED, workspaces, signupPolicy),
+      administrationRoutes,
+      administrationUserRoutes,
+    ],
     e2eRoutes: [createAuthE2eRoutes(workspaces)],
-    publishers: [{name: 'auth', table: authOutbox, db, eventSchemas: authEventSchemas}],
+    publishers: [{name: 'auth', table: authOutbox, db, eventSchemas: authPublisherEventSchemas}],
     subscribers: [subscriber(AUTH_PASSWORD_RESET_SEND_REQUESTED, onPasswordResetSendRequested)],
     interModulePresentations: [createAuthInterModulePresentation()],
   };

package/src/metrics/instance.ts

@@ -3,7 +3,7 @@ import {instanceMetrics} from '@shipfox/node-opentelemetry';
 export type AuthTokenType = 'session' | 'job_lease' | 'runner_session';
 export type AuthTokenVerificationOutcome = 'ok' | 'rejected';
 export type AuthTokenRefreshOutcome = 'rotated' | 'grace' | 'rejected';
-export type AuthRateLimitAction = 'login' | 'email-send';
+export type AuthRateLimitAction = 'login' | 'email-send' | 'bootstrap' | 'lookup';
 export type AuthRateLimitScope = 'ip' | 'email';
 export type AuthRateLimitOutcome = 'allowed' | 'blocked' | 'unavailable';
 

package/src/presentation/auth/refresh-cookie.test.ts

@@ -6,6 +6,10 @@ vi.mock('#config.js', () => ({
     AUTH_REFRESH_COOKIE_NAME: 'shipfox_refresh_token',
     AUTH_REFRESH_TOKEN_EXPIRES_IN_DAYS: 14,
     AUTH_PASSWORD_ENABLED: true,
+    AUTH_SIGNUP_GATE_ENABLED: false,
+    AUTH_SIGNUP_ALLOWED_EMAIL_DOMAINS: '',
+    AUTH_SIGNUP_ALLOWED_EMAILS: '',
+    AUTH_SIGNUP_NOT_ALLOWED_MESSAGE: undefined,
   },
 }));
 

package/src/presentation/e2eRoutes/index.test.ts

@@ -14,6 +14,7 @@ describe('auth E2E routes', () => {
           preflightInvitationAcceptance: vi.fn(),
           acceptInvitation: vi.fn(),
           requireActiveMembership: vi.fn(),
+          getWorkspaceOperatingState: vi.fn(),
         }),
       ],
       swagger: false,