diff --git a/docs/core/tasks.md b/docs/core/tasks.md index 30ce89a..7993b2b 100644 --- a/docs/core/tasks.md +++ b/docs/core/tasks.md @@ -3003,6 +3003,114 @@ DERP (Disaster Emergency Recovery Protocol) was established as backup when Claud --- +### 90. Arbiter 2.x - Unified Access Manager (Subscription → Whitelist Integration) +**Time:** 20-30 hours (5 phases) +**Status:** OPEN — Architecture validated by Gemini, ready to build +**Priority:** Tier 1 — SOFT LAUNCH BLOCKER +**Documentation:** `docs/tasks/arbiter-2x/` + `/home/claude/arbiter-2x-implementation-guide.md` + +**WHAT THIS IS:** +Complete rewrite of subscription → server access flow. Merges Arbiter (Discord roles) + Whitelist Manager (server access) into single Node.js application with PostgreSQL backend. Subscription-driven whitelist with master list synced to all Minecraft servers. + +**THE FLOW:** +1. User subscribes (any tier, even $1 Awakened) +2. Paymenter webhook → Arbiter assigns Discord role +3. User links Minecraft account: `/link ` (Discord slash command) +4. Arbiter validates via Mojang API, gets UUID +5. Stores in PostgreSQL: discord_id, minecraft_username, minecraft_uuid +6. Master whitelist auto-syncs to all whitelisted servers +7. User can now join any Minecraft server + +**WHY REWRITE:** +Current Whitelist Manager is broken: +- Hardcoded server name keywords (fails when servers change) +- WebSocket console commands (unreliable, returns "UNKNOWN") +- No subscription integration +- No master whitelist concept +- Manual-only operation + +**ARCHITECTURE DECISIONS (Gemini validated March 31, 2026):** +- ✅ Single Node.js app (Arbiter 2.x) instead of separate services +- ✅ PostgreSQL instead of SQLite (concurrent write safety at scale) +- ✅ Discord `/link` slash command (Mojang API validation) +- ✅ Pterodactyl File Management API (not WebSocket console) +- ✅ Hybrid sync: Event-driven push + hourly cron reconciliation +- ✅ UUIDs WITH DASHES in whitelist.json (Minecraft 1.8+ requirement) + +**IMPLEMENTATION PHASES:** + +**Phase 1: Database Migration** +- [ ] Provision PostgreSQL 15+ database +- [ ] Execute schema creation (users, subscriptions, server_sync_log) +- [ ] Apply indexes for 500-user scale optimization +- [ ] Migrate legacy data from SQLite + +**Phase 2: Core Functions** +- [ ] Initialize `pg` connection pool +- [ ] Implement Mojang API validation + UUID formatting +- [ ] Build Application API client for auto-discovery +- [ ] Build Client API file write (`Content-Type: text/plain`) +- [ ] Build Client API reload command (safe-fail on HTTP 412) + +**Phase 3: Discord Integration** +- [ ] Register `/link ` slash command +- [ ] UUID validation flow on linking +- [ ] Auto-DM new subscribers with link instructions +- [ ] Update Paymenter webhook handler for role assignment + +**Phase 4: Sync System** +- [ ] Event-driven immediate sync (on /link, on subscribe) +- [ ] node-cron hourly reconciliation (0 * * * *) +- [ ] Sequential batch processing (prevent rate limits) +- [ ] Sync logging to server_sync_log table + +**Phase 5: Admin Panel & Testing** +- [ ] Dashboard view for server_sync_log status +- [ ] Manual "Force Sync" trigger button +- [ ] View linked Minecraft accounts vs Discord IDs +- [ ] Final testing and production deployment + +**CRITICAL GOTCHAS (from Gemini):** +- `Content-Type: text/plain` for file write (NOT application/json) +- Mojang returns UUIDs without dashes, Minecraft needs WITH dashes +- HTTP 412 = server offline, NOT an error (file saved for next boot) +- Sequential processing prevents Panel API rate limiting +- Use Application API for discovery, Client API for file ops + +**DELIVERABLES:** +- Arbiter 2.x Node.js application +- PostgreSQL database with proper schema + indexes +- `/link` Discord slash command with Mojang validation +- Pterodactyl auto-discovery (by node allocation, not name) +- Master whitelist sync system (event-driven + hourly cron) +- Admin panel for sync monitoring + manual triggers +- Complete migration from broken Whitelist Manager + +**DEPENDENCIES:** +- PostgreSQL 15+ +- Node.js 20 LTS +- Pterodactyl Panel v1.12.1 (Client + Application API keys) +- Mojang API (public, no auth required) +- Discord Bot with slash command permissions + +**SUCCESS CRITERIA:** +- User subscribes → links Minecraft account → auto-whitelisted within 5 minutes +- Master whitelist = single source of truth (database) +- All servers sync from master list (hourly reconciliation) +- Server discovery is automatic (no hardcoded names) +- Works reliably for remote RV operations (no manual intervention) +- Handles 500 subscribers by September 2027 + +**RETIREMENT:** +Once Arbiter 2.x deployed: +- Retire old Whitelist Manager (Python Flask app on Billing VPS) +- Retire old Arbiter 1.x (if not already migrated) +- Update all documentation to reference new unified system + +**See implementation guide for complete technical specification with code examples.** + +--- + ---