vps-health-api/README.md

# vps-health-api

Lightweight health monitoring API for the VPS. Node 22, HTTP-native, zero runtime deps.

## Endpoints

Read endpoints require `Authorization: Bearer $HEALTH_TOKEN`. The single write
endpoint uses its own token, `$HOSTS_INGEST_TOKEN`, so a workstation agent can
push its snapshot without gaining read access to the Defenseurs reports.

| Method | Path | Token | Description |
|--------|------|-------|-------------|
| GET | `/health` | `HEALTH_TOKEN` | CPU, memory, disk, uptime, Logto reachability |
| GET | `/defenseurs` | `HEALTH_TOKEN` | Defenseurs executive status (status.json) |
| GET | `/defenseurs/findings?project=X` | `HEALTH_TOKEN` | Detailed findings for a project's Defenseur |
| GET | `/defenseurs/state` | `HEALTH_TOKEN` | Sergent's per-finding state (findings-state.json) |
| GET | `/reports/scans?date=YYYY-MM-DD` | `HEALTH_TOKEN` | Aggregated scan reports for a UTC date |
| GET | `/hosts` | `HEALTH_TOKEN` | Latest snapshot of every allowlisted workstation |
| POST | `/hosts/<id>` | `HOSTS_INGEST_TOKEN` | Ingest one workstation snapshot |

Routing resolves before authentication: an unknown path or a wrong method
answers `404`, never `401`.

### `POST /hosts/<id>`

Body: the `GET /health` payload minus `logto` and `timestamp` — `hostname`,
`uptime`, `cpu{model,cores,loadAvg,usagePercent}`,
`memory{totalGB,usedGB,freeGB,usagePercent}`, `disk{…same four…}`.
`loadAvg` must hold exactly 3 finite numbers (the 1, 5 and 15-minute
averages); any other length is a `400`.

`<id>` must match `^[a-z0-9][a-z0-9-]{0,31}$` and be listed in
`HOSTS_ALLOWED_IDS`. That regex is the path-traversal control — anything that
fails it never reaches a handler.

| Code | Case |
|------|------|
| 204 | Snapshot accepted and written |
| 400 | Unparsable JSON, missing field, or wrong type |
| 401 | Ingest token missing or wrong |
| 403 | `<id>` well-formed but not in the allowlist |
| 404 | `<id>` outside the format (never reaches the handler) |
| 413 | Body past 4 KiB — connection cut |
| 503 | `HOSTS_INGEST_TOKEN` not configured (fail-closed) |

The stored object is rebuilt field by field from a whitelist (numbers must be
finite, strings are capped at 128 chars, everything else dropped) and written
atomically via a temp file + `rename`. `receivedAt` is stamped by the server on
arrival; a client-supplied timestamp is ignored.

Strings are truncated, not filtered: control characters and markup are kept so
a legitimate value is never mangled. Consumers must escape them when rendering
(React text nodes do; `dangerouslySetInnerHTML` or an `href` would not).

A process killed mid-write can leave a `.<id>.<pid>.<ms>.tmp` file behind.
Startup removes the ones older than an hour; `GET /hosts` never reads them.

Example:

```
curl -X POST -H "Authorization: Bearer $HOSTS_INGEST_TOKEN" \
  -H "Content-Type: application/json" --data @snapshot.json \
  "https://health.lacompagniemaximus.com/hosts/thinkpad"
```

### `GET /hosts`

```
{ "staleAfterSeconds": 900,
  "hosts": [ { "id", "hostname", "uptime", "cpu", "memory", "disk",
               "receivedAt", "ageSeconds", "online" } ] }
```

One entry per allowlisted id. `online = ageSeconds <= staleAfterSeconds`,
computed server-side. A host that never checked in — or whose snapshot file is
unreadable — degrades to `{ id, receivedAt: null, ageSeconds: null, online:
false, neverSeen: true }` instead of failing the response, so the dashboard can
say "agent not installed" during commissioning.

### `GET /defenseurs/state`

Serves the Sergent's `findings-state.json` verbatim — per-finding `firstSeen`,
`unverified` status and 30-day history. It is the only source that carries a
finding's age, which is why the admin dashboard's drill-down reads it alongside
`/defenseurs`. The file is not parsed or checked for freshness here: the Sergent
writes it atomically and quarantines unreadable state itself, and staleness is
judged by the reader.

- `200` — raw file content
- `200 { status: "no_data" }` — file absent or unreadable (same contract as `/defenseurs`)
- `401` — missing or invalid token

