@shipfox/api-auth 10.0.0 → 10.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-auth",
   "license": "MIT",
-  "version": "10.0.0",
+  "version": "10.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -27,8 +27,8 @@
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
     "@shipfox/api-common-dto": "9.2.0",
-    "@shipfox/api-auth-context": "10.0.0",
-    "@shipfox/api-auth-dto": "10.0.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",

package/src/core/administration.ts

@@ -6,6 +6,7 @@ import {config} from '#config.js';
 import {
   bootstrapFirstAdminOwner as bootstrapFirstAdminOwnerInDb,
   grantAdminRoleWithAudit,
+  hasActiveAdminOwner,
   listAdminGrantSummaries,
   revokeAdminGrantWithAudit,
 } from '#db/admin-grants.js';
@@ -105,6 +106,10 @@ export async function bootstrapFirstAdminOwner(
   });
 }
 
+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> {

package/src/db/admin-grants.test.ts

@@ -1,7 +1,12 @@
 import {eq} from 'drizzle-orm';
 import {LastAdminOwnerError} from '#core/errors.js';
 import {userFactory} from '#test/index.js';
-import {createAdminGrant, findCurrentAdminRole, revokeAdminGrant} from './admin-grants.js';
+import {
+  createAdminGrant,
+  findCurrentAdminRole,
+  hasActiveAdminOwner,
+  revokeAdminGrant,
+} from './admin-grants.js';
 import {db} from './db.js';
 import {users} from './schema/users.js';
 
@@ -26,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

@@ -32,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;
@@ -111,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
@@ -126,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();
     }
 
@@ -252,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})
@@ -358,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/index.test.ts

@@ -78,7 +78,10 @@ describe('authModule', () => {
         getWorkspaceOperatingState: vi.fn(),
       },
     });
-    expect(module.routes).toHaveLength(3);
+    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

@@ -18,6 +18,7 @@ import {createRunnerSessionAuthMethod} from '#presentation/auth/runner-session-a
 import {createAuthE2eRoutes} from '#presentation/e2eRoutes/index.js';
 import {createAuthInterModulePresentation} from '#presentation/inter-module.js';
 import {
+  administrationBootstrapRoutes,
   administrationRoutes,
   administrationUserRoutes,
 } from '#presentation/routes/administration.js';
