Skip to main content

historica_minisign/
lib.rs

1//! Signed claims that vouch for Historica revisions.
2//!
3//! Historica's decision 0046 — *who vouches for a revision* — observes that
4//! every revision document states an `author` and nothing checks it, and that
5//! the digest machinery answers *whether these are the bytes* while saying
6//! nothing about *whose word they are*. Its answer is that the trust layer is a
7//! separate tool writing more readable files, because a revision document
8//! cannot carry a signature over itself: its identity is the SHA-256 of its own
9//! bytes, and a document cannot contain a signature over a digest that depends
10//! on the signature.
11//!
12//! This is that tool. It writes two kinds of file and reads a third:
13//!
14//! - a **claim** ([`claim`]) in `history/claims/`, one key vouching for one
15//!   revision digest in one role at one moment — or for one file at that
16//!   revision, naming the file's content digest (decision 0004) — filed beside
17//!   the revision it vouches for ([`naming`]) and identified by the SHA-256 of
18//!   its own bytes rather than by what it is called;
19//! - its **signature**, minisign, detached, beside it;
20//! - the **trust policy** ([`trust`]) in `history/trust/`, one key to a file,
21//!   which says whose word this copy accepts and never crosses a store
22//!   boundary.
23//!
24//! Nothing here writes a Historica document, and Historica knows nothing about
25//! any of it beyond the promise 0046 extracted: a directory at the store root
26//! that Historica does not name belongs to whichever tool wrote it.
27//!
28//! # Verifying without signing
29//!
30//! [`verify`] is the half that must be cheap to depend on, so `sign` is a
31//! feature and `default-features = false` leaves a library that only ever
32//! reads. That is not hypothetical tidiness: 0046 defers *enforcement at
33//! receive* — a `receive` that refuses history no trusted key vouches for —
34//! and if that is ever built it must not drag key generation and a secret-key
35//! parser into a version-control core.
36//!
37//! # Checking a claim without this tool
38//!
39//! Two commands, and neither is Historica nor this crate:
40//!
41//! ```console
42//! $ minisign -Vm "2026-08-18 drop the private export — author.claim.txt" -P RWTd8LRC…
43//! $ shasum -a 256 history/revisions/2026-08/….rev.txt
44//! ```
45//!
46//! Decision 0002 requires that to keep working: what this crate writes is what
47//! the `minisign` command writes, and what the command writes is accepted here.
48
49#![forbid(unsafe_code)]
50#![deny(missing_docs)]
51
52pub mod claim;
53pub mod layout;
54pub mod naming;
55pub mod trust;
56pub mod verify;
57
58#[cfg(feature = "sign")]
59pub mod key;
60#[cfg(feature = "sign")]
61pub mod sign;
62
63pub use claim::{Claim, ClaimError, ContentDigest, Key, Role, Scope};
64pub use trust::Trust;
65pub use verify::{FileCheck, Finding, Report, Severity};