feat(admin): deployment-admin dashboard (instance operator surface)

[viktormarinho]

What is this contribution about?

Adds an instance-level operator dashboard at /_admin, gated by the DEPLOYMENT_ADMIN_EMAILS env allowlist (not a per-org role), for debugging user issues and fixing org membership: search/list users, impersonate a user, list orgs with member counts, and add a member to any org — with an impersonation indicator in the account popover. The raw Better Auth admin plugin (/api/auth/admin/*) is fenced off so a pushed adminUserIds id can't call set-role/set-user-password directly (everything routes through the curated /api/_admin/* handlers, which call auth.api.* in-process); the surface is mounted under _admin because an underscore is illegal in an org slug and can't shadow a real org. Impersonation and member-add are audited via PostHog, thrown better-auth APIErrors are mapped to their real HTTP status instead of 500, and shared helpers (getInitials/formatDate/isAlreadyMemberError, plus a NoPermissionState action slot) remove duplicated logic.

Screenshots/Demonstration

UI-affecting (admin dashboard + impersonation pill). Screenshots to be added.

How to Test

1. Start the app with DEPLOYMENT_ADMIN_EMAILS=you@example.com and sign in as that (verified) user.
2. Open the account popover → "Admin Dashboard"; confirm Users and Organizations tabs load, search works, and "Impersonate" switches the session (amber "Impersonating" indicator appears, "Stop impersonation" restores you).
3. As a non-allowlisted user, visit /_admin and confirm the "restricted to deployment admins" gate; confirm POST /api/auth/admin/set-role returns 404. E2E: bun test packages/e2e/tests/deployment-admin.spec.ts (needs the Postgres+NATS rig).

Migration Notes

No DB migration. New env var DEPLOYMENT_ADMIN_EMAILS (CSV of operator emails) — unset means no deployment admins. Revocation takes effect on next restart.

Review Checklist

• PR title is clear and descriptive
• Changes are tested and working
• Documentation is updated (if needed)
• No breaking changes

---

Summary by cubic

Adds an instance-level deployment admin dashboard at /_admin, gated by DEPLOYMENT_ADMIN_EMAILS, for operators to search users, impersonate, view orgs, and add members. Secures the surface with CSRF Origin checks, fences raw better-auth admin endpoints, forwards real APIError statuses, and exempts /api/_admin/* from org SSO.

• New Features

  • Dashboard: Users (search by email/name, impersonate with indicator and one‑click stop) and Organizations (list with member counts, add members with a role).
  • API: /api/_admin/me, /api/_admin/users?searchValue&limit, /api/_admin/orgs?search&limit, POST /api/_admin/orgs/:orgId/members, POST /api/_admin/impersonate.
  • UX: "Admin Dashboard" in the account popover; stop‑impersonating calls the better-auth endpoint directly.

• Bug Fixes

  • Access/security: allowlist via DEPLOYMENT_ADMIN_EMAILS with email verification checked after the allowlist (non‑allowlisted get 403; allowlisted unverified get email_not_verified), reject untrusted Origin on mutating routes (CSRF), fence /api/auth/admin/* (except stop-impersonating), mount ADMIN_API_PREFIX before :org, and exempt /api/_admin/* from org SSO.
  • Errors/auditing: map better-auth APIError by shape (name === "APIError" + numeric 4xx/5xx) to forward status/message/code (never cause); durable stdout + PostHog events for impersonate and member‑add.

^{Written for commit 0d52f1d. Summary will update on new commits.}