```
curl -H "Authorization: Bearer $HEALTH_TOKEN" \
  "https://health.lacompagniemaximus.com/defenseurs/state"
```

### `GET /defenseurs/findings`

Query params:

- `project` (required) — project name, looked up in `agents-map.json` (e.g. `la-suite-booking`)
- `category` (optional) — exact match, one of `deps|secrets|code|acces|infra`
- `severity` (optional) — threshold, one of `CRITICAL|HIGH|MEDIUM|LOW|INFO`
  - default (no param): `MEDIUM`, `HIGH`, `CRITICAL`
  - `LOW` returns `LOW`+`MEDIUM`+`HIGH`+`CRITICAL` but still hides `INFO`
  - `INFO` returns `INFO` only (explicit opt-in)

Responses:

- `200 { agent, project, timestamp, findings: Finding[] }` — report present (empty `findings` if clean scan; no `status` field)
- `200 { findings: [], status: "no_data" }` — no report on file for the agent
- `400` — missing `project` or invalid `category` / `severity`
- `401` — missing or invalid token
- `404` — unknown project
- `500` — `agents-map.json` unreadable or corrupted

Example:

```
curl -H "Authorization: Bearer $HEALTH_TOKEN" \
  "https://health.lacompagniemaximus.com/defenseurs/findings?project=la-suite-booking&severity=HIGH"
```

## Config

| Env var | Default | Purpose |
|---------|---------|---------|
| `PORT` | `3001` | HTTP port |
| `HEALTH_TOKEN` | — | Bearer token for the read routes (fail-closed if missing) |
| `REPORTS_DIR` | `/data/defenseurs/reports` | Scan reports dir |
| `DEFENSEURS_STATUS_PATH` | `/data/defenseurs/status.json` | Served by `/defenseurs` |
| `DEFENSEURS_FINDINGS_STATE_PATH` | `/data/defenseurs/findings-state.json` | Served by `/defenseurs/state` |
| `DEFENSEURS_AGENTS_MAP_PATH` | `/data/defenseurs/agents-map.json` | Project -> agent snapshot |
| `LOGTO_HEALTH_URL` | auth.lacompagniemaximus.com | Logto OIDC discovery URL |
| `HOSTS_DIR` | `/data/hosts` | Where workstation snapshots are **written** |
| `HOSTS_ALLOWED_IDS` | `thinkpad` | Comma-separated allowlist of host ids |
| `HOSTS_INGEST_TOKEN` | — | Bearer token for `POST /hosts/<id>` (503 if missing) |
| `HOSTS_STALE_SECONDS` | `900` | Age past which a host is reported offline |

## Bind-mounts (Coolify)

Mounted read-only (`:ro`) — written on the host by the Defenseurs Sergent:

- `/data/defenseurs` -> `/data/defenseurs:ro` — holds `status.json`,
  `findings-state.json` and `agents-map.json`, all written there directly by
  the Sergent. (`/home/defenseur/defenseurs/status.json` is an obsolete decoy
  nobody reads.)
- `/home/defenseur/defenseurs/reports` -> `/data/defenseurs/reports:ro` — its
  own mount, nested inside the previous one.

Two layers keep the API out of these files: the `:ro` mode (a suffix on the
Coolify destination path, copied as-is into the generated compose), and Unix
permissions (content owned by `defenseur:defenseur`, uid and gid 1001,
directories 755/775, files 664, while the container runs as uid 1000 with no
supplementary group). The group bits grant write, so the second layer holds
only while the owning group is not gid 1000 (`node` in the image, `ubuntu` on
the host): a `chgrp ubuntu` would drop it silently.

`__tests__/writes.test.js` pins that `node:fs` writes go nowhere but
`HOSTS_DIR`, and that the only shell commands are the two read-only ones in
`metrics.js`, on every path it exercises: boot, nominal reads and ingest,
rejections, invalid input, a corrupt file, missing files.

Read-write — the API is the writer:

- `<host>/data/hosts/` -> `/data/hosts/` (`HOSTS_DIR`). Must be writable by uid
  1000, the `node` user the container runs as, otherwise every ingest 500s.

## Workstation agent

`agent/` holds the zero-dependency collector that runs from cron on a
workstation and feeds `POST /hosts/<id>`. It is not part of the server image —
it is installed by copying files onto the machine it measures. Install steps,
crontab line and failure modes: [`agent/README.md`](agent/README.md).

## Tests

```
npm install
npm test
```