Admin Panel

Site-wide administration dashboard for user management, statistics, and domain/email blacklists

SPEC 019 — Admin Panel

Field	Value
Status	DRAFT
Priority	P1 — Core Product
Backend	equa-server/modules/admin/
Frontend	equa-web/src/modules/admin/

---

1. Feature Purpose

The Admin Panel provides site-level administrators with tools to manage users, view platform statistics, and enforce domain/email blacklists. Unlike organization-level roles (SPEC 012), admin access is granted through the GlobalRolesUsers table and operates across all organizations on the platform. This is the control plane for platform operators to monitor health, manage abuse, and support users.

---

2. Current State (Verified)

2.1 Global Role System

Detail	Value
Entity	GlobalRolesUsers — maps users to site-level roles
Role field	role (GlobalRole integer enum)
Guard	Middleware checks GlobalRolesUsers before allowing admin endpoint access
Scope	Admin privileges are platform-wide, not scoped to any organization

2.2 User Management

Detail	Value
Capabilities	List all users, search by email, enable/disable accounts, view user details
Backend	equa-server/modules/admin/ handles user queries and mutations
Endpoints	equa-server/modules/api/src/endpoints/admin-endpoints.ts

2.3 Site Statistics

Detail	Value
Metrics	Total users, organizations, active sessions, recent sign-ups, storage usage
Source	Aggregation queries against Users, Organizations, Sessions tables
Display	Dashboard cards and charts on the admin frontend

2.4 Blacklists

Detail	Value
Domain blacklist	DomainBlacklists — blocks registration from specific email domains
Email blacklist	EmailBlacklists — blocks specific email addresses
Enforcement	Checked during registration and invitation flows

2.5 Frontend

Component	Path
Admin module	equa-web/src/modules/admin/
Dashboard	Admin landing page with stats cards
User management	Searchable user table with action menus

---

3. Data Model

GlobalRolesUsers

Column	Type	Constraints
user	uuid	PK, FK → Users
role	integer	NOT NULL — GlobalRole enum value

DomainBlacklists

Column	Type	Constraints
id	uuid	PK
domain	varchar	UNIQUE, NOT NULL — e.g. spam-domain.com
reason	varchar	nullable
createdBy	uuid	FK → Users
createdAt	timestamp	DEFAULT now()

EmailBlacklists

Column	Type	Constraints
id	uuid	PK
email	citext	UNIQUE, NOT NULL
reason	varchar	nullable
createdBy	uuid	FK → Users
createdAt	timestamp	DEFAULT now()

---

4. API Endpoints

Method	Path	Auth	Description
GET	/api/v1/admin/stats	Admin	Platform-wide statistics (users, orgs, sessions, storage)
GET	/api/v1/admin/users	Admin	Paginated user list with search and filters
GET	/api/v1/admin/users/:userId	Admin	Single user detail (orgs, sessions, activity)
PUT	/api/v1/admin/users/:userId	Admin	Update user (enable/disable, modify fields)
DELETE	/api/v1/admin/users/:userId	Admin	Soft-delete or permanently remove a user account
GET	/api/v1/admin/organizations	Admin	Paginated organization list
GET	/api/v1/admin/blacklists/domains	Admin	List domain blacklist entries
POST	/api/v1/admin/blacklists/domains	Admin	Add a domain to the blacklist
DELETE	/api/v1/admin/blacklists/domains/:id	Admin	Remove a domain from the blacklist
GET	/api/v1/admin/blacklists/emails	Admin	List email blacklist entries
POST	/api/v1/admin/blacklists/emails	Admin	Add an email to the blacklist
DELETE	/api/v1/admin/blacklists/emails/:id	Admin	Remove an email from the blacklist

All “Admin” auth endpoints require the requesting user to have an entry in GlobalRolesUsers with an appropriate admin role.

---

5. Frontend Components

