Module trust_roots

Expand description

Shared trust-roots TOML file model.

Three call sites read/write the same [[trust_root]] file format: mkit trust {add,list,remove} (commands/trust.rs), mkit verify --trusted/--trust-roots (commands/verify.rs), and mkit verify-attest --trust-roots (commands/verify_attest.rs). This module owns the parser, the writer, and the repo-local path-fencing policy so none of the three grow a second trust-file format (issue #693).

Grammar (a strict subset of TOML):

[[trust_root]]
keyid = "ed25519:..."
kind  = "ed25519"
pubkey_hex = "..."

kind is one of ed25519, secp256k1 (alias secp256k1-sec1), p256-sec1 (alias p256), or bls12381-thr. Anything else is ignored.
algorithm is accepted as an alias for kind (per docs/specs/SPEC-RELEASE-THRESHOLD.md); either field name works.
pubkey_hex is the raw public key bytes in lowercase hex. For bls12381-thr, the bytes are the 96-byte G2 compressed aggregated cohort public key (the MinSig variant).

Lines outside a [[trust_root]] block, comments (#), and blank lines are ignored. A missing file parses to zero entries — the caller’s documented “no trust-roots configured” UX.

Structs§

TrustEntry: One validated [[trust_root]] block: hex-decoded is deferred to the consumer (registry build / commit-signer compare) so callers that only need to list or rewrite the file never touch key bytes.

Functions§

default_trust_roots_path: Resolve the user-scoped default trust-roots path: $XDG_CONFIG_HOME/mkit/trust-roots.toml.
find_ed25519_signer: Does entries contain a live ed25519 trust root whose pubkey bytes equal signer? Used by mkit verify --trusted to cross-check a commit/remix/tag’s embedded signer field — commit signing is Ed25519-only today (issue #693 implementation notes).
hex_decode
keyid_matches_pubkey: Cross-check (#223) that keyid is consistent with the declared public key bytes. The canonical keyid shape is <prefix>:<body>:
load_entries: Load and parse the trust-roots file at path. A missing file parses to an empty list (not an error).
load_registry: Load the trust-roots file at path into an mkit-attest Registry, for DSSE attestation verification (mkit verify-attest).
note_if_missing: Print a hint (not an error) when a trust-roots path passed a safety check but the file doesn’t exist yet. An empty registry means every signer check will fail closed; the caller’s own report loop covers the substance, this is just so a first-time user isn’t left wondering why nothing verified.
parse: Parse every [[trust_root]] block in text. Blocks with missing keyid/pubkey_hex, unparsable hex, or a keyid/pubkey mismatch (#223) are dropped with a stderr note rather than surfaced as a hard error — matches verify-attest’s tolerant-parser policy.
save: Write entries to path, creating parent directories as needed.
serialize: Serialize entries back to the [[trust_root]] file grammar. Round-trips through parse (modulo comments — this rewrites the whole file, so any hand-added comments in a file mkit trust subsequently edits are NOT preserved).
short_keyid: Shorten a keyid for display: <prefix>:<first-16-hex>….
warn_if_unsafe_trust_roots: Refuse to operate on an in-repo trust-roots file unless the user passed --trust-roots explicitly. Without this gate, a hostile cloned repo could ship <repo>/.mkit/trust-roots.toml listing attacker keys and a trust-consuming command would trust it implicitly. See docs/THREAT-MODEL.md §5 “Trust-roots scope”.