Skip to main content

Crate audit_trail

Crate audit_trail 

Source
Expand description

§audit-trail

Tamper-evident audit logging via cryptographically chained records.

Every audited event becomes a Record capturing the canonical who / what / when / where / result tuple, together with the hash of the preceding record. Any modification to a past record breaks the chain at that point and is trivially detectable on re-verification.

§Public surface

  • Record — the audited event (5W + chain links).
  • Chain — the append-only chain that wires a Hasher, a Sink, and a Clock.
  • Hasher — pluggable hash function (SHA-256, BLAKE3, …).
  • Sink — pluggable backend that persists each record.
  • Clock — pluggable time source.
  • Verifier — replays a chain and proves it is untampered.
  • codec — stable binary record encoding (alloc feature).
  • FileSink / FileReader — append-only file persistence (std feature).

§Optional features

  • std (default) — enables std-dependent items (FileSink, FileReader) and std::error::Error impls. Implies alloc.
  • alloc — enables owned-record and in-memory sink types (OwnedRecord, MemorySink) plus the codec module for serialising records to bytes.
  • sha2 — enables the reference Sha256Hasher backed by the sha2 crate.
  • blake3 — enables the reference Blake3Hasher backed by the blake3 crate.

Without any optional features, the crate ships traits, the Chain, and the Verifier only — callers supply their own hasher, sink, and clock.

§Design principles

  • Zero-allocation hot path. Records borrow their string fields; the append path never touches the heap.
  • No async runtime dependency. The append API is synchronous.
  • no_std capable. Enable with default-features = false.

See .dev/ROADMAP.md for the path to 1.0.

§License

Dual-licensed under Apache-2.0 OR MIT.

Modules§

codecalloc
Stable binary codec for serialising audit records to bytes.

Structs§

Action
The verb of an audited event (the “what”).
Actor
The subject performing an audited action (the “who”).
Blake3Hasherblake3
BLAKE3 Hasher.
Chain
An append-only chain of audit records.
Digest
Fixed-size hash output.
FileReaderstd
Iterator that yields OwnedRecord values decoded from an audit log produced by crate::FileSink.
FileSinkstd
Append-only file-backed Sink.
MemorySinkalloc
In-memory Sink: appends every record into a Vec<OwnedRecord>.
OwnedRecordalloc
Owned counterpart to Record. Holds String-backed fields instead of borrowed &strs, so it can outlive the call that produced it.
Record
A single audited event in the chain.
RecordId
Monotonically-increasing identifier for an audit record.
Sha256Hashersha2
SHA-256 Hasher.
SystemClockstd
Wall-clock time source backed by std::time::SystemTime. Requires the std feature.
Target
The resource an audited action was performed on (the “where”).
Timestamp
A timestamp expressed as nanoseconds since the Unix epoch.
Verifier
Replays a chain of records and proves their hash linkage is intact.

Enums§

Error
Error categories produced by audit-trail.
Outcome
Outcome of an audited action (the “result”).
SinkError
Opaque error returned by crate::Sink implementations.

Constants§

HASH_LEN
Size, in bytes, of a hash output produced by a Hasher.
VERSION
Crate version string, populated by Cargo at build time.

Traits§

Clock
Pluggable time source for the audit chain.
Hasher
Pluggable hash function used to chain audit records.
Sink
A target that consumes audit records produced by a crate::Chain.

Type Aliases§

Result
Convenience Result type alias used throughout the crate.