proxmox/services/sankofa-it-read-api/README.md

# Sankofa IT read API (Phase 0)

Minimal **read-only** JSON service for `reports/status/live_inventory.json` and `drift.json`. Intended to run on a **LAN** host (or CT) with access to the repo checkout and optional SSH to Proxmox for refresh.

**Production LAN install:** `bash scripts/deployment/bootstrap-sankofa-it-read-api-lan.sh` (rsync to `/opt/proxmox` on the seed node, `/etc/sankofa-it-read-api.env`, systemd, portal merge). See [SANKOFA_IT_OPS_KEYCLOAK_PORTAL_NEXT_STEPS.md](../../docs/03-deployment/SANKOFA_IT_OPS_KEYCLOAK_PORTAL_NEXT_STEPS.md).

## Run

```bash
cd /path/to/proxmox
python3 services/sankofa-it-read-api/server.py
```

With API key protection for `/v1/*`:

```bash
export IT_READ_API_KEY='your-long-random-secret'
python3 services/sankofa-it-read-api/server.py
```

Clients send `X-API-Key: your-long-random-secret` on `/v1/inventory/*`. `/health` stays unauthenticated.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/health` | Liveness; includes `oidc_issuer_configured` when `IT_BFF_OIDC_ISSUER` set |
| GET | `/v1/summary` | Envelope: artifact mtimes, `guest_count`, duplicate IP bucket count, `seed_unreachable` |
| GET | `/v1/collector-contract` | Serves `config/it-operations/live-collectors-contract.json` |
| GET | `/v1/portmap/joined` | Stub (Phase 2); `stale: true` until UniFi/NPM collectors exist |
| GET | `/v1/inventory/live` | Latest live guest inventory |
| GET | `/v1/inventory/drift` | Latest drift report |
| POST | `/v1/inventory/refresh` | Runs export script (requires `IT_READ_API_KEY`); body includes `drift_exit_code` (**2** = duplicate guest IPs) |

Optional **`IT_READ_API_CORS_ORIGINS`**: comma-separated browser origins; enables `OPTIONS` and `Access-Control-Allow-*` for direct SPA calls (prefer Next.js `/api/it/*` proxy so keys stay server-side).

## systemd

See [`config/systemd/sankofa-it-read-api.service.example`](../../config/systemd/sankofa-it-read-api.service.example).

## Next (full BFF)

Replace with OIDC-validated service, Postgres, and Proxmox/UniFi adapters per [SANKOFA_IT_OPERATIONS_CONTROLLER_SPEC.md](../../docs/02-architecture/SANKOFA_IT_OPERATIONS_CONTROLLER_SPEC.md).