# HarborForge OpenClaw Server Connector Plugin — Project Plan

## 1) Goal
Provide a secure, lightweight plugin/agent that connects servers to HarborForge Monitor, streams telemetry in real time, and falls back to HTTP heartbeat when WebSocket is unavailable.

## 2) Scope
- **Handshake + auth** using backend-issued challenge + RSA-OAEP encrypted payload.
- **WebSocket telemetry** to `/monitor/server/ws`.
- **HTTP heartbeat** to `/monitor/server/heartbeat` as fallback.
- **System metrics**: CPU/Mem/Disk/Swap/Uptime/OpenClaw version/Agents list.
- **Retry & backoff**, offline handling, and minimal local state.

## 3) Non-Goals
- No UI in the plugin.
- No provider billing calls from plugin.
- No multi-tenant auth beyond challenge + server identifier.

## 4) Architecture
```
plugin/
  config/          # load config & secrets
  crypto/          # RSA-OAEP encrypt/decrypt helpers
  collector/       # system + openclaw metrics
  transport/       # ws + http heartbeat
  state/           # retry/backoff, last sent, cache
  main.ts|py        # entry
```

### 4.1 Config
- `backend_url`
- `identifier`
- `challenge_uuid`
- `report_interval_sec` (default: 20-30s)
- `http_fallback_interval_sec` (default: 60s)
- `log_level`

### 4.2 Security
- Fetch public key: `GET /monitor/public/server-public-key`
- Encrypt payload with RSA-OAEP
- Include `nonce` + `ts` (UTC) to prevent replay
- **Challenge valid**: 10 minutes
- **Offline threshold**: 7 minutes

## 5) Communication Flow
### 5.1 Handshake (WS)
1. Plugin reads `identifier + challenge_uuid`.
2. Fetch RSA public key.
3. Encrypt payload: `{identifier, challenge_uuid, nonce, ts}`.
4. Connect WS `/monitor/server/ws` and send `encrypted_payload`.
5. On success: begin periodic telemetry push.

### 5.2 Fallback (HTTP)
If WS fails:
- POST telemetry to `/monitor/server/heartbeat` with same payload fields.
- Retry with exponential backoff (cap 5–10 min).

## 6) Telemetry Schema (example)
```
{
  identifier: "vps.t1",
  openclaw_version: "x.y.z",
  cpu_pct: 12.5,
  mem_pct: 41.2,
  disk_pct: 62.0,
  swap_pct: 0.0,
  agents: [ { id: "a1", name: "agent", status: "running" } ],
  last_seen_at: "2026-03-11T21:00:00Z"
}
```

## 7) Reliability
- Automatic reconnect on WS drop
- HTTP fallback if WS unavailable > 2 intervals
- Exponential backoff on failures
- Local cache for last successful payload

## 8) Deployment Options
- **Systemd service** (preferred for VPS)
- **Docker container** (optional)
- Single-binary build if using Go/Rust

## 9) Milestones
**M1 – POC (2–3 days)**
- CLI config loader + HTTP heartbeat
- See online + metrics in Monitor

**M2 – WS realtime (2–3 days)**
- Full handshake + WS streaming
- Reconnect & fallback logic

**M3 – Packaging (1–2 days)**
- systemd unit + sample config
- installation script

**M4 – Hardening & Docs (1–2 days)**
- logging, metrics, docs
- troubleshooting guide

## 10) Deliverables
- Plugin source
- Config template + systemd unit
- Integration docs
- Test script + example payloads

## 11) Open Questions
- Preferred language (Go/Python/Node/Rust)?
- How to read OpenClaw agent list (API vs local state)?
- Required log format / retention?

---

**Next step:** confirm preferred runtime (Go/Python/Node) and I will scaffold the project structure + first heartbeat implementation.