164 lines
4.2 KiB
Markdown
164 lines
4.2 KiB
Markdown
# 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.
|