@shipfox/api-auth 13.1.0 → 17.0.0

package/src/presentation/routes/administration.ts

@@ -1,4 +1,9 @@
-import {AUTH_USER} from '@shipfox/api-auth-context';
+import {randomUUID} from 'node:crypto';
+import {
+  AUTH_USER,
+  adoptAdministrationActorGuard,
+  requireAdministrationActor,
+} from '@shipfox/api-auth-context';
 import {
   adminBootstrapStateSchema,
   administratorUserLookupQuerySchema,
@@ -8,6 +13,8 @@ import {
   bootstrapAdminOwnerResponseSchema,
   grantAdminRoleBodySchema,
   grantAdminRoleResponseSchema,
+  impersonateResponseSchema,
+  impersonateUserBodySchema,
   listAdminGrantsQuerySchema,
   listAdminGrantsResponseSchema,
   reactivateAdministratorUserBodySchema,
@@ -17,6 +24,7 @@ import {
   revokeAdministratorUserSessionsResponseSchema,
   suspendAdministratorUserBodySchema,
 } from '@shipfox/api-auth-dto';
+import type {WorkspacesInterModuleClient} from '@shipfox/api-workspaces-dto/inter-module';
 import {decodeTimestampIdCursor, encodeTimestampIdCursor} from '@shipfox/node-drizzle';
 import {ClientError, defineRoute, type RouteGroup} from '@shipfox/node-fastify';
 import type {FastifyRequest} from 'fastify';
@@ -27,6 +35,7 @@ import {
   findAdministratorUserSummary,
   getAdminBootstrapState,
   grantAdministratorRole,
+  impersonateUser,
   listAdministratorGrantSummaries,
   reactivateAdministratorUser,
   revokeAdministratorGrant,
@@ -44,12 +53,20 @@ import {
   AdminGrantNotFoundError,
   AdminIdempotencyKeyReuseError,
   AdminRoleRequiredError,
+  CannotImpersonateAdministratorError,
+  CannotImpersonateSelfError,
+  EmailNotVerifiedError,
+  ImpersonationDisabledError,
+  ImpersonationExpiredError,
+  ImpersonationTargetNotActiveError,
   InvalidAdminBootstrapTokenError,
+  InvalidCredentialsError,
   LastAdminOwnerError,
   UserNotFoundError,
 } from '#core/errors.js';
 import {getClientContext} from '#presentation/auth/jwt-auth.js';
-import {createAuthIpRateLimitPreHandler} from './rate-limit.js';
+import {toUserDto} from '#presentation/dto/user.js';
+import {createAuthActorRateLimitPreHandler, createAuthIpRateLimitPreHandler} from './rate-limit.js';
 
 const idempotencyKeyMaxLength = 256;
 
@@ -159,6 +176,40 @@ function translateAdministrationError(error: unknown): never {
       {status: 409},
     );
   }
+  if (error instanceof ImpersonationDisabledError) {
+    throw new ClientError('Impersonation is disabled', 'impersonation-disabled', {status: 403});
+  }
+  if (error instanceof CannotImpersonateSelfError) {
+    throw new ClientError('Cannot impersonate yourself', 'cannot-impersonate-self', {
+      status: 403,
+    });
+  }
+  if (error instanceof CannotImpersonateAdministratorError) {
+    throw new ClientError(
+      'Cannot impersonate an administrator',
+      'cannot-impersonate-administrator',
+      {status: 403},
+    );
+  }
+  if (error instanceof ImpersonationTargetNotActiveError) {
+    throw new ClientError('User cannot be impersonated', 'impersonation-target-not-active', {
+      status: 403,
+    });
+  }
+  // The mint primitive re-checks login eligibility (active, verified) on the
+  // row it reads, and a concurrent suspension or unverification between the
+  // in-transaction ladder read and that read surfaces these errors. Map them
+  // to the same documented client error instead of a generic 500.
+  if (error instanceof EmailNotVerifiedError || error instanceof InvalidCredentialsError) {
+    throw new ClientError('User cannot be impersonated', 'impersonation-target-not-active', {
+      status: 403,
+    });
+  }
+  if (error instanceof ImpersonationExpiredError) {
+    throw new ClientError('Impersonation session has expired', 'impersonation-expired', {
+      status: 410,
+    });
+  }
   throw error;
 }
 
@@ -362,20 +413,88 @@ const revokeRoute = defineRoute({
   },
 });
 
-export const administrationRoutes: RouteGroup = {
+export const administrationRoutes: RouteGroup = adoptAdministrationActorGuard({
   prefix: '/admin/auth/admin-grants',
   auth: AUTH_USER,
   routes: [bootstrapRoute, listRoute, grantRoute, revokeRoute],
-};
+});
 
