Split-attestation provenance: module declarations and daemon observations, never merged

Closed
IC
3mo ago
+2827-82

Implements the #58 disposition. Closes #58.

Modules self-report build facts at HELLO; the daemon independently observes process facts. The two travel as separate typed members and never merge — a module's declaration can be false, so it is never presented as something the daemon attested.

What's here

ModuleManifest.provenance — optional block, four optional fields: build_git_sha, build_lock_digest, wire_crate_version, store_schema_version. Absent is fine and stays fine: the module registers normally and reports unverifiable.

supervisor.provenance — new channel-0 op, whole-box or exact-module. Each entry carries module_declared (reported with the block, or unverifiable) and daemon_observed (pid, spawn time, exact spawned-from path, running-image evidence). The daemon's own identity rides in the same response, so one call answers "what is this daemon, and what is it supervising".

Spawn-fact capture — the supervisor retains pid, spawn timestamp, the exact program path it executed, and the spawn-time file identity, captured around spawn(). Provenance answers come from those captured facts, never from current configuration: a rescan can repoint config while the old process runs, and reading config would attest a path the child was never spawned from. Every exit path clears the facts through one helper.

Executable identity — on Linux, /proc/<pid>/exe and the captured spawned-from path are opened at read time and hashed through the open handles (never reopened after metadata, so the file can't be swapped between the stat and the hash). Digests are cached by (dev, inode, size, mtime), bounded at 64 entries. macOS compares spawn-time and current inode — deliberately weaker than a hash, and the response says which method produced the evidence. Elsewhere: typed unavailable. No failure path ever produces a placeholder digest.

ck provenance <module> — human output keeps source labels (MODULE-DECLARED / DAEMON-OBSERVED) so a declared value can't be read as an observed one; --json forwards the typed response unchanged.

What proves it

  • A stub HELLOs with forty fs as its build sha, plus distinct sentinels in the other three fields. The test asserts none of them appears anywhere in the daemon-observed record or the daemon's own identity. Mutation: routing a daemon field to read a declared value reddens it.
  • Linux executable replacement: spawn a copy, atomically replace it on disk, call provenance. /proc/<pid>/exe hashes the still-running old inode while the path hashes the replacement → Mismatch. This is the deploy-skew case as a regression test.
  • The CLI test asserts declared values are absent from the observed section, not merely present in the declared one — a renderer that duplicates a value into both sections fails it.
  • Rescan trap: updating configuration to a different program without restarting must not change spawned_from.

Wire compatibility

No breaks. The server.describe golden differs from master by one additive op-list entry; build_git_sha and build_lock_digest keys and values are byte-identical. The new manifest block adopts those same field names rather than introducing synonyms, so one vocabulary covers server.describe, the daemon record, and the module declaration. Ten golden fixtures total: five new, five regenerated op lists. TS client tests pass unchanged — it doesn't parse this op in this PR.

Declared values are untrusted input

They're module-controlled strings that reach an operator's terminal, so they're bounded at the daemon boundary — non-empty, ≤128 bytes, printable ASCII — and a manifest violating that is refused at HELLO. Absent and malformed are deliberately different outcomes. ck also escapes non-printable bytes at render, so a value from an older daemon can't emit control sequences into the terminal region where the daemon's verdict prints. Both halves are independently load-bearing (severing either reddens a different test).

Deliberately not here

No origin_delta, no buildable_at_head, no git, network, or deploy logic entered the daemon — verified mechanically: the only added dependency is sha2, and Cargo.lock gains no packages.

Two things for you to decide

1. CK_BUILD_REV vs SUBC_BUILD_GIT_SHA. Asked in #58 and unanswered, so the branch currently carries the rename. My disposition proposed "standardize CK_BUILD_REV" without checking that build.rs already emitted SUBC_BUILD_GIT_SHA for the same purpose — so what you approved was a rename, and that wasn't visible from what I wrote. It's self-contained (four sites, all in subc-core, cargo:rustc-env only, nothing in scripts or CI). I lean toward reverting to your existing names: it isn't load-bearing for #58 and it's diff noise in a PR you'll read for the attestation logic. Say the word and I'll revert it; the wire field names are unaffected either way.

2. The SDK helper has no first-party user. subc-client-rs::build_provenance is unit-tested but every in-tree module hardcodes provenance: None, so the "modules self-report" half is demonstrated only by the test stub. Wiring it into echo-module would make the reference module teach the feature, but that changes a reference module's behavior and wasn't in the plan, so I left it. Happy to add it here or as a follow-up.

Known gap, filed rather than fixed

Between wait() returning and the exit handler clearing spawn facts there's a scheduler-bounded window where a probe could read a recycled pid. Worst case is a false Match; exploiting it needs a hostile fork inside that window and a coincidental hash match. Closing it properly means widening the probe signature for a liveness gate, which didn't belong in this PR. I'll file it separately unless you'd rather have it here.

Verification

14 commits, each reviewed independently by a cross-family model at 0 blocking findings, plus a security review and two whole-branch passes. At the merge with master: fmt, clippy -D warnings, 742 tests, both fleet scripts, git diff --check, and bun test all pass. Gates were also run on the merge result, not just the branch — master moved 20 commits during the work and one of them touched fake-aft-stub.rs, which this PR also extends.


View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith with what you need. Autofix is disabled.