Add admin impersonation console to the dashboard

[Sharqiewicz]

Summary

Adds an operator-facing admin console and short-lived impersonation sessions for profiles holding the out-of-band vortex_admin role.

The implementation keeps the operator's Supabase session separate, stores only a hash of the temporary impersonation token on the server, attributes impersonated API events to both the operator and target, prevents impersonation chaining and API-credential minting, and supports revocation, expiry, role-removal invalidation, and a global kill switch.

Current implementation

• Searchable, paginated account list and account detail view.
• Auditable 30-minute, non-renewable impersonation sessions.
• One live session per operator/target pair.
• Persistent dashboard banner with immediate local exit and best-effort server revocation.
• Atomic cross-tab browser state and account-cache cleanup on every identity transition.
• Operator and impersonation-session attribution on API client events.

Security posture and agreed first-iteration scope

Important

The current branch resolves an impersonation token as the target profile with the target's full application permissions. This is not the intended final scope for the first production iteration.

The first iteration must provide a server-enforced read-only support mode. Hiding buttons in the dashboard is not an authorization boundary: the API must default-deny mutations while req.impersonation is present and allow only an explicit set of support reads.

Expected read-only capabilities include:

• search and inspect profiles, customer entities, provider accounts, and KYC/KYB state;
• inspect quotes, ramps, transaction history, and operational errors without changing them;
• inspect impersonation-session history and end the current session;
• perform quote/rate discovery only if it is explicitly classified and enforced as non-operational.

The impersonated principal must not be able to:

• register, update, or start ramps or otherwise initiate money movement;
• create or mutate provider customers, fiat accounts, payout destinations, recipients, or invitations;
• start, submit, or update KYC/KYB processes;
• mint, rotate, or otherwise modify API credentials;
• perform any other state-changing operation that has not been explicitly allowlisted.

Required first-iteration follow-up

• Add a centralized, default-deny read-only authorization boundary for impersonated requests.
• Add route-level regression tests proving every financial, compliance, credential, and account mutation is rejected while impersonating.
• Update the security specification and accepted-risk entry to describe the reduced scope.

Additional hardening before production use

• Require recent step-up authentication, preferably MFA or a fresh OTP, before starting impersonation.
• Move the raw impersonation credential out of localStorage, preferably behind an HttpOnly secure cookie or backend-for-frontend session.
• Add a short server-enforced inactivity timeout in addition to the existing absolute lifetime.
• Require a support reason or ticket reference when starting a session and include it in the audit record.
• Alert on impersonation starts, denied mutation attempts, revocation failures, and unusual operator/target activity.

Verification completed for the current implementation

• 68 focused API lifecycle, authorization, and audit tests.
• 95 dashboard tests.
• API, dashboard, SDK, and shared-package typechecks.
• Dashboard production build.

[netlify]

✅ Deploy Preview for vortex-sandbox ready!

Name	Link
🔨 Latest commit	94c4210
🔍 Latest deploy log	https://app.netlify.com/projects/vortex-sandbox/deploys/6a759fa0d54d9a00082df5e9
😎 Deploy Preview	https://deploy-preview-1321--vortex-sandbox.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[netlify]

✅ Deploy Preview for vortexfi ready!

Name	Link
🔨 Latest commit	94c4210
🔍 Latest deploy log	https://app.netlify.com/projects/vortexfi/deploys/6a759fa0ef275d0008682c59
😎 Deploy Preview	https://deploy-preview-1321--vortexfi.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[netlify]

✅ Deploy Preview for vrtx-dashboard ready!

Name	Link
🔨 Latest commit	94c4210
🔍 Latest deploy log	https://app.netlify.com/projects/vrtx-dashboard/deploys/6a759fa060986900083f5bd9
😎 Deploy Preview	https://deploy-preview-1321--vrtx-dashboard.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

Pull request overview

Adds a high-risk admin impersonation console across the API and dashboard; despite the title, subaccounts remain deferred.

Changes:

• Adds role-gated impersonation sessions and principal substitution.
• Adds dashboard account search, auditing, and “Log in as” flows.
• Adds migrations, tests, operational tooling, and security documentation.

Reviewed changes

