@shipfox/api-auth 10.0.0 → 10.2.0

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

@@ -1,9 +1,20 @@
 import {ADMINISTRATION_ACTION_PERFORMED} from '@shipfox/api-common-dto';
-import {sql} from 'drizzle-orm';
+import {eq, 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 {createAuthTestApp, createVerifiedSession, resetCapturedMail} from '#test/routes.js';
+import {authRateLimits} from '#db/schema/rate-limits.js';
+import {refreshTokens} from '#db/schema/refresh-tokens.js';
+import {users} from '#db/schema/users.js';
+import {
+  cookieHeader,
+  createAuthTestApp,
+  createVerifiedSession,
+  getSetCookie,
+  login,
+  resetCapturedMail,
+} from '#test/routes.js';
 
 const BOOTSTRAP_TOKEN = 'test-bootstrap-token';
 
@@ -20,6 +31,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 +83,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 +247,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');
@@ -534,4 +671,238 @@ describe('Auth administration routes', () => {
     expect(finalOwnerRevoke.statusCode).toBe(409);
     expect(finalOwnerRevoke.json().code).toBe('last-owner');
   });
+
+  test('suspends users, invalidates sessions, and reactivates without restoring them', async () => {
+    const owner = await createVerifiedSession('admin-user-moderation-owner');
+    const target = await createVerifiedSession('admin-user-moderation-target');
+
+    await app.inject({
+      method: 'POST',
+      url: '/admin/auth/admin-grants/bootstrap',
+      headers: authHeaders(owner.token, 'moderation-bootstrap'),
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+    await app.inject({
+      method: 'POST',
+      url: '/admin/auth/admin-grants',
+      headers: authHeaders(owner.token, 'moderation-grant'),
+      payload: {
+        user_id: owner.userId,
+        role: 'admin-operator',
+        reason: 'User moderation access',
+      },
+    });
+
+    const rotatedBeforeSuspension = await app.inject({
+      method: 'POST',
+      url: '/auth/refresh',
+      headers: {cookie: target.refreshCookie},
+      payload: {},
+    });
+    expect(rotatedBeforeSuspension.statusCode).toBe(200);
+    const rotatedRefreshCookie = cookieHeader(getSetCookie(rotatedBeforeSuspension));
+
+    const suspended = await app.inject({
+      method: 'POST',
+      url: `/admin/auth/users/${target.userId}/suspend`,
+      headers: authHeaders(owner.token, 'suspend-user'),
+      payload: {reason: 'Account security review'},
+    });
+
+    expect(suspended.statusCode).toBe(200);
+    expect(suspended.json()).toMatchObject({
+      id: target.userId,
+      status: 'suspended',
+      admin_role: null,
+      correlation_id: expect.any(String),
+    });
+
+    const suspendedMe = await app.inject({
+      method: 'GET',
+      url: '/auth/me',
+      headers: {authorization: `Bearer ${target.token}`},
+    });
+    const suspendedLogin = await login(app, {email: target.email, password: target.password});
+    expect(suspendedMe.statusCode).toBe(401);
+    expect(suspendedLogin.statusCode).toBe(401);
+
+    const suspendedDbUser = (
+      await db().select({status: users.status}).from(users).where(eq(users.id, target.userId))
+    )[0];
+    const targetSessions = await db()
+      .select({sessionId: refreshTokens.sessionId, revokedAt: refreshTokens.revokedAt})
+      .from(refreshTokens)
+      .where(eq(refreshTokens.userId, target.userId));
+    expect(suspendedDbUser?.status).toBe('suspended');
+    expect(targetSessions).toHaveLength(2);
+    expect(targetSessions.every(({revokedAt}) => revokedAt instanceof Date)).toBe(true);
+
+    const suspendedRefresh = await app.inject({
+      method: 'POST',
+      url: '/auth/refresh',
+      headers: {cookie: rotatedRefreshCookie},
+      payload: {},
+    });
+    expect(suspendedRefresh.statusCode).toBe(401);
+
+    const suspensionEvent = (await db().select().from(authOutbox)).find(
+      (event) =>
+        event.eventType === ADMINISTRATION_ACTION_PERFORMED &&
+        (event.payload as {command?: string}).command === 'auth.user.suspend',
+    );
+    expect(suspensionEvent?.payload).toMatchObject({
+      actorId: owner.userId,
+      actorRole: 'admin-owner',
+      requiredRole: 'admin-operator',
+      targetId: target.userId,
+      reason: 'Account security review',
+      result: 'succeeded',
+    });
+    expect(JSON.stringify(suspensionEvent?.payload)).not.toContain('suspend-user');
+    expect(JSON.stringify(suspensionEvent?.payload)).not.toContain(target.password);
+
+    const repeatedSuspension = await app.inject({
+      method: 'POST',
+      url: `/admin/auth/users/${target.userId}/suspend`,
+      headers: authHeaders(owner.token, 'suspend-user'),
+      payload: {reason: 'Account security review'},
+    });
+    expect(repeatedSuspension.statusCode).toBe(200);
+    expect(repeatedSuspension.json().correlation_id).toBe(suspended.json().correlation_id);
+
+    const reusedSuspensionKey = await app.inject({
+      method: 'POST',
+      url: `/admin/auth/users/${target.userId}/suspend`,
+      headers: authHeaders(owner.token, 'suspend-user'),
+      payload: {reason: 'A different reason'},
+    });
+    expect(reusedSuspensionKey.statusCode).toBe(409);
+    expect(reusedSuspensionKey.json().code).toBe('idempotency-key-reused');
+
+    const reactivated = await app.inject({
+      method: 'POST',
+      url: `/admin/auth/users/${target.userId}/reactivate`,
+      headers: authHeaders(owner.token, 'reactivate-user'),
+      payload: {},
+    });
+    expect(reactivated.statusCode).toBe(200);
+    expect(reactivated.json()).toMatchObject({
+      id: target.userId,
+      status: 'active',
+      correlation_id: expect.any(String),
+    });
+
+    const oldRefreshAfterReactivation = await app.inject({
+      method: 'POST',
+      url: '/auth/refresh',
+      headers: {cookie: target.refreshCookie},
+      payload: {},
+    });
+    expect(oldRefreshAfterReactivation.statusCode).toBe(401);
+    const rotatedRefreshAfterReactivation = await app.inject({
+      method: 'POST',
+      url: '/auth/refresh',
+      headers: {cookie: rotatedRefreshCookie},
+      payload: {},
+    });
+    expect(rotatedRefreshAfterReactivation.statusCode).toBe(401);
+
+    const newLogin = await login(app, {email: target.email, password: target.password});
+    expect(newLogin.statusCode).toBe(200);
+    const secondLogin = await login(app, {email: target.email, password: target.password});
+    expect(secondLogin.statusCode).toBe(200);
+
+    const revoked = await app.inject({
+      method: 'POST',
+      url: `/admin/auth/users/${target.userId}/revoke-sessions`,
+      headers: authHeaders(owner.token, 'revoke-user-sessions'),
+      payload: {reason: 'End all active sessions'},
+    });
+    expect(revoked.statusCode).toBe(200);
+    expect(revoked.json()).toMatchObject({
+      id: target.userId,
+      status: 'active',
+      sessions_revoked: 2,
+      correlation_id: expect.any(String),
+    });
+
+    const newRefresh = await app.inject({
+      method: 'POST',
+      url: '/auth/refresh',
+      headers: {cookie: cookieHeader(getSetCookie(newLogin))},
+      payload: {},
+    });
+    expect(newRefresh.statusCode).toBe(401);
+    const secondRefresh = await app.inject({
+      method: 'POST',
+      url: '/auth/refresh',
+      headers: {cookie: cookieHeader(getSetCookie(secondLogin))},
+      payload: {},
+    });
+    expect(secondRefresh.statusCode).toBe(401);
+
+    const repeatedRevoke = await app.inject({
+      method: 'POST',
+      url: `/admin/auth/users/${target.userId}/revoke-sessions`,
+      headers: authHeaders(owner.token, 'revoke-user-sessions'),
+      payload: {reason: 'End all active sessions'},
+    });
+    expect(repeatedRevoke.statusCode).toBe(200);
+    expect(repeatedRevoke.json().sessions_revoked).toBe(2);
+    expect(repeatedRevoke.json().correlation_id).toBe(revoked.json().correlation_id);
+  });
+
+  test('protects the final active owner from suspension', async () => {
+    const owner = await createVerifiedSession('admin-suspend-final-owner');
+
+    await app.inject({
+      method: 'POST',
+      url: '/admin/auth/admin-grants/bootstrap',
+      headers: authHeaders(owner.token, 'suspend-final-bootstrap'),
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+
+    const suspended = await app.inject({
+      method: 'POST',
+      url: `/admin/auth/users/${owner.userId}/suspend`,
+      headers: authHeaders(owner.token, 'suspend-final-owner'),
+      payload: {reason: 'Attempt to suspend final owner'},
+    });
+
+    expect(suspended.statusCode).toBe(409);
+    expect(suspended.json().code).toBe('last-owner');
+  });
+
+  test('rejects user moderation by an observer', async () => {
+    const owner = await createVerifiedSession('admin-moderation-role-owner');
+    const observer = await createVerifiedSession('admin-moderation-role-observer');
+    const target = await createVerifiedSession('admin-moderation-role-target');
+
+    await app.inject({
+      method: 'POST',
+      url: '/admin/auth/admin-grants/bootstrap',
+      headers: authHeaders(owner.token, 'moderation-role-bootstrap'),
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+    await app.inject({
+      method: 'POST',
+      url: '/admin/auth/admin-grants',
+      headers: authHeaders(owner.token, 'moderation-role-grant'),
+      payload: {
+        user_id: observer.userId,
+        role: 'admin-observer',
+        reason: 'Read-only administration access',
+      },
+    });
+
+    const response = await app.inject({
+      method: 'POST',
+      url: `/admin/auth/users/${target.userId}/suspend`,
+      headers: authHeaders(observer.token, 'moderation-role-suspend'),
+      payload: {reason: 'Observer should not mutate users'},
+    });
+
+    expect(response.statusCode).toBe(403);
+    expect(response.json().code).toBe('forbidden');
+  });
 });

package/src/presentation/routes/administration.ts

@@ -1,6 +1,8 @@
 import {AUTH_USER} from '@shipfox/api-auth-context';
 import {
+  adminBootstrapStateSchema,
   administratorUserLookupQuerySchema,
+  administratorUserMutationResponseSchema,
   administratorUserSummarySchema,
   bootstrapAdminOwnerBodySchema,
   bootstrapAdminOwnerResponseSchema,
@@ -8,8 +10,12 @@ import {
   grantAdminRoleResponseSchema,
   listAdminGrantsQuerySchema,
   listAdminGrantsResponseSchema,
+  reactivateAdministratorUserBodySchema,
   revokeAdminGrantBodySchema,
   revokeAdminGrantResponseSchema,
+  revokeAdministratorUserSessionsBodySchema,
+  revokeAdministratorUserSessionsResponseSchema,
+  suspendAdministratorUserBodySchema,
 } from '@shipfox/api-auth-dto';
 import {decodeTimestampIdCursor, encodeTimestampIdCursor} from '@shipfox/node-drizzle';
 import {ClientError, defineRoute, type RouteGroup} from '@shipfox/node-fastify';
@@ -19,9 +25,13 @@ import {requireAdminRole} from '#core/admin-role.js';
 import {
   bootstrapFirstAdminOwner,
   findAdministratorUserSummary,
+  getAdminBootstrapState,
   grantAdministratorRole,
   listAdministratorGrantSummaries,
+  reactivateAdministratorUser,
   revokeAdministratorGrant,
+  revokeAdministratorUserSessions,
+  suspendAdministratorUser,
 } from '#core/administration.js';
 import type {AdminGrant} from '#core/entities/admin-grant.js';
 import type {
@@ -99,6 +109,16 @@ function toAdministratorGrantSummaryDto(grant: AdministratorGrantSummary) {
   };
 }
 
+function toAdministratorUserMutationDto(result: {
+  user: AdministratorUserSummary;
+  correlationId: string;
+}) {
+  return {
+    ...toAdministratorUserSummaryDto(result.user),
+    correlation_id: result.correlationId,
+  };
+}
+
 function translateAdministrationError(error: unknown): never {
   if (error instanceof AdminRoleRequiredError) {
     throw new ClientError('Administrator role required', 'forbidden', {
@@ -165,6 +185,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: '/',
@@ -217,6 +247,75 @@ const userLookupRoute = defineRoute({
   },
 });
 
+const suspendUserRoute = defineRoute({
+  method: 'POST',
+  path: '/:userId/suspend',
+  description: 'Suspend a user and revoke all of its active sessions.',
+  schema: {
+    params: z.object({userId: z.string().uuid()}),
+    body: suspendAdministratorUserBodySchema,
+    response: {200: administratorUserMutationResponseSchema},
+  },
+  errorHandler: translateAdministrationError,
+  handler: async (request) => {
+    const result = await suspendAdministratorUser({
+      actorId: requireActorId(request),
+      userId: request.params.userId,
+      reason: request.body.reason,
+      idempotencyKey: requireIdempotencyKey(request),
+      correlationId: request.id,
+    });
+    return toAdministratorUserMutationDto(result);
+  },
+});
+
+const reactivateUserRoute = defineRoute({
+  method: 'POST',
+  path: '/:userId/reactivate',
+  description: 'Reactivate a suspended user without restoring revoked sessions.',
+  schema: {
+    params: z.object({userId: z.string().uuid()}),
+    body: reactivateAdministratorUserBodySchema,
+    response: {200: administratorUserMutationResponseSchema},
+  },
+  errorHandler: translateAdministrationError,
+  handler: async (request) => {
+    const result = await reactivateAdministratorUser({
+      actorId: requireActorId(request),
+      userId: request.params.userId,
+      ...(request.body.reason ? {reason: request.body.reason} : {}),
+      idempotencyKey: requireIdempotencyKey(request),
+      correlationId: request.id,
+    });
+    return toAdministratorUserMutationDto(result);
+  },
+});
+
+const revokeUserSessionsRoute = defineRoute({
+  method: 'POST',
+  path: '/:userId/revoke-sessions',
+  description: 'Revoke all active sessions for a user without changing account status.',
+  schema: {
+    params: z.object({userId: z.string().uuid()}),
+    body: revokeAdministratorUserSessionsBodySchema,
+    response: {200: revokeAdministratorUserSessionsResponseSchema},
+  },
+  errorHandler: translateAdministrationError,
+  handler: async (request) => {
+    const result = await revokeAdministratorUserSessions({
+      actorId: requireActorId(request),
+      userId: request.params.userId,
+      ...(request.body.reason ? {reason: request.body.reason} : {}),
+      idempotencyKey: requireIdempotencyKey(request),
+      correlationId: request.id,
+    });
+    return {
+      ...toAdministratorUserMutationDto(result),
+      sessions_revoked: result.sessionsRevoked,
+    };
+  },
+});
+
 const grantRoute = defineRoute({
   method: 'POST',
   path: '/',
@@ -269,8 +368,14 @@ 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,
-  routes: [userLookupRoute],
+  routes: [userLookupRoute, suspendUserRoute, reactivateUserRoute, revokeUserSessionsRoute],
 };

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;