Component	Path	Description
AdminDashboard	admin/AdminDashboard.tsx	Landing page with statistics cards (users, orgs, sessions, storage)
UserManagement	admin/UserManagement.tsx	Searchable, paginated user table with inline actions
UserDetail	admin/UserDetail.tsx	Full user profile view with organization memberships and session history
DomainBlacklist	admin/DomainBlacklist.tsx	CRUD table for blocked domains
EmailBlacklist	admin/EmailBlacklist.tsx	CRUD table for blocked email addresses
OrgBrowser	admin/OrgBrowser.tsx	Paginated organization list with summary stats

Frontend Behavior

• Route guard — Admin routes are protected by a global role check; non-admins see a 403 page or are redirected.
• Search — User management supports real-time search by email, username, or user ID with debounced API calls.
• Bulk actions — User list supports multi-select for bulk enable/disable operations.
• Statistics refresh — Dashboard stats auto-refresh on a 60-second interval while the page is visible.
• Confirmation modals — Destructive actions (disable user, delete blacklist entry) require confirmation before execution.

---

6. Business Rules

1. Global role separation — Admin access is completely separate from organization-level roles. Being an org admin does not grant platform admin access.
2. GlobalRolesUsers is the single source of truth — All admin middleware checks this table; there is no fallback to environment variables or hardcoded user IDs.
3. Domain blacklist enforcement — During registration and team invitation, the email domain is checked against DomainBlacklists; matching domains are rejected with a generic error (no leak of blacklist existence).
4. Email blacklist enforcement — Specific email addresses in EmailBlacklists are blocked from registration and invitation with the same generic error.
5. Blacklist is case-insensitive — Domain comparison is lowercase; email comparison uses citext for case-insensitive matching.
6. User disable vs delete — Disabling a user (enabled = false) blocks login but preserves data. Deletion removes the account and is irreversible.
7. Audit trail — Blacklist entries record createdBy to track which admin added them.
8. Self-protection — Admins cannot disable or delete their own account through the admin panel.
9. No self-promotion — Adding entries to GlobalRolesUsers is restricted to existing admins or direct database access; there is no self-service admin promotion endpoint.
10. Statistics are real-time — Stats endpoints run live aggregation queries; no materialized views or caches are used.

---

7. Acceptance Criteria

• Only users with a GlobalRolesUsers entry can access admin endpoints and routes
• Non-admin users receive 403 on admin API calls and are redirected on frontend
• Admin dashboard displays correct counts for users, organizations, and active sessions
• User management table supports pagination and search by email/username
• Admin can disable a user account; disabled user cannot log in
• Admin can re-enable a disabled user account
• Admin cannot disable their own account
• Admin can add a domain to the blacklist; new registrations from that domain are blocked
• Admin can add a specific email to the blacklist; that email cannot register or be invited
• Blacklist checks are case-insensitive
• Blacklist rejections show generic error messages (no information leak)
• Admin can remove blacklist entries; previously blocked domains/emails can register again
• Organization browser displays all organizations with summary information
• Destructive actions require confirmation modal

---

8. Risks

Risk	Impact	Mitigation
Privilege escalation via direct DB insert into GlobalRolesUsers	Unauthorized admin access	Restrict DB write access; audit GlobalRolesUsers changes
Admin account compromise	Full platform control	Require 2FA for admin accounts; log all admin actions
Real-time stats queries on large datasets	Slow dashboard load, DB strain	Add query timeouts; consider materialized views if scale demands
Blacklist bypass via email aliases (e.g. [e-mail])	Blocked users re-register	Normalize emails (strip + aliases) before blacklist check
Accidental user deletion	Irreversible data loss	Implement soft-delete with grace period before hard purge
No rate limiting on admin endpoints	Abuse by compromised admin session	Add rate limiting; log and alert on unusual admin activity patterns
Blacklist reason field is optional	Poor audit trail for why domains/emails were blocked	Consider making reason required or defaulting to a standard message
Self-protection rule bypass via API	Admin disables own account, locks themselves out	Server-side check preventing self-targeting on disable/delete endpoints