F 03 Admin Impersonation

Status: 🟢 ready to test Owner: Adilet Last updated: 2026-05-08 Last verified on production: —

Goal

An admin can temporarily browse the app as another user, to debug what the user sees, troubleshoot a bug report, or spot-check a tester's balance. The session is clearly marked with a banner; impersonation is fully reversible without signing out.

Actors

• Primary — Admin
• Secondary — The impersonated target (no notification by design; this is a read-only debug tool)

Preconditions

• Admin is signed in.
• Target user exists.

Trigger

Admin opens the target user's profile (/app/admin/users/:id) and clicks the "View as user" action.

Happy path — start impersonation

Happy path — end impersonation

Acceptance criteria

• AC-1 — Given the admin clicks "View as user" on a Tester profile, when the page reloads, then the impersonation banner is visible at the top and the sidebar shows the Tester's role-appropriate menu.
• AC-2 — Given an active impersonation, when the admin navigates to /app/test-cycles, then they see only the cycles the target is a member of (not all cycles).
• AC-3 — Given an active impersonation, when the admin attempts a destructive write that requires admin role (e.g. POST a tester assignment), then it is blocked — impersonation grants read parity, not write parity.
• AC-4 — Given an active impersonation, when the admin clicks "End session", then the cookie is cleared and the next page render shows the admin's own sidebar.
• AC-5 — Given an admin signs out while impersonating, when the session ends, then admin_impersonation_log.ended_at is also set.

Test data / fixtures

• Baseline seed
• At least one tester with at least one filed issue, so impersonation has something to display.

Negative paths

Manual QA checklist

• Open /app/admin/users/:id for a tester who has filed issues
• Click "View as user" — banner appears, redirected to /app
• Sidebar shows Tester's items (Test Cycles · Balance · Browse)
• Navigate to /app/test-cycles/balance — see target's earnings, not your own
• Navigate to /app/test-cycles — see only target's cycles
• Try to create a new cycle from /app/admin/test-cycles/new — should work (admin write parity persists for the admin's own actions, not for target's actions; verify what the policy actually does on prod)
• Click "End session" in banner — banner disappears, sidebar reverts to admin's
• Verify admin_impersonation_log has start + end timestamps for the session

Automated test outline

test.describe("F-03 impersonation", () => {
  test("admin starts and ends impersonation", async ({ page }) => { … });
  test("impersonating reflects target's data", async ({ page }) => { … });
  test("self-impersonation blocked", async ({ request }) => { … });
});

Code references

• UI: src/components/test-cycles/ImpersonationBanner.tsx
• API: src/app/api/admin/impersonate/route.ts (POST, DELETE)
• Hooks: src/hooks/test-cycles/impersonation.ts
• Auth helper: src/lib/auth/resolve-user.ts — reads impersonation cookie
• Schema: admin_impersonation_log table

Events emitted (proposed)

• admin.impersonation_started — { admin_user_id, target_user_id, ip, user_agent }
• admin.impersonation_ended — { admin_user_id, target_user_id, duration_seconds }

Open questions / known gaps

• No "frozen-write" mode flag: writes performed during impersonation are attributed to the admin in DB columns like created_by, but the user in the audit trail is the admin (correct behavior — verify in tests).
• No notification to the impersonated user (deliberate — debug tool).
• Admin sidebar leak fix shipped in #144.