---
phase: 01-foundation
plan: 05
subsystem: auth
tags: [super-admin, next-auth, prisma, next.js, tailwind, vitest, rbac, multi-tenant]

requires:
  - phase: 01-04
    provides: "CASL RBAC with withPermission() middleware pattern (super-admin is parallel middleware)"
  - phase: 01-02
    provides: "getCurrentUser() from session, isSuperAdmin in JWT token"
  - phase: 01-01
    provides: "Tenant schema with status/suspendedAt/gracePeriodEndsAt fields"

provides:
  - "withSuperAdmin() HOF middleware guard (parallel to withPermission, no CASL needed)"
  - "GET /api/admin/tenants — lists all tenants with userCount, subscriberCount=0"
  - "GET /api/admin/tenants/[id] — tenant detail with users list"
  - "POST /api/admin/tenants/[id]/suspend — suspend (PENDING_SUSPENSION + 7-day grace) or activate"
  - "(super-admin)/layout.tsx — server guard + sidebar nav for /admin/* routes"
  - "/admin dashboard with total/active/suspended counts"
  - "/admin/tenants table with status badges, suspend/activate actions"
  - "middleware.ts updated: /admin/* requires isSuperAdmin in JWT token"
  - "93 total tests passing across all Phase 1 test files"
  - "Second demo tenant (Test ISP 2 + admin2@demo.com) added to seed for isolation tests"

affects:
  - "02-billing: super-admin API pattern for platform-level views"
  - "All phases: withSuperAdmin() is the reference guard for platform endpoints"

tech-stack:
  added: []
  patterns:
    - "withSuperAdmin(handler) HOF — mirrors withPermission() but uses isSuperAdmin instead of CASL"
    - "Super-admin layout as server component with getCurrentUser() redirect guard"
    - "Client component tenant table with optimistic refresh after suspend/activate actions"
    - "Next.js 15 dynamic route params resolved with Promise<P> await in HOF"

key-files:
  created:
    - src/lib/middleware/super-admin.ts
    - src/app/api/admin/tenants/route.ts
    - src/app/api/admin/tenants/[id]/route.ts
    - src/app/api/admin/tenants/[id]/suspend/route.ts
    - src/app/(super-admin)/layout.tsx
    - src/app/(super-admin)/admin/page.tsx
    - src/app/(super-admin)/admin/tenants/page.tsx
    - src/lib/__tests__/super-admin.test.ts
  modified:
    - prisma/seed.ts
    - src/middleware.ts

key-decisions:
  - "withSuperAdmin() implemented as standalone HOF (not via CASL) — super-admin access is binary, not permission-based"
  - "Next.js 15 route params wrapped in Promise<P> — HOF awaits params before passing to handler"
  - "Tenant table page is a client component — requires useEffect + fetch for suspend/activate interactivity"
  - "Admin dashboard page fetches /api/admin/tenants via server-side fetch with forwarded session cookie"
  - "subscriberCount hardcoded to 0 — Subscriber model added in Phase 2; API shape is forward-compatible"
  - "middleware.ts redirects non-super-admin to /login on /admin/* paths — layout provides second guard layer"

patterns-established:
  - "Super-admin API routes: always wrap with withSuperAdmin() — never withPermission()"
  - "Dynamic route HOFs: use generic type parameter <P = Record<string, string>> for type-safe params"
  - "Super-admin UI: server layout guards redirect, client pages fetch /api/admin/* endpoints"

duration: 6min
completed: 2026-03-04
---

# Phase 1 Plan 5: Super-Admin Panel Summary

**withSuperAdmin() middleware + /admin tenant management UI + 93 tests validating full Phase 1 foundation (auth, RBAC, tenant isolation, super-admin)**

## Performance

- **Duration:** 6 min
- **Started:** 2026-03-04T11:01:34Z
- **Completed:** 2026-03-04T11:07:04Z
- **Tasks:** 2
- **Files modified:** 10

## Accomplishments

