160 lines
4.7 KiB
Markdown
160 lines
4.7 KiB
Markdown
# P0-006: Admin Authentication Architecture - Single-Admin Fundamental Decision
|
|
|
|
**Priority:** P0 (Critical - Affects Architecture)
|
|
**Status:** INVESTIGATION_REQUIRED
|
|
**Date Created:** 2025-12-16
|
|
**Related Investigation:** docs/4_LOG/December_2025/2025-12-18_CANTFUCKINGTHINK3_Investigation.md
|
|
|
|
---
|
|
|
|
## Problem Statement
|
|
|
|
RedFlag is designed as a **single-admin homelab tool**, but the current architecture includes multi-user scaffolding (users table, role systems, complex authentication) that should not exist in a true single-admin system.
|
|
|
|
**Critical Question:** Why does a single-admin homelab tool need ANY database table for users?
|
|
|
|
## Current Architecture (Multi-User Leftovers)
|
|
|
|
### What Exists:
|
|
- Database `users` table with role system
|
|
- `EnsureAdminUser()` function
|
|
- Multi-user authentication patterns
|
|
- Email fields, user management scaffolding
|
|
|
|
### What Actually Works:
|
|
- Single admin credential in .env file
|
|
- Agent JWT authentication (correctly implemented)
|
|
- NO actual multi-user functionality used
|
|
|
|
## Root Cause Analysis
|
|
|
|
**The Error:** Attempting to preserve and simplify broken multi-user architecture instead of asking "what should single-admin actually look like?"
|
|
|
|
**Why This Happened:**
|
|
1. Previous multi-user scaffolding added in bad commit
|
|
2. I tried to salvage/simplify instead of deleting
|
|
3. Didn't think from first principles about single-admin needs
|
|
4. Violated ETHOS principle: "less is more"
|
|
|
|
## Impact
|
|
|
|
**Security:**
|
|
- Unnecessary database table increases attack surface
|
|
- Complexity creates more potential bugs
|
|
- Violates simplicity principle
|
|
|
|
**Reliability:**
|
|
- More code = more potential failures
|
|
- Authentication complexity is unnecessary
|
|
|
|
**User Experience:**
|
|
- Confusion about "users" vs "admin"
|
|
- Setup flow more complex than needed
|
|
|
|
## Simplified Architecture Needed
|
|
|
|
### Single-Admin Model:
|
|
```
|
|
✓ Admin credentials live in .env ONLY
|
|
✕ No database table needed
|
|
✕ No user management UI
|
|
✕ No role systems
|
|
✕ No email/password reset flows
|
|
```
|
|
|
|
### Authentication Flow:
|
|
1. Server reads admin credentials from .env on startup
|
|
2. Admin login validates against .env only
|
|
3. NO database storage of admin user
|
|
4. Agents use JWT tokens (already correctly implemented)
|
|
|
|
### Benefits:
|
|
- Simpler = more secure
|
|
- Less code = less bugs
|
|
- Clear single-admin model
|
|
- Follows ETHOS principle: "less is more"
|
|
- Homelab-appropriate design
|
|
|
|
## Proposed Solution
|
|
|
|
**Option 1: Complete Removal**
|
|
1. REMOVE users table entirely
|
|
2. Store admin credentials only in .env
|
|
3. Admin login validates against .env only
|
|
4. No database users at all
|
|
|
|
**Option 2: Minimal Migration**
|
|
1. Remove all user management
|
|
2. Keep table structure but don't use it for auth
|
|
3. Clear documentation that admin is ENV-only
|
|
|
|
**Recommendation:** Option 1 (complete removal)
|
|
- Simpler = better for homelab
|
|
- Less attack surface
|
|
- ETHOS compliant: remove what's not needed
|
|
|
|
## Files Affected
|
|
|
|
**Database:**
|
|
- Remove migrations: users table, user management
|
|
- Simplify: admin auth checks
|
|
|
|
**Server:**
|
|
- Remove: User management endpoints, role checks
|
|
- Simplify: Admin auth middleware (validate against .env)
|
|
|
|
**Agents:**
|
|
- NO changes needed (JWT already works correctly)
|
|
|
|
**Documentation:**
|
|
- Update: Authentication architecture docs
|
|
- Remove: User management docs
|
|
- Clarify: Single-admin only design
|
|
|
|
## Verification Plan
|
|
|
|
**Test Cases:**
|
|
1. Fresh install with .env admin credentials
|
|
2. Login validates against .env only
|
|
3. No database user storage
|
|
4. Agent authentication still works (JWT)
|
|
|
|
**Success Criteria:**
|
|
- Admin login works with .env credentials
|
|
- No users table in database
|
|
- Simpler authentication flow
|
|
- All existing functionality preserved
|
|
|
|
## Test Plan
|
|
|
|
**Fresh Install:**
|
|
1. Start with NO database
|
|
2. Create .env with admin credentials
|
|
3. Start server
|
|
4. Verify admin login works with .env password
|
|
5. Verify NO users table created
|
|
|
|
**Agent Auth:**
|
|
1. Ensure agent registration still works
|
|
2. Verify agent commands still work
|
|
3. Ensure JWT tokens still validate
|
|
|
|
## Status
|
|
|
|
**Current State:** INVESTIGATION_REQUIRED
|
|
- Need to verify current auth implementations
|
|
- Determine what's actually used vs. legacy scaffolding
|
|
- Decide between complete removal vs. minimal migration
|
|
- Consider impact on existing installations
|
|
|
|
**Next Step:** Read CANTFUCKINGTHINK3 investigation to understand full context
|
|
|
|
---
|
|
|
|
**Key Insight:** This is the most important architectural decision for RedFlag's future. Single-admin tool should have single-admin architecture. Removing unnecessary complexity will improve security, reliability, and maintainability while honoring ETHOS principles.
|
|
|
|
**Related Backlog Items:**
|
|
- P0-005_Setup-Flow-Broken.md (partially caused by this architecture)
|
|
- P2-002_Migration-Error-Reporting.md (migration complexity from unnecessary tables)
|
|
- P4-006_Architecture-Documentation-Gaps.md (this needs to be documented)
|