Add docs and project files - force for Culurien

docs/4_LOG/2025-11/Status-Updates/simple-update-checklist.md

@@ -0,0 +1,102 @@
+# Simple Agent Update Checklist
+
+## Version Bumping Process for RedFlag v0.2.0 - TESTED AND WORKING
+
+### ✅ TESTED RESULTS (Real Server Deployment)
+
+**Backend APIs Verified:**
+1. `GET /api/v1/agents/:id/updates/available` - Returns update availability with nonce security
+2. `POST /api/v1/agents/:id/update-nonce?target_version=X` - Generates Ed25519-signed nonces
+3. `GET /api/v1/agents/:id/updates/status` - Returns update progress status
+
+**Test Results:**
+```bash
+✅ Update Available Check: {"currentVersion":"0.1.23","hasUpdate":true,"latestVersion":"0.2.0"}
+✅ Nonce Generation: {"agent_id":"2392dd78-70cf-49f7-b40e-673cf3afb944","update_nonce":"eyJhZ2VudF...==","expires_in_seconds":600}
+✅ Update Status Check: {"error":null,"progress":null,"status":"idle"}
+```
+
+### Version Update Process - CONFIRMED WORKING
+
+### 1. Update Agent Version in Config Builder
+**File:** `aggregator-server/internal/services/config_builder.go`
+**Line:** 272
+**Change:** `config["agent_version"] = "0.1.23"` → `config["agent_version"] = "0.2.0"`
+
+### 2. Update Default Agent Version (Optional)
+**File:** `aggregator-server/internal/config/config.go`
+**Line:** 89
+**Change:** `cfg.LatestAgentVersion = getEnv("LATEST_AGENT_VERSION", "0.1.23")` → `cfg.LatestAgentVersion = getEnv("LATEST_AGENT_VERSION", "0.2.0")`
+
+### 3. Update Agent Builder Config (Optional)
+**File:** `aggregator-server/internal/services/agent_builder.go`
+**Line:** 77 (already covered by config builder)
+
+### 4. Update Update Package Version
+**File:** `aggregator-server/internal/services/config_builder.go`
+**Line:** 172 (for struct comment only)
+
+### 5. Create Signed Update Package
+**Endpoint:** `POST /api/v1/updates/packages/sign`
+**Request Body:**
+```json
+{
+  "version": "0.2.0",
+  "platform": "linux",
+  "architecture": "amd64"
+}
+```
+
+### 6. Verify Update Shows Available
+**Endpoint:** `GET /api/v1/agents/:id/updates/available`
+**Expected Response:**
+```json
+{
+  "hasUpdate": true,
+  "currentVersion": "0.1.23",
+  "latestVersion": "0.2.0"
+}
+```
+
+## Authentication Routing Guidelines
+
+### Agent Communication Routes (AgentAuth/JWT)
+**Group:** `/agents/:id/*`
+**Middleware:** `AuthMiddleware()` - Agent JWT authentication
+**Purpose:** Agent-to-server communication
+**Examples:**
+- `GET /agents/:id/commands`
+- `POST /agents/:id/system-info`
+- `POST /agents/:id/updates`
+
+### Admin Dashboard Routes (WebAuth/Bearer)
+**Group:** `/api/v1/*` (admin routes)
+**Middleware:** `WebAuthMiddleware()` - Admin browser session
+**Purpose:** Admin UI and server management
+**Examples:**
+- `GET /agents` - List agents for dashboard
+- `POST /agents/:id/update` - Manual agent update
+- `GET /agents/:id/updates/available` - Check if update available
+- `GET /agents/:id/updates/status` - Get update progress
+
+## Update Package Table Structure
+
+**Table:** `agent_update_packages`
+**Fields:**
+- `version`: Target version string
+- `platform`: Target OS platform
+- `architecture`: Target CPU architecture
+- `binary_path`: Path to signed binary
+- `signature`: Ed25519 signature of binary
+- `checksum`: SHA256 hash of binary
+- `is_active`: Whether package is available
+
+## Update Flow Check
+
+1. **Agent Reports Current Version:** During check-in
+2. **Server Checks Latest:** Via `GetLatestVersion()` from packages table
+3. **Version Comparison:** Using `isVersionUpgrade(new, current)`
+4. **UI Shows Available:** When `hasUpdate = true`
+5. **Admin Triggers Update:** Generates nonce and sends command
+6. **Agent Receives Nonce:** Via update command
+7. **Agent Uses Nonce:** During version upgrade process