# fleet-hostapi — workstation host-info agent

A tiny **read-only, loopback-only** Go HTTP service that runs on the diskless
workstation and reports facts about the machine the kiosk renders on. It is the
OS-side implementation of the contract in [`../../HOST-API.md`](../../HOST-API.md)
(authored alongside the kiosk-app SPA that consumes it).

```
GET http://localhost:9099/v1/host  ->  application/json   (os, hardware, net, kiosk, agent)
GET http://localhost:9099/healthz  ->  200 ok
```

## Properties (and why)

- **Loopback only.** Binds `127.0.0.1`; refuses to start on any routable address.
  Host facts must never reach the boot LAN.
- **Read only.** No endpoint mutates anything; it reads `/proc`, `/sys`,
  `/etc/os-release`, and the build-time facts file.
- **No per-host state baked in** (invariant #1). Host-specific fields (kernel,
  hostname, IP, MAC, board, uptime) are read at **runtime**. The only baked facts
  are image-generic — image version + weston/chromium versions — written to
  `/etc/fleet-hostinfo.json` by the build provisioner.
- **Stdlib only → reproducible build** (the verity hash is a security property).
  Built `CGO_ENABLED=0 -trimpath -buildvcs=false -ldflags=-buildid=`; identical
  bytes across builds with the same Go toolchain.
- **CORS + Private Network Access.** The SPA is cross-origin and the fetch is a
  Chromium private-network request, so responses carry
  `Access-Control-Allow-Private-Network: true`. The matching browser-side
  allowance is in `files/kiosk/chromium-kiosk-policy.json`
  (`InsecurePrivateNetworkRequestsAllowedForUrls`, scoped to the kiosk origin).

## Build / install

Done by the `2b-hostapi` provisioner in `diskless.pkr.hcl`: installs the Go
toolchain, builds the static binary to `/usr/local/bin/fleet-hostapi`, writes the
facts file, installs + enables `fleet-hostapi.service`, and adds the binary to
fapolicyd trust (2c-STIG-postfix). The toolchain is removed in 2d hygiene — only
the static binary ships.

Local build:

```bash
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -buildvcs=false \
  -ldflags '-s -w -buildid=' -o fleet-hostapi .
```

## Config (env, set in the unit)

| Var | Default | Notes |
|---|---|---|
| `FLEET_HOSTAPI_ADDR` | `127.0.0.1:9099` | must be loopback |
| `FLEET_HOSTAPI_ALLOW_ORIGIN` | `*` | tighten to the kiosk origin in prod |
| `FLEET_HOSTAPI_FACTS` | `/etc/fleet-hostinfo.json` | build-time facts |