@shipfox/api-auth 15.0.0 → 17.0.0

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

@@ -1,8 +1,14 @@
+import {impersonateResponseSchema} from '@shipfox/api-auth-dto';
 import {ADMINISTRATION_ACTION_PERFORMED} from '@shipfox/api-common-dto';
-import {eq, sql} from 'drizzle-orm';
+import {userAccessTokenKey} from '@shipfox/node-auth-root-key';
+import {hashOpaqueToken} from '@shipfox/node-tokens';
+import {asc, eq, sql} from 'drizzle-orm';
 import type {FastifyInstance} from 'fastify';
+import {signUserToken, verifyUserToken} from '#core/jwt.js';
 import {type AuthRateLimitAction, hashAuthRateLimitIdentifier} from '#core/rate-limit.js';
 import {db} from '#db/db.js';
+import {adminCommandResults} from '#db/schema/admin-command-results.js';
+import {adminGrants} from '#db/schema/admin-grants.js';
 import {authOutbox} from '#db/schema/outbox.js';
 import {authRateLimits} from '#db/schema/rate-limits.js';
 import {refreshTokens} from '#db/schema/refresh-tokens.js';
@@ -13,7 +19,10 @@ import {
   createVerifiedSession,
   getSetCookie,
   login,
+  ROUTE_TEST_SECRET,
   resetCapturedMail,
+  setAuthJwtExpiresIn,
+  setImpersonationEnabled,
 } from '#test/routes.js';
 
 const BOOTSTRAP_TOKEN = 'test-bootstrap-token';
@@ -31,22 +40,36 @@ function authHeaders(token: string, idempotencyKey: string) {
   };
 }
 
