# REPORT — agent v0.19.0: bootstrap contract v2 (relay hub passphrase, no host key in guest) (2026-06-11)

> Overwrite-latest report. Cumulative history: [CHANGELOG.md](CHANGELOG.md).

Lockstep two-repo change with `felhom-controller` v0.40.0. Fixes the onboarding **401** found last
session: the agent used to bake its **host** hub key into the guest's `bootstrap.json`, but the hub's
`/api/v1/report` authenticates a **customer-scoped** key, so the controller could never report ONLINE.
The agent now bakes a **v2 bootstrap** carrying only what the controller needs to **pull** its own
config from the hub — the agent never touches the customer-scoped key or the CF tokens. Validated live
on the demo (guest 9201).

## What changed
- **`internal/provision/doc.go`** — `SchemaV1 → SchemaV2 = "felhom.bootstrap/v2"`. `DocCustomer` drops
  `name`/`domain`/`email` (keeps `id`); `DocHub` drops `api_key`/`host_id`, adds **`retrieval_password`**
  (SECRET); `DocLocalAPI` unchanged. Byte-compatible with the controller's `internal/bootstrap.Bootstrap`.
- **`internal/provision/backhalf.go`** — renders the v2 Doc; validation now requires `customer.id` +
  `hub.url` + `hub.retrieval_password` (was `customer.id` + `customer.domain`). Mint / 0600 write /
  `chown 100000:100000` / `pct set -mp9 …,ro=1` unchanged.
- **`cmd/felhom-agent/main.go` `--selftest=provision`** — **new required `-hub-password`** flag (the
  customer's hub retrieval passphrase; the customer must already exist in the hub). Stops baking
  `cfg.Hub.APIKey` / `cfg.Hub.HostID`. `-customer-domain/-name/-email` still accepted (bring-up may use
  them) but **not** baked into the v2 Doc. Success text updated (reboot → controller pulls + merges).
- **`configs/build-golden.sh`** — default `CONTROLLER_IMAGE` bumped off the stale `:v0.35.0` →
  `:0.40.0` (matches the registry's no-`v` tag convention; latent footgun fixed).

## Cross-repo contract checksum-diff (rendered bootstrap.json field set)
Agent renderer output ingested by the controller's `json.Unmarshal` — **every field populated**, exact:

| level | fields (agent emits == controller ingests) |
|---|---|
| top | `schema, customer, hub, local_api` |
| customer | `id` |
| hub | `url, retrieval_password` |
| local_api | `endpoint, fingerprint, token` |

## Tests — `internal/provision`, all green
- `doc_test.go`: pins the v2 key set — `customer:[id]`, `hub:[url, retrieval_password]` (asserts **no**
  `api_key`/`host_id`), `local_api:[endpoint, fingerprint, token]`; schema == `felhom.bootstrap/v2`.
- `backhalf_test.go`: asserts the rendered bootstrap has `Schema==SchemaV2`, `hub.url` +
  `hub.retrieval_password` (no host key), the per-guest token in `local_api`, 0600, chown to
  `100000:100000`, `pct set -mp9 …,ro=1`, and the token never leaks into the `Result`.

`go build ./... && go test ./...` green.

## Live validation (demo Proxmox `felhom-pve`)
- Agent **v0.19.0** built (`-X main.version=0.19.0`), streamed to the demo host (sha256-verified),
  installed at `/usr/local/bin/felhom-agent`, daemon restarted (`active`, `felhom-agent 0.19.0`).
- Golden re-baked with controller `:0.40.0` →
  `local:backup/vzdump-lxc-9100-2026_06_11-13_26_45.tar.zst` (baked image confirmed `:0.40.0`).
- `--selftest=provision -customer-id demo-felhom -hub-password <passphrase>` → guest 9201 brought up +
  bootstrap mounted. The written `bootstrap.json` (0600) has `customer:[id]`, `hub:[url,
  retrieval_password]` (**no host key**), `local_api:{endpoint,fingerprint,token}`. ✓
- After `pct reboot` the golden's baked unit deployed controller `:0.40.0`, which **pulled** its
  config from the hub (customer-scoped key `4b11c0c3…`) and merged in the per-guest `local_api`; the
  guest reported **ONLINE at v0.40.0** (no 401). The agent baked **no** customer secret beyond the
  per-guest local-API token (passphrase aside — see below). ✓
- 8C invariant unaffected: agent-direct `POST /disks/format` on data-bearing `/dev/sdb1` → **HTTP 403
  pending_signature**, disk untouched. ✓

## What broke / what's missing
- **Finding #1 still open (separate spec):** provisioning while the daemon runs leaves the new guest's
  local-API channel 401 until `systemctl restart felhom-agent` (the running daemon doesn't reload the
  freshly-minted token). Workaround applied; reproduced.
- **Passphrase-at-rest:** the retrieval passphrase rides in the guest's 0600 `bootstrap.json` (decision
  (d) — the agent relays it, never the customer key/CF tokens). Acceptable for now (single-customer
  scoped; matches the old `docker-setup.sh --hub-password` model); post-onboard hardening (detach mount
  / rotate) is a separate future item.
- Operational note: the UTF-8 (Hungarian) passphrase must be transported byte-exact (base64) to the
  provision call; a `kubectl cp` stderr line polluted the first capture and produced a garbage
  passphrase (re-extracted + re-provisioned cleanly).

## Versions / artifacts
- Agent **v0.19.0** (CHANGELOG updated). Pushed to `main`: commit `e5a1819` (code) — this REPORT in
  the follow-up commit. Lockstep controller **v0.40.0** (commit `6a594f9`). New golden volid above.
- No secrets committed (passphrase, customer key, CF tokens, local-api token — out-of-band/redacted).