feat: Staff Impersonation backend + frontend wiring (#75)

* feat: implement Staff Impersonation backend and wire frontend Add server-side impersonation session management with full audit logging, replacing the frontend-only mock. Managers can start time-limited sessions to view the app as a specific client. Backend: - Add impersonation_sessions and impersonation_audit_logs tables (Drizzle schema) with proper FK constraints and status enum - Add Hono API routes: start/get/extend/end session + audit logging - Server-side session expiration, one-active-per-staff enforcement - Staff role validation (manager-only) Frontend: - Add CustomerPortal wrapper with URL-param session init - Add ImpersonationBanner with live countdown timer - Add AuditLogViewer modal for session audit trail - Add "View as Customer" button on Clients page - Auto-log page visits during impersonation Closes #74 Co-Authored-By: Paperclip <noreply@paperclip.ing> * chore: remove unused useNavigate import from Clients.tsx Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: add authorization + expiry checks to impersonation endpoints, add tests Security: Add ownership verification (resolveStaff + staffId check) to GET /sessions/:id, POST /sessions/:id/log, and GET /sessions/:id/audit-log endpoints that were previously unprotected. Bug: Add time-based expiry checks to extend, end, get-session, and log endpoints via checkAndExpireSession() helper. Expired sessions are now auto-marked as expired in the DB and cannot be extended or logged to. Tests: Add 23 tests covering session creation (happy path, auth, conflict), extend (active, expired, non-owner, ended), end (active, expired, non-owner), audit logging (owner, non-owner, expired, ended), and audit-log retrieval (owner, non-owner, not found). Addresses QA review on PR #75 (GRO-66). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: resolve @groombook/db source in vitest config Add resolve alias so vitest can resolve @groombook/db from source TypeScript files without requiring a prior build step. Fixes CI test failures when dist/ has not been compiled. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Groom Book CEO <ceo@groombook.dev> Co-authored-by: Paperclip <noreply@paperclip.ing> Co-authored-by: Groom Book CTO <cto@groombook.dev> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Scrubs McBarkley <scrubs@groombook.app>
2026-03-20 08:16:09 +00:00
parent ea5450651d
commit 70958542f8
6 changed files with 974 additions and 0 deletions
@@ -0,0 +1,330 @@
+import { Hono } from "hono";
+import { zValidator } from "@hono/zod-validator";
+import { z } from "zod";
+import {
+  and,
+  eq,
+  getDb,
+  impersonationSessions,
+  impersonationAuditLogs,
+  staff,
+  clients,
+  desc,
+} from "@groombook/db";
+import type { JwtPayload } from "../middleware/auth.js";
+
+type Env = { Variables: { jwtPayload: JwtPayload } };
+
+export const impersonationRouter = new Hono<Env>();
+
+const SESSION_TIMEOUT_MINUTES = 30;
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function expiresAt(minutes = SESSION_TIMEOUT_MINUTES) {
+  return new Date(Date.now() + minutes * 60_000);
+}
+
+/** Resolve the staff row for the authenticated OIDC subject. */
+async function resolveStaff(sub: string) {
+  const db = getDb();
+  const [row] = await db
+    .select()
+    .from(staff)
+    .where(eq(staff.oidcSub, sub));
+  return row ?? null;
+}
+
+/** Expire any timed-out active sessions for a given staff member. */
+async function expireTimedOutSessions(staffId: string) {
+  const db = getDb();
+  const now = new Date();
+  const active = await db
+    .select()
+    .from(impersonationSessions)
+    .where(
+      and(
+        eq(impersonationSessions.staffId, staffId),
+        eq(impersonationSessions.status, "active")
+      )
+    );
+  for (const s of active) {
+    if (s.expiresAt <= now) {
+      await db
+        .update(impersonationSessions)
+        .set({ status: "expired", endedAt: now })
+        .where(eq(impersonationSessions.id, s.id));
+    }
+  }
+}
+
+/**
+ * Check if an active session has expired by time. If so, mark it expired in DB
+ * and return true. Returns false if the session is still valid.
+ */
+async function checkAndExpireSession(
+  session: typeof impersonationSessions.$inferSelect
+): Promise<boolean> {
+  if (session.status !== "active") return false;
+  if (session.expiresAt > new Date()) return false;
+  const db = getDb();
+  const now = new Date();
+  await db
+    .update(impersonationSessions)
+    .set({ status: "expired", endedAt: now })
+    .where(eq(impersonationSessions.id, session.id));
+  return true;
+}
+
+// ─── POST / — Start a new impersonation session ─────────────────────────────
+
+const startSessionSchema = z.object({
+  clientId: z.string().uuid(),
+  reason: z.string().max(500).optional(),
+});
+
+impersonationRouter.post(
+  "/sessions",
+  zValidator("json", startSessionSchema),
+  async (c) => {
+    const db = getDb();
+    const jwt = c.get("jwtPayload") as JwtPayload;
+    const body = c.req.valid("json");
+
+    // Resolve authenticated staff
+    const staffRow = await resolveStaff(jwt.sub);
+    if (!staffRow) return c.json({ error: "Staff record not found" }, 403);
+    if (staffRow.role !== "manager") {
+      return c.json({ error: "Only managers can impersonate clients" }, 403);
+    }
+
+    // Verify client exists
+    const [client] = await db
+      .select()
+      .from(clients)
+      .where(eq(clients.id, body.clientId));
+    if (!client) return c.json({ error: "Client not found" }, 404);
+
+    // Expire timed-out sessions first
+    await expireTimedOutSessions(staffRow.id);
+
+    // Enforce one active session per staff member
+    const [existing] = await db
+      .select()
+      .from(impersonationSessions)
+      .where(
+        and(
+          eq(impersonationSessions.staffId, staffRow.id),
+          eq(impersonationSessions.status, "active")
+        )
+      );
+    if (existing) {
+      return c.json(
+        { error: "You already have an active impersonation session", sessionId: existing.id },
+        409
+      );
+    }
+
+    const [session] = await db
+      .insert(impersonationSessions)
+      .values({
+        staffId: staffRow.id,
+        clientId: body.clientId,
+        reason: body.reason ?? null,
+        expiresAt: expiresAt(),
+      })
+      .returning();
+
+    // Log session start
+    await db.insert(impersonationAuditLogs).values({
+      sessionId: session!.id,
+      action: "session_started",
+      metadata: { reason: body.reason ?? null },
+    });
+
+    return c.json(session!, 201);
+  }
+);
+
+// ─── GET /sessions/:id — Get session details ────────────────────────────────
+
+impersonationRouter.get("/sessions/:id", async (c) => {
+  const db = getDb();
+  const jwt = c.get("jwtPayload") as JwtPayload;
+  const staffRow = await resolveStaff(jwt.sub);
+  if (!staffRow) return c.json({ error: "Staff record not found" }, 403);
+
+  const [session] = await db
+    .select()
+    .from(impersonationSessions)
+    .where(eq(impersonationSessions.id, c.req.param("id")));
+  if (!session) return c.json({ error: "Session not found" }, 404);
+  if (session.staffId !== staffRow.id) {
+    return c.json({ error: "Not your session" }, 403);
+  }
+
+  // Auto-expire if timed out
+  if (await checkAndExpireSession(session)) {
+    session.status = "expired";
+    session.endedAt = new Date();
+  }
+
+  return c.json(session);
+});
+
+// ─── POST /sessions/:id/extend — Extend session timeout ─────────────────────
+
+impersonationRouter.post("/sessions/:id/extend", async (c) => {
+  const db = getDb();
+  const jwt = c.get("jwtPayload") as JwtPayload;
+  const staffRow = await resolveStaff(jwt.sub);
+  if (!staffRow) return c.json({ error: "Staff record not found" }, 403);
+
+  const [session] = await db
+    .select()
+    .from(impersonationSessions)
+    .where(eq(impersonationSessions.id, c.req.param("id")));
+  if (!session) return c.json({ error: "Session not found" }, 404);
+  if (session.staffId !== staffRow.id) {
+    return c.json({ error: "Not your session" }, 403);
+  }
+  if (session.status !== "active") {
+    return c.json({ error: "Session is not active" }, 400);
+  }
+
+  // Check time-based expiry
+  if (await checkAndExpireSession(session)) {
+    return c.json({ error: "Session has expired" }, 400);
+  }
+
+  const newExpiry = expiresAt();
+  const [updated] = await db
+    .update(impersonationSessions)
+    .set({ expiresAt: newExpiry })
+    .where(eq(impersonationSessions.id, session.id))
+    .returning();
+
+  await db.insert(impersonationAuditLogs).values({
+    sessionId: session.id,
+    action: "session_extended",
+    metadata: { newExpiresAt: newExpiry.toISOString() },
+  });
+
+  return c.json(updated);
+});
+
+// ─── POST /sessions/:id/end — End session ────────────────────────────────────
+
+impersonationRouter.post("/sessions/:id/end", async (c) => {
+  const db = getDb();
+  const jwt = c.get("jwtPayload") as JwtPayload;
+  const staffRow = await resolveStaff(jwt.sub);
+  if (!staffRow) return c.json({ error: "Staff record not found" }, 403);
+
+  const [session] = await db
+    .select()
+    .from(impersonationSessions)
+    .where(eq(impersonationSessions.id, c.req.param("id")));
+  if (!session) return c.json({ error: "Session not found" }, 404);
+  if (session.staffId !== staffRow.id) {
+    return c.json({ error: "Not your session" }, 403);
+  }
+  if (session.status !== "active") {
+    return c.json({ error: "Session is not active" }, 400);
+  }
+
+  // Check time-based expiry
+  if (await checkAndExpireSession(session)) {
+    return c.json({ error: "Session has expired" }, 400);
+  }
+
+  const now = new Date();
+  const [updated] = await db
+    .update(impersonationSessions)
+    .set({ status: "ended", endedAt: now })
+    .where(eq(impersonationSessions.id, session.id))
+    .returning();
+
+  await db.insert(impersonationAuditLogs).values({
+    sessionId: session.id,
+    action: "session_ended",
+  });
+
+  return c.json(updated);
+});
+
+// ─── POST /sessions/:id/log — Log an audit entry ────────────────────────────
+
+const logEntrySchema = z.object({
+  action: z.string().min(1).max(200),
+  pageVisited: z.string().max(500).optional(),
+  metadata: z.record(z.unknown()).optional(),
+});
+
+impersonationRouter.post(
+  "/sessions/:id/log",
+  zValidator("json", logEntrySchema),
+  async (c) => {
+    const db = getDb();
+    const jwt = c.get("jwtPayload") as JwtPayload;
+    const body = c.req.valid("json");
+
+    const staffRow = await resolveStaff(jwt.sub);
+    if (!staffRow) return c.json({ error: "Staff record not found" }, 403);
+
+    const [session] = await db
+      .select()
+      .from(impersonationSessions)
+      .where(eq(impersonationSessions.id, c.req.param("id")));
+    if (!session) return c.json({ error: "Session not found" }, 404);
+    if (session.staffId !== staffRow.id) {
+      return c.json({ error: "Not your session" }, 403);
+    }
+    if (session.status !== "active") {
+      return c.json({ error: "Session is not active" }, 400);
+    }
+
+    // Check time-based expiry
+    if (await checkAndExpireSession(session)) {
+      return c.json({ error: "Session has expired" }, 400);
+    }
+
+    const [entry] = await db
+      .insert(impersonationAuditLogs)
+      .values({
+        sessionId: session.id,
+        action: body.action,
+        pageVisited: body.pageVisited ?? null,
+        metadata: body.metadata ?? null,
+      })
+      .returning();
+
+    return c.json(entry, 201);
+  }
+);
+
+// ─── GET /sessions/:id/audit-log — Get audit trail ──────────────────────────
+
+impersonationRouter.get("/sessions/:id/audit-log", async (c) => {
+  const db = getDb();
+  const jwt = c.get("jwtPayload") as JwtPayload;
+  const staffRow = await resolveStaff(jwt.sub);
+  if (!staffRow) return c.json({ error: "Staff record not found" }, 403);
+
+  const [session] = await db
+    .select()
+    .from(impersonationSessions)
+    .where(eq(impersonationSessions.id, c.req.param("id")));
+  if (!session) return c.json({ error: "Session not found" }, 404);
+  if (session.staffId !== staffRow.id) {
+    return c.json({ error: "Not your session" }, 403);
+  }
+
+  const logs = await db
+    .select()
+    .from(impersonationAuditLogs)
+    .where(eq(impersonationAuditLogs.sessionId, session.id))
+    .orderBy(desc(impersonationAuditLogs.createdAt));
+
+  return c.json(logs);
+});