Copilot reviewed 55 out of 56 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
docs/security-spec/RISK-REGISTER.md	Records impersonation risk.
docs/security-spec/README.md	Indexes the new specification.
docs/security-spec/01-auth/admin-impersonation.md	Defines impersonation security controls.
docs/security-spec/01-auth/admin-auth.md	Separates both admin surfaces.
docs/product-dashboard.md	Documents operator UI behavior.
docs/architecture-identity-model.md	Documents principal substitution.
apps/dashboard/src/types/bun-test.d.ts	Declares Bun mocking types.
apps/dashboard/src/stores/impersonation.store.ts	Manages impersonation state.
apps/dashboard/src/stores/impersonation.store.test.ts	Tests session transitions.
apps/dashboard/src/stores/auth.store.ts	Exports account-state cleanup.
apps/dashboard/src/services/auth.ts	Stores impersonation credentials.
apps/dashboard/src/services/auth.test.ts	Tests token precedence.
apps/dashboard/src/services/api/api-client.ts	Sends impersonation bearer tokens.
apps/dashboard/src/services/api/api-client.test.ts	Tests impersonated requests.
apps/dashboard/src/services/api/admin-console.service.ts	Defines admin API client.
apps/dashboard/src/routeTree.gen.ts	Registers admin routes.
apps/dashboard/src/routes/_app/admin.tsx	Adds account search and audit UI.
apps/dashboard/src/routes/_app/admin.$profileId.tsx	Adds account details.
apps/dashboard/src/routes/_app.tsx	Mounts impersonation banner.
apps/dashboard/src/hooks/useAdminConsole.ts	Adds admin query hooks.
apps/dashboard/src/components/layout/ImpersonationBanner.tsx	Displays active-session warning.
apps/dashboard/src/components/layout/AppSidebar.tsx	Adds role-gated navigation.
apps/dashboard/src/components/admin/ImpersonateDialog.tsx	Confirms impersonation starts.
apps/dashboard/src/components/admin/AdminAccountsTable.tsx	Displays searchable accounts.
apps/api/src/models/profileRole.model.ts	Adds vortex_admin.
apps/api/src/models/index.ts	Registers session associations.
apps/api/src/models/adminImpersonationSession.model.ts	Models impersonation sessions.
apps/api/src/database/migrations/060-create-admin-impersonation-sessions.ts	Creates session storage.
apps/api/src/database/migrations/059-allow-vortex-admin-profile-role.ts	Extends role constraints.
apps/api/src/config/vars.ts	Adds the kill switch.
apps/api/src/api/services/impersonation.service.ts	Implements session lifecycle.
apps/api/src/api/services/impersonation.service.test.ts	Tests lifecycle invariants.
apps/api/src/api/routes/v1/index.ts	Mounts admin-console routes.
apps/api/src/api/routes/v1/api-credentials.route.ts	Blocks credential minting.
apps/api/src/api/routes/v1/api-credentials.route.test.ts	Tests credential blocking.
apps/api/src/api/routes/v1/admin-console/impersonation.route.ts	Defines session routes.
apps/api/src/api/routes/v1/admin-console/admin-console.route.test.ts	Tests admin-console authorization.
apps/api/src/api/routes/v1/admin-console/accounts.route.ts	Defines account routes.
apps/api/src/api/observability/types.ts	Adds impersonation operations.
apps/api/src/api/observability/apiClientEvent.service.ts	Adds operator attribution.
apps/api/src/api/observability/apiClientEvent.service.test.ts	Tests attribution metadata.
apps/api/src/api/middlewares/vortexAdminAuth.ts	Adds role authorization.
apps/api/src/api/middlewares/vortexAdminAuth.test.ts	Tests role authorization.
apps/api/src/api/middlewares/supabaseAuth.ts	Resolves substituted principals.
apps/api/src/api/middlewares/supabaseAuth.impersonation.test.ts	Tests Supabase impersonation.
apps/api/src/api/middlewares/ownershipAuth.impersonation.test.ts	Tests target ownership.
apps/api/src/api/middlewares/dualAuth.ts	Supports impersonation bearer tokens.
apps/api/src/api/middlewares/bearerPrincipal.ts	Centralizes bearer resolution.
apps/api/src/api/middlewares/bearerPrincipal.test.ts	Tests principal resolution.
apps/api/src/api/controllers/admin/profileRoles.controller.ts	Restricts HTTP role grants.
apps/api/src/api/controllers/admin/profileRoles.controller.test.ts	Tests role restrictions.
apps/api/src/api/controllers/admin-console/impersonation.controller.ts	Implements session endpoints.
apps/api/src/api/controllers/admin-console/accounts.controller.ts	Implements account queries.
apps/api/scripts/grant-vortex-admin.ts	Adds out-of-band role grant.
apps/api/package.json	Registers the grant command.
apps/api/.env.example	Documents the kill switch.