Module sign 

Signed overlays (C-052, spec/threat-model.md §4).

Detached Ed25519 signatures over raw file bytes: <file>.sig sidecars naming the signing key (kid) plus the hex signature. Verification resolves kid against a trusted-keys set; enforcement hooks into include loading via ParseOptions (E032). Key files are bearer credentials (0600, never committed, never logged).

Structs

Sidecar

Parsed sidecar: the claiming key id plus the raw signature.

Functions

generate_secret_key

Generate a fresh secret seed from OS randomness.

load_secret_key

Parse a 64-hex-char Ed25519 secret seed (a <name>.secret file).

load_trusted_keys

Parse a trusted-keys TOML document ([[keys]] id/public) into an id-keyed map. Malformed entries are hard errors naming the entry, never key material.

public_hex

Hex of a verifying key (for the trusted-keys TOML).

read_sidecar

Read a sibling sidecar or report it missing (unsigned). Public so enforcement paths share the exact unsigned wording.

secret_hex

Hex of a signing key’s seed (for <name>.secret files).

sidecar_path_for

Sidecar path for a file: .sig appended to the full filename (foo.active ↔ foo.active.sig). Detached, so signatures survive formatters, and distinct from other tools’ habits.

sign_bytes

Sign raw bytes: the sidecar body for <file>.sig. The key id is validated first — raw interpolation into TOML would otherwise admit injection via quotes, escapes, or newlines.

valid_kid

Key-id charset: printable, no TOML metacharacters, no controls, non-empty. Enforced when writing sidecars, when parsing them, and when loading trusted sets — an id that cannot round-trip byte-identical through TOML is rejected everywhere (injection and log-forging resistance).

verify_bytes

Verify file bytes against sidecar text and a trusted-keys map. Returns the signing key id on success; every failure names the file and the reason, never key material.

verify_file

Verify a file on disk plus its sibling sidecar: point-in-time attestation for operators (TOCTOU between check and use is the caller’s concern). Enforcement paths that go on to PARSE the file must read once and call verify_bytes on the buffer instead — see the include hook.

Type Aliases

TrustedKeys

A trusted key set: key id → public key. Cloned into the parser when overlay enforcement is on (small maps; no lifetimes).