-export const administrationBootstrapRoutes: RouteGroup = {
+export const administrationBootstrapRoutes: RouteGroup = adoptAdministrationActorGuard({
   prefix: '/admin/auth',
   auth: AUTH_USER,
   routes: [bootstrapStateRoute],
-};
+});
 
-export const administrationUserRoutes: RouteGroup = {
-  prefix: '/admin/auth/users',
-  auth: AUTH_USER,
-  routes: [userLookupRoute, suspendUserRoute, reactivateUserRoute, revokeUserSessionsRoute],
-};
+function createImpersonateUserRoute(workspaces: WorkspacesInterModuleClient) {
+  return defineRoute({
+    method: 'POST',
+    path: '/:userId/impersonate',
+    description:
+      'Mint a short-lived, marked, audited impersonated session for an active, verified, non-administrator user.',
+    schema: {
+      params: z.object({userId: z.string().uuid()}),
+      body: impersonateUserBodySchema,
+      response: {200: impersonateResponseSchema},
+    },
+    // The limiter runs ahead of the impersonated-session rejection: a request
+    // carrying an already-issued impersonated token must consume the
+    // `impersonate` IP and actor buckets instead of being rejected by the
+    // guard first, or marked-session probes would bypass the limiter entirely.
+    // The guard still runs before the authorization inside the command.
+    preHandler: [
+      createAuthActorRateLimitPreHandler('impersonate'),
+      (request) => {
+        requireAdministrationActor(request);
+        return undefined;
+      },
+    ],
+    errorHandler: translateAdministrationError,
+    handler: async (request) => {
+      const client = getClientContext(request);
+      const result = await impersonateUser({
+        actorId: requireActorId(request),
+        ...(client?.impersonatorId ? {actorImpersonatorId: client.impersonatorId} : {}),
+        targetUserId: request.params.userId,
+        reason: request.body.reason,
+        idempotencyKey: requireIdempotencyKey(request),
+        // Fastify's default request IDs are process-local counters that reset
+        // after a redeploy, so a replay could collide with an earlier mint's
+        // ID and suppress the required failure event in the ambiguous-COMMIT
+        // reconciliation. The correlation is a fresh process-independent UUID
+        // per invocation.
+        correlationId: randomUUID(),
+        workspaces,
+      });
+      // `server_time` is the issuer's clock at response time: the banner
+      // derives its countdown and Extend availability from this anchor.
+      return {
+        token: result.token,
+        expires_at: result.expiresAt.toISOString(),
+        server_time: new Date().toISOString(),
+        impersonator_id: result.impersonatorId,
+        user: toUserDto(result.user),
+      };
+    },
+  });
+}
+
+export function createAdministrationUserRoutes(
+  workspaces: WorkspacesInterModuleClient,
+): RouteGroup[] {
+  return [
+    adoptAdministrationActorGuard({
+      prefix: '/admin/auth/users',
+      auth: AUTH_USER,
+      routes: [userLookupRoute, suspendUserRoute, reactivateUserRoute, revokeUserSessionsRoute],
+    }),
+    // The impersonate route mounts outside the adopted guard on purpose: its
+    // limiter must run before the impersonated-session rejection (see
+    // `createImpersonateUserRoute`), so the guard is applied positionally
+    // there. Every other route under `/admin/auth/users` keeps the adoption.
+    {
+      prefix: '/admin/auth/users',
+      auth: AUTH_USER,
+      routes: [createImpersonateUserRoute(workspaces)],
+    },
+  ];
+}

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

@@ -1,3 +1,4 @@
+import {getUserContext} from '@shipfox/api-auth-context';
 import {ClientError, type FastifyReply, type FastifyRequest} from '@shipfox/node-fastify';
 import {enforceRateLimit as enforceSharedRateLimit} from '@shipfox/node-rate-limit';
 import {
@@ -28,6 +29,16 @@ const policies: Record<
   lookup: {
     ip: {limit: 60, windowSeconds: 5 * 60},
   },
+  impersonate: {
+    // Bounds mint and probing attempts: the IP bucket bounds aggregate source
+    // traffic, and the actor bucket is a per-actor cap that prevents an actor
+    // from evading the bound by rotating IPs (every request still consumes the
+    // IP bucket first, so a shared NAT cannot exhaust it faster by pooling
+    // actors). Ladder denials by an identifiable actor role are audited as
+    // `failed` events.
+    ip: {limit: 20, windowSeconds: 15 * 60},
+    actor: {limit: 20, windowSeconds: 15 * 60},
+  },
 };
 
 interface EmailBody {
@@ -111,3 +122,32 @@ export function createAuthIpRateLimitPreHandler(action: AuthRateLimitAction) {
     });
   };
 }