- withSuperAdmin() HOF middleware guard that checks isSuperAdmin from JWT session (returns 401/403 otherwise)
- Full admin API: list all tenants, get tenant detail, suspend/activate with 7-day grace period
- /admin/* UI panel: server-guarded layout, dashboard stats, tenant table with status badges and action buttons
- 93 tests passing across all Phase 1 test files (auth 8, RBAC 66, tenant isolation 6, super-admin 11, setup 2)
- Second demo tenant (Test ISP 2 + admin2@demo.com) added to seed for cross-tenant isolation testing

## Task Commits

Each task was committed atomically:

1. **Task 1: Super-admin API routes and middleware guard** - `df40eae` (feat)
2. **Task 2: Super-admin UI panel and comprehensive test harness** - `25a12ef` (feat)

**Plan metadata:** _(docs commit follows)_

## Files Created/Modified

- `src/lib/middleware/super-admin.ts` - withSuperAdmin() HOF: 401 if no session, 403 if not isSuperAdmin
- `src/app/api/admin/tenants/route.ts` - GET all tenants with userCount, sorted by createdAt desc
- `src/app/api/admin/tenants/[id]/route.ts` - GET single tenant detail with users list
- `src/app/api/admin/tenants/[id]/suspend/route.ts` - POST suspend (PENDING_SUSPENSION + grace) or activate
- `src/app/(super-admin)/layout.tsx` - Server guard + sidebar nav (Dashboard, Tenants) + sign out
- `src/app/(super-admin)/admin/page.tsx` - Dashboard: total/active/pending/suspended counts
- `src/app/(super-admin)/admin/tenants/page.tsx` - Tenant table with status badges + suspend/activate buttons
- `src/lib/__tests__/super-admin.test.ts` - 11 tests: middleware guard (401/403/allow), suspension logic
- `prisma/seed.ts` - Added Test ISP 2 tenant + admin2@demo.com user
- `src/middleware.ts` - /admin/* requires isSuperAdmin in JWT token at edge middleware level

## Decisions Made

- **withSuperAdmin() as standalone HOF**: Super-admin access is binary (isSuperAdmin: true/false), not permission-based — using CASL for this would be over-engineering. Parallel pattern to withPermission() but simpler.
- **Next.js 15 params as Promise**: Route handler params in Next.js 15 can be a Promise. HOF awaits params before passing to handler for forward compatibility.
- **Client component for tenant table**: Suspend/activate interactivity requires useState + fetch. Server component for layout guard, client component for interactive table.
- **subscriberCount=0 placeholder**: Subscriber model is Phase 2. API shape is forward-compatible — clients can expect this field to grow.
- **Dual guard strategy**: middleware.ts provides JWT-level edge guard; layout.tsx provides server component guard; API handlers provide endpoint-level guard. Three layers for defense in depth.

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

Phase 1 Foundation is complete. All requirements met:
- TENANT-01: Multi-tenant architecture with tenant isolation (01-03)
- TENANT-02: RBAC with 5-role permission matrix (01-04)
- TENANT-03: Super-admin can view/manage all tenants (01-05)
- AUTH-01: JWT sessions with NextAuth credentials provider (01-02)
- AUTH-02: Tenant-scoped email uniqueness (01-01)
- AUTH-03: Super-admin has no tenant scope (01-01, 01-02)
- AUTH-04: Grace period suspension (01-01, 01-05)
- INFRA-01: Docker PostgreSQL + Redis dev environment (01-01)
- INFRA-02: 93 unit/integration tests across auth, RBAC, isolation, super-admin (01-04, 01-05)

Phase 2 (Billing/Accounting) can begin. Relevant handoffs:
- Subscriber model will use tenantId from same schema pattern as User
- JournalEntryService COA structure defined in Phase 2 (cannot retrofit)
- CASL string subject casts (any) should be upgraded to class-based subjects when Prisma models are defined

---
*Phase: 01-foundation*
*Completed: 2026-03-04*