feat(admin): platform_admin flag + guard + read-only Overview/Workspaces (MN-104)

[ikrasovytskyi]

Summary

First cut of the superadmin panel's backend foundation — deliberately narrow, matching the ticket's own design notes ("start with Overview + Users + Workspaces..."). Everything here is read-only.

• platform_admins is a separate table, not a column on user — better-auth owns that table (there's an existing warning comment in auth-schema.ts forbidding app columns on it, easy to have missed). Presence of a row = admin.
• Seeded via PLATFORM_ADMIN_EMAIL at boot: looks up the user by email and grants if found; logs and no-ops (retried every restart) if they haven't signed up yet — safe to set the env var before the first operator's sign-up.
• PlatformAdminGuard follows the exact WorkspaceAccessGuard convention (@UseGuards(AuthGuard, PlatformAdminGuard)), 403 not 404 since /admin's existence isn't a secret.
• AdminOverviewService reads the existing entitlements/plan catalogue rather than recomputing pricing (per the ticket's own instruction) — estimatedMrrUsd is plan price + $12/seat overage summed across workspaces, explicitly labeled an estimate since it can drift from Stripe's actual invoiced total on proration/timing.
• Known limitation, documented rather than hidden: per-workspace billable-seat lookups are one query per workspace (AccessService has no bulk variant) — fine at today's scale, needs revisiting well before thousands of workspaces.

Deliberately NOT built in this pass — each is substantial, safety-sensitive work in its own right, not a bolt-on to a read-only overview: impersonation (needs the "never trigger a charge/mutation while impersonating" guarantee designed and tested, not assumed), token revoke, GDPR export/erase, security audit log, billing ops UI (comp/refund/plan-change — MN-196's setOverride/clearOverride are the seam this will call), agent operability, moderation, growth metrics.

Test plan

• 8 unit tests (platform-admin.service.test.ts, platform-admin.guard.test.ts) covering isPlatformAdmin, seedFromEnv (grants when found / no-ops when not), grant, revoke, and the guard's allow/reject paths.
• 6 new integration tests (test/admin.test.ts): 401 with no auth, 403 for an authenticated non-admin, and a granted platform admin seeing counts/workspace rows across accounts they don't belong to — proving this is genuinely cross-workspace, not scoped by membership like every other endpoint.
• Full local CI gate on a fresh branch rebased onto latest main: pnpm lint && pnpm typecheck && pnpm test && pnpm build && pnpm docs:check && pnpm install --frozen-lockfile — all green, 820 tests passed (real testcontainer Postgres, migration 0046_puzzling_harrier.sql applied cleanly).
• Live end-to-end verification against the running docker stack: signed up a real user, hit GET /admin/overview unauthenticated (401), authenticated-but-not-admin (403), granted platform_admin directly in Postgres, then got real cross-workspace data back — totalWorkspaces: 11, totalUsers: 13, totalRecords: 10103 — and GET /admin/workspaces correctly listed workspaces the test operator had zero membership in (e.g. pre-existing dev-stack workspaces from earlier sessions), proving the cross-tenant read path actually works, not just against fixtures the test created itself.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	storyos-docs	9c6f26c	Commit Preview URL Branch Preview URL	Jul 18 2026, 03:35 PM