FM-S08 — Spike: Proxmox client — typed crate versus reqwest transport

[Andreas-Froyland]

Epic: #9 · Blocks: M6 Proxmox accounts/TLS/discovery · type:spike

Question

Does the experimental proxmox-client crate (crates.io, landrzejewski/proxmox-client-rust) satisfy authentication, UPID task polling, custom TLS trust and pinning, unknown-field tolerance, and cancellation against PVE 8.x and 9.x — or does Fleet keep a small reqwest transport plus typed provider DTOs?

Evidence required

• Authentication: API-token auth against both PVE 8.x and 9.x; how credentials are supplied (secret-reference friendly, no env-var singleton).
• TLS: custom root trust and certificate fingerprint pinning without disabling verification anywhere; per-request control.
• UPID: task handle retrieval and polling with deadline/timeout semantics; does it expose cancellation and distinguish "unknown final state" from failure?
• Unknown-field tolerance: loose/null Perl JSON shapes (null vs missing, stringly-typed numbers) — does the typed surface error or tolerate?
• Endpoint coverage for the M6 epics: cluster resources, node/storage/template discovery, QEMU/LXC list/status, guest-agent network/OS data.
• Maintenance snapshot: release cadence, open issues, adoption, license, MSRV/dependency weight (does it drag the whole proxmox-rs workspace?).

Recorded fallback (from spikes.md)

Small reqwest transport plus typed provider DTOs, borrowing Purple's parsing patterns. Never accept invalid certificates as the production answer.

Acceptance criteria

• Evidence gathered against the question, on both PVE 8.x and 9.x if reachable (the integration VM's PVE host is available; recorded/simulated fixtures otherwise)
• Decision recorded in docs/planning/spikes.md with the rejected option named
• docs/research/ecosystem.md Proxmox section refreshed with current versions/commits
• If the crate is chosen: license checked against the inbound policy and pinned with a rationale

Non-goals

• Production provider code inside the spike (a disposable probe project outside the repository is the vehicle, as in FM-S01/FM-S05)
• Choosing M6's account model, permission vocabulary, or executor kinds

[Andreas-Froyland]

Spike executed; decision and evidence recorded in PR #98 (docs only, per spike rules).

Outcome summary

Fallback chosen: small reqwest transport + typed provider DTOs with a custom rustls fingerprint-pinning verifier.

Decisive failure (security gate, not a feature gap): proxmox-client 0.9.2's entire TLS surface is accept_invalid_certs(bool) (reqwest danger_accept_invalid_certs). The integration host presents PVE's own cluster CA, so system-trust verification fails and the crate's only working configurations are "disable verification" (forbidden by ADR-0005) or nothing. No pinning hook, no custom root store, no preconfigured-TLS passthrough.

Everything else passed — token auth, UPID status/log/stop (raw String UPID, Fleet parses), broad QEMU/LXC/cluster/storage coverage (incl. 26 guest-agent methods), and genuinely tolerant decoding (all-Option, envelope handles data: null, VmConfig flattens indexed params into extra).

The fallback was proven live against the PVE 9.2.2 host, both directions:

• a ServerCertVerifier that SHA-256-hashes the leaf certificate against the pinned fingerprint connected successfully, and
• a wrong fingerprint was refused at the TLS handshake.
  All on reqwest 0.12 + rustls ring — the TLS stack the tailscale provider already uses. No new transport dependency class, no duplicated reqwest major, no aws-lc-rs.

Supply chain, for the record: 3 commits ever, 3 releases in one week, zero stars, 591 downloads, one maintainer, one open issue. Secondary candidate proxmox-api 0.2.0 rejected faster (default client hardcodes danger_accept_invalid_certs(true); Debug prints the raw token).

• Evidence gathered against the question (live PVE 9.2; 8.x validated through fixtures later per the epic)
• Decision recorded in docs/planning/spikes.md with the rejected option named
• docs/research/ecosystem.md Proxmox section refreshed
• No crate adopted; license policy untouched