+
+/**
+ * Rate limits an authenticated route by source IP and by actor. Every request
+ * consumes the IP bucket, which bounds aggregate source traffic; the actor
+ * bucket is an additional per-actor cap that prevents an actor from evading
+ * the bound by rotating IPs. Runs after authentication (auth is an `onRequest`
+ * hook), so the user context is set.
+ */
+export function createAuthActorRateLimitPreHandler(action: AuthRateLimitAction) {
+  return async (request: FastifyRequest, reply: FastifyReply): Promise<void> => {
+    await enforceRateLimit({
+      request,
+      reply,
+      action,
+      scope: 'ip',
+      identifier: request.ip,
+    });
+    const client = getUserContext(request);
+    if (client) {
+      await enforceRateLimit({
+        request,
+        reply,
+        action,
+        scope: 'actor',
+        identifier: client.userId,
+      });
+    }
+  };
+}

package/src/presentation/routes/session/login.test.ts

@@ -1,8 +1,10 @@
 import type {FastifyInstance} from 'fastify';
+import {verifyUserToken} from '#core/jwt.js';
 import {
   createAuthTestApp,
   listMembershipsByUserMock,
   login,
+  ROUTE_TEST_SECRET,
   resetCapturedMail,
   signup,
   uniqueEmail,
@@ -36,6 +38,9 @@ describe('POST /auth/login', () => {
     expect(res.json().token).toBeDefined();
     expect(res.json().user.email).toBe(email);
     expect(res.json().admin_role).toBeNull();
+    expect(res.json().impersonator_id).toBeUndefined();
+    const claims = await verifyUserToken({token: res.json().token, secret: ROUTE_TEST_SECRET});
+    expect(claims.impersonatorId).toBeUndefined();
     expect(res.headers['set-cookie']).toContain('shipfox_refresh_token=');
     expect(res.headers['set-cookie']).toContain('HttpOnly');
     expect(res.headers['set-cookie']).toContain('Secure');

package/src/presentation/routes/session/me.test.ts

@@ -35,6 +35,30 @@ describe('GET /auth/me', () => {
     expect(res.statusCode).toBe(200);
     expect(res.json().user.email).toBe(account.email);
     expect(res.json().admin_role).toBeNull();
+    expect(res.json().impersonator_id).toBeUndefined();
+  });
+
+  test('returns impersonator_id for a marked session token', async () => {
+    const account = await createVerifiedSession('me-impersonated');
+    const impersonatorId = crypto.randomUUID();
+    const token = await signUserToken({
+      userId: account.userId,
+      impersonatorId,
+      email: account.email,
+      memberships: [],
+      secret: ROUTE_TEST_SECRET,
+      expiresIn: '15m',
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/auth/me',
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().user.email).toBe(account.email);
+    expect(res.json().impersonator_id).toBe(impersonatorId);
   });
 
   test('returns the current Auth-owned role for dashboard presentation', async () => {

package/src/presentation/routes/session/me.ts

@@ -34,6 +34,7 @@ export const meRoute = defineRoute({
     return {
       user: toUserDto(result.user),
       admin_role: await getCurrentAdminRole({userId: client.userId}),
+      impersonator_id: client.impersonatorId,
     };
   },
 });

package/src/presentation/routes/session/refresh.test.ts

@@ -1,8 +1,10 @@
 import type {FastifyInstance} from 'fastify';
+import {verifyUserToken} from '#core/jwt.js';
 import {
   cookieHeader,
   createAuthTestApp,
   listMembershipsByUserMock,
+  ROUTE_TEST_SECRET,
   resetCapturedMail,
   signupVerifyLogin,
 } from '#test/routes.js';
@@ -34,6 +36,15 @@ describe('POST /auth/refresh', () => {
     expect(res.statusCode).toBe(200);
     expect(res.json().token).toBeDefined();
     expect(res.json().user.email).toBe(account.email);
+    // The refresh contract stays unmarked: the response never exposes
+    // impersonator_id and rotation re-issues an ordinary access token.
+    // refreshAccessToken signs from (user, memberships, sessionId) and never
+    // sees the access token, so a marker cannot survive rotation here (ADR 0014
+    // keeps impersonated sessions access-token-only; refresh restores the
+    // administrator's session).
+    expect(res.json().impersonator_id).toBeUndefined();
+    const claims = await verifyUserToken({token: res.json().token, secret: ROUTE_TEST_SECRET});
+    expect(claims.impersonatorId).toBeUndefined();
     expect(res.headers['set-cookie']).toContain('shipfox_refresh_token=');
     expect(res.headers['set-cookie']).toContain('HttpOnly');
     expect(res.headers['set-cookie']).toContain('Secure');

package/test/routes.ts

@@ -11,7 +11,7 @@ import {createJwtAuthMethod} from '#presentation/auth/jwt-auth.js';
 import {
   administrationBootstrapRoutes,
   administrationRoutes,
-  administrationUserRoutes,
+  createAdministrationUserRoutes,
 } from '#presentation/routes/administration.js';
 import {buildAuthRoutes} from '#presentation/routes/index.js';
 
@@ -21,6 +21,20 @@ const testConfig = vi.hoisted(
     challenges: Map<string, string>;
     mailer: Mailer;
     clientBaseUrl: string;
+    authConfig: {
+      ADMIN_BOOTSTRAP_TOKEN: string;
+      AUTH_JWT_EXPIRES_IN: string;
+      AUTH_IMPERSONATION_ENABLED: boolean;
+      AUTH_REFRESH_TOKEN_EXPIRES_IN_DAYS: number;
+      AUTH_REFRESH_ROTATION_GRACE_SECONDS: number;
+      AUTH_REFRESH_COOKIE_NAME: string;
+      AUTH_PASSWORD_ENABLED: boolean;
+      AUTH_SIGNUP_GATE_ENABLED: boolean;
+      AUTH_SIGNUP_ALLOWED_EMAIL_DOMAINS: string;
+      AUTH_SIGNUP_ALLOWED_EMAILS: string;
+      AUTH_SIGNUP_NOT_ALLOWED_MESSAGE: string | undefined;
+      CLIENT_BASE_URL: string;
+    };
   } => {
     const captured: MailMessage[] = [];
     const mailer: Mailer = {
@@ -29,11 +43,26 @@ const testConfig = vi.hoisted(
         return Promise.resolve();
       },
     };
+    const authConfig = {
+      ADMIN_BOOTSTRAP_TOKEN: 'test-bootstrap-token',
+      AUTH_JWT_EXPIRES_IN: '15m',
+      AUTH_IMPERSONATION_ENABLED: true,
+      AUTH_REFRESH_TOKEN_EXPIRES_IN_DAYS: 14,
+      AUTH_REFRESH_ROTATION_GRACE_SECONDS: 30,
+      AUTH_REFRESH_COOKIE_NAME: 'shipfox_refresh_token',
+      AUTH_PASSWORD_ENABLED: true,
+      AUTH_SIGNUP_GATE_ENABLED: false,
+      AUTH_SIGNUP_ALLOWED_EMAIL_DOMAINS: '',
+      AUTH_SIGNUP_ALLOWED_EMAILS: '',
+      AUTH_SIGNUP_NOT_ALLOWED_MESSAGE: undefined,
+      CLIENT_BASE_URL: 'https://app.example.test',
+    };
     return {
       captured,
       challenges: new Map(),
       mailer,
-      clientBaseUrl: 'https://app.example.test',
+      clientBaseUrl: authConfig.CLIENT_BASE_URL,
+      authConfig,
     };
   },
 );
@@ -52,19 +81,7 @@ const workspaceTestDoubles = vi.hoisted(() => {
 const workspaces = workspaceTestDoubles as unknown as WorkspacesInterModuleClient;
 
 vi.mock('#config.js', () => ({
-  config: {
-    ADMIN_BOOTSTRAP_TOKEN: 'test-bootstrap-token',
-    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_PASSWORD_ENABLED: true,
-    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,
-  },
+  config: testConfig.authConfig,
   mailer: testConfig.mailer,
 }));
 
@@ -92,6 +109,16 @@ export function resetCapturedMail(): void {
   listMembershipsByUserMock.mockResolvedValue({memberships: []});
 }
 
+/** Flips `AUTH_IMPERSONATION_ENABLED` for the shared route-test config mock. */
+export function setImpersonationEnabled(enabled: boolean): void {
+  testConfig.authConfig.AUTH_IMPERSONATION_ENABLED = enabled;
+}
+
+/** Flips `AUTH_JWT_EXPIRES_IN` for the shared route-test config mock. */
+export function setAuthJwtExpiresIn(expiresIn: string): void {
+  testConfig.authConfig.AUTH_JWT_EXPIRES_IN = expiresIn;
+}
+
 export function capturedMail(): MailMessage[] {
   return testConfig.captured;
 }
@@ -162,7 +189,7 @@ export async function createAuthTestApp(params?: {
       buildAuthRoutes(true, workspaces),
       administrationBootstrapRoutes,
       administrationRoutes,
-      administrationUserRoutes,
+      ...createAdministrationUserRoutes(workspaces),
     ],
     swagger: false,
   };