From c7461946dad4908a71777975eba5b1da7bdb654e Mon Sep 17 00:00:00 2001 From: "Claude (Chronicler #35)" Date: Tue, 31 Mar 2026 22:44:21 +0000 Subject: [PATCH] docs: Add Task #90 - Arbiter 2.x Unified Access Manager WHAT WAS DONE: - Added Task #90 to tasks.md (Tier 1, Soft Launch Blocker) - Documented complete architecture from Gemini consultation - 5-phase implementation plan with detailed checklists - Critical gotchas and technical specifications captured WHY: Tonight's Gemini consultation revealed current Whitelist Manager is architecturally broken (hardcoded server names, unreliable WebSocket status detection, no subscription integration). Solution: merge Arbiter + Whitelist Manager into single Node.js app with PostgreSQL backend. GEMINI ARCHITECTURAL DECISIONS (validated March 31, 2026): - Single unified app instead of separate microservices - PostgreSQL for concurrent write safety at 500-user scale - Discord /link slash command with Mojang API validation - Pterodactyl File Management API (replace WebSocket console) - Hybrid sync: event-driven push + hourly cron reconciliation - Master whitelist = database, all servers sync from it IMPLEMENTATION PHASES: 1. Database Migration (PostgreSQL setup, schema, indexes) 2. Core Functions (Mojang validation, Panel API clients) 3. Discord Integration (/link command, auto-DM subscribers) 4. Sync System (event-driven + cron, sequential processing) 5. Admin Panel (sync monitoring, manual triggers) CRITICAL GOTCHAS CAPTURED: - Content-Type: text/plain for Panel file write (not application/json) - Mojang UUIDs without dashes, Minecraft needs WITH dashes - HTTP 412 = server offline, NOT error (file saved for boot) - Sequential processing prevents Panel API rate limiting CONTEXT: Discovered issues during attempt to fix Task #86 (Whitelist Manager v1.12.1 compatibility). Realized entire architecture needs rewrite for subscription-driven access control. Gemini provided complete technical specification with code examples ready to implement. BLOCKS: - Soft launch (subscribers need automatic whitelist access) RETIRES: - Old Whitelist Manager (Python Flask on Billing VPS) - Old Arbiter 1.x (if not already migrated) FILES: - docs/core/tasks.md (modified, +112 lines for Task #90) NEXT STEPS: - Create task directory: docs/tasks/arbiter-2x/ - Copy Gemini implementation guide to task directory - Begin Phase 1: PostgreSQL database setup Signed-off-by: The Golden Chronicler --- docs/core/tasks.md | 108 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) 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.** + +--- + ---