@shipfox/api-auth 9.3.0 → 10.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-auth",
   "license": "MIT",
-  "version": "9.3.0",
+  "version": "10.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -27,19 +27,19 @@
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
     "@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/api-auth-context": "10.1.0",
+    "@shipfox/api-auth-dto": "10.1.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.4",
+    "@shipfox/node-fastify": "0.4.0",
     "@shipfox/node-jwt": "0.3.2",
     "@shipfox/node-email": "0.3.4",
     "@shipfox/node-mailer": "0.2.4",
-    "@shipfox/node-module": "1.0.3",
+    "@shipfox/node-module": "1.0.4",
     "@shipfox/node-opentelemetry": "0.6.3",
     "@shipfox/node-outbox": "0.2.6",
     "@shipfox/node-postgres": "0.4.4",

package/src/core/administration.ts

@@ -1,15 +1,22 @@
 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,
-  listAdminGrants,
+  hasActiveAdminOwner,
+  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,
@@ -21,6 +28,7 @@ import {
 } 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';
@@ -98,9 +106,47 @@ export async function bootstrapFirstAdminOwner(
   });
 }
 
-export async function listAdministratorGrants(params: {actorId: string}): Promise<AdminGrant[]> {
-  await requireAdminRole({userId: params.actorId, minimumRole: ADMIN_OWNER_ROLE});
-  return await listAdminGrants();
+export async function getAdminBootstrapState(): Promise<'available' | 'closed'> {
+  return (await hasActiveAdminOwner()) ? 'closed' : 'available';
+}
+
+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(

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/db/admin-grants.test.ts

@@ -4,7 +4,7 @@ import {userFactory} from '#test/index.js';
 import {
   createAdminGrant,
   findCurrentAdminRole,
-  listAdminGrants,
+  hasActiveAdminOwner,
   revokeAdminGrant,
 } from './admin-grants.js';
 import {db} from './db.js';
@@ -18,7 +18,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 () => {
@@ -32,6 +31,17 @@ describe('admin grants db', () => {
     expect(await findCurrentAdminRole({userId: user.id})).toBeNull();
   });
 
+  test('reopens bootstrap when the sole owner user is suspended', async () => {
+    const user = await userFactory.create({emailVerifiedAt: new Date()});
+    await createAdminGrant({userId: user.id, role: 'admin-owner'});
+
+    await expect(hasActiveAdminOwner()).resolves.toBe(true);
+
+    await db().update(users).set({status: 'suspended'}).where(eq(users.id, user.id));
+
+    await expect(hasActiveAdminOwner()).resolves.toBe(false);
+  });
+
   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()});

package/src/db/admin-grants.ts

@@ -3,10 +3,16 @@ 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, asc, eq, isNull, sql} from 'drizzle-orm';
+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 type {AdministratorGrantSummary} from '#core/entities/administrator-read-model.js';
 import {
   AdminBootstrapClosedError,
   AdminGrantAlreadyExistsError,
@@ -26,6 +32,24 @@ import {authOutbox} from './schema/outbox.js';
 import {users} from './schema/users.js';
 
 type Tx = Parameters<Parameters<ReturnType<typeof db>['transaction']>[0]>[0];
+type AdminOwnerQueryExecutor = ReturnType<typeof db> | Tx;
+
+function activeAdminOwnerWhere() {
+  return and(
+    eq(adminGrants.role, 'admin-owner'),
+    isNull(adminGrants.revokedAt),
+    eq(users.status, 'active'),
+  );
+}
+
+async function listActiveAdminOwners(executor: AdminOwnerQueryExecutor) {
+  return await executor
+    .select({id: adminGrants.id})
+    .from(adminGrants)
+    .innerJoin(users, eq(adminGrants.userId, users.id))
+    .where(activeAdminOwnerWhere())
+    .limit(2);
+}
 
 export interface CreateAdminGrantParams {
   userId: string;
@@ -42,9 +66,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> {
@@ -63,6 +129,18 @@ export async function findCurrentAdminRole(params: {userId: string}): Promise<Ad
   return highestAdminRole(rows.map(({role}) => role));
 }
 
+/**
+ * An owner is active only while both the grant and its user account remain
+ * active. A suspended owner's grant is retained, but it intentionally does
+ * not prevent deployment-bound bootstrap recovery.
+ */
+export async function hasActiveAdminOwner(
+  executor: AdminOwnerQueryExecutor = db(),
+): Promise<boolean> {
+  const rows = await listActiveAdminOwners(executor);
+  return rows.length > 0;
+}
+
 export async function revokeAdminGrant(params: {grantId: string}): Promise<AdminGrant | undefined> {
   return await db().transaction(async (tx) => {
     // All owner grant changes share one lock so concurrent revocations cannot
@@ -78,17 +156,7 @@ export async function revokeAdminGrant(params: {grantId: string}): Promise<Admin
     if (!grant) return undefined;
 
     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'),
-          ),
-        );
+      const activeOwners = await listActiveAdminOwners(tx);
       if (activeOwners.length <= 1) throw new LastAdminOwnerError();
     }
 
@@ -204,19 +272,7 @@ export async function bootstrapFirstAdminOwner(
     });
     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();
+    if (await hasActiveAdminOwner(tx)) throw new AdminBootstrapClosedError();
 
     const userRows = await tx
       .select({id: users.id, status: users.status})
@@ -310,17 +366,7 @@ export async function revokeAdminGrantWithAudit(
     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'),
-          ),
-        );
+      const activeOwners = await listActiveAdminOwners(tx);
       if (activeOwners.length <= 1) throw new LastAdminOwnerError();
     }
 

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/index.test.ts

@@ -78,7 +78,10 @@ describe('authModule', () => {
         getWorkspaceOperatingState: vi.fn(),
       },
     });
-    expect(module.routes).toHaveLength(2);
+    expect(module.routes).toHaveLength(4);
+    expect(module.routes).toEqual(
+      expect.arrayContaining([expect.objectContaining({prefix: '/admin/auth'})]),
+    );
     const signupPolicy = buildAuthRoutes.mock.calls[0]?.[2];
 
     expect(signupPolicy).toEqual(expect.objectContaining({isSignupAllowed: expect.any(Function)}));

package/src/index.ts

@@ -17,7 +17,11 @@ 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} from '#presentation/routes/administration.js';
+import {
+  administrationBootstrapRoutes,
+  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';
@@ -36,7 +40,6 @@ export {
 export {
   bootstrapFirstAdminOwner,
   grantAdministratorRole,
-  listAdministratorGrants,
   revokeAdministratorGrant,
 } from '#core/administration.js';
 export type {
@@ -112,7 +115,9 @@ export function createAuthModule({
     loginMethods: passwordLoginMethods(config.AUTH_PASSWORD_ENABLED),
     routes: [
       buildAuthRoutes(config.AUTH_PASSWORD_ENABLED, workspaces, signupPolicy),
+      administrationBootstrapRoutes,
       administrationRoutes,
+      administrationUserRoutes,
     ],
     e2eRoutes: [createAuthE2eRoutes(workspaces)],
     publishers: [{name: 'auth', table: authOutbox, db, eventSchemas: authPublisherEventSchemas}],

package/src/metrics/instance.ts

@@ -3,7 +3,12 @@ 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' | 'bootstrap';
+export type AuthRateLimitAction =
+  | 'login'
+  | 'email-send'
+  | 'bootstrap'
+  | 'bootstrap-state'
+  | 'lookup';
 export type AuthRateLimitScope = 'ip' | 'email';
 export type AuthRateLimitOutcome = 'allowed' | 'blocked' | 'unavailable';