Struct HashChain

pub struct HashChain { /* private fields */ }

A live hash chain: holds the root key and current head hash.

Cloning is cheap (Arc’d). Thread-safe via parking_lot::Mutex on the head and chain id (the latter so that Self::load_head_from_file can adopt the persisted id from a previous process invocation).

Implementations

impl HashChain

pub fn new(root_key: &[u8]) -> Self

Construct a new chain with the given root key and all-zero head. Call HashChain::load_head_from_file after construction to resume from an existing chain head persisted in the audit log.

pub fn resume(root_key: &[u8], head: [u8; 32], id: ChainId) -> Self

Resume from a known head hash. Use this when you have the head computed by HashChain::head from a previous session.

pub fn load_head_from_file(&self, path: &Path) -> Result<(), ChainLoadError>

Read the last record_hash (and the matching chain_id) from the audit log and use them as the current state. This lets a fresh process pick up where the last left off without breaking the chain’s identity (both head and id are restored). Tolerates: missing file, empty file, all-blank file. Corrupt JSON or a wrong-length hash in the last line is reported as Err so the caller can refuse to start (a silent reset would let the chain appear to verify while being disconnected from prior records).

pub fn id(&self) -> ChainId

Returns the chain id. If Self::load_head_from_file has been called and the file contained a chain_id, that id is returned; otherwise a fresh id is generated lazily on first call and cached.

pub fn adopt_id(&self, id: ChainId)

Adopt the chain id from an external source (e.g. a sidecar file persisted by crate::decision::DecisionLog). Idempotent: if an id has already been observed (loaded from the audit log or set explicitly), this is a no-op.

pub fn head(&self) -> [u8; 32]

pub fn set_head(&self, head: [u8; 32])

Set the current head. Use this to resume a chain from a previously serialized head hash (e.g. when starting a new process that wants to continue appending to an existing log).

pub fn append(&self, canonical_record: &[u8]) -> ([u8; 32], [u8; 32])

Append a record: returns (prev_hash, new_hash).

The canonical record bytes should be the canonical JSON serialization of the record (see crate::decision::canonical).

Thread-safe: the head read, HMAC computation, and head write happen inside a single critical section. Concurrent appenders serialize.

Note: this advances the in-memory head before the caller has persisted anything. If the caller’s persistence step fails, the chain is left one step ahead of the on-disk file. Callers that need an atomic “compute hash + persist” should use Self::try_append_with_io instead.

pub fn try_append_with_io<F, T>( &self, canonical_record: &[u8], persist: F, ) -> Result<T>

where F: FnOnce([u8; 32], [u8; 32]) -> Result<T>,

Atomic “compute hash + persist” for callers that hold an external lock (typically a file lock). The chain head is only advanced if the closure succeeds — so a failed write leaves the chain unchanged and a retry will produce the same hash.

Lock order: caller must hold the outer (file) lock before entering this method; we then take the chain head lock. The file lock is released by the caller, the chain head lock by this method’s return.

pub fn verify( &self, canonical_record: &[u8], claimed_prev: &[u8; 32], claimed_hash: &[u8; 32], ) -> Result<()>

Verify a single record’s hash matches what the chain would produce.

pub fn verify_chain( &self, records: &[(Vec<u8>, [u8; 32], [u8; 32])], ) -> Result<()>

Verify a full chain given the records. The first record’s prev_hash must equal [0; HASH_LEN]. The last record’s hash must equal the current head.

Trait Implementations

impl Clone for HashChain

fn clone(&self) -> HashChain

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HashChain

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.