chore: initial import

2025-12-18 00:29:15 +01:00
commit 789397eb33
22 changed files with 5944 additions and 0 deletions
--- a/docs/NODE_AGENT_CONTRACT.md
+++ b/docs/NODE_AGENT_CONTRACT.md
@@ -0,0 +1,163 @@
+# Node Agent Contract
+
+This document defines the API contract between VaultMesh Node Agents and the Command Center.
+
+## Heartbeat Endpoint
+
+### Request
+
+```
+POST /api/agent/heartbeat
+Content-Type: application/json
+```
+
+### Heartbeat Schema
+
+```json
+{
+  "node_id": "UUID v4",
+  "hostname": "string",
+  "os_profile": "string",
+  "cloudflare_ok": "boolean",
+  "services_ok": "boolean",
+  "vaultmesh_root": "string",
+  "timestamp": "ISO 8601 / RFC 3339"
+}
+```
+
+### Field Definitions
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `node_id` | UUID v4 | Unique identifier for this node. Should persist across reboots. |
+| `hostname` | String | System hostname (from `hostname::get()` or `/etc/hostname`) |
+| `os_profile` | String | VaultMesh profile name: `ArchVault`, `DebianVault`, etc. |
+| `cloudflare_ok` | Boolean | `true` if `cloudflared` service is active |
+| `services_ok` | Boolean | `true` if VAULTMESH_ROOT exists and is healthy |
+| `vaultmesh_root` | String | Path to VAULTMESH_ROOT (e.g., `/var/lib/vaultmesh`) |
+| `timestamp` | RFC 3339 | UTC timestamp when heartbeat was generated |
+
+### Response
+
+**Success (200 OK)**:
+```json
+{
+  "status": "ok"
+}
+```
+
+**Error (4xx/5xx)**:
+```json
+{
+  "error": "description"
+}
+```
+
+## Environment Variables
+
+The node agent is configured via environment variables, typically set in `/etc/vaultmesh/agent.env`.
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `VAULTMESH_NODE_ID` | No | Auto-generated UUID v4 | Persistent node identifier |
+| `VAULTMESH_CC_URL` | No | `http://127.0.0.1:8088` | Command Center base URL |
+| `VAULTMESH_OS_PROFILE` | No | `ArchVault` | OS profile name to report |
+| `VAULTMESH_ROOT` | No | `/var/lib/vaultmesh` | Path to check for services_ok |
+| `VAULTMESH_HEARTBEAT_SECS` | No | `30` | Seconds between heartbeats |
+| `RUST_LOG` | No | `info` | Log level (trace, debug, info, warn, error) |
+
+### Example `/etc/vaultmesh/agent.env`
+
+```bash
+VAULTMESH_NODE_ID=550e8400-e29b-41d4-a716-446655440000
+VAULTMESH_CC_URL=https://cc.vaultmesh.example
+VAULTMESH_OS_PROFILE=ArchVault
+VAULTMESH_ROOT=/var/lib/vaultmesh
+VAULTMESH_HEARTBEAT_SECS=30
+RUST_LOG=info
+```
+
+## Node Registration
+
+Nodes self-register on first heartbeat. There is no explicit registration endpoint.
+
+When the Command Center receives a heartbeat with a new `node_id`, it creates a new entry. Subsequent heartbeats update the existing entry.
+
+### Node ID Persistence
+
+For consistent tracking, the `VAULTMESH_NODE_ID` should be persisted. Options:
+
+1. **Environment file**: Set in `/etc/vaultmesh/agent.env`
+2. **Machine ID**: Could derive from `/etc/machine-id`
+3. **Auto-generated**: If not set, agent generates a new UUID on each start (not recommended for production)
+
+**Recommended**: Generate a UUID once during node bootstrap and store in `agent.env`:
+
+```bash
+# During node bootstrap
+echo "VAULTMESH_NODE_ID=$(uuidgen)" >> /etc/vaultmesh/agent.env
+```
+
+## Health Checks
+
+### cloudflare_ok
+
+The agent runs:
+```bash
+systemctl is-active --quiet cloudflared
+```
+
+Returns `true` if exit code is 0 (service active).
+
+### services_ok
+
+The agent checks if `VAULTMESH_ROOT` exists and is a directory:
+```rust
+std::path::Path::new(vaultmesh_root).is_dir()
+```
+
+Future versions may add additional checks:
+- Disk space
+- Key services running
+- ProofChain integrity
+
+## Error Handling
+
+### Network Errors
+
+If the agent cannot reach the Command Center:
+- Log error at WARN/ERROR level
+- Sleep for heartbeat interval
+- Retry on next cycle
+
+No exponential backoff in V1. The agent will retry every `VAULTMESH_HEARTBEAT_SECS` seconds indefinitely.
+
+### Invalid Response
+
+If CC returns non-2xx status:
+- Log warning with status code
+- Continue normal operation
+- Retry on next cycle
+
+## Security Considerations
+
+### Transport Security
+
+- Agent should connect to CC via HTTPS (Cloudflare Tunnel)
+- `reqwest` configured with `rustls-tls` (no OpenSSL dependency)
+
+### Authentication (Future)
+
+V1 has no agent authentication. Future versions may add:
+- Signed JWTs
+- Shared secrets
+- mTLS
+
+### Data Sensitivity
+
+Heartbeat data is low-sensitivity:
+- No secrets or credentials
+- No PII
+- No file contents
+
+The `vaultmesh_root` path and hostname are the most identifying fields.