# 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)