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: '/',