@@ -114,6 +115,7 @@ export function createAuthModule({
     loginMethods: passwordLoginMethods(config.AUTH_PASSWORD_ENABLED),
     routes: [
       buildAuthRoutes(config.AUTH_PASSWORD_ENABLED, workspaces, signupPolicy),
+      administrationBootstrapRoutes,
       administrationRoutes,
       administrationUserRoutes,
     ],

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

package/src/presentation/routes/administration.test.ts

@@ -1,8 +1,10 @@
 import {ADMINISTRATION_ACTION_PERFORMED} from '@shipfox/api-common-dto';
 import {sql} from 'drizzle-orm';
 import type {FastifyInstance} from 'fastify';
+import {type AuthRateLimitAction, hashAuthRateLimitIdentifier} from '#core/rate-limit.js';
 import {db} from '#db/db.js';
 import {authOutbox} from '#db/schema/outbox.js';
+import {authRateLimits} from '#db/schema/rate-limits.js';
 import {createAuthTestApp, createVerifiedSession, resetCapturedMail} from '#test/routes.js';
 
 const BOOTSTRAP_TOKEN = 'test-bootstrap-token';
@@ -20,6 +22,30 @@ function authHeaders(token: string, idempotencyKey: string) {
   };
 }
 
+async function seedExhaustedIpBucket(params: {
+  action: AuthRateLimitAction;
+  identifier: string;
+  limit: number;
+  windowSeconds: number;
+}): Promise<void> {
+  const windowMs = params.windowSeconds * 1000;
+  const windowStart = new Date(Math.floor(Date.now() / windowMs) * windowMs);
+  await db()
+    .insert(authRateLimits)
+    .values({
+      action: params.action,
+      scope: 'ip',
+      identifierHmac: hashAuthRateLimitIdentifier({
+        action: params.action,
+        scope: 'ip',
+        identifier: params.identifier,
+      }),
+      windowStart,
+      count: params.limit,
+      expiresAt: new Date(windowStart.getTime() + windowMs),
+    });
+}
+
 describe('Auth administration routes', () => {
   let app: FastifyInstance;
 
@@ -48,6 +74,78 @@ describe('Auth administration routes', () => {
     expect(response.statusCode).toBe(401);
   });
 
+  test('requires an authenticated session for bootstrap state', async () => {
+    const response = await app.inject({
+      method: 'GET',
+      url: '/admin/auth/bootstrap-state',
+    });
+
+    expect(response.statusCode).toBe(401);
+  });
+
+  test('reports only available or closed bootstrap state', async () => {
+    const account = await createVerifiedSession('admin-bootstrap-state');
+
+    const available = await app.inject({
+      method: 'GET',
+      url: '/admin/auth/bootstrap-state',
+      headers: {authorization: `Bearer ${account.token}`},
+    });
+
+    expect(available.statusCode).toBe(200);
+    expect(available.json()).toEqual({state: 'available'});
+
+    const bootstrap = await app.inject({
+      method: 'POST',
+      url: '/admin/auth/admin-grants/bootstrap',
+      headers: authHeaders(account.token, 'bootstrap-state-bootstrap'),
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+    expect(bootstrap.statusCode).toBe(201);
+
+    const closed = await app.inject({
+      method: 'GET',
+      url: '/admin/auth/bootstrap-state',
+      headers: {authorization: `Bearer ${account.token}`},
+    });
+
+    expect(closed.statusCode).toBe(200);
+    expect(closed.json()).toEqual({state: 'closed'});
+    expect(JSON.stringify(closed.json())).not.toContain(BOOTSTRAP_TOKEN);
+  });
+
+  test('keeps bootstrap-state reads separate from the bootstrap write limit', async () => {
+    const account = await createVerifiedSession('admin-bootstrap-state-rate-limit');
+    const ip = '127.0.0.1';
+
+    await seedExhaustedIpBucket({
+      action: 'bootstrap',
+      identifier: ip,
+      limit: 5,
+      windowSeconds: 15 * 60,
+    });
+    const state = await app.inject({
+      method: 'GET',
+      url: '/admin/auth/bootstrap-state',
+      headers: {authorization: `Bearer ${account.token}`},
+    });
+    expect(state.statusCode).toBe(200);
+
+    await resetAdministrationState();
+    await seedExhaustedIpBucket({
+      action: 'bootstrap-state',
+      identifier: ip,
+      limit: 60,
+      windowSeconds: 5 * 60,
+    });
+    const blocked = await app.inject({
+      method: 'GET',
+      url: '/admin/auth/bootstrap-state',
+      headers: {authorization: `Bearer ${account.token}`},
+    });
+    expect(blocked.statusCode).toBe(429);
+  });
+
   test('does not register the removed versioned administration namespace', async () => {
     const response = await app.inject({
       method: 'GET',
@@ -140,6 +238,36 @@ describe('Auth administration routes', () => {
     expect(JSON.stringify(events[0]?.payload)).not.toContain(BOOTSTRAP_TOKEN);
   });
 
+  test('serializes concurrent bootstrap attempts to one active first owner', async () => {
+    const first = await createVerifiedSession('admin-bootstrap-race-first');
+    const second = await createVerifiedSession('admin-bootstrap-race-second');
+
+    const responses = await Promise.all(
+      [first, second].map((account, index) =>
+        app.inject({
+          method: 'POST',
+          url: '/admin/auth/admin-grants/bootstrap',
+          headers: authHeaders(account.token, `bootstrap-race-${index}`),
+          payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+        }),
+      ),
+    );
+
+    expect(responses.map((response) => response.statusCode).sort()).toEqual([201, 409]);
+    const activeOwnerRoles = await Promise.all(
+      [first, second].map(async (account) => {
+        const response = await app.inject({
+          method: 'GET',
+          url: `/admin/auth/users?user_id=${account.userId}`,
+          headers: {authorization: `Bearer ${account.token}`},
+        });
+        return response.statusCode === 200 && response.json().admin_role === 'admin-owner';
+      }),
+    );
+
+    expect(activeOwnerRoles.filter(Boolean)).toHaveLength(1);
+  });
+
   test('lets an owner list, grant, and revoke roles with idempotent audited mutations', async () => {
     const owner = await createVerifiedSession('admin-grant-owner');
     const target = await createVerifiedSession('admin-grant-target');

package/src/presentation/routes/administration.ts

@@ -1,5 +1,6 @@
 import {AUTH_USER} from '@shipfox/api-auth-context';
 import {
+  adminBootstrapStateSchema,
   administratorUserLookupQuerySchema,
   administratorUserSummarySchema,
   bootstrapAdminOwnerBodySchema,
@@ -19,6 +20,7 @@ import {requireAdminRole} from '#core/admin-role.js';
 import {
   bootstrapFirstAdminOwner,
   findAdministratorUserSummary,
+  getAdminBootstrapState,
   grantAdministratorRole,
   listAdministratorGrantSummaries,
   revokeAdministratorGrant,
@@ -165,6 +167,16 @@ const bootstrapRoute = defineRoute({
   },
 });
 
+const bootstrapStateRoute = defineRoute({
+  method: 'GET',
+  path: '/bootstrap-state',
+  description: 'Read whether first administrator owner bootstrap is available.',
+  schema: {response: {200: adminBootstrapStateSchema}},
+  preHandler: createAuthIpRateLimitPreHandler('bootstrap-state'),
+  errorHandler: translateAdministrationError,
+  handler: async () => ({state: await getAdminBootstrapState()}),
+});
+
 const listRoute = defineRoute({
   method: 'GET',
   path: '/',
@@ -269,6 +281,12 @@ export const administrationRoutes: RouteGroup = {
   routes: [bootstrapRoute, listRoute, grantRoute, revokeRoute],
 };
 
+export const administrationBootstrapRoutes: RouteGroup = {
+  prefix: '/admin/auth',
+  auth: AUTH_USER,
+  routes: [bootstrapStateRoute],
+};
+
 export const administrationUserRoutes: RouteGroup = {
   prefix: '/admin/auth/users',
   auth: AUTH_USER,

package/src/presentation/routes/rate-limit.ts

@@ -23,6 +23,9 @@ const policies: Record<
   bootstrap: {
     ip: {limit: 5, windowSeconds: 15 * 60},
   },
+  'bootstrap-state': {
+    ip: {limit: 60, windowSeconds: 5 * 60},
+  },
   lookup: {
     ip: {limit: 60, windowSeconds: 5 * 60},
   },

package/test/routes.ts

@@ -9,6 +9,7 @@ import {db} from '#db/db.js';
 import {authOutbox} from '#db/schema/outbox.js';
 import {createJwtAuthMethod} from '#presentation/auth/jwt-auth.js';
 import {
+  administrationBootstrapRoutes,
   administrationRoutes,
   administrationUserRoutes,
 } from '#presentation/routes/administration.js';
@@ -156,7 +157,12 @@ export async function createAuthTestApp(params?: {
 }): Promise<FastifyInstance> {
   const appConfig: AppConfig = {
     auth: [createJwtAuthMethod()],
-    routes: [buildAuthRoutes(true, workspaces), administrationRoutes, administrationUserRoutes],
+    routes: [
+      buildAuthRoutes(true, workspaces),
+      administrationBootstrapRoutes,
+      administrationRoutes,
+      administrationUserRoutes,
+    ],
     swagger: false,
   };
   if (params?.fastifyOptions) appConfig.fastifyOptions = params.fastifyOptions;