@shipfox/api-auth 13.1.0 → 17.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-auth",
   "license": "MIT",
-  "version": "13.1.0",
+  "version": "17.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -26,25 +26,25 @@
     "@node-rs/argon2": "^2.0.2",
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
-    "@shipfox/api-common-dto": "12.0.0",
-    "@shipfox/api-auth-context": "12.2.0",
-    "@shipfox/api-auth-dto": "12.0.0",
-    "@shipfox/api-email-challenges": "1.1.9",
-    "@shipfox/api-workspaces-dto": "12.0.0",
+    "@shipfox/api-common-dto": "15.0.0",
+    "@shipfox/api-auth-context": "17.0.0",
+    "@shipfox/api-auth-dto": "17.0.0",
+    "@shipfox/api-email-challenges": "1.1.11",
+    "@shipfox/api-workspaces-dto": "15.0.0",
     "@shipfox/inter-module": "0.2.3",
     "@shipfox/config": "1.2.4",
     "@shipfox/node-drizzle": "0.3.5",
     "@shipfox/node-auth-root-key": "0.2.3",
-    "@shipfox/node-fastify": "0.4.2",
+    "@shipfox/node-fastify": "0.4.3",
     "@shipfox/node-jwt": "0.4.0",
     "@shipfox/node-email": "0.3.5",
-    "@shipfox/node-mailer": "0.2.5",
-    "@shipfox/node-module": "1.0.6",
-    "@shipfox/node-opentelemetry": "0.6.4",
+    "@shipfox/node-mailer": "0.2.6",
+    "@shipfox/node-module": "1.0.7",
+    "@shipfox/node-opentelemetry": "0.6.5",
     "@shipfox/node-outbox": "0.2.6",
-    "@shipfox/node-postgres": "0.5.0",
+    "@shipfox/node-postgres": "0.5.1",
     "@shipfox/node-rate-limit": "0.4.0",
