diff --git a/Agent_Endpoint_Specifications_Phase1.md b/Agent_Endpoint_Specifications_Phase1.md new file mode 100644 index 0000000..a7ec558 --- /dev/null +++ b/Agent_Endpoint_Specifications_Phase1.md @@ -0,0 +1,403 @@ +# Agent Endpoint Specifications - Phase 1 Release + +**Last Updated**: February 21, 2026 +**Status**: Active Development +**Target**: Pre-Launch Release + +--- + +## ๐Ÿ“‹ Current Agent Capabilities (Baseline) + +**Already Implemented**: +- โœ… Provisioning (dev + game containers) +- โœ… Lifecycle control (`/start`, `/stop`, `/restart`) +- โœ… State reporting (`/status`, `/health`) +- โœ… PTY-backed WebSocket console (`/console/stream`) +- โœ… Minecraft player telemetry (`/game/players`) +- โœ… Self-update system (`/agent/update`, `/agent/update/status`) +- โœ… Version endpoint (`/version`) +- โœ… Autostart subsystem +- โœ… Periodic update checks (notify/auto/off modes) + +--- + +## ๐ŸŽฏ New Endpoints for Phase 1 + +### **Priority 1: Mod Management (CRITICAL - Blocking Release)** + +#### **GET /game/mods** - Mod Detection + +**Purpose**: List all installed mods with metadata + +**Response**: +```json +{ + "variant": "forge", + "variant_version": "47.2.0", + "minecraft_version": "1.20.1", + "mods": [ + { + "id": "jei", + "name": "Just Enough Items", + "version": "15.2.0.27", + "filename": "jei-1.20.1-forge-15.2.0.27.jar", + "description": "Item and recipe viewing mod", + "required": false, + "server_side": true, + "client_side": true, + "dependencies": ["minecraft@1.20.1", "forge@>=47.0.0"], + "enabled": true, + "source": "curated" + } + ], + "total_count": 1, + "scan_timestamp": "2026-02-21T16:00:00Z" +} +``` + +**Implementation Requirements**: +- Scan `/server/mods/` directory for .jar files +- Detect variant by checking for: + - Forge: `/server/config/forge-*.toml` or `META-INF/mods.toml` in JARs + - Fabric: `/server/fabric.mod.json` or `fabric.mod.json` in JARs + - Paper: `/server/plugins/*.jar` exists +- Parse metadata from: + - **Forge**: `META-INF/mods.toml` or `mcmod.info` + - **Fabric**: `fabric.mod.json` + - **Paper**: `plugin.yml` +- Cache results for 5-10 minutes +- Gracefully handle missing/corrupt metadata (fallback to filename) + +--- + +#### **POST /game/mods/install** - Install Curated Mod + +**Purpose**: Download and install mod from curated artifact store + +**Request**: +```json +{ + "source": "curated", + "mod_id": "jei", + "version": "15.2.0.27", + "artifact_url": "https://artifacts.zerolaghub.com/mods/forge/jei-15.2.0.27.jar", + "artifact_hash": "sha256:abc123..." +} +``` + +**Response**: +```json +{ + "success": true, + "mod": { /* full mod object */ }, + "action": "installed", + "restart_required": true +} +``` + +**Implementation Requirements**: +- Download from `artifact_url` to temp directory +- **Verify SHA-256 hash matches `artifact_hash`** (CRITICAL - security) +- Only accept URLs from `artifacts.zerolaghub.com` domain +- Drop privileges to minecraft user before file operations +- Move verified file to `/server/mods/{filename}` +- Set permissions: owner=minecraft, mode=0644 +- Return error if hash mismatch +- Return error if disk full + +**Security (Non-Negotiable)**: +```go +// Example secure implementation pattern: +// 1. Download to /tmp/ +// 2. Verify hash +// 3. If valid, install as minecraft user +exec.Command("su", "-", "minecraft", "-c", + "cp /tmp/verified-mod.jar /server/mods/mod.jar").Run() +``` + +--- + +#### **PATCH /game/mods/:mod_id** - Enable/Disable Mod + +**Purpose**: Toggle mod enabled state without removing + +**Request**: +```json +{ + "enabled": false +} +``` + +**Response**: +```json +{ + "success": true, + "mod": { /* updated mod object */ }, + "action": "disabled", + "restart_required": true +} +``` + +**Implementation**: +- Disable: Rename `.jar` โ†’ `.jar.disabled` +- Enable: Rename `.jar.disabled` โ†’ `.jar` +- Alternative: Move to `/server/mods-disabled/` directory + +--- + +#### **DELETE /game/mods/:mod_id** - Remove Mod + +**Purpose**: Permanently remove mod + +**Response**: +```json +{ + "success": true, + "action": "removed", + "restart_required": true +} +``` + +**Implementation**: +- Delete `.jar` file from `/server/mods/` +- Optional: Move to `/server/mods-removed/` for rollback capability + +--- + +### **Priority 2: Process Metrics (HIGH)** + +#### **GET /metrics/process** - Game Process Stats + +**Purpose**: Expose game server process metrics + +**Response**: +```json +{ + "process": { + "pid": 12345, + "status": "running", + "uptime_seconds": 3600, + "restart_count": 2, + "last_start": "2026-02-21T15:30:00Z", + "last_crash": "2026-02-21T12:00:00Z" + }, + "memory": { + "rss_bytes": 2147483648, + "vms_bytes": 4294967296 + } +} +``` + +**Implementation**: +- Read from `/proc/{pid}/stat` and `/proc/{pid}/status` +- Track restart count in state file +- Return 404 if process not running (not an error) + +--- + +### **Priority 3: Agent Health (MEDIUM)** + +#### **GET /metrics/agent** - Agent Health + +**Purpose**: Expose agent operational metrics + +**Response**: +```json +{ + "agent": { + "version": "v1.2.3", + "uptime_seconds": 86400, + "last_update_check": "2026-02-21T14:00:00Z", + "update_available": false + }, + "handlers": { + "console_sessions": 2, + "active_websockets": 3, + "provisioning_active": false + } +} +``` + +--- + +### **Priority 4: Provisioning Progress (LOW)** + +#### **GET /metrics/provisioning** - Install Progress + +**Purpose**: Real-time provisioning status + +**Response**: +```json +{ + "active": true, + "current_step": "downloading_artifacts", + "progress_percent": 45, + "started_at": "2026-02-21T15:00:00Z", + "estimated_completion": "2026-02-21T15:10:00Z" +} +``` + +--- + +## ๐Ÿ”’ Security Requirements (CRITICAL) + +### **Privilege Separation** + +**MUST**: All mod file operations run as non-root user + +``` +โœ… DO: Use su/sudo to drop privileges +โŒ DON'T: Write files as root +``` + +### **Hash Verification** + +**MUST**: Verify SHA-256 before installing curated mods + +``` +Process: +1. Download to temp directory +2. Calculate SHA-256 hash +3. Compare with expected hash +4. If match โ†’ install +5. If mismatch โ†’ delete and error +``` + +### **URL Whitelisting** + +**MUST**: Only download from trusted domains + +``` +Allowed: +โœ… artifacts.zerolaghub.com + +Rejected: +โŒ Arbitrary URLs +โŒ User-provided URLs +โŒ External mod sites (Phase 2) +``` + +### **Container Isolation** + +**Verify**: +- Game server runs as non-root user (minecraft/gameserver) +- LXC containers are unprivileged +- Network segmentation active (10.200.0.0/24 VLAN) + +--- + +## ๐Ÿ“ฆ Suggested Go Package Structure + +``` +internal/ +โ”œโ”€โ”€ mods/ +โ”‚ โ”œโ”€โ”€ scanner.go // Directory scanning +โ”‚ โ”œโ”€โ”€ forge.go // Forge metadata parser +โ”‚ โ”œโ”€โ”€ fabric.go // Fabric metadata parser +โ”‚ โ”œโ”€โ”€ paper.go // Paper plugin parser +โ”‚ โ”œโ”€โ”€ installer.go // Download + install logic +โ”‚ โ””โ”€โ”€ types.go // Structs and enums +โ”œโ”€โ”€ metrics/ +โ”‚ โ”œโ”€โ”€ process.go // Game process metrics +โ”‚ โ”œโ”€โ”€ agent.go // Agent health metrics +โ”‚ โ””โ”€โ”€ provisioning.go // Provisioning progress +โ””โ”€โ”€ handlers/ + โ”œโ”€โ”€ game.go // Mod endpoints + โ””โ”€โ”€ metrics.go // Metrics endpoints +``` + +--- + +## ๐ŸŽฏ Implementation Priority + +### **Week 1: Mod Detection + Install** +1. `GET /game/mods` with .jar listing +2. Forge metadata parsing +3. `POST /game/mods/install` with hash verification +4. Test with 5-10 mods + +### **Week 2: Mod Management** +1. `PATCH /game/mods/:id` (enable/disable) +2. `DELETE /game/mods/:id` (remove) +3. Fabric metadata parsing +4. Paper plugin parsing + +### **Week 3: Metrics** +1. `GET /metrics/process` +2. `GET /metrics/agent` +3. Optional: `GET /metrics/provisioning` + +--- + +## ๐Ÿšซ Phase 2 Features (NOT Phase 1) + +**Defer These**: +- โŒ User upload handling (requires malware scanning) +- โŒ Dependency resolution +- โŒ Mod update checking +- โŒ Config file management +- โŒ Rollback/restore functionality +- โŒ Dev container โ†’ Game server transfer + +--- + +## ๐Ÿงช Testing Requirements + +### **Mod Detection**: +- Empty directory โ†’ Empty array +- Forge mods โ†’ Correct parsing +- Fabric mods โ†’ Correct parsing +- Paper plugins โ†’ Correct parsing +- Corrupt metadata โ†’ Graceful fallback +- Mixed types โ†’ Correct variant detection + +### **Mod Installation**: +- Valid hash โ†’ Success +- Invalid hash โ†’ Error, no install +- Network failure โ†’ Error, no corruption +- Disk full โ†’ Error +- Invalid URL โ†’ Rejection + +### **Security**: +- File ops run as minecraft user +- Hash mismatch prevents install +- Malformed requests don't crash agent + +--- + +## ๐Ÿ“Š API Integration + +**API Will**: +- Cache `GET /game/mods` responses +- Validate user ownership before agent calls +- Handle authentication/authorization +- Aggregate metrics with Prometheus data + +**Agent Doesn't Handle**: +- User authentication (API's job) +- Ownership validation (API's job) +- Billing (API's job) +- Frontend concerns (API's job) + +--- + +## โœ… Definition of Done + +**Phase 1 Complete When**: +- โœ… All mod variants parse correctly (Forge/Fabric/Paper) +- โœ… Hash verification prevents tampered artifacts +- โœ… Mod enable/disable/remove works +- โœ… Process metrics accurate +- โœ… All file operations use dropped privileges +- โœ… Tests pass for all scenarios +- โœ… Error handling graceful (no crashes) +- โœ… Integration with API tested + +--- + +## ๐Ÿ”— Related Documentation + +- **API Integration**: See `game.js` endpoint specifications +- **Security Model**: See Drift Prevention Card DEC-008 +- **Container Architecture**: See Infrastructure documentation +- **Mod Catalog**: See artifact store structure (to be documented)