d3ro-voice/docs/map/08-admin-console.md

7.1 KiB

08 — Admin Console (Next.js) Map

Surface: apps/admin Stack: Next.js 16 App Router + MUI (@d3ro/ui theme) + Supabase service role + .NET proxy Role: back office CRM/ops — users, subscriptions, models, usage, audit, releases, ads


1. Route tree (src/app/)

Public

Route Purpose
/login Email/password → /api/auth/login; Google OAuth via Supabase → /auth/callback; maps error keys
/unauthorized 403 screen
/auth/callback OAuth code → session exchange

Protected (admin) (guarded by (admin)/layout.tsx → requireManager())

Route Purpose
/ Dashboard: backend stats, node health, MRR/ARR/active subscriptions (Supabase), recent errors
/pipelines AI/voice pipeline telemetry; explicit "unavailable" card when no measured data
/models LLM model + STT provider manager (presets, CRUD, test)
/releases Forgejo live release hub (assets, platforms, sizes, downloads, SHA-256)
/users User directory: search + tier/role filters
/users/[id] User 360: profile, subscription, 30-day usage, role change (admin+), payment history
/subscriptions Subscription ops list + filters; license issuer (super_admin)
/subscriptions/new Grant VIP subscription (admin+)
/subscriptions/[id] Subscription detail: edit (manager+) / delete (admin+)
/ads Ad mediation console (10 networks, all fail_closed) + reward stats
/support Stub — explicit "not configured" panel
/usage Combined LLM + STT usage/cost analytics
/audit-log Supabase audit log list + target filter + pagination
/audit-log/[id] Audit detail with before/after diff

2. API route handlers (src/app/api/)

Route Methods Behavior
/api/auth/login POST Validate body, reject honeypot trap, in-memory rate limit/lockout, proxy to .NET /api/auth/login (7s timeout, HTTPS in prod), validate token/role/email/expiry, sign HMAC session cookie d3ro_admin_session
/api/auth/logout POST/GET Clear cookie; GET redirects /login
/api/admin/backend/[...segments] GET/POST/PUT/DELETE Allow-list proxy to .NET /api/admin/*; required role by path; same-origin for non-GET; ≤64KB; UUID idempotency-key for mutations
/api/admin/license POST Same-origin + requireVerifiedBackendSession('super_admin'); sign Ed25519 key with ADMIN_LICENSE_PRIVATE_KEY (@d3ro/core/utils/crypto-license); best-effort audit
/api/admin/supabase/[operation] GET/POST/PATCH/DELETE admin-users, admin-subscriptions, admin-payments via RPCs; strict allow-lists; Payple live history returns 501
/auth/callback GET Supabase OAuth exchange

3. Libraries (src/lib/)

File Purpose
admin-session.ts Session types, secret validation (≥32 bytes), strict cookie parse, adminCookieSecure() escape hatch
security.ts server-only HMAC-SHA256 sign/verify, in-memory rate limit/lockout, runtime security validation
admin-guard.ts RSC guards requireManager/requireAdmin/requireSuperAdmin, role helpers
edge-session.ts Edge-runtime HMAC verify via WebCrypto (used by proxy.ts)
backend-session.ts requireApiServerOrigin, requireVerifiedBackendSession(minRole) (verifies cookie + .NET /api/auth/me), fetchAdminBackend
api-server.ts server-only data access to .NET backend (stats, users, endpoints, usage reports)
backend-admin-client.ts client CRUD for model/STT endpoints with auto idempotency keys
admin-api.ts client callAdminApi for Supabase admin operations
supabase-admin.ts service-role client, actor resolution RPC, product user fetch
supabase-browser.ts / supabase-server.ts client/server Supabase wrappers
ad-monetization.ts MEDIATION_ROSTER (fail_closed) + ad reward stats
subscription-metrics.ts MRR/ARR/active/tier breakdown
audit-sanitize.ts recursive redaction of sensitive keys in audit snapshots
forgejo-releases.ts Forgejo release feed parser (RELEASE_REPO_URL)
console-theme.ts design tokens + MUI style presets

Root files: instrumentation.ts (startup security validation), proxy.ts (edge middleware: public paths, auth redirect, security headers), robots.ts (disallow all).


4. Components (src/components/)

admin-sidebar (nav island: Core Platform / Customer & Revenue / Intelligence & Security), unavailable-admin-panel (reusable "NOT CONNECTED", no sample data), audit-diff-viewer, payment-history, subscription-form, role-change-dialog + role-change-button, memo-dialog, license-issuer-button + license-issuer-dialog, checksum-copy.


5. Admin status summary

  • Dashboard, models, releases, users, subscriptions, usage, audit log, ads: implemented against real backend/Supabase data.
  • Security: HMAC signed sessions, RSC + edge guards, rate limit/lockout, honeypot, strict origin/allow-list, no-store, robots disallow, audit redaction. Red-team scenarios were exercised (see memory/project_status.md).
  • Explicit fail-closed / not-configured states (by design, not bugs):
    • /support stub — no ticket/SLA/diagnostics contract.
    • /ads — all 10 networks fail_closed; no live bids.
    • admin-payments Payple live history → 501.
    • UnavailableAdminPanel whenever Supabase env absent; writes disabled, no sample metrics.
    • /pipelines and dashboard node/error sections render only measured data.
  • Deploy: apps/admin/Dockerfile → GHCR + NAS compose; the duplicate root Dockerfile.admin was deleted 2026-09-26 (Wave 3, cd9d199) since apps/admin/Dockerfile is the one actually used. GitLab admin NAS deploy job disabled.
  • Wave 6 hardening (2026-11-14): extracted lib/request-security.ts (isSameOriginRequest, ADMIN_UUID_PATTERN, byte-bounded JSON body reader) and components/detail-row.tsx (Row SSOT); hardened logout (sameSite: 'strict', CSRF, no-store), license/login/backend/supabase routes, users/[id] & subscriptions/[id] (requireManager() + UUID notFound()), and client unmount/timer/sttMemo/non-finite or negative cost guards (payment-history, checksum-copy, license-issuer-dialog, models/page.tsx).
  • 2026-11-04 Wave 4 hygiene: Removed three unreferenced chart components (dau-chart, feature-usage-chart, top-users-chart) and the admin recharts dependency; no active admin route imported them.
  • 2026-10-28 designpaca audit (SHELL-15): console-theme.ts C.dim upgraded from #67789e to #7e8eb0 (WCAG AA 4.94:1 on dark card surface), panelSx/innerCoreSx/filterBtnSx/statusBadgeSx/primaryButtonSx flattened (removed backdropFilter blur, decorative gradients, uppercase, and positive letterSpacing), 1.0:1 foreground/background token collisions (--d3-status-successBg, --d3-status-dangerBg, --d3-tag-cyanBg) fixed across admin-sidebar.tsx, ads, releases, subscriptions, usage, users, and login, sub-11px font sizes raised to 11px, and keyboard navigation (role="button", tabIndex={0}) + aria-label added to sidebar and dialog controls.