felhom-agent/REPORT.md

felhom-agent — latest task report

This file holds the report for the most recent change, fully overwritten each task. Cumulative history lives in CHANGELOG.md.

Task: authz signed-op verifier (slice 2) — v0.2.0

Turned the Phase-4 reference VerifySignedOp into a production package (internal/authz): a key-type-agnostic SSHSIG verifier for operator-signed destructive ops, the full anti-replay/authorization pipeline, and a durable, crash-safe nonce store. This is what slice 4 (reconcile) calls to gate destructive desired-state deltas. Pushed to main. Build/vet/test green locally (Go 1.26) and on the build server.

Public surface (internal/authz)

• Verifier — New(signers []AllowedSigner, store NonceStore, hostID string) *Verifier; Verify(blob, sigArmored []byte) (*VerifiedOp, error). Optional ClockSkew (default 2m, not-yet-valid only) and Logger (advisory key_id-mismatch warning).
• OpBlob — canonical signed object; Target{HostID,GuestID} with corrected host_id/guest_id json tags; Params json.RawMessage, Nonce, IssuedAt, ExpiresAt, KeyID.
• VerifiedOp — Op, HostID, GuestID, Params, Nonce, IssuedAt, ExpiresAt, KeyID (advisory), Signer (matched), KeyIDMatchesSigner.
• AllowedSigner + NewAllowedSigner(keyID, role, authorizedKeyLine); roles RoleOperational / RoleRecovery (doc 04 two-key model; role-scoping enforced by the caller).
• NonceStore interface + MemoryNonceStore (tests) and FileNonceStore (durable).
• Typed errors: ErrMalformed, ErrNamespace, ErrUnknownSigner, ErrBadSignature, ErrTarget, ErrExpired, ErrNotYetValid, ErrReplay (errors.Is-friendly).
• Config: config.AuthzConfig (nonce-store path + pinned Signers).

Locked pipeline (order load-bearing)

parse armor → namespace (fixed felhom-op-v1) → parse pubkey → allow-list by key MATERIAL (not key_id) → crypto verify over RAW received bytes → parse blob → target (host strict, guest surfaced) → time window → nonce recorded LAST. Each post-crypto stage rejects even with a valid signature; an invalid signature can never consume a nonce.

Durable nonce store — mechanism & guarantee

fsync'd append-only JSONL log + in-memory index (replayed on open) + periodic compaction.

• Crash-safe: a nonce is written and fsync'd before SeenOrRecord returns false, so the caller acts only after the durable record. A crash between verify and execute drops the op (fail-safe) and never enables a replay. I/O failure → returns seen=true (op not executed).
• Survives restart: the log is replayed into the index on OpenFileNonceStore.
• Pruning: expired nonces dropped only at compaction (never before exp) — and an expired op is rejected by the time check before the nonce check, so pruning is housekeeping, not a hole.
• Concurrency-safe: single mutex over file handle + index.

OPEN choices

• Clock skew: 2-minute tolerance on not-yet-valid only; expiry not extended (window stays an honest bound).
• Durable mechanism: fsync'd append log + compaction (simple, honest, no embedded-KV dep).
• Fixtures: committed real ssh-keygen -Y sign vector (hermetic + proves OpenSSH interop) + in-Go minting for rejection cases; the sk case is synthetic (spec-faithful, no hardware).
• Package name: authz (control-plane-authorization layer, matches doc 04).

Test matrix (all pass — 14 tests)

Real ssh-keygen fixture · happy path · per-stage rejection {namespace, unknown-signer, tampered, retargeted-host, expired, not-yet-valid, replay} · invalid-sig-does-NOT-burn-nonce (then the valid op with that nonce still succeeds) · replay-rejected-across-restart (durable store) · key-type-agnostic synthetic sk-ssh-ed25519 · byte-exactness (re-serialized blob fails crypto).

Corrections to the Phase-4 §7 reference (for production)

• Target needed host_id/guest_id json tags — fixed.
• The doc's "Go 1.24.4 / x/crypto v0.52.0" does not hold: x/crypto v0.52.0 declares go 1.25.0 and won't build on Go 1.24. Resolved by upgrading the build server to go1.26.0 (backward-compatible — felhom-controller/hub build unchanged; distro Go package left intact, upstream Go fronted on PATH).
• Free function → constructed Verifier; returns full VerifiedOp; typed errors; clock-skew; durable nonce store (the net-new engineering).
• Shared-contract flag (not built): the hub and felhom-sign CLI must produce byte-identical canonical JSON or signatures won't verify; a shared canonicalizer both import is the right home.

Verification

• go build/vet/test green locally (go1.26.0) and on the build server (upgraded to go1.26.0).
• Real OpenSSH ssh-keygen (OpenSSH 10.0p2) minted the committed fixture and self-verified it before commit.

Repo state

• Branch: main only. Dep: golang.org/x/crypto v0.52.0 (+ x/sys indirect); go 1.25.0.