feat(licence): CONSPECT-3 device proof-of-possession (PoP) on the heartbeat client (ADR-I007)

[aperim-agent]

CONSPECT-3 device proof-of-possession (PoP) on the heartbeat client (ADR-I007)

Why now (security-critical, broken in production): Conspect API v0.9.0 is enforcing device-PoP on the device-mutating ops. The merged renew-only heartbeat client (#177, account-JWT only, no PoP) is rejected pop-invalid, so leases can no longer renew. This wires device-PoP onto the heartbeat path.

Design recorded in ADR-I007.

What the wire requires (extracted byte-exact from /tmp/salvage/conspect-openapi.v0.9.0.json)

• GET /v0/devices/licence/challenge?orgId=… → DeviceChallenge{ nonce ^[0-9a-f]{64}$ single-use ~120 s, expiresAtMs }.
• HeartbeatRequest gains a required nonce; HeartbeatResponse gains nextNonce (RFC 9449 DPoP-nonce — steady-state needs no extra /challenge).
• Conspect-Device-PoP header = a base64 COSE_Sign1 (EdDSA) over the canonical pre-image htm | htu | sha256(body) | instance_id | nonce | iat, verified server-side against the stored device key (continuity); server checks iat ±60 s and burns the nonce.

Keypair finding (the renew-only #177 had no private key)

#177 dropped activate (where a keypair would be generated); it held only a configured public-key string. This PR adds device keypair generation + durable persistence at the cli boundary.

Implementation (split to respect the leaf-crate invariant)

• Leaf crate (multiview-licence, pure crypto, no I/O, no RNG): canonical_pop_preimage (hand-rolled deterministic CBOR, mirroring the proven canonical_key_preimage), a DeviceSigner seam, and pop_header_value building a standard untagged COSE_Sign1 via coset 0.4.2. The loop obtains the nonce (cold-start /challenge, steady-state nextNonce), serialises the body once (sent verbatim, so device + server hash byte-identical bodies), signs, sends the header, and remembers nextNonce. Ed25519 signing is deterministic (RFC 8032) so no RNG enters the leaf crate.
• cli boundary (multiview-cli/src/licence.rs): DeviceKeyStore generates-once + durably-persists (crash-durable, 0600) the Ed25519 device keypair beside the lease state, reloads on restart for a stable identity, fail-closed on a corrupt key (never silently regenerates a new identity). ConspectHttpServer implements fetch_challenge + the verbatim-body heartbeat with the PoP header. The PoP nonce is kept strictly separate from the durable idempotency FileNonceStore.
• Never off air (inv Bump actions/checkout from 4 to 6 #1/Bump vite from 6.4.3 to 8.0.16 in /web #10): every PoP failure (nonce expired/missing, /challenge unreachable, signing error, keypair unavailable, server pop-invalid) is a new fail-closed HeartbeatError::Pop — skip the cycle, keep last-good, back off, never panic, never tighten output. Proven by heartbeat_pop_loop.rs + the existing CONSPECT-2/3 chaos gate.

Dependency / licensing

coset is the only new crate (its ciborium/ciborium-io closure was already in-graph). Apache-2.0, deny-clean. cargo deny check → advisories ok, bans ok, licenses ok, sources ok.

Tests (RED → GREEN, committed separately)

• tests/heartbeat_pop.rs (6): the pre-image is byte-exact; the produced COSE_Sign1 self-verifies against the device public key over the exact pre-image; alg = EdDSA; a changed body changes the proof.
• tests/heartbeat_pop_loop.rs (6): cold-start fetches one challenge then heartbeats with a verified PoP; steady-state reuses nextNonce and skips the round-trip; unreachable /challenge, pop-invalid, and no-binding all keep last-good.
• licence.rs device-key tests (8): generate-once-reload, 0600 perms, verifiable signing, fail-closed on corrupt, + the 4 panel-fix tests below (0600-despite-broad-temp, weak-perm-fail-closed, concurrent-one-durable-winner, durable-round-trip).
• The existing 22 heartbeat_client tests pass with a bound test signer.

Update — Codex 3-lens panel majors fixed (head 1167c7fd)

The first panel BLOCKED on the CLI device-key file lifecycle (the devicePublicKey-on-heartbeat note was adjudicated a false positive — heartbeat carries only nonce per the spec/ADR; no wire change). Fixed, matching #177's proven crash-durable/atomic FileNonceStore protocol (a RED test per fix, committed separately):

1. Secret exposure — install_new uses a unique temp opened O_EXCL (create_new) + an explicit set_permissions(0600), so a pre-existing broad-perm device-key.tmp can't be reused and the final seed is always 0600.
2. Weak-perm key — load_existing stats the mode and fails closed on anything but 0600 (a world-readable 0644 signing secret is refused, never trusted).
3. Crash-durability — the parent-dir fsync Result is propagated (was swallowed), so a non-durable identity can't silently regenerate and break continuity.
4. Concurrent first-boot race — atomic create-once via hard_link to the final path: the winner persists durably, losers get AlreadyExists and reload the winner, so every returned signer's seed equals the one on disk.
5. (minor) fresh-nonce expiry — obtain_pop_nonce now expiry-checks a freshly-fetched /challenge nonce (not only a held one), failing closed instead of signing a doomed pop-invalid.

The leaf crate stays no-RNG/no-I/O; both --features heartbeat suites + the never-off-air chaos gate stay green.

Gate evidence

• cargo fmt --all -- --check → clean
• cargo clippy -p multiview-licence --features heartbeat --all-targets -D warnings → 0 (the fix(ffmpeg): bypass libswscale for identity NV12 scale (hw Defect A) #179 leg)
• cargo clippy -p multiview-cli --features heartbeat --all-targets -D warnings → 0
• cargo clippy --workspace --all-targets -D warnings → 0
• cargo test -p multiview-licence --features heartbeat → all green; cargo test -p multiview-cli --features heartbeat → all green (98 lib + integration)
• cargo deny check → ok

⚠️ Required rule-26 follow-up (NOT done here)

This implementation is spec-correct + unit-tested, NOT live-server-validated (no live Conspect account/server is available in this environment). The operator must validate the PoP against the live Conspect server. Load-bearing unknowns to confirm against the live server (the spec under-specifies them and its examples are unreliable — the DeviceChallenge example nonce is 65 chars, violating its own ^[0-9a-f]{64}$; the header example g1gg… is truncated):

1. the canonical pre-image byte-layout (we use a CBOR map(6) matching the house canonical_key_preimage style),
2. the iat unit (we use epoch seconds — inferred from the ±60 s leeway),
3. attached vs detached COSE payload (we attach the pre-image),
4. tagged vs untagged COSE_Sign1 (we emit untagged; tagging is a one-line to_tagged_vec() swap if required).
5. Device-key ↔ activate continuity: heartbeat verifies the proof against the key Conspect stored for this binding at the original activate. The loaded/generated DeviceKeyStore key MUST be that same registered key — the operator live-validates this. A fresh device with no activate-registered key will pop-invalid until the device-side activate slice lands (deferred, out of scope here per ADR-I007): activate is where this generated public key first reaches the server (as devicePublicKey) and its RFC 7638 thumbprint becomes the lease cnf_jkt. So this PR makes renewal spec-correct, but an end-to-end live renewal also depends on that registration path existing.

Do not merge until the 3-lens cross-vendor panel runs (auth/crypto = HIGH-risk) — per the operator's instruction.

🤖 Generated with Claude Code