+function impersonatedToken(userId: string, email: string): Promise<string> {
+  return signUserToken({
+    userId,
+    email,
+    name: 'Impersonated User',
+    memberships: [],
+    impersonatorId: crypto.randomUUID(),
+    secret: ROUTE_TEST_SECRET,
+    expiresIn: '15m',
+  });
+}
+
 async function seedExhaustedIpBucket(params: {
   action: AuthRateLimitAction;
   identifier: string;
   limit: number;
   windowSeconds: number;
+  scope?: 'ip' | 'actor';
 }): Promise<void> {
+  const scope = params.scope ?? 'ip';
   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',
+      scope,
       identifierHmac: hashAuthRateLimitIdentifier({
         action: params.action,
-        scope: 'ip',
+        scope,
         identifier: params.identifier,
       }),
       windowStart,
@@ -64,6 +87,8 @@ describe('Auth administration routes', () => {
 
   beforeEach(async () => {
     resetCapturedMail();
+    setImpersonationEnabled(true);
+    setAuthJwtExpiresIn('15m');
     await resetAdministrationState();
   });
 
@@ -92,6 +117,92 @@ describe('Auth administration routes', () => {
     expect(response.statusCode).toBe(401);
   });
 
+  test('rejects an impersonated session on the bootstrap route before any side effect', async () => {
+    const account = await createVerifiedSession('admin-bootstrap-impersonated');
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/admin/auth/admin-grants/bootstrap',
+      headers: authHeaders(
+        await impersonatedToken(account.userId, account.email),
+        'impersonated-bootstrap',
+      ),
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+
+    expect(response.statusCode).toBe(403);
+    expect(response.json()).toEqual({code: 'admin-role-required'});
+    await expect(db().select().from(adminGrants)).resolves.toHaveLength(0);
+    await expect(db().select().from(authOutbox)).resolves.toHaveLength(0);
+  });
+
+  test('rejects an impersonated session on the bootstrap-state route', async () => {
+    const account = await createVerifiedSession('admin-bootstrap-state-impersonated');
+
+    const response = await app.inject({
+      method: 'GET',
+      url: '/admin/auth/bootstrap-state',
+      headers: {authorization: `Bearer ${await impersonatedToken(account.userId, account.email)}`},
+    });
+
+    expect(response.statusCode).toBe(403);
+    expect(response.json()).toEqual({code: 'admin-role-required'});
+  });
+
+  test('rejects an impersonated session on user administration before roles are consulted', async () => {
+    const owner = await createVerifiedSession('admin-users-impersonated');
+
+    const bootstrap = await app.inject({
+      method: 'POST',
+      url: '/admin/auth/admin-grants/bootstrap',
+      headers: authHeaders(owner.token, 'users-impersonated-bootstrap'),
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+    expect(bootstrap.statusCode).toBe(201);
+
+    const response = await app.inject({
+      method: 'GET',
+      url: `/admin/auth/users?user_id=${owner.userId}`,
+      headers: {authorization: `Bearer ${await impersonatedToken(owner.userId, owner.email)}`},
+    });
+
+    // The impersonated subject is an owner, so a guard that consulted roles
+    // would let the request through; rejection proves the mark wins first.
+    expect(response.statusCode).toBe(403);
+    expect(response.json()).toEqual({code: 'admin-role-required'});
+  });
+
+  test('rejects an impersonated session on the grant route before any side effect', async () => {
+    const owner = await createVerifiedSession('admin-grant-impersonated');
+    const target = await createVerifiedSession('admin-grant-impersonated-target');
+
+    const bootstrap = await app.inject({
+      method: 'POST',
+      url: '/admin/auth/admin-grants/bootstrap',
+      headers: authHeaders(owner.token, 'grant-impersonated-bootstrap'),
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+    expect(bootstrap.statusCode).toBe(201);
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/admin/auth/admin-grants',
+      headers: authHeaders(
+        await impersonatedToken(owner.userId, owner.email),
+        'impersonated-grant',
+      ),
+      payload: {user_id: target.userId, role: 'admin-observer', reason: 'Impersonated attempt'},
+    });
+
+    // The impersonated subject is an owner, so a guard that consulted roles
+    // would let the grant through; rejection proves the mark wins first and
+    // that no grant or audit event is left behind.
+    expect(response.statusCode).toBe(403);
+    expect(response.json()).toEqual({code: 'admin-role-required'});
+    await expect(db().select().from(adminGrants)).resolves.toHaveLength(1);
+    await expect(db().select().from(authOutbox)).resolves.toHaveLength(1);
+  });
+
   test('reports only available or closed bootstrap state', async () => {
     const account = await createVerifiedSession('admin-bootstrap-state');
 
@@ -913,4 +1024,718 @@ describe('Auth administration routes', () => {
     expect(response.statusCode).toBe(403);
     expect(response.json().code).toBe('forbidden');
   });
+
+  function impersonateMint(params: {
+    token: string;
+    targetUserId: string;
+    idempotencyKey: string;
+    reason?: string;
+  }) {
+    return app.inject({
+      method: 'POST',
+      url: `/admin/auth/users/${params.targetUserId}/impersonate`,
+      headers: authHeaders(params.token, params.idempotencyKey),
+      payload: {reason: params.reason ?? 'Support reproduction'},
+    });
+  }
+
+  async function bootstrapOwner(prefix: string): Promise<string> {
+    const owner = await createVerifiedSession(`${prefix}-owner`);
+    const bootstrap = await app.inject({
+      method: 'POST',
+      url: '/admin/auth/admin-grants/bootstrap',
+      headers: authHeaders(owner.token, `${prefix}-bootstrap`),
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+    expect(bootstrap.statusCode).toBe(201);
+    return owner.token;
+  }
+
+  type ImpersonationEventPayload = {
+    command: string;
+    result: 'succeeded' | 'failed';
+    idempotencyKeyFingerprint: string;
+    actorId: string;
+    actorRole: string;
+    requiredRole: string;
+    targetType: string;
+    targetId: string;
+    reason: string;
+  };
+
+  function impersonationEvents(): Promise<ImpersonationEventPayload[]> {
+    return db()
+      .select()
+      .from(authOutbox)
+      .orderBy(asc(authOutbox.createdAt))
+      .then((rows) =>
+        rows
+          .filter(
+            (event) =>
+              event.eventType === ADMINISTRATION_ACTION_PERFORMED &&
+              (event.payload as {command?: string}).command === 'auth.user.impersonate',
+          )
+          .map((event) => event.payload as ImpersonationEventPayload),
+      );
+  }
+
+  test('mints an impersonated session with the contract shape, no cookie, and no refresh material', async () => {
+    const ownerToken = await bootstrapOwner('impersonate-mint');
+    const target = await createVerifiedSession('impersonate-mint-target');
+
+    const minted = await impersonateMint({
+      token: ownerToken,
+      targetUserId: target.userId,
+      idempotencyKey: 'impersonate-mint',
+      reason: 'Support reproduction',
+    });
+
+    expect(minted.statusCode).toBe(200);
+    expect(minted.headers['set-cookie']).toBeUndefined();
+    const body = impersonateResponseSchema.parse(minted.json());
+    expect(body.impersonator_id).not.toBe(target.userId);
+    expect(body.user.id).toBe(target.userId);
+    const ttlMs = Date.parse(body.expires_at) - Date.parse(body.server_time);
+    expect(ttlMs).toBeGreaterThan(0);
+    expect(ttlMs).toBeLessThanOrEqual(15 * 60 * 1000);
+
+    const me = await app.inject({
+      method: 'GET',
+      url: '/auth/me',
+      headers: {authorization: `Bearer ${body.token}`},
+    });
+    expect(me.statusCode).toBe(200);
+    expect(me.json()).toMatchObject({
+      user: {id: target.userId, email: target.email},
+      impersonator_id: body.impersonator_id,
+    });
+
+    // The minted token cannot be refreshed: no refresh session exists.
+    const refresh = await app.inject({
+      method: 'POST',
+      url: '/auth/refresh',
+      headers: {cookie: `shipfox_refresh_token=${body.token}`},
+      payload: {},
+    });
+    expect(refresh.statusCode).toBe(401);
+    const targetSessions = await db()
+      .select()
+      .from(refreshTokens)
+      .where(eq(refreshTokens.userId, target.userId));
+    // The fixture session's own refresh row is untouched: the mint creates none.
+    expect(targetSessions).toHaveLength(1);
+    expect(JSON.stringify(targetSessions)).not.toContain(hashOpaqueToken(body.token));
+
+    // One success event, redacted: no token, no raw key, no reason leak beyond the reason itself.
+    const events = await impersonationEvents();
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      command: 'auth.user.impersonate',
+      targetType: 'user',
+      targetId: target.userId,
+      requiredRole: 'admin-operator',
+      reason: 'Support reproduction',
+      result: 'succeeded',
+    });
+    expect(JSON.stringify(events[0])).not.toContain(body.token);
+    expect(JSON.stringify(events[0])).not.toContain('impersonate-mint');
+
+    // The stored command result is fingerprint-only.
+    const storedRows = await db()
+      .select()
+      .from(adminCommandResults)
+      .where(eq(adminCommandResults.command, 'auth.user.impersonate'));
+    expect(storedRows).toHaveLength(1);
+    const stored = storedRows[0]?.result;
+    if (!stored || !('impersonation' in stored)) throw new Error('Missing stored result');
+    expect(stored.impersonation).toEqual({
+      targetUserId: target.userId,
+      expiresAt: body.expires_at,
+      tokenFingerprints: [hashOpaqueToken(body.token)],
+    });
+    expect(JSON.stringify(storedRows[0]?.result)).not.toContain(body.token);
+  });
+
+  test('rejects the mint when AUTH_IMPERSONATION_ENABLED is false and audits the denial', async () => {
+    const ownerToken = await bootstrapOwner('impersonate-disabled');
+    const target = await createVerifiedSession('impersonate-disabled-target');
+    setImpersonationEnabled(false);
+
+    const response = await impersonateMint({
+      token: ownerToken,
+      targetUserId: target.userId,
+      idempotencyKey: 'impersonate-disabled',
+    });
+
+    expect(response.statusCode).toBe(403);
+    expect(response.json()).toEqual({code: 'impersonation-disabled'});
+    const events = await impersonationEvents();
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({result: 'failed', command: 'auth.user.impersonate'});
+    await expect(
+      db()
+        .select()
+        .from(adminCommandResults)
+        .where(eq(adminCommandResults.command, 'auth.user.impersonate')),
+    ).resolves.toHaveLength(0);
+  });
+
+  test('rejects the mint for observers and audits the denial with the actor role', async () => {
+    const ownerToken = await bootstrapOwner('impersonate-observer');
+    const observer = await createVerifiedSession('impersonate-observer-actor');
+    const target = await createVerifiedSession('impersonate-observer-target');
+    await app.inject({
+      method: 'POST',
+      url: '/admin/auth/admin-grants',
+      headers: authHeaders(ownerToken, 'impersonate-observer-grant'),
+      payload: {
+        user_id: observer.userId,
+        role: 'admin-observer',
+        reason: 'Read-only administration access',
+      },
+    });
+
+    const response = await impersonateMint({
+      token: observer.token,
+      targetUserId: target.userId,
+      idempotencyKey: 'impersonate-observer-mint',
+    });
+
+    expect(response.statusCode).toBe(403);
+    expect(response.json()).toEqual({
+      code: 'forbidden',
+      details: {required_role: 'admin-operator'},
+    });
+    const events = await impersonationEvents();
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      actorId: observer.userId,
+      actorRole: 'admin-observer',
+      requiredRole: 'admin-operator',
+      result: 'failed',
+    });
+  });
+
+  test('rejects ineligible targets: unverified, suspended, and unknown users', async () => {
+    const ownerToken = await bootstrapOwner('impersonate-ladder');
+    const unverified = await createVerifiedSession('impersonate-ladder-unverified');
+    await db().update(users).set({emailVerifiedAt: null}).where(eq(users.id, unverified.userId));
+    const suspended = await createVerifiedSession('impersonate-ladder-suspended');
+    await db().update(users).set({status: 'suspended'}).where(eq(users.id, suspended.userId));
+
+    const unverifiedTarget = await impersonateMint({
+      token: ownerToken,
+      targetUserId: unverified.userId,
+      idempotencyKey: 'impersonate-ladder-unverified',
+    });
+    expect(unverifiedTarget.statusCode).toBe(403);
+    expect(unverifiedTarget.json().code).toBe('impersonation-target-not-active');
+
+    const suspendedTarget = await impersonateMint({
+      token: ownerToken,
+      targetUserId: suspended.userId,
+      idempotencyKey: 'impersonate-ladder-suspended',
+    });
+    expect(suspendedTarget.statusCode).toBe(403);
+    expect(suspendedTarget.json().code).toBe('impersonation-target-not-active');
+
+    const missingTarget = await impersonateMint({
+      token: ownerToken,
+      targetUserId: crypto.randomUUID(),
+      idempotencyKey: 'impersonate-ladder-missing',
+    });
+    expect(missingTarget.statusCode).toBe(404);
+    expect(missingTarget.json().code).toBe('not-found');
+
+    // Every ladder denial by an identifiable admin role is audited with one
+    // `failed` event carrying the actor, the reason, and the key fingerprint.
+    const events = await impersonationEvents();
+    expect(events).toHaveLength(2);
+    expect(events.map((event) => event.result)).toEqual(['failed', 'failed']);
+    expect(events.every((event) => event.actorRole === 'admin-owner')).toBe(true);
+    expect(events.every((event) => event.reason === 'Support reproduction')).toBe(true);
+    // The unknown-target 404 is a client-contract error, not a denial: it is
+    // reported to the caller and never enters the failure-event stream.
+    expect(
+      events.some(
+        (event) =>
+          event.idempotencyKeyFingerprint === hashOpaqueToken('impersonate-ladder-missing'),
+      ),
+    ).toBe(false);
+  });
+
+  test('rejects impersonating an administrator target even for an owner', async () => {
+    const ownerToken = await bootstrapOwner('impersonate-admin-target');
+    const secondOwner = await createVerifiedSession('impersonate-admin-target-second');
+    await app.inject({
+      method: 'POST',
+      url: '/admin/auth/admin-grants',
+      headers: authHeaders(ownerToken, 'impersonate-admin-target-grant'),
+      payload: {user_id: secondOwner.userId, role: 'admin-owner', reason: 'Second owner'},
+    });
+
+    const response = await impersonateMint({
+      token: ownerToken,
+      targetUserId: secondOwner.userId,
+      idempotencyKey: 'impersonate-admin-target-mint',
+    });
+    expect(response.statusCode).toBe(403);
+    expect(response.json().code).toBe('cannot-impersonate-administrator');
+    const events = await impersonationEvents();
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      result: 'failed',
+      actorRole: 'admin-owner',
+      reason: 'Support reproduction',
+    });
+  });
+
+  test('rejects self-impersonation with cannot-impersonate-self', async () => {
+    const ownerToken = await bootstrapOwner('impersonate-self');
+    const owner = await createVerifiedSession('impersonate-self-actor');
+    await app.inject({
+      method: 'POST',
+      url: '/admin/auth/admin-grants',
+      headers: authHeaders(ownerToken, 'impersonate-self-grant'),
+      payload: {user_id: owner.userId, role: 'admin-operator', reason: 'Operator'},
+    });
+
+    const response = await impersonateMint({
+      token: owner.token,
+      targetUserId: owner.userId,
+      idempotencyKey: 'impersonate-self-mint',
+    });
+    expect(response.statusCode).toBe(403);
+    expect(response.json().code).toBe('cannot-impersonate-self');
+    const events = await impersonationEvents();
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      result: 'failed',
+      actorRole: 'admin-operator',
+      reason: 'Support reproduction',
+    });
+  });
+
+  test('replays in-window with the original expiry, a fresh signature, and its own event', async () => {
+    const ownerToken = await bootstrapOwner('impersonate-replay');
+    const target = await createVerifiedSession('impersonate-replay-target');
+
+    const minted = await impersonateMint({
+      token: ownerToken,
+      targetUserId: target.userId,
+      idempotencyKey: 'impersonate-replay',
+    });
+    expect(minted.statusCode).toBe(200);
+    const first = impersonateResponseSchema.parse(minted.json());
+
+    const replayed = await impersonateMint({
+      token: ownerToken,
+      targetUserId: target.userId,
+      idempotencyKey: 'impersonate-replay',
+    });
+    expect(replayed.statusCode).toBe(200);
+    const second = impersonateResponseSchema.parse(replayed.json());
+    expect(second.expires_at).toBe(first.expires_at);
+    expect(second.token).not.toBe(first.token);
+
+    // The re-signed token's `exp` never exceeds the advertised expiry: the
+    // replay re-signs with the remaining lifetime to the stored `expires_at`,
+    // and the initial mint advertises the token's actual signed `exp`.
+    const firstClaims = await verifyUserToken({token: first.token, secret: userAccessTokenKey()});
+    expect(firstClaims.exp * 1000).toBe(Date.parse(first.expires_at));
+    const secondClaims = await verifyUserToken({token: second.token, secret: userAccessTokenKey()});
+    expect(secondClaims.exp * 1000).toBeLessThanOrEqual(Date.parse(first.expires_at));
+
+    const me = await app.inject({
+      method: 'GET',
+      url: '/auth/me',
+      headers: {authorization: `Bearer ${second.token}`},
+    });
+    expect(me.statusCode).toBe(200);
+    expect(me.json().user.id).toBe(target.userId);
+
+    // Two events under one fingerprint (the second is the replay marker) and
+    // two stored fingerprints; no raw token anywhere.
+    const events = await impersonationEvents();
+    expect(events).toHaveLength(2);
+    expect(events[0]?.idempotencyKeyFingerprint).toBe(events[1]?.idempotencyKeyFingerprint);
+    expect(events.every((event) => event.result === 'succeeded')).toBe(true);
+    const storedRows = await db()
+      .select()
+      .from(adminCommandResults)
+      .where(eq(adminCommandResults.command, 'auth.user.impersonate'));
+    const stored = storedRows[0]?.result;
+    if (!stored || !('impersonation' in stored)) throw new Error('Missing stored result');
+    expect(stored.impersonation.tokenFingerprints).toEqual([
+      hashOpaqueToken(first.token),
+      hashOpaqueToken(second.token),
+    ]);
+    expect(stored.impersonation.expiresAt).toBe(first.expires_at);
+    expect(JSON.stringify(storedRows[0]?.result)).not.toContain(first.token);
+    expect(JSON.stringify(storedRows[0]?.result)).not.toContain(second.token);
+  });
+
+  test('replays after expiry with impersonation-expired', async () => {
+    const ownerToken = await bootstrapOwner('impersonate-expired');
+    const target = await createVerifiedSession('impersonate-expired-target');
+
+    const minted = await impersonateMint({
+      token: ownerToken,
+      targetUserId: target.userId,
+      idempotencyKey: 'impersonate-expired',
+    });
+    expect(minted.statusCode).toBe(200);
+
+    const storedRows = await db()
+      .select()
+      .from(adminCommandResults)
+      .where(eq(adminCommandResults.command, 'auth.user.impersonate'));
+    const stored = storedRows[0]?.result;
+    if (!stored || !('impersonation' in stored)) throw new Error('Missing stored result');
+    await db()
+      .update(adminCommandResults)
+      .set({
+        result: {
+          impersonation: {
+            ...stored.impersonation,
+            expiresAt: new Date(Date.now() - 1000).toISOString(),
+          },
+        },
+      })
+      .where(eq(adminCommandResults.id, storedRows[0]?.id ?? ''));
+
+    const replayed = await impersonateMint({
+      token: ownerToken,
+      targetUserId: target.userId,
+      idempotencyKey: 'impersonate-expired',
+    });
+    expect(replayed.statusCode).toBe(410);
+    expect(replayed.json().code).toBe('impersonation-expired');
+    const events = await impersonationEvents();
+    expect(events.at(-1)).toMatchObject({result: 'failed'});
+  });
+
+  test('a replay with a revoked operator grant fails closed and is audited', async () => {
+    const ownerToken = await bootstrapOwner('impersonate-revoke');
+    const operator = await createVerifiedSession('impersonate-revoke-operator');
+    const target = await createVerifiedSession('impersonate-revoke-target');
+    await app.inject({
+      method: 'POST',
+      url: '/admin/auth/admin-grants',
+      headers: authHeaders(ownerToken, 'impersonate-revoke-grant'),
+      payload: {user_id: operator.userId, role: 'admin-operator', reason: 'Operator'},
+    });
+
+    const minted = await impersonateMint({
+      token: operator.token,
+      targetUserId: target.userId,
+      idempotencyKey: 'impersonate-revoke-mint',
+    });
+    expect(minted.statusCode).toBe(200);
+
+    // Revoke the operator's grant (keep the owner's), then replay the same key.
+    const grants = await app.inject({
+      method: 'GET',
+      url: '/admin/auth/admin-grants',
+      headers: {authorization: `Bearer ${ownerToken}`},
+    });
+    const grantId = (grants.json().grants as Array<{grant_id: string; user: {id: string}}>).find(
+      (grant) => grant.user.id === operator.userId,
+    )?.grant_id;
+    expect(grantId).toBeDefined();
+    const revoked = await app.inject({
+      method: 'DELETE',
+      url: `/admin/auth/admin-grants/${grantId}`,
+      headers: authHeaders(ownerToken, 'impersonate-revoke-revoke'),
+      payload: {reason: 'E2E grant revocation'},
+    });
+    expect(revoked.statusCode).toBe(200);
+
+    const replayed = await impersonateMint({
+      token: operator.token,
+      targetUserId: target.userId,
+      idempotencyKey: 'impersonate-revoke-mint',
+    });
+    expect(replayed.statusCode).toBe(403);
+    expect(replayed.json().code).toBe('forbidden');
+    // The initial mint remains the only recorded event: the strict event
+    // schema requires an actor role, and the actor is role-less after the
+    // revocation, so the denial itself is the fail-closed record.
+    const events = await impersonationEvents();
+    expect(events).toHaveLength(1);
+    expect(events[0]?.result).toBe('succeeded');
+  });
+
+  test('a replay with the flag turned off fails closed and is audited', async () => {
+    const ownerToken = await bootstrapOwner('impersonate-flag-replay');
+    const target = await createVerifiedSession('impersonate-flag-replay-target');
+
+    const minted = await impersonateMint({
+      token: ownerToken,
+      targetUserId: target.userId,
+      idempotencyKey: 'impersonate-flag-replay',
+    });
+    expect(minted.statusCode).toBe(200);
+
+    setImpersonationEnabled(false);
+    const replayed = await impersonateMint({
+      token: ownerToken,
+      targetUserId: target.userId,
+      idempotencyKey: 'impersonate-flag-replay',
+    });
+    expect(replayed.statusCode).toBe(403);
+    expect(replayed.json().code).toBe('impersonation-disabled');
+
+    const events = await impersonationEvents();
+    expect(events).toHaveLength(2);
+    expect(events[1]).toMatchObject({
+      result: 'failed',
+      idempotencyKeyFingerprint: events[0]?.idempotencyKeyFingerprint,
+    });
+  });
+
+  test('a replay after the target is suspended mid-window fails closed and is audited', async () => {
+    const ownerToken = await bootstrapOwner('impersonate-target-suspend');
+    const target = await createVerifiedSession('impersonate-target-suspend-target');
+
+    const minted = await impersonateMint({
+      token: ownerToken,
+      targetUserId: target.userId,
+      idempotencyKey: 'impersonate-target-suspend',
+    });
+    expect(minted.statusCode).toBe(200);
+
+    // Suspend the target mid-window, then replay the same key: the ladder
+    // re-runs on every replay, so the suspension ends the capability.
+    await db().update(users).set({status: 'suspended'}).where(eq(users.id, target.userId));
+
+    const replayed = await impersonateMint({
+      token: ownerToken,
+      targetUserId: target.userId,
+      idempotencyKey: 'impersonate-target-suspend',
+    });
+    expect(replayed.statusCode).toBe(403);
+    expect(replayed.json().code).toBe('impersonation-target-not-active');
+
+    const events = await impersonationEvents();
+    expect(events).toHaveLength(2);
+    expect(events[1]).toMatchObject({
+      result: 'failed',
+      actorRole: 'admin-owner',
+      idempotencyKeyFingerprint: events[0]?.idempotencyKeyFingerprint,
+    });
+  });
+
+  test('a replay after the target gains an administrator grant mid-window fails closed and is audited', async () => {
+    const ownerToken = await bootstrapOwner('impersonate-target-grant');
+    const target = await createVerifiedSession('impersonate-target-grant-target');
+
+    const minted = await impersonateMint({
+      token: ownerToken,
+      targetUserId: target.userId,
+      idempotencyKey: 'impersonate-target-grant',
+    });
+    expect(minted.statusCode).toBe(200);
+
+    // Promote the target mid-window: the anti-escalation rule (no active
+    // administrator grant on the target) must hold on the replay path too.
+    await app.inject({
+      method: 'POST',
+      url: '/admin/auth/admin-grants',
+      headers: authHeaders(ownerToken, 'impersonate-target-grant-grant'),
+      payload: {user_id: target.userId, role: 'admin-operator', reason: 'Mid-window promotion'},
+    });
+
+    const replayed = await impersonateMint({
+      token: ownerToken,
+      targetUserId: target.userId,
+      idempotencyKey: 'impersonate-target-grant',
+    });
+    expect(replayed.statusCode).toBe(403);
+    expect(replayed.json().code).toBe('cannot-impersonate-administrator');
+
+    const events = await impersonationEvents();
+    expect(events).toHaveLength(2);
+    expect(events[1]).toMatchObject({
+      result: 'failed',
+      actorRole: 'admin-owner',
+      idempotencyKeyFingerprint: events[0]?.idempotencyKeyFingerprint,
+    });
+  });
+
+  test('mints with AUTH_JWT_EXPIRES_IN below the 15-minute cap', async () => {
+    const ownerToken = await bootstrapOwner('impersonate-below-cap');
+    const target = await createVerifiedSession('impersonate-below-cap-target');
+    setAuthJwtExpiresIn('5m');
+
+    const minted = await impersonateMint({
+      token: ownerToken,
+      targetUserId: target.userId,
+      idempotencyKey: 'impersonate-below-cap',
+    });
+    expect(minted.statusCode).toBe(200);
+    const body = impersonateResponseSchema.parse(minted.json());
+    const ttlSeconds = (Date.parse(body.expires_at) - Date.parse(body.server_time)) / 1000;
+    expect(ttlSeconds).toBeGreaterThan(290);
+    expect(ttlSeconds).toBeLessThanOrEqual(300);
+    // The signed token carries the same whole-second expiry as the response.
+    const claims = await verifyUserToken({token: body.token, secret: userAccessTokenKey()});
+    expect(claims.exp - claims.iat).toBe(300);
+    expect(new Date(claims.exp * 1000).toISOString()).toBe(body.expires_at);
+  });
+
+  test('rejects idempotency-key reuse across different targets', async () => {
+    const ownerToken = await bootstrapOwner('impersonate-key-reuse');
+    const first = await createVerifiedSession('impersonate-key-reuse-first');
+    const second = await createVerifiedSession('impersonate-key-reuse-second');
+
+    const minted = await impersonateMint({
+      token: ownerToken,
+      targetUserId: first.userId,
+      idempotencyKey: 'impersonate-key-reuse',
+    });
+    expect(minted.statusCode).toBe(200);
+
+    const reused = await impersonateMint({
+      token: ownerToken,
+      targetUserId: second.userId,
+      idempotencyKey: 'impersonate-key-reuse',
+    });
+    expect(reused.statusCode).toBe(409);
+    expect(reused.json().code).toBe('idempotency-key-reused');
+    // The 409 is a client-contract error: no denial event is published under
+    // the same fingerprint, so replay markers stay unambiguous.
+    const events = await impersonationEvents();
+    expect(events).toHaveLength(1);
+    expect(events[0]?.result).toBe('succeeded');
+  });
+
+  test('rate-limits impersonation mints by source IP', async () => {
+    const ownerToken = await bootstrapOwner('impersonate-rate-limit');
+    const target = await createVerifiedSession('impersonate-rate-limit-target');
+
+    await seedExhaustedIpBucket({
+      action: 'impersonate',
+      identifier: '127.0.0.1',
+      limit: 20,
+      windowSeconds: 15 * 60,
+    });
+    const blocked = await impersonateMint({
+      token: ownerToken,
+      targetUserId: target.userId,
+      idempotencyKey: 'impersonate-rate-limit',
+    });
+    expect(blocked.statusCode).toBe(429);
+  });
+
+  test('rate-limits impersonation mints per actor', async () => {
+    const owner = await createVerifiedSession('impersonate-actor-limit-owner');
+    const bootstrap = await app.inject({
+      method: 'POST',
+      url: '/admin/auth/admin-grants/bootstrap',
+      headers: authHeaders(owner.token, 'impersonate-actor-limit-bootstrap'),
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+    expect(bootstrap.statusCode).toBe(201);
+    const target = await createVerifiedSession('impersonate-actor-limit-target');
+
+    await seedExhaustedIpBucket({
+      action: 'impersonate',
+      scope: 'actor',
+      identifier: owner.userId,
+      limit: 20,
+      windowSeconds: 15 * 60,
+    });
+    const blocked = await impersonateMint({
+      token: owner.token,
+      targetUserId: target.userId,
+      idempotencyKey: 'impersonate-actor-limit',
+    });
+    expect(blocked.statusCode).toBe(429);
+  });
+
+  test('rate-limits an impersonated-session probe on the mint route before the guard rejects it', async () => {
+    const owner = await createVerifiedSession('impersonate-probe-owner');
+    const target = await createVerifiedSession('impersonate-probe-target');
+    const markedToken = await impersonatedToken(owner.userId, owner.email);
+
+    // The limiter runs ahead of the administration guard, so a marked-session
+    // probe consumes the `impersonate` buckets and is throttled (429) instead
+    // of being rejected by the guard first and bypassing the limiter (403).
+    await seedExhaustedIpBucket({
+      action: 'impersonate',
+      identifier: '127.0.0.1',
+      limit: 20,
+      windowSeconds: 15 * 60,
+    });
+    const ipBlocked = await app.inject({
+      method: 'POST',
+      url: `/admin/auth/users/${target.userId}/impersonate`,
+      headers: authHeaders(markedToken, 'impersonate-probe-mint'),
+      payload: {reason: 'Nested impersonation attempt'},
+    });
+    expect(ipBlocked.statusCode).toBe(429);
+
+    // The per-actor bucket is consumed the same way: the marked token's
+    // subject is the actor keying the bucket. The limiter enforces IP before
+    // actor, and the first half exhausted the 127.0.0.1 IP bucket, so the
+    // probe must come from a fresh source IP for the 429 to be attributable
+    // to the seeded actor bucket alone.
+    await seedExhaustedIpBucket({
+      action: 'impersonate',
+      scope: 'actor',
+      identifier: owner.userId,
+      limit: 20,
+      windowSeconds: 15 * 60,
+    });
+    const actorBlocked = await app.inject({
+      method: 'POST',
+      url: `/admin/auth/users/${target.userId}/impersonate`,
+      headers: authHeaders(markedToken, 'impersonate-probe-mint'),
+      remoteAddress: '10.0.0.1',
+      payload: {reason: 'Nested impersonation attempt'},
+    });
+    expect(actorBlocked.statusCode).toBe(429);
+  });
+
+  test('rejects an impersonated actor on the mint route before any side effect', async () => {
+    const owner = await createVerifiedSession('impersonate-actor');
+    const target = await createVerifiedSession('impersonate-actor-target');
+
+    const response = await app.inject({
+      method: 'POST',
+      url: `/admin/auth/users/${target.userId}/impersonate`,
+      headers: authHeaders(
+        await impersonatedToken(owner.userId, owner.email),
+        'impersonate-actor-mint',
+      ),
+      payload: {reason: 'Nested impersonation attempt'},
+    });
+
+    expect(response.statusCode).toBe(403);
+    expect(response.json()).toEqual({code: 'admin-role-required'});
+    await expect(db().select().from(adminCommandResults)).resolves.toHaveLength(0);
+    await expect(db().select().from(authOutbox)).resolves.toHaveLength(0);
+  });
+
+  test('requires a bounded reason on the mint route', async () => {
+    const ownerToken = await bootstrapOwner('impersonate-reason');
+    const target = await createVerifiedSession('impersonate-reason-target');
+
+    const withoutReason = await app.inject({
+      method: 'POST',
+      url: `/admin/auth/users/${target.userId}/impersonate`,
+      headers: authHeaders(ownerToken, 'impersonate-reason-missing'),
+      payload: {},
+    });
+    expect(withoutReason.statusCode).toBe(400);
+
+    const withControlCharacter = await app.inject({
+      method: 'POST',
+      url: `/admin/auth/users/${target.userId}/impersonate`,
+      headers: authHeaders(ownerToken, 'impersonate-reason-control'),
+      payload: {reason: 'Support\u0000reproduction'},
+    });
+    expect(withControlCharacter.statusCode).toBe(400);
+  });
 });