Superadmin impersonation, hardened auth/upload paths, dependency updates

- Add superadmin impersonation: sessions.impersonated_by (migration 0003) is
  stamped onto audit rows so impersonated actions are attributable, with a
  persistent ImpersonationBanner in the app shell.
- Harden auth and upload handling across routes (safe redirect targets,
  filename sanitization, checkout grant handling).
- Update dependencies: Sentry 8 -> 10, @fastify/static 8 -> 10,
  react-router-dom 6.30.6; add find-my-way / fast-uri overrides.
- Add tests for safe-next, checkout-grant, and upload-filename.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

apps/api/src/auth/plugin.ts

@@ -4,6 +4,8 @@ import { SESSION_COOKIE, loadSession } from './sessions';
 import { isProd, env } from '../env';
 import { ensureSuperadminFlag } from './superadmin';
 
+export type FirmRole = 'owner' | 'attorney' | 'paralegal' | 'staff';
+
 declare module 'fastify' {
   interface FastifyRequest {
     user?: {
@@ -14,12 +16,17 @@ declare module 'fastify' {
       isSuperadmin: boolean;
       isSuspended: boolean;
       emailVerified: boolean;
+      /** Superadmin id when this session was opened via admin impersonation, else null. */
+      impersonatedBy: string | null;
     };
   }
   interface FastifyInstance {
     requireAuth: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
     requireFirm: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
     requireSuperadmin: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+    requireRole: (
+      ...roles: FirmRole[]
+    ) => (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
     setSessionCookie: (reply: FastifyReply, token: string, expiresAt: Date) => void;
     clearSessionCookie: (reply: FastifyReply) => void;
   }
@@ -49,6 +56,7 @@ async function plugin(app: FastifyInstance) {
       isSuperadmin,
       isSuspended: session.user.isSuspended,
       emailVerified: Boolean(session.user.emailVerifiedAt),
+      impersonatedBy: session.session.impersonatedBy,
     };
   });
 
@@ -67,8 +75,28 @@ async function plugin(app: FastifyInstance) {
     if (!req.user) return reply.code(401).send({ error: 'unauthorized' });
     if (req.user.isSuspended) return reply.code(403).send({ error: 'account_suspended' });
     if (!req.user.isSuperadmin) return reply.code(403).send({ error: 'forbidden' });
+    // A superadmin who impersonated their way into a firm must not be able to steer the
+    // platform-wide admin surface from inside that borrowed session.
+    if (req.user.impersonatedBy) return reply.code(403).send({ error: 'forbidden_while_impersonating' });
   });
 
+  // Role gate for firm-scoped routes that only some members of a firm should reach (billing,
+  // full-firm export, account deletion). Compose AFTER requireFirm — it assumes req.user is set
+  // and firmId is present. Superadmins pass, unless they're inside an impersonated session, in
+  // which case they get exactly the target user's real authority and nothing more.
+  app.decorate(
+    'requireRole',
+    (...roles: FirmRole[]) =>
+      async (req: FastifyRequest, reply: FastifyReply) => {
+        if (!req.user) return reply.code(401).send({ error: 'unauthorized' });
+        if (req.user.isSuspended) return reply.code(403).send({ error: 'account_suspended' });
+        if (req.user.isSuperadmin && !req.user.impersonatedBy) return;
+        if (!roles.includes(req.user.role as FirmRole)) {
+          return reply.code(403).send({ error: 'insufficient_role', required: roles });
+        }
+      },
+  );
+
   app.decorate('setSessionCookie', (reply: FastifyReply, token: string, expiresAt: Date) => {
     reply.setCookie(SESSION_COOKIE, token, {
       path: '/',

apps/api/src/auth/sessions.ts

@@ -4,6 +4,9 @@ import { getDb, sessions, users } from '@lawdesk/db';
 
 const SESSION_BYTES = 32;
 const SESSION_TTL_DAYS = 30;
+// Impersonation sessions are support tools, not logins: they expire in an hour so an admin who
+// walks away can't leave a live session inside a customer's firm for the normal 30 days.
+const IMPERSONATION_TTL_MS = 60 * 60 * 1000;
 
 export const SESSION_COOKIE = 'sid';
 
@@ -19,17 +22,23 @@ export interface CreateSessionOpts {
   userId: string;
   ip?: string | null;
   userAgent?: string | null;
+  /** Superadmin id when this session is an impersonation of `userId`. */
+  impersonatedBy?: string | null;
 }
 
 export async function createSession(opts: CreateSessionOpts): Promise<{ token: string; expiresAt: Date }> {
   const token = generateSessionToken();
   const id = hashSessionToken(token);
-  const expiresAt = new Date(Date.now() + SESSION_TTL_DAYS * 24 * 60 * 60 * 1000);
+  const impersonatedBy = opts.impersonatedBy ?? null;
+  const expiresAt = new Date(
+    Date.now() + (impersonatedBy ? IMPERSONATION_TTL_MS : SESSION_TTL_DAYS * 24 * 60 * 60 * 1000),
+  );
 
   await getDb().insert(sessions).values({
     id,
     userId: opts.userId,
     expiresAt,
+    impersonatedBy,
     ip: opts.ip ?? null,
     userAgent: opts.userAgent ?? null,
   });