-    "@shipfox/node-tokens": "0.3.2"
+    "@shipfox/node-tokens": "0.3.3"
   },
   "imports": {
     "#*": "./dist/*"

package/src/config.ts

@@ -10,6 +10,10 @@ export const config = createConfig({
     desc: 'How long an access token stays valid. Accepts a duration string such as 15m, 1h, or 7d.',
     default: '15m',
   }),
+  AUTH_IMPERSONATION_ENABLED: bool({
+    desc: 'Whether administrators can mint impersonated sessions for target users. Defaults to false: the source-available client ships no impersonation banner, so enable it only where every signed-in surface renders one.',
+    default: false,
+  }),
   AUTH_JOB_LEASE_TOKEN_EXPIRES_IN: str({
     desc: 'How long a job lease token stays valid. Set it longer than the longest job (JOB_MAX_DURATION is 60 minutes) plus a safety margin.',
     default: '90m',

package/src/core/administration.ts

@@ -1,6 +1,7 @@
 import {timingSafeEqual} from 'node:crypto';
 import type {AdminRole} from '@shipfox/api-auth-dto';
 import {createAdministrationActionEvent} from '@shipfox/api-common-dto';
+import type {WorkspacesInterModuleClient} from '@shipfox/api-workspaces-dto/inter-module';
 import type {TimestampIdCursor} from '@shipfox/node-drizzle';
 import {hashOpaqueToken} from '@shipfox/node-tokens';
 import {config} from '#config.js';
@@ -18,7 +19,14 @@ import {
   type UserModerationResult,
 } from '#db/admin-user-moderation.js';
 import {findAdministratorUser as findAdministratorUserInDb} from '#db/admin-users.js';
-import {requireAdminRole} from './admin-role.js';
+import {
+  type ImpersonationResult,
+  impersonateUserWithAudit,
+  impersonationSucceededEventExists,
+  publishImpersonationFailure,
+} from '#db/impersonation.js';
+import {recordImpersonationOutcome} from '#metrics/index.js';
+import {getCurrentAdminRole, requireAdminRole} from './admin-role.js';
 import type {AdminGrant} from './entities/admin-grant.js';
 import type {
   AdministratorGrantSummary,
@@ -29,7 +37,15 @@ import {
   AdminGrantAlreadyExistsError,
   AdminGrantNotFoundError,
   AdminIdempotencyKeyReuseError,
+  AdminRoleRequiredError,
+  CannotImpersonateAdministratorError,
+  CannotImpersonateSelfError,
+  EmailNotVerifiedError,
+  ImpersonationDisabledError,
+  ImpersonationExpiredError,
+  ImpersonationTargetNotActiveError,
   InvalidAdminBootstrapTokenError,
+  InvalidCredentialsError,
   LastAdminOwnerError,
   UserNotFoundError,
 } from './errors.js';
@@ -43,6 +59,35 @@ const REVOKE_COMMAND = 'auth.admin_grant.revoke';
 const SUSPEND_USER_COMMAND = 'auth.user.suspend';
 const REACTIVATE_USER_COMMAND = 'auth.user.reactivate';
 const REVOKE_USER_SESSIONS_COMMAND = 'auth.user.revoke-sessions';
+const IMPERSONATE_COMMAND = 'auth.user.impersonate';
+
+/**
+ * Client-contract errors are reported to the caller, not the denial stream: a
+ * 404 for an unknown target or a 409 for a reused key is a request mistake,
+ * and auditing each retry would drown the `failed` event stream under durable
+ * rows that a security review cannot distinguish from genuine denials.
+ */
+function isImpersonationClientContractError(error: unknown): boolean {
+  return error instanceof AdminIdempotencyKeyReuseError || error instanceof UserNotFoundError;
+}
+
+/**
+ * Deterministic authorization and eligibility denials. They are raised before
+ * the command transaction writes anything, so the transaction is known to have
+ * rolled back and the failure event is an unambiguous audit of the denial.
+ */
+function isImpersonationDenial(error: unknown): boolean {
+  return (
+    error instanceof ImpersonationDisabledError ||
+    error instanceof AdminRoleRequiredError ||
+    error instanceof CannotImpersonateSelfError ||
+    error instanceof CannotImpersonateAdministratorError ||
+    error instanceof ImpersonationTargetNotActiveError ||
+    error instanceof ImpersonationExpiredError ||
+    error instanceof EmailNotVerifiedError ||
+    error instanceof InvalidCredentialsError
+  );
+}
 
 export function administrationCommandFingerprint(command: string, input: unknown): string {
   return hashOpaqueToken(`${command}:${JSON.stringify(input)}`);
@@ -329,11 +374,137 @@ export async function revokeAdministratorUserSessions(
   );
 }
 
+export interface ImpersonateUserParams extends AdministrationMutationContext {
+  targetUserId: string;
+  reason: string;
+  /**
+   * The actor's own session mark, from the verified request context. The
+   * positional `/admin` guard rejects an impersonated actor before this
+   * command runs; the command refuses the same mark defensively.
+   */
+  actorImpersonatorId?: string | undefined;
+  workspaces: WorkspacesInterModuleClient;
+}
+
+/**
+ * Mints a short-lived, marked, audited impersonated session for a target
+ * user. Enforces the authorization and eligibility ladder (rules 1-6), the
+ * fingerprint-only idempotency flow (replay re-runs the ladder and re-signs
+ * with the original expiry), and the audit event contract: success and replay
+ * events commit atomically with the command result, and failure events commit
+ * in their own transaction after the rollback.
+ */
+export async function impersonateUser(params: ImpersonateUserParams): Promise<ImpersonationResult> {
+  const idempotencyKeyFingerprint = hashOpaqueToken(params.idempotencyKey);
+  const requestFingerprint = administrationCommandFingerprint(IMPERSONATE_COMMAND, {
+    targetUserId: params.targetUserId,
+    reason: params.reason,
+  });
+  try {
+    // Rule 1: the capability is an explicit opt-in; the flag is a kill switch
+    // and must hold on the replay path as well as the initial mint.
+    if (!config.AUTH_IMPERSONATION_ENABLED) throw new ImpersonationDisabledError();
+    // Rule 3: an impersonated actor cannot impersonate (nested impersonation).
+    if (params.actorImpersonatorId !== undefined) {
+      throw new AdminRoleRequiredError(ADMIN_OPERATOR_ROLE);
+    }
+    // Rule 2: minimum admin-operator, the same bar as suspension and session
+    // revocation. Re-checked inside the transaction on every path, replay
+    // included, so a revocation mid-window ends the capability immediately.
+    await requireAdminRole({
+      userId: params.actorId,
+      minimumRole: ADMIN_OPERATOR_ROLE,
+    });
+    const result = await impersonateUserWithAudit({
+      actorId: params.actorId,
+      targetUserId: params.targetUserId,
+      reason: params.reason,
+      idempotencyKeyFingerprint,
+      requestFingerprint,
+      correlationId: params.correlationId,
+      workspaces: params.workspaces,
+    });
+    recordImpersonationOutcome('succeeded');
+    return result;
+  } catch (error) {
+    // The command did not hand out a token, so the attempt is a failed outcome
+    // regardless of why: mint-volume and denial-spike alerts key off this.
+    recordImpersonationOutcome('failed');
+    // Client-contract errors (unknown target, reused key) are reported to the
+    // caller and never enter the denial stream.
+    if (isImpersonationClientContractError(error)) throw error;
+    // Deterministic denials always audit: their transaction rolled back with
+    // nothing written, so the `failed` event is unambiguous even when a
+    // previous mint under the same key left a committed result row.
+    if (isImpersonationDenial(error)) {
+      await publishImpersonationFailureForActor(params, {
+        idempotencyKeyFingerprint,
+        correlationId: params.correlationId,
+      });
+      throw error;
+    }
+    // An unexpected error may be an ambiguous COMMIT: the mint transaction
+    // committed (result row and `succeeded` event are durable) but the driver
+    // raised on the acknowledgement. Publishing a `failed` event then would
+    // contradict the committed trail, so reconcile against the committed
+    // `succeeded` event for THIS invocation before writing anything: the event
+    // is written atomically with the result row, and its correlationId is
+    // unique per request, so a result row committed by an earlier mint or
+    // replay under the same key is never mistaken for this invocation's
+    // commit. The reconcile is best-effort: never mask the original error.
+    let committed = false;
+    try {
+      committed = await impersonationSucceededEventExists({
+        actorId: params.actorId,
+        idempotencyKeyFingerprint,
+        correlationId: params.correlationId,
+      });
+    } catch {
+      // Fall through: publish the failure event rather than losing the denial.
+    }
+    if (!committed) {
+      await publishImpersonationFailureForActor(params, {
+        idempotencyKeyFingerprint,
+        correlationId: params.correlationId,
+      });
+    }
+    throw error;
+  }
+}
+
+async function publishImpersonationFailureForActor(
+  params: ImpersonateUserParams,
+  audit: {idempotencyKeyFingerprint: string; correlationId: string},
+): Promise<void> {
+  // Failures publish from a separate committed transaction after the rollback:
+  // the main transaction is gone, so an event written inside it would
+  // disappear, and the role check runs before it even opens.
+  let actorRole: AdminRole | null = null;
+  try {
+    actorRole = await getCurrentAdminRole({userId: params.actorId});
+  } catch {
+    // The failure event is best-effort; never mask the original error.
+  }
+  await publishImpersonationFailure({
+    actorId: params.actorId,
+    targetUserId: params.targetUserId,
+    reason: params.reason,
+    actorRole,
+    idempotencyKeyFingerprint: audit.idempotencyKeyFingerprint,
+    correlationId: audit.correlationId,
+  });
+}
+
 export {
   AdminBootstrapClosedError,
   AdminGrantAlreadyExistsError,
   AdminGrantNotFoundError,
   AdminIdempotencyKeyReuseError,
+  CannotImpersonateAdministratorError,
+  CannotImpersonateSelfError,
+  ImpersonationDisabledError,
+  ImpersonationExpiredError,
+  ImpersonationTargetNotActiveError,
   InvalidAdminBootstrapTokenError,
   LastAdminOwnerError,
   UserNotFoundError,

package/src/core/auth.test.ts

@@ -6,6 +6,7 @@ import {and, desc, eq, sql} from 'drizzle-orm';
 import {
   changePassword,
   confirmPasswordReset as coreConfirmPasswordReset,
+  createImpersonatedSessionToken as coreCreateImpersonatedSessionToken,
   createSessionForUser as coreCreateSessionForUser,
   login as coreLogin,
   refreshAccessToken as coreRefreshAccessToken,
@@ -58,6 +59,7 @@ const testConfig = vi.hoisted(
 vi.mock('#config.js', () => ({
   config: {
     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',
@@ -93,6 +95,11 @@ const workspaces = {
 const login = (params: {email: string; password: string}) => coreLogin({...params, workspaces});
 const createSessionForUser = (params: {userId?: string; email?: string}) =>
   coreCreateSessionForUser({...params, workspaces});
+const createImpersonatedSessionToken = (params: {
+  targetUserId: string;
+  impersonatorId: string;
+  expiresIn?: string;
+}) => coreCreateImpersonatedSessionToken({...params, workspaces});
 const refreshAccessToken = (params: {refreshToken: string}) =>
   coreRefreshAccessToken({...params, workspaces});
 const confirmPasswordReset = (params: {token: string; newPassword: string}) =>
@@ -445,6 +452,78 @@ describe('auth core', () => {
     await Promise.all([unverifiedExpectation, suspendedExpectation]);
   });
 
+  test('createImpersonatedSessionToken mints a marked access-token-only session with a capped TTL', async () => {
+    const target = await userFactory.create({emailVerifiedAt: new Date()});
+    const impersonatorId = crypto.randomUUID();
+    const membership = {
+      workspaceId: crypto.randomUUID(),
+      role: 'admin' as const,
+      workspaceStatus: 'active' as const,
+    };
+    listMembershipsByUserMock.mockResolvedValue({memberships: [membership]});
+
+    const result = await createImpersonatedSessionToken({
+      targetUserId: target.id,
+      impersonatorId,
+    });
+
+    expect(result.user.id).toBe(target.id);
+    expect(result.expiresAt.getTime() - Date.now()).toBeGreaterThan(0);
+    expect(result.expiresAt.getTime() - Date.now()).toBeLessThanOrEqual(15 * 60 * 1000);
+
+    const claims = await verifyUserToken({token: result.token, secret: userAccessTokenKey()});
+    expect(claims.sub).toBe(target.id);
+    expect(claims.impersonatorId).toBe(impersonatorId);
+    expect(claims.refreshSessionId).toBeUndefined();
+    expect(claims.memberships).toEqual([membership]);
+    // TTL is capped at 15 minutes (AUTH_JWT_EXPIRES_IN is 15m in this suite).
+    expect(claims.exp - claims.iat).toBeLessThanOrEqual(15 * 60);
+    expect(claims.exp - claims.iat).toBeGreaterThan(0);
+    // The advertised expiry is the token's actual signed `exp`, never a
+    // clock-derived estimate: the response and the bearer token cannot diverge.
+    expect(result.expiresAt.getTime()).toBe(claims.exp * 1000);
+
+    // No refresh session row and no refresh token material for the target.
+    const sessions = await db()
+      .select({sessionId: refreshTokens.sessionId})
+      .from(refreshTokens)
+      .where(eq(refreshTokens.userId, target.id));
+    expect(sessions).toHaveLength(0);
+  });
+
+  test('createImpersonatedSessionToken re-signs with an explicit lifetime without extending the cap', async () => {
+    const target = await userFactory.create({emailVerifiedAt: new Date()});
+
+    const result = await createImpersonatedSessionToken({
+      targetUserId: target.id,
+      impersonatorId: crypto.randomUUID(),
+      expiresIn: '30m',
+    });
+
+    const claims = await verifyUserToken({token: result.token, secret: userAccessTokenKey()});
+    expect(claims.exp - claims.iat).toBeLessThanOrEqual(15 * 60);
+  });
+
+  test('createImpersonatedSessionToken reuses the createSessionForUser eligibility rules', async () => {
+    const unverified = await userFactory.create();
+    const suspended = await userFactory.create({emailVerifiedAt: new Date()});
+    await db().update(users).set({status: 'suspended'}).where(eq(users.id, suspended.id));
+    const impersonatorId = crypto.randomUUID();
+
+    await expect(
+      createImpersonatedSessionToken({targetUserId: unverified.id, impersonatorId}),
+    ).rejects.toBeInstanceOf(EmailNotVerifiedError);
+    await expect(
+      createImpersonatedSessionToken({targetUserId: suspended.id, impersonatorId}),
+    ).rejects.toBeInstanceOf(InvalidCredentialsError);
+    await expect(
+      createImpersonatedSessionToken({
+        targetUserId: crypto.randomUUID(),
+        impersonatorId,
+      }),
+    ).rejects.toBeInstanceOf(UserNotFoundError);
+  });
+
   test('refreshAccessToken rotates the refresh token', async () => {
     const user = await userFactory.create({emailVerifiedAt: new Date()});
     const loginResult = await login({email: user.email, password: user.plainPassword});

package/src/core/auth.ts

@@ -11,6 +11,7 @@ import {
 } from '@shipfox/api-workspaces-dto/inter-module';
 import {isInterModuleKnownError} from '@shipfox/inter-module';
 import {userAccessTokenKey} from '@shipfox/node-auth-root-key';
+import {durationToSeconds} from '@shipfox/node-jwt';
 import {generateOpaqueToken, hashOpaqueToken} from '@shipfox/node-tokens';
 import {config} from '#config.js';
 import {consumePasswordReset, createPasswordReset} from '#db/password-resets.js';
@@ -38,6 +39,7 @@ import {
   AuthDependencyUnavailableError,
   EmailNotVerifiedError,
   EmailTakenError,
+  ImpersonationDisabledError,
   InvalidCredentialsError,
   InvitationEmailMismatchError,
   SignupNotAllowedError,
@@ -46,7 +48,7 @@ import {
   TokenInvalidError,
   UserNotFoundError,
 } from './errors.js';
-import {signUserToken, type TokenMembership} from './jwt.js';
+import {signUserToken, type TokenMembership, verifyUserToken} from './jwt.js';
 import {hashPassword, verifyPassword} from './password.js';
 import type {SignupPolicy} from './ports.js';
 import {createEnvironmentSignupPolicy} from './signup-policy.js';
@@ -461,6 +463,101 @@ export async function createSessionForUser(
   return {token, refreshToken, user, adminRole};
 }
 
+/**
+ * Cap for impersonated session tokens: the TTL is min(`AUTH_JWT_EXPIRES_IN`,
+ * this), so an impersonated window can never outlive 15 minutes no matter how
+ * the deployment configures ordinary access tokens.
+ */
+export const IMPERSONATION_MAX_TTL_SECONDS = 15 * 60;
+
+export interface CreateImpersonatedSessionTokenParams {
+  targetUserId: string;
+  /** The administrator the token is minted for; signed into the `impersonatorId` claim. */
+  impersonatorId: string;
+  workspaces: WorkspacesInterModuleClient;
+  /**
+   * Re-sign lifetime override used by an idempotent replay: the remaining
+   * lifetime to the stored `expires_at`, so a replay never extends the window.
+   * Defaults to min(`AUTH_JWT_EXPIRES_IN`, 15 minutes).
+   */
+  expiresIn?: string | undefined;
+}
+
+export interface CreateImpersonatedSessionTokenResult {
+  token: string;
+  expiresAt: Date;
+  user: User;
+}
+
+function impersonationTtlSeconds(): number {
+  const configuredSeconds = durationToSeconds(config.AUTH_JWT_EXPIRES_IN);
+  const ttlSeconds = Math.min(configuredSeconds, IMPERSONATION_MAX_TTL_SECONDS);
+  if (ttlSeconds <= 0) {
+    throw new TypeError(
+      `AUTH_JWT_EXPIRES_IN must be a valid duration of at least 1 second, got ${config.AUTH_JWT_EXPIRES_IN}`,
+    );
+  }
+  return ttlSeconds;
+}
+
+/**
+ * Mints an access-token-only impersonated session for a target user: the same
+ * eligibility as login (active account, verified email), the target's real
+ * membership claims, a capped TTL, the `impersonatorId` claim, and **no**
+ * `refreshSessionId`. It creates no refresh session and sets no cookie, so
+ * nothing persisted can resurrect the session after the token window.
+ */
+export async function createImpersonatedSessionToken(
+  params: CreateImpersonatedSessionTokenParams,
+): Promise<CreateImpersonatedSessionTokenResult> {
+  // Rule 1 lives in the mint primitive as well as the command entry, so the
+  // exported package API can never bypass the kill switch: the flag is a
+  // configuration read that also holds on the in-transaction replay path.
+  if (!config.AUTH_IMPERSONATION_ENABLED) throw new ImpersonationDisabledError();
+
+  const user = await findUserById({id: params.targetUserId});
+  if (!user) {
+    throw new UserNotFoundError(params.targetUserId);
+  }
+  if (user.emailVerifiedAt === null) {
+    throw new EmailNotVerifiedError();
+  }
+  if (user.status !== 'active') {
+    throw new InvalidCredentialsError();
+  }
+
+  const memberships = await loadTokenMemberships(user.id, params.workspaces);
+  const ttlSeconds =
+    params.expiresIn === undefined
+      ? impersonationTtlSeconds()
+      : Math.min(durationToSeconds(params.expiresIn), IMPERSONATION_MAX_TTL_SECONDS);
+  if (ttlSeconds <= 0) {
+    throw new TypeError(
+      `Impersonation token TTL must be at least 1 second, got ${params.expiresIn}`,
+    );
+  }
+
+  const token = await signUserToken({
+    userId: user.id,
+    email: user.email,
+    name: user.name,
+    memberships,
+    impersonatorId: params.impersonatorId,
+    secret: userAccessTokenKey(),
+    expiresIn: `${ttlSeconds}s`,
+  });
+
+  // The advertised expiry is the token's actual signed `exp`, never a
+  // clock-derived estimate: the signer stamps `iat`/`exp` in whole seconds, so
+  // `Date.now() + ttl` could drift up to a second from the signed claims in
+  // either direction. Deriving `expiresAt` from the signed token keeps the
+  // response, the stored command result, and the bearer token exactly aligned,
+  // which is what lets a replay re-sign with a TTL that never extends the
+  // window (`exp` of the re-signed token is at most the original `exp`).
+  const claims = await verifyUserToken({token, secret: userAccessTokenKey()});
+  return {token, expiresAt: new Date(claims.exp * 1000), user};
+}
+
 export interface RefreshAccessTokenResult {
   token: string;
   /** Undefined on a grace-window hit: keep the existing cookie instead of rotating it. */

package/src/core/errors.ts

@@ -137,6 +137,41 @@ export class AdminIdempotencyKeyReuseError extends Error {
   }
 }
 
+export class ImpersonationDisabledError extends Error {
+  constructor() {
+    super('Impersonation is disabled');
+    this.name = 'ImpersonationDisabledError';
+  }
+}
+
+export class CannotImpersonateSelfError extends Error {
+  constructor() {
+    super('Cannot impersonate yourself');
+    this.name = 'CannotImpersonateSelfError';
+  }
+}
+
+export class CannotImpersonateAdministratorError extends Error {
+  constructor() {
+    super('Cannot impersonate an administrator');
+    this.name = 'CannotImpersonateAdministratorError';
+  }
+}
+
+export class ImpersonationTargetNotActiveError extends Error {
+  constructor() {
+    super('Impersonation target is not active or verified');
+    this.name = 'ImpersonationTargetNotActiveError';
+  }
+}
+
+export class ImpersonationExpiredError extends Error {
+  constructor() {
+    super('Impersonation session has expired');
+    this.name = 'ImpersonationExpiredError';
+  }
+}
+
 export class TokenInvalidError extends Error {
   constructor(reason?: string) {
     super(reason ? `Invalid token: ${reason}` : 'Invalid token');

package/src/core/jwt.test.ts

@@ -31,10 +31,102 @@ describe('jwt', () => {
     expect(claims.name).toBe('Token User');
     expect(claims.memberships).toEqual(memberships);
     expect(claims).not.toHaveProperty('adminRole');
+    expect(claims.impersonatorId).toBeUndefined();
     expect(claims.iat).toBeTypeOf('number');
     expect(claims.exp).toBeGreaterThan(claims.iat);
   });
 
+  test('signs and verifies a token carrying an impersonatorId claim', async () => {
+    const userId = crypto.randomUUID();
+    const impersonatorId = crypto.randomUUID();
+
+    const token = await signUserToken({
+      userId,
+      impersonatorId,
+      email: `jwt-${crypto.randomUUID()}@example.com`,
+      memberships: [],
+      secret: SECRET,
+      expiresIn: '15m',
+    });
+    const claims = await verifyUserToken({token, secret: SECRET});
+
+    expect(claims.sub).toBe(userId);
+    expect(claims.impersonatorId).toBe(impersonatorId);
+  });
+
+  test('rejects a non-UUID impersonatorId at signing time', async () => {
+    await expect(
+      signUserToken({
+        userId: crypto.randomUUID(),
+        impersonatorId: 'not-a-uuid',
+        email: `jwt-${crypto.randomUUID()}@example.com`,
+        memberships: [],
+        secret: SECRET,
+        expiresIn: '15m',
+      }),
+    ).rejects.toThrow('impersonatorId must be a UUID');
+  });
+
+  test('rejects a self-impersonation impersonatorId at signing time', async () => {
+    const userId = crypto.randomUUID();
+    await expect(
+      signUserToken({
+        userId,
+        impersonatorId: userId,
+        email: `jwt-${crypto.randomUUID()}@example.com`,
+        memberships: [],
+        secret: SECRET,
+        expiresIn: '15m',
+      }),
+    ).rejects.toThrow('impersonatorId must differ from userId');
+  });
+
+  test('rejects a self-impersonation impersonatorId in a different UUID casing', async () => {
+    const userId = crypto.randomUUID();
+    await expect(
+      signUserToken({
+        userId,
+        impersonatorId: userId.toUpperCase(),
+        email: `jwt-${crypto.randomUUID()}@example.com`,
+        memberships: [],
+        secret: SECRET,
+        expiresIn: '15m',
+      }),
+    ).rejects.toThrow('impersonatorId must differ from userId');
+  });
+
+  test('rejects a crafted token whose impersonatorId equals sub', async () => {
+    const userId = crypto.randomUUID();
+    const token = await new SignJWT({
+      email: `jwt-${crypto.randomUUID()}@example.com`,
+      memberships: [],
+      impersonatorId: userId,
+    })
+      .setProtectedHeader({alg: 'HS256'})
+      .setSubject(userId)
+      .setIssuedAt()
+      .setExpirationTime('7d')
+      .sign(encodeSecret(SECRET));
+
+    await expect(verifyUserToken({token, secret: SECRET})).rejects.toThrow();
+  });
+
+  test('rejects a crafted token whose impersonatorId equals sub in a different casing', async () => {
+    const userId = crypto.randomUUID();
+    const token = await new SignJWT({
+      email: `jwt-${crypto.randomUUID()}@example.com`,
+      memberships: [],
+      impersonatorId: userId.toUpperCase(),
+    })
+      .setProtectedHeader({alg: 'HS256'})
+      .setSubject(userId)
+      .setIssuedAt()
+      .setExpirationTime('7d')
+      .sign(encodeSecret(SECRET));
+
+    await expect(verifyUserToken({token, secret: SECRET})).rejects.toThrow();
+  });
+
   test('signs and verifies a token with empty memberships', async () => {
     const userId = crypto.randomUUID();
     const email = `jwt-${crypto.randomUUID()}@example.com`;