DEV Community: mroczect

libvctrl 2.0.0: A Stable, Production-Ready Version Control Foundation

mroczect — Mon, 10 Aug 2026 20:19:32 +0000

libvctrl

Overview

libvctrl is an all-in-one, batteries-included Software Development Kit for building custom version control systems. It aggregates three foundational layers -- contracts, reference implementations, and cryptography -- into a single coherent namespace, allowing developers to bootstrap a fully functional, content-addressable VCS backend without stitching multiple crates together manually.

The SDK applies the Facade Pattern: every essential type, trait, and implementation is re-exported at the crate root. A simple use libvctrl::*; grants access to the entire stack. Low-level cryptographic primitives are namespaced under the crypto module to prevent collision with the VCS-level Hash type.

Every crate in the stack enforces #![forbid(unsafe_code)], denies unwrap_used, expect_used, and panic at the compiler level, and passes clippy::pedantic plus clippy::nursery. The result is a memory-safe, panic-free, production-grade foundation.

Architecture

Three-Layer Design

The SDK is composed of three re-exported sub-crates, each with a distinct responsibility:

Layer	Crate	Module Alias	Responsibility
Contracts	`libvctrl_handler`	`handler`	Pure data types, behavior traits, error definitions, structural limits. Zero business logic.
Implementations	`libvctrl_core`	`reference`	Ready-to-use backends: in-memory store, binary codec, SHA-512 hasher adapter, object builders, validators.
Cryptography	`libvctrl_sha512`	`crypto`	Pure-Rust, `no_std`-compatible SHA-512, HMAC-SHA-512, HKDF-SHA-512.

Workspace Dependency Graph

graph TD
    subgraph Workspace["libvctrl workspace"]
        handler["libvctrl_handler<br/><b>Contracts</b><br/>types + traits + errors<br/>(no dependencies)"]
        sha512["libvctrl_sha512<br/><b>Cryptography</b><br/>SHA-512 / HMAC / HKDF<br/>(standalone, no_std)"]
        core["libvctrl_core<br/><b>Implementations</b><br/>stores + codec + hash + builders"]
        sdk["libvctrl<br/><b>SDK (this crate)</b><br/>facade re-exports"]
        plumbing["libvctrl_plumbing<br/>(low-level CLI,<br/>not yet implemented)"]
        porcelain["libvctrl_porcelain<br/>(high-level CLI,<br/>not yet implemented)"]
        docs["libvctrl_docs<br/>(documentation)"]
    end

    core -->|depends on| handler
    core -->|depends on| sha512
    sdk -->|re-exports| handler
    sdk -->|re-exports| core
    sdk -->|re-exports| sha512
    plumbing -.->|will depend on| handler
    porcelain -.->|will depend on| handler

    style sdk fill:#4a7c59,stroke:#2d4a33,color:#fff,stroke-width:3px
    style handler fill:#5b7daa,stroke:#3a5278,color:#fff
    style core fill:#7a5daa,stroke:#4a3d78,color:#fff
    style sha512 fill:#8a6d3b,stroke:#5c4928,color:#fff

Internal Module Architecture

The following diagram shows how the SDK's root-level re-exports map to the three sub-crates and their internal modules:

graph LR
    subgraph SDK["libvctrl (SDK root)"]
        direction TB
        root_types["Blob, Commit, Tree, Tag,<br/>Hash, UserID, EntryKind,<br/>CommitMeta, TreeEntry"]
        root_traits["Encoder, Decoder, Hasher,<br/>ObjectStore, RefStore,<br/>Signer, Transport, Verifier"]
        root_errors["VctrlError"]
        root_constants["HASH_LENGTH,<br/>MAX_BLOB_SIZE,<br/>MAX_MESSAGE_LENGTH,<br/>MAX_NAME_LENGTH,<br/>MAX_TREE_ENTRIES"]
        root_impl["BinaryEncoder, BinaryDecoder,<br/>Sha512Hasher, MemoryStore,<br/>MemoryRefStore"]
        root_builders["BlobBuilder, CommitBuilder,<br/>TagBuilder, TreeBuilder,<br/>TreeEntryBuilder"]
        root_validate["validate_hash_bytes,<br/>validate_name"]
        root_crypto["crypto::<br/>SHA-512, HMAC, HKDF"]
    end

    subgraph Handler["handler (libvctrl_handler)"]
        h_types["types"]
        h_traits["traits"]
        h_errors["errors"]
        h_constants["constants"]
        h_enums["enums"]
        h_macros["macros"]
    end

    subgraph Reference["reference (libvctrl_core)"]
        r_codec["codec"]
        r_hash["hash"]
        r_object["object"]
        r_store["store"]
        r_validate["validate"]
    end

    subgraph CryptoLib["crypto (libvctrl_sha512)"]
        c_hash["Hash"]
        c_hmac["Hmac"]
        c_hkdf["Hkdf"]
    end

    root_types --> h_types
    root_traits --> h_traits
    root_errors --> h_errors
    root_constants --> h_constants
    root_impl --> r_codec
    root_impl --> r_hash
    root_impl --> r_store
    root_builders --> r_object
    root_validate --> r_validate
    root_crypto --> c_hash
    root_crypto --> c_hmac
    root_crypto --> c_hkdf

Object Lifecycle and Data Flow

The following sequence diagram illustrates the complete lifecycle of a VCS object: construction via a builder, validation, encoding into the binary wire format, hashing for content-addressable identity, storage, and retrieval:

sequenceDiagram
    participant App as Application
    participant Builder as Object Builder
    participant Validate as validate module
    participant Encoder as BinaryEncoder
    participant Hasher as Sha512Hasher
    participant Store as MemoryStore

    rect rgb(230, 240, 230)
        Note over App,Builder: 1. CONSTRUCT
        App->>Builder: TreeBuilder::new().entry(...).build()
        Builder->>Validate: validate_name() for each entry
        Validate-->>Builder: Ok or VctrlError
        Builder-->>App: Tree (immutable)
    end

    rect rgb(230, 230, 245)
        Note over App,Encoder: 2. ENCODE
        App->>Encoder: encode_tree(&tree)
        Encoder-->>App: Vec&lt;u8&gt; (versioned binary payload)
    end

    rect rgb(245, 235, 220)
        Note over App,Hasher: 3. HASH
        App->>Hasher: hash(&encoded_bytes)
        Hasher-->>App: Hash (64-byte SHA-512 digest)
    end

    rect rgb(240, 230, 230)
        Note over App,Store: 4. STORE
        App->>Store: put(&hash, &data)
        Store-->>App: Ok(())
    end

    rect rgb(235, 235, 235)
        Note over App,Store: 5. RETRIEVE
        App->>Store: get(&hash)
        Store-->>App: Box&lt;dyn Read&gt;
        Note over App: BinaryDecoder.decode_*() restores original object
    end

Core Features

Contracts Layer (handler)

Immutable Domain Models -- Blob, Tree, Commit, Tag, Hash, UserID, TreeEntry, CommitMeta are strongly-typed, immutable value objects. Construction validates all invariants at the boundary.
Behavior Traits -- Encoder, Decoder, Hasher, ObjectStore, RefStore, Signer, Transport, Verifier define the interfaces that any concrete backend must implement.
Unified Error Type -- VctrlError is the single error enum returned by every fallible operation across the entire SDK.
Structural Limits -- HASH_LENGTH, MAX_BLOB_SIZE, MAX_MESSAGE_LENGTH, MAX_NAME_LENGTH, MAX_TREE_ENTRIES centralize all magic numbers. Every constructor, encoder, and decoder references these constants.
Logical Entry Kinds -- EntryKind (Blob, Executable, Symlink, Tree, Submodule) decouples object classification from raw filesystem mode bits.
Helper Macros -- vctrl_error_other! and similar macros simplify ergonomic error construction.

Implementations Layer (reference)

Binary Codec -- BinaryEncoder and BinaryDecoder implement a deterministic, versioned, little-endian wire format with length-prefixed variable-length fields. Full round-trip fidelity for all four object types.
Defensive Decoding -- BinaryDecoder is panic-free. Every slice access is bounds-checked. Malformed or truncated payloads return VctrlError::CorruptedData.
DoS-Resistant Allocation -- Before allocating memory for variable-length fields (blob data, commit messages, tag messages), the decoder validates the requested length against MAX_BLOB_SIZE, MAX_MESSAGE_LENGTH, and MAX_TREE_ENTRIES.
SHA-512 Content Addressing -- Sha512Hasher delegates to the audited, pure-Rust libvctrl_sha512 crate to produce 64-byte digests.
In-Memory Object Store -- MemoryStore implements ObjectStore with HashMap<Hash, Vec<u8>> for testing, simulation, and prototyping.
In-Memory Reference Store -- MemoryRefStore implements RefStore with a RefsIterator for managing named references (branches, tags) in RAM.
Fluent Object Builders -- BlobBuilder, CommitBuilder, TagBuilder, TreeBuilder, TreeEntryBuilder solve the telescoping constructor problem with a step-by-step fluent API. Validation is deferred to the .build() call.
Input Validation -- validate_hash_bytes enforces 64-byte length. validate_name enforces non-empty, length-limited, path-traversal-free identifiers.

Cryptography Layer (crypto)

SHA-512 -- Pure-Rust, no_std-compatible one-shot and incremental hashing.
HMAC-SHA-512 -- Hash-based Message Authentication Code for authenticated object integrity.
HKDF-SHA-512 -- HMAC-based Key Derivation Function for deriving session keys or object encryption keys.

Cross-Cutting Guarantees

Zero Unsafe -- #![forbid(unsafe_code)] across all crates.
No Panics -- unwrap_used, expect_used, and panic are denied at the compiler level in the SDK crate. The decoder and validators return Result for every fallible operation.
Strict Linting -- clippy::all, clippy::pedantic, clippy::nursery, clippy::cargo are all denied.
Wire Format Versioning -- Every serialized payload begins with a version byte (currently 2). Incompatible formats are rejected early, enabling future breaking changes without silent data corruption.

Technology Stack

Component	Technology	Version	Purpose
Language	Rust	Edition 2024, toolchain 1.85+	Primary implementation language
Contracts	`libvctrl_handler`	4.0.0	Trait definitions, domain types, errors, limits
Implementations	`libvctrl_core`	2.0.0	Reference backends (store, codec, hash, builders, validate)
Cryptography	`libvctrl_sha512`	2.0.0	SHA-512, HMAC-SHA-512, HKDF-SHA-512
Property Testing	`proptest`	1.11.0	Arbitrary generation and fuzz-style testing (dev-dependency)

Lint and Safety Configuration

[lints.rust]
unsafe_code = "forbid"
missing_docs = "deny"
rust_2018_idioms = "deny"
unreachable_pub = "deny"
unused_qualifications = "deny"

[lints.clippy]
all = "deny"
pedantic = "deny"
nursery = "deny"
cargo = "deny"
missing_const_for_fn = "deny"
redundant_clone = "deny"
unwrap_used = "deny"
expect_used = "deny"
panic = "deny"

Project Structure

Workspace Layout

libvctrl/
├── libvctrl/                  # SDK facade (this crate)
│   ├── src/
│   │   └── lib.rs             # Root re-exports, lint config, documentation
│   └── Cargo.tom
├── libvctrl_handler/          # Contracts: types, traits, errors
│   ├── src/
│   │   ├── constants.rs
│   │   ├── enums.rs
│   │   ├── errors.rs
│   │   ├── lib.rs
│   │   ├── macros.rs
│   │   ├── traits.rs
│   │   └── types.rs
│   └── Cargo.tom
├── libvctrl_core/             # Reference implementations
│   ├── src/
│   │   ├── codec/
│   │   │   ├── binary_decoder.rs
│   │   │   ├── binary_encoder.rs
│   │   │   └── mod.rs
│   │   ├── hash/
│   │   │   ├── mod.rs
│   │   │   └── sha512.rs
│   │   ├── object/
│   │   │   ├── blob.rs
│   │   │   ├── commit.rs
│   │   │   ├── mod.rs
│   │   │   ├── tag.rs
│   │   │   └── tree.rs
│   │   ├── store/
│   │   │   ├── memory.rs
│   │   │   ├── mod.rs
│   │   │   └── ref_store.rs
│   │   ├── validate/
│   │   │   ├── hash.rs
│   │   │   ├── mod.rs
│   │   │   └── name.rs
│   │   └── lib.rs
│   └── Cargo.tom
├── libvctrl_sha512/           # Cryptographic primitives
│   ├── src/
│   │   └── ...
│   └── Cargo.tom
├── libvctrl_plumbing/         # Low-level CLI (not yet implemented)
├── libvctrl_porcelain/        # High-level CLI (not yet implemented)
├── libvctrl_docs/             # Documentation assets
└── Cargo.tom                  # Workspace root

SDK Crate Internal Structure

libvctrl/src/
└── lib.rs         # All re-exports, module declarations, and crate-level documentation

The SDK crate is intentionally minimal at the source level. Its sole purpose is to orchestrate re-exports and enforce the unified namespace. All logic lives in the three dependency crates.

Getting Started

Prerequisites

Rust toolchain -- Stable Rust 1.85 or later. Edition 2024 is required.
Cargo -- Included with the Rust toolchain.
Internet access to crates.io -- For resolving dependencies during the initial build.

Install or update the toolchain:

rustup install stable
rustup default stable
rustup update stable

Verify the version:

rustc --version
# Expected: rustc 1.85.0 or later

Installation

As a Dependency (crates.io)

Add libvctrl to your project's Cargo.toml:

[dependencies]
libvctrl = "1.0"

From Source (Workspace)

Clone the repository and build the entire workspace:

git clone https://github.com/mroczect/libvctrl.git
cd libvctrl
cargo build

Build only the SDK crate:

cargo build -p libvctrl

Configuration

Feature Flags

Feature	Default	Description
`sha384`	Enabled	Enables SHA-384 support via `libvctrl_sha512/sha384`. Truncates SHA-512 to 384 bits for applications that prefer shorter digests.
`opt_size`	Disabled	Optimizes the `libvctrl_sha512` crate for binary size rather than speed. Useful for WASM or embedded targets.

To disable the default SHA-384 feature:

[dependencies]
libvctrl = { version = "1.0", default-features = false }

To enable size optimization:

[dependencies]
libvctrl = { version = "1.0", features = ["opt_size"] }

Structural Limits

These constants are defined in libvctrl_handler and are referenced throughout the SDK. They cannot be changed at runtime but serve as documentation for system capacity:

Constant	Value	Purpose
`HASH_LENGTH`	64	Expected byte length of a `Hash` digest (SHA-512 = 64 bytes)
`MAX_BLOB_SIZE`	(defined in handler)	Maximum blob data size in bytes. Decoders reject larger blobs.
`MAX_MESSAGE_LENGTH`	(defined in handler)	Maximum commit/tag message length in bytes.
`MAX_NAME_LENGTH`	(defined in handler)	Maximum identifier name length in bytes.
`MAX_TREE_ENTRIES`	(defined in handler)	Maximum number of entries in a single `Tree` object.

Usage

Importing the SDK

The facade design allows two import styles:

Wildcard import (recommended for application code):

use libvctrl::*;

Targeted imports (recommended for library code):

use libvctrl::{Blob, TreeBuilder, BinaryEncoder, Sha512Hasher, MemoryStore, Encoder, Hasher};

Building and Encoding a Blob

use libvctrl::{BlobBuilder, BinaryEncoder, Encoder};

let blob = BlobBuilder::new(b"file content".to_vec()).build();
let encoder = BinaryEncoder;
let bytes = encoder.encode_blob(&blob)?;

Building a Tree with Entries

use libvctrl::{
    EntryKind, Hash, TreeBuilder, TreeEntryBuilder,
    BinaryEncoder, Sha512Hasher, Encoder, Hasher,
};

let blob_hash = Hash::from_bytes(&[0xAB; 64])?;

let entry = TreeEntryBuilder::new(
    "src/main.rs".to_string(),
    EntryKind::Blob,
    blob_hash,
).build()?;

let tree = TreeBuilder::new().entry(entry).build()?;

let encoded = BinaryEncoder.encode_tree(&tree)?;
let tree_hash = Sha512Hasher.hash(&encoded);

Building a Commit

use libvctrl::{CommitBuilder, Hash, UserID, EntryKind, TreeBuilder, TreeEntryBuilder};

let tree_hash = Hash::from_bytes(&[0x00; 64])?;
let author = UserID::new("Alice".to_string(), "alice@example.com".to_string())?;

let commit = CommitBuilder::new(tree_hash, author.clone(), author, "Initial commit".to_string())
    .build()?;

let encoded = BinaryEncoder.encode_commit(&commit)?;

Building a Tag

use libvctrl::{TagBuilder, Hash, UserID};

let target = Hash::from_bytes(&[0xFF; 64])?;
let tagger = UserID::new("Bob".to_string(), "bob@example.com".to_string())?;

let tag = TagBuilder::new("v1.0.0".to_string(), target, "Release 1.0.0".to_string())
    .tagger(tagger)
    .build()?;

Full Lifecycle: Build, Encode, Hash, Store, Retrieve

use libvctrl::{
    EntryKind, Hash, TreeBuilder, TreeEntryBuilder,
    BinaryEncoder, BinaryDecoder, Sha512Hasher,
    MemoryStore, Encoder, Decoder, Hasher, ObjectStore, VctrlError,
};
use std::io::Read;

// 1. Build a Tree containing a single file entry
let blob_hash = Hash::from_bytes(&[0xAB; 64])?;
let entry = TreeEntryBuilder::new("file.txt".to_string(), EntryKind::Blob, blob_hash).build()?;
let tree = TreeBuilder::new().entry(entry).build()?;

// 2. Encode the Tree into binary format
let encoder = BinaryEncoder;
let encoded_bytes = encoder.encode_tree(&tree)?;

// 3. Hash the encoded bytes to get a content-addressable identifier
let hasher = Sha512Hasher;
let tree_hash = hasher.hash(&encoded_bytes);

// 4. Store the encoded object
let mut store = MemoryStore::new();
store.put(&tree_hash, &encoded_bytes)?;

// 5. Retrieve and verify
assert!(store.exists(&tree_hash)?);
let mut reader = store.get(&tree_hash)?;
let mut buf = Vec::new();
reader.read_to_end(&mut buf).map_err(VctrlError::IoError)?;
assert_eq!(buf, encoded_bytes);

// 6. Decode back to the original object
let decoder = BinaryDecoder;
let decoded_tree = decoder.decode_tree(&buf)?;
assert_eq!(decoded_tree, tree);

Using the Reference Store

use libvctrl::{MemoryRefStore, Hash, RefStore};

let ref_store = MemoryRefStore::new();
let commit_hash = Hash::from_bytes(&[0x42; 64])?;

// Set a branch reference
ref_store.set("refs/heads/main", &commit_hash)?;

// Resolve it later
let resolved = ref_store.resolve("refs/heads/main")?;
assert_eq!(resolved, commit_hash);

Validating Inputs

use libvctrl::{validate_name, validate_hash_bytes, VctrlError};

// Valid names
assert!(validate_name("src/main.rs").is_ok());
assert!(validate_name("README.md").is_ok());

// Path traversal attacks are rejected
assert!(validate_name("../../etc/passwd").is_err());
assert!(validate_name("..").is_err());

// Hash validation
let valid_hash_bytes = [0u8; 64];
assert!(validate_hash_bytes(&valid_hash_bytes).is_ok());

// Wrong length is rejected
assert!(validate_hash_bytes(&[0u8; 32]).is_err());

Accessing Cryptographic Primitives

The crypto module provides low-level access to SHA-512, HMAC, and HKDF, isolated from the VCS-level Hash type:

use libvctrl::crypto;

// One-shot SHA-512 hash
let digest = crypto::Hash::hash(b"message");
assert_eq!(digest.as_bytes().len(), 64);

// Incremental SHA-512
let mut state = crypto::Hash::new();
state.update(b"chunk 1");
state.update(b"chunk 2");
let digest = state.finalize();

API Reference

Root-Level Re-exports

The following table lists every public item available at the libvctrl:: root namespace:

Types (from handler)

Item	Kind	Description
`Blob`	Struct	Immutable content-addressable file data object
`Tree`	Struct	Immutable directory listing of `TreeEntry` objects
`TreeEntry`	Struct	Named, typed pointer to a child object (file or subtree)
`Commit`	Struct	Immutable snapshot metadata: tree, parents, author, committer, message
`CommitMeta`	Struct	Timestamp, timezone offset, optional encoding
`Tag`	Struct	Immutable named pointer to a target object with optional tagger
`Hash`	Struct	64-byte cryptographic digest wrapper (content-addressable identifier)
`UserID`	Struct	Name + email identity (author, committer, tagger)
`EntryKind`	Enum	Blob, Executable, Symlink, Tree, Submodule

Traits (from handler)

Item	Description
`Encoder`	Serialize VCS objects into bytes
`Decoder`	Deserialize VCS objects from bytes
`Hasher`	Compute content-addressable `Hash` values
`ObjectStore`	Persist and retrieve raw serialized objects by `Hash`
`RefStore`	Manage named references (branches, tags) pointing to `Hash` values
`Signer`	Cryptographically sign objects
`Verifier`	Verify cryptographic signatures
`Transport`	Push/pull objects to/from remote stores

Implementations (from reference)

Item	Trait Implemented	Description
`BinaryEncoder`	`Encoder`	Versioned, little-endian, length-prefixed binary serialization
`BinaryDecoder`	`Decoder`	Panic-free, bounds-checked binary deserialization
`Sha512Hasher`	`Hasher`	SHA-512 digest adapter bridging `libvctrl_sha512`
`MemoryStore`	`ObjectStore`	In-memory `HashMap`-backed object storage
`MemoryRefStore`	`RefStore`	In-memory named reference storage

Builders (from reference)

Item	Target Type	Description
`BlobBuilder`	`Blob`	Fluent builder for blob data
`TreeBuilder`	`Tree`	Accumulates `TreeEntry` objects, finalizes into immutable `Tree`
`TreeEntryBuilder`	`TreeEntry`	Assembles name + kind + hash, defers validation to `build()`
`CommitBuilder`	`Commit`	Step-by-step configuration of tree, parents, author, committer, message, metadata
`TagBuilder`	`Tag`	Step-by-step configuration of name, target, tagger, message, metadata

Validators (from reference)

Item	Signature	Description
`validate_hash_bytes`	`(&[u8]) -> Result<(), VctrlError>`	Ensures slice is exactly 64 bytes
`validate_name`	`(&str) -> Result<(), VctrlError>`	Ensures non-empty, within length limit, no path traversal

Error and Constants

Item	Description
`VctrlError`	Unified error enum for all fallible operations
`HASH_LENGTH`	Expected hash byte length (64)
`MAX_BLOB_SIZE`	Maximum blob data size
`MAX_MESSAGE_LENGTH`	Maximum commit/tag message length
`MAX_NAME_LENGTH`	Maximum identifier name length
`MAX_TREE_ENTRIES`	Maximum entries per Tree

Sub-Modules

Module	Source Crate	Description
`handler`	`libvctrl_handler`	Direct access to the contracts layer
`reference`	`libvctrl_core`	Direct access to the implementations layer
`crypto`	`libvctrl_sha512`	SHA-512, HMAC-SHA-512, HKDF-SHA-512 primitives
`codec`	`libvctrl_core::codec`	Binary encoder/decoder modules
`object`	`libvctrl_core::object`	Object builder modules
`store`	`libvctrl_core::store`	Storage backend modules
`validate`	`libvctrl_core::validate`	Validation utility modules
`constants`	`libvctrl_handler::constants`	System-wide limit constants
`enums`	`libvctrl_handler::enums`	Logical type enumerations
`errors`	`libvctrl_handler::errors`	Error type definitions
`macros`	`libvctrl_handler::macros`	Helper macros
`traits`	`libvctrl_handler::traits`	Behavior trait definitions
`types`	`libvctrl_handler::types`	Domain model type definitions

BinaryEncoder Method Reference

Method	Input	Wire Format
`encode_blob`	`&Blob`	`VERSION(1B) + data_len(8B u64 LE) + data`
`encode_tree`	`&Tree`	`VERSION(1B) + entry_count(4B u32 LE) + [entries]`
`encode_commit`	`&Commit`	`VERSION(1B) + tree_hash(64B) + parent_count(1B) + parents + author + committer + msg + metadata`
`encode_tag`	`&Tag`	`VERSION(1B) + name + target_hash(64B) + tagger? + msg + metadata`

BinaryDecoder Method Reference

Method	Input	Error Conditions
`decode_blob`	`&[u8]`	Empty data, version mismatch, truncated length prefix, blob exceeds `MAX_BLOB_SIZE`, length mismatch
`decode_tree`	`&[u8]`	Truncated data, version mismatch, entry count exceeds `MAX_TREE_ENTRIES`, invalid UTF-8, malformed hash
`decode_commit`	`&[u8]`	Truncated data, version mismatch, message exceeds `MAX_MESSAGE_LENGTH`, invalid UTF-8 in any string field
`decode_tag`	`&[u8]`	Truncated data, version mismatch, invalid tagger presence byte, invalid UTF-8, message exceeds limit

Sha512Hasher Method Reference

Method	Input	Output
`hash`	`&[u8]`	`Hash` (64-byte SHA-512 digest)

MemoryStore Method Reference

Method	Description
`new()`	Creates an empty in-memory store
`put(&Hash, &mut dyn Read)`	Stores serialized object data under the given hash
`get(&Hash)`	Retrieves a `Box<dyn Read>` for the object
`exists(&Hash)`	Checks whether an object is present
`remove(&Hash)`	Removes an object from the store

MemoryRefStore Method Reference

Method	Description
`new()`	Creates an empty reference store
`resolve(&str)`	Resolves a reference name to its `Hash`
`set(&str, &Hash)`	Sets a reference name to point to a hash
`iter()`	Returns a `RefsIterator` over all stored references

Binary Wire Format Specification

All payloads share a common structure: a leading version byte followed by type-specific fields. All multi-byte integers are little-endian. Variable-length data is length-prefixed. The current wire format version is 2.

Blob

Offset  Size    Field
0       1       VERSION (u8, value = 2)
1       8       data_len (u64 LE)
9       N       data (N = data_len bytes)

Total size: 9 + data_len bytes.

Tree

Offset  Size    Field
0       1       VERSION (u8, value = 2)
1       4       entry_count (u32 LE)
5       ...     entries (repeated entry_count times):
                  +0      1       name_len (u8)
                  +1      N       name (UTF-8, N = name_len)
                  +1+N    1       kind (0=Blob, 1=Executable, 2=Symlink, 3=Tree, 4=Submodule)
                  +2+N    64      hash (raw SHA-512 bytes)

Entry size: 1 + name_len + 1 + 64 bytes each.

Commit

Offset  Size    Field
0       1       VERSION (u8, value = 2)
1       64      tree_hash
65      1       parent_count (u8)
66      P*64    parent_hashes (P = parent_count)
..      1       author_name_len (u8)
..      N       author_name (UTF-8)
..      1       author_email_len (u8)
..      N       author_email (UTF-8)
..      1       committer_name_len (u8)
..      N       committer_name (UTF-8)
..      1       committer_email_len (u8)
..      N       committer_email (UTF-8)
..      4       msg_len (u32 LE)
..      N       message (UTF-8)
..      8       timestamp (i64 LE, Unix epoch seconds)
..      2       timezone_offset (i16 LE, minutes from UTC)
..      1       encoding_len (u8)
..      N       encoding (UTF-8; 0 means None)

Tag

Offset  Size    Field
0       1       VERSION (u8, value = 2)
1       1       name_len (u8)
2       N       name (UTF-8)
..      64      target_hash
..      1       has_tagger (u8: 0 = absent, 1 = present)
..      [if has_tagger == 1:]
            1       tagger_name_len (u8)
            N       tagger_name (UTF-8)
            1       tagger_email_len (u8)
            N       tagger_email (UTF-8)
..      4       msg_len (u32 LE)
..      N       message (UTF-8)
..      8       timestamp (i64 LE)
..      2       timezone_offset (i16 LE)
..      1       encoding_len (u8)
..      N       encoding (UTF-8; 0 means None)

Testing

Running Tests

# Run all tests across the workspace
cargo test

# Run tests for the SDK crate only
cargo test -p libvctrl

# Run tests with verbose output per test
cargo test -p libvctrl -- --nocapture

# Run only round-trip encode/decode tests
cargo test -p libvctrl round_trip

# Run property-based tests (proptest)
cargo test -p libvctrl proptest

Test Coverage Areas

Category	What Is Tested
Encode/decode round-trips	All four object types: `Blob`, `Tree`, `Commit`, `Tag` -- encoded then decoded must equal the original
Corrupted data rejection	Truncated payloads, wrong version bytes, invalid UTF-8 sequences, malformed hashes
DoS limit enforcement	Blobs exceeding `MAX_BLOB_SIZE`, messages exceeding `MAX_MESSAGE_LENGTH`, trees exceeding `MAX_TREE_ENTRIES`
Validation edge cases	Empty names, overly long names, path traversal sequences (`..`, `/`), incorrect hash lengths
Store operations	`put`/`get` round-trips in `MemoryStore`, `exists` checks, reference resolution in `MemoryRefStore`
Builder validation	Missing required fields, invalid field values, type invariants enforced at `build()`
Property tests	`proptest`-driven fuzzing with arbitrary byte sequences, random name strings, random entry counts

Contributing

Contributions are welcome. All contributions must meet the following standards before merge.

Code Quality Requirements

No unsafe code. The crate forbids it at the compiler level. Do not attempt to add unsafe blocks.
No panics. unwrap_used, expect_used, and panic are denied. All fallible operations must return Result.
Clippy compliance. All contributions must pass cargo clippy -- -D warnings with clippy::pedantic, clippy::nursery, and clippy::cargo enabled.
Documentation. Every public item must have a doc comment explaining its purpose, design rationale, and error conditions. Module-level docs must include at least one code example.
Tests. Every new feature or bug fix must include tests covering both the happy path and all relevant failure modes.
Format. Run cargo fmt before committing. CI rejects unformatted code.

Architectural Requirements

Wire format stability. Changes to the binary wire format must bump the VERSION constant in both binary_encoder.rs and binary_decoder.rs. Never change the encoding of an existing version.
Contract stability. Changes to trait signatures in libvctrl_handler are breaking changes and require a major version bump. Update libvctrl_core and libvctrl together.
Facade consistency. Every new public item in a sub-crate that is intended for general use must be re-exported at the libvctrl root. Keep the root namespace ergonomic.

Local CI Checklist

Run the following before opening a pull request:

# Format check
cargo fmt --check

# Lint (workspace-wide)
cargo clippy -- -D warnings

# Test (workspace-wide)
cargo test

# Documentation build (check for broken doc links)
cargo doc --no-deps

# Individual crate checks (if modifying a specific crate)
cargo fmt --check -p libvctrl
cargo clippy -p libvctrl -- -D warnings
cargo test -p libvctrl
cargo doc -p libvctrl --no-deps

Future Feature Flags (Guidance)

When adding feature flags in the future, follow these conventions:

Hash algorithm flags (e.g., sha512, blake3) should gate the corresponding hasher implementation and its dependency. The Sha512Hasher re-export should be conditional on the sha512 feature.
Store backend flags (e.g., memory-store, fs-store) should gate the corresponding store implementation. The MemoryStore re-export should be conditional on memory-store.
no_std flag should gate off all std-dependent modules (stores, std::io) and retain only the codec and hash modules that can operate without allocation.

License

This project is licensed under the MIT License.

Repository: https://github.com/mroczect/libvctrl

Documentation: https://docs.rs/libvctrl

Introducing librage: A Safe, Simple, and Uniform Rust Wrapper for Age Encryption

mroczect — Thu, 06 Aug 2026 13:29:16 +0000

Introducing librage: A Safe, Simple, and Uniform Rust Wrapper for Age Encryption

Modern applications need encryption that is fast, secure, and easy to integrate. The age format delivers the cryptography, and rage provides a superb Rust implementation. But the raw rage API, while powerful, can feel low‑level when all you want is a straightforward encrypt‑this / decrypt‑that interface with no surprises. That’s where librage steps in.

librage is a thin, idiomatic Rust wrapper around rage that gives every operation a uniform response envelope (LibrageResponse<T>), automatically zeroizes all sensitive material, and exposes the full power of age without requiring you to juggle error types or boxed trait objects manually. It even works with streaming, SSH keys, and ASCII‑armoured output right out of the box.

In this post I’ll explain why I built librage, how it makes your life easier, and how you can start encrypting in three lines of code.

The Problem: Great Library, Unfriendly API

The rage crate is undoubtedly well‑designed. But using it directly often means:

Manually parsing key strings into x25519::Recipient or ssh::Identity.
Boxing trait objects for identities and recipients.
Handling diverse error variants (EncryptError, DecryptError, ParseRecipientKeyError) and mapping them into your application’s error model.
Remembering to zeroize plaintext and secrets yourself.

I found myself writing the same boilerplate in every project: key parsing, error conversion, zeroize wrappers, and a custom result type that could speak JSON. librage consolidates all of that into one ergonomic crate.

Uniform API: Everything Returns `LibrageResponse<T>`

The central design decision is that every public function returns a LibrageResponse<T>:

pub struct LibrageResponse<T: Serialize> {
    pub success: bool,
    pub data: Option<T>,
    pub error: Option<ErrorBody>,
}

If the call succeeds, success is true and data contains the result. If it fails, success is false and error holds a machine‑readable error code (INVALID_PUBLIC_KEY, DECRYPTION_FAILED, etc.) and a human‑readable message. A simple .to_json() call gives you a ready‑to‑send JSON string—perfect for APIs, CLIs, or FFI.

Feature‑Rich, Minimalist Surface

librage exposes everything you need, and nothing you don’t:

X25519 keys: generate keypairs, encrypt/decrypt with one or multiple recipients.
Passphrase (scrypt): encrypt with a passphrase—no keys to manage.
SSH keys: encrypt to an SSH public key, decrypt with the corresponding private key (passphrase‑protected keys supported).
Tag & tagpq recipients: full support for the age tagging mechanism.
Streaming: incremental encryption and decryption for large files or network streams.
ASCII armour: opt‑in PEM encoding for safe transport over text channels.
File utilities: read recipients and identities from files, including multi‑line SSH private keys, ignoring comments and blank lines.
Zeroize by default: secret keys (KeyGenData::secret_key), ciphertexts, and plaintexts are all wrapped in Zeroizing and automatically wiped on drop.
Clean error model: LibrageError implements std::error::Error and transparently converts from all relevant rage error types.

No need to box identities yourself—librage handles it internally. You just pass &str keys or slices.

Quick Example: From Keygen to Decrypted Text

use librage::*;

// Generate a new X25519 keypair
let res = generate_keypair();
assert!(res.success);
let kp = res.data.unwrap();

// Encrypt some bytes
let plaintext = b"Hello, librage!";
let enc = encrypt(plaintext, &kp.public_key).unwrap();
println!("Ciphertext: {}", enc.data.as_string()); // hex or PEM

// Decrypt it back
let dec = decrypt(&enc.data.ciphertext, &kp.secret_key).unwrap();
assert_eq!(dec.data.as_bytes(), plaintext);

The same pattern holds for passphrase encryption, SSH, and streaming—just swap encrypt for encrypt_with_passphrase, encrypt_with_ssh, etc. Every function returns the same LibrageResponse, so error handling stays consistent.

Security Without Headaches

I baked several safety measures directly into the library:

Zeroization – KeyGenData::secret_key is Zeroizing<String>. When the struct is dropped, the memory is overwritten. Similarly, EncryptOutput and DecryptOutput use Zeroizing<Vec<u8>> for ciphertext and plaintext.
No hidden panics – all fallible operations propagate LibrageError. The library never calls unwrap() or expect() on user‑facing code paths.
Delegation to rage – cryptographic operations are left entirely to the well‑audited rage crate; librage only smoothes the interface.
Passphrase‑handling notes – functions that accept a &str passphrase do not zeroize the original input (Rust strings are immutable); for long‑lived secrets, consider using SecretString externally. The documentation is explicit about this.

Who Should Use librage?

Backend services that need to encrypt payloads or tokens before storing them.
CLI tools that want a JSON‑based interface for key management and encryption.
Desktop or mobile apps (via Rust bindings) that require secure local storage.
Developers learning age who want a gentle, high‑level introduction without sacrificing access to the full feature set.
Anyone who’s tired of re‑implementing the same error mapping and zeroize wrappers.

Because librage re‑exports the underlying age types where needed (e.g., Box<dyn age::Identity> for advanced use), you can still drop down to the raw rage API if you ever need to.

What’s Next?

The library is feature‑complete and ready for production. Potential future additions include:

A dedicated EncryptOutput/DecryptOutput to‑file helpers.
Integration with the secrecy crate for even stricter passphrase handling.
WASM support for browser‑based applications.

Contributions are welcome! The code is MIT licensed and lives on GitHub:

github.com/mroczect/librage

If you need encryption that’s secure by design and simple by choice, give librage a try. It removes the ceremony so you can focus on your application’s logic. I’d love to hear your feedback or see what you build with it—drop a comment or open an issue on the repo!

Introducing age-credentials: A Backend‑Agnostic Account Engine for the Age Encryption Era

mroczect — Thu, 06 Aug 2026 13:26:18 +0000

Introducing age-credentials: A Backend‑Agnostic Account Engine for the Age Encryption Era

Managing user accounts and their cryptographic keys is one of the most critical parts of any secure application. Yet, many solutions either tie you to a specific storage backend, force you to use a command‑line tool, or leave the encryption details to you. age-credentials changes that.

age-credentials is a pure Rust library that provides a complete, backend‑agnostic account management engine built on the age encryption format. It handles everything from key generation and passphrase‑protected private key storage, to encrypting and decrypting data for specific accounts, all through a clean, trait‑based API. You bring your storage (files, databases, vaults, memory – anything that implements a simple trait), and the engine does the rest.

In this post, I’ll walk through why I built age-credentials, how it works, and how you can start using it today.

The Problem: Reinventing Account Management Every Time

Whether you're building a CLI tool that needs to store API keys securely, a collaborative editor that manages identities, or a service that provisions short‑lived credentials, you always end up solving the same problems:

Generate a strong cryptographic key pair.
Encrypt the private key with a user‑provided passphrase so it can be recovered later.
Associate a public identity (name, email, public key) with the account.
Provide an easy way to encrypt data for, and decrypt data from, a specific account.
Support import/export workflows.
Never let secret keys or plaintext leak into logs or core dumps.

Most solutions either hardcode a filesystem layout, assume a particular database, or leave the encryption entirely to you. age-credentials decouples the business logic (what you want to do) from the storage (how you do it).

Architecture: Traits, Not Assumptions

At the heart of the library lies the AccountBackend trait:

pub trait AccountBackend {
    fn save_identity(&mut self, identity: &Identity) -> Result<()>;
    fn load_identity(&self, fingerprint: &Fingerprint) -> Result<Option<Identity>>;
    fn delete_identity(&mut self, fingerprint: &Fingerprint) -> Result<()>;
    fn store_encrypted_private_key(&mut self, fingerprint: &Fingerprint, key: &[u8]) -> Result<()>;
    fn load_encrypted_private_key(&self, fp: &Fingerprint) -> Result<Option<Zeroizing<Vec<u8>>>>;
    fn list_fingerprints(&self) -> Result<Vec<Fingerprint>>;
    fn find_by_email(&self, email: &str) -> Result<Option<Fingerprint>> { … }
}

By implementing this trait, you decide where identities and encrypted private keys live. The library never touches a filesystem or a database directly. This makes it easy to integrate into any existing system – whether you're using SQLite, a cloud object store, or just a HashMap for testing.

The AccountEngine struct (stateless) then provides all the high‑level operations on top of any backend:

create_account – generates a key pair, encrypts the secret key with a passphrase, stores the identity and the encrypted blob.
encrypt_for_account – encrypts data to a user's public key.
decrypt_for_account – unlocks the private key with the passphrase and decrypts.
change_passphrase – re‑wraps the private key with a new passphrase.
export_account / import_account – transfer accounts as passphrase‑encrypted hex blobs.
delete_account, list_accounts, find_by_email.

All methods are synchronous, return Result<_, AccountError>, and never panic.

Strong Typing and Validation

Every domain object is validated at construction. For example:

let user = UserID::new("Alice", "alice@example.com")?;

This validates that the name is between 2 and 255 characters, contains only allowed characters, and that the email has exactly one @ sign, non‑empty parts, and a valid length. You can't accidentally create an invalid user.

A Fingerprint is always a non‑empty hexadecimal string. If you try to create one from garbage, you get an AccountError::InvalidFingerprint immediately.

Security by Design

Several features make age-credentials safe by default:

Zeroize – Secret keys (Zeroizing<String>) and decrypted plaintext (Zeroizing<Vec<u8>>) are automatically wiped from memory when they go out of scope.
Passphrase minimum length – at least 8 characters, enforced at the engine level.
No panics – every fallible operation propagates a structured AccountError enum. There are no hidden unwrap() calls.
Delegation to librage – all cryptographic operations are performed by the well‑audited rage library.
Armored encryption – optionally wrap ciphertext in the age‑standard PEM armor, making it safe for transmission over text channels.

Quick Example: Creating an Account and Sending an Encrypted Message

use age_credentials::account::AccountEngine;
use age_credentials::backend::traits::AccountBackend;
use age_credentials::domain::types::UserID;

// Your custom backend (e.g., files, memory, database)
struct MyBackend { /* ... */ }
impl AccountBackend for MyBackend { /* ... */ }

let mut backend = MyBackend::new();

// Create an account for Alice
let alice = UserID::new("Alice Example", "alice@example.com")?;
let account = AccountEngine::create_account(
    &mut backend,
    alice,
    "strong‑passphrase",
    None, // optional label
)?;

// Encrypt a message to Alice
let ciphertext = AccountEngine::encrypt_for_account(
    &backend,
    &account.fingerprint,
    b"Hello, Alice!",
)?;

// Alice decrypts it later with her passphrase
let plaintext = AccountEngine::decrypt_for_account(
    &backend,
    &account.fingerprint,
    "strong‑passphrase",
    &ciphertext,
)?;

assert_eq!(*plaintext, b"Hello, Alice!");

No files were harmed in this example. Replace MyBackend with your production storage, and you have a fully working account system.

Export and Import

Need to move an account between devices? The engine supports an export format that bundles the identity and encrypted private key into a single passphrase‑protected blob:

let exported = AccountEngine::export_account(
    &backend,
    &account.fingerprint,
    "original‑passphrase",
)?;
// `exported` is a hex‑encoded string

// On another device, with a different backend:
let imported_identity = AccountEngine::import_account(
    &mut backend2,
    &exported,
    "original‑passphrase",
)?;

No plaintext private key ever leaves the library.

Who Is This For?

age-credentials is designed for Rust developers who need an embeddable, secure account system without reinventing the wheel. Some use cases:

CLI tools that store per‑user secrets (API tokens, SSH keys).
Decentralised applications where users manage their own identities.
Collaborative editors that need to encrypt documents for specific participants.
Provisioning systems that generate one‑off credentials and encrypt them for a recipient.
Games that save per‑player encrypted profiles.

Because the backend is abstract, you can even use it to prototype entirely in memory before committing to a persistent storage design.

What's Next?

The library is fully functional and ready for production use. Some enhancements on the horizon:

A reference filesystem backend implementation.
Support for custom account metadata.
Account status (active, suspended, revoked).
Integration with version‑controlled storage via libvctrl for an auditable account history.

Contributions are very welcome! The code is MIT licensed and available on GitHub:

github.com/mroczect/age-credentials

If you're tired of re‑implementing account management for every project, give age-credentials a try. It takes care of the hard parts so you can focus on building your application. I'd love to hear your feedback and use cases in the comments!

Introducing libvctrl: A Content‑Addressed Version Control Engine for Rust Applications

mroczect — Thu, 06 Aug 2026 13:23:43 +0000

libvctrl is an open‑source library that provides a complete, content‑addressed version control engine designed to be embedded directly into Rust applications. It offers the full machinery of modern version control – objects, references, commits, merges, cryptographic signatures, garbage collection, and much more – all without depending on an external CLI tool or shelling out to Git.

The library is built on a clean trait‑based architecture. Every major component (hashing, encoding, storage, merging, signing) is defined as a trait, allowing you to plug in custom implementations or use the robust defaults. The default hasher is SHA‑512, the default encoding is a compact binary format with versioning, and the reference store can be backed by memory, an append‑only file, or wrapped in Arc<Mutex<>> for thread‑safe access.

Whether you are building a collaborative editor, a game that needs to version its assets, a document management system, or a custom DevOps tool, libvctrl gives you a production‑ready foundation for versioning arbitrary data.

Feature Overview

Complete object model – Blob, Tree, Commit, and Tag. All objects are identified by a 64‑byte SHA‑512 hash.
Pluggable hashing – Hasher trait; default Sha512Hasher uses type‑prefixed SHA‑512.
Pluggable encoding – Encoder / Decoder traits; default binary format with strict size limits to prevent malformed input attacks.
Full version control operations
- Commit creation, checkout, diff, log, log with graph topology, blame, stash
- Merge (three‑way, octopus), rebase, cherry‑pick, revert
- Branch and tag management (lightweight and annotated, with cryptographic signing)
Storage backends
- MemoryStore – hash‑map‑based store, ideal for testing and in‑memory usage.
- FileStore – append‑only binary file with tombstone deletion for garbage collection.
- SyncAdapter – wraps any ObjectStore / RefStore in Arc<Mutex<>> for safe concurrent access.
Cryptographic signing & verification – trait‑based Signer / Verifier (example with Ed25519 included in tests).
Advanced merging – recursive three‑way merge with pluggable ConflictResolver trait.
Merge base detection – BFS‑based find_merge_base and is_ancestor helpers with a configurable search limit.
Reflog – optional log of all reference changes; MemoryRefStore implements ReflogStore.
RevWalk – timestamp‑ordered commit iterator that returns (Hash, Commit) pairs.
Patch generation & application – binary patches for tree‑to‑tree transformations (blob‑only).
Garbage collection – mark‑and‑sweep reachable objects; removes unreachable ones and writes tombstones in the file store.
Index – a staging‑area abstraction (Index) to incrementally build a tree before committing.
Extensibility – custom encoders, hashers, merge strategies, conflict resolvers, and transport layers.

Data Model

All objects are content‑addressed. A Hash is a fixed 64‑byte array, displayed as a 128‑character hex string.

Type	Description
`Blob`	Raw byte content.
`TreeEntry`	A named entry (`name`, `kind` – Blob or Tree, `hash`).
`Tree`	An immutable, sorted list of `TreeEntry`. Duplicate names are rejected.
`Commit`	Points to a tree, lists parent commits, and stores author, committer, timestamp, message, an optional signature, and custom headers (key‑value pairs).
`Tag`	Lightweight (a direct ref) or annotated (a full object with tagger, message, timestamp, optional signature).
`Object`	Enum `Blob`, `Tree`, `Commit`, or `Tag`.
`UserID`	Name and email, each 1–255 characters.

Hashing & Encoding

`Hasher` Trait

pub trait Hasher {
    fn hash_blob(&self, data: &[u8]) -> Hash;
    fn hash_tree_encoded(&self, data: &[u8]) -> Hash;
    fn hash_commit_encoded(&self, data: &[u8]) -> Hash;
    fn hash_tag_encoded(&self, data: &[u8]) -> Hash;
}

The default Sha512Hasher follows the pattern type SP length NUL data, hashed with SHA‑512. The HashVerifier extension trait (auto‑implemented) adds verify_* methods that recompute the hash and compare it to the expected value.

`Encoder` / `Decoder` Traits

pub trait Encoder {
    fn encode_tree(&self, tree: &Tree, buf: &mut Vec<u8>) -> Result<(), VctrlError>;
    fn encode_commit(&self, commit: &Commit, buf: &mut Vec<u8>) -> Result<(), VctrlError>;
    fn encode_tag(&self, tag: &Tag, buf: &mut Vec<u8>) -> Result<(), VctrlError>;
}

pub trait Decoder {
    fn decode_tree(&self, data: &[u8]) -> Result<Tree, VctrlError>;
    fn decode_commit(&self, data: &[u8]) -> Result<Commit, VctrlError>;
    fn decode_tag(&self, data: &[u8]) -> Result<Tag, VctrlError>;
}

The default binary encoder/decoder uses a compact, versioned format. Commit version 2 and tag version 2 support additional headers and signatures, while enforcing tight limits on field sizes (e.g., max tree entries 100 000, max message length 1 MiB) to prevent resource exhaustion.

Storage Abstraction

libvctrl separates concerns: object storage is handled by ObjectStore, reference management by RefStore.

`ObjectStore` Trait

pub trait ObjectStore {
    fn put(&mut self, hash: &Hash, obj: &Object) -> Result<(), VctrlError>;
    fn get(&self, hash: &Hash) -> Result<Option<Object>, VctrlError>;
    fn exists(&self, hash: &Hash) -> Result<bool, VctrlError>;
    fn all_hashes(&self) -> Result<Vec<Hash>, VctrlError>;
    fn remove(&mut self, hash: &Hash) -> Result<(), VctrlError>;
}

`RefStore` Trait

pub trait RefStore {
    fn set_ref(&mut self, name: &str, hash: &Hash) -> Result<(), VctrlError>;
    fn get_ref(&self, name: &str) -> Result<Option<Hash>, VctrlError>;
    fn delete_ref(&mut self, name: &str) -> Result<(), VctrlError>;
    fn set_head(&mut self, target: &str) -> Result<(), VctrlError>;
    fn head(&self) -> Result<Option<Hash>, VctrlError>;
    fn head_ref_name(&self) -> Result<Option<String>, VctrlError>;
    fn list_refs(&self, prefix: &str) -> Result<Vec<String>, VctrlError>;
}

Extension Trait `ObjectStoreExt`

Provides convenient helper methods:

fn get_commit(&self, hash: &Hash) -> Result<Commit, VctrlError>;
fn get_tree(&self, hash: &Hash) -> Result<Tree, VctrlError>;
fn get_blob(&self, hash: &Hash) -> Result<Vec<u8>, VctrlError>;
fn get_verified(&self, hash: &Hash, encoder: &dyn Encoder, hasher: &dyn Hasher) -> Result<Object, VctrlError>;

get_verified recomputes the hash of the encoded object and returns a Corrupted error on mismatch, enabling integrity checks.

Built‑in Backends

MemoryStore + MemoryRefStore – Fast, in‑memory hash maps. MemoryRefStore also implements ReflogStore.
FileStore – Append‑only binary file with a magic header, versioning, and record types for objects, ref operations, and tombstone deletions. It is crash‑safe and reads the entire file at startup to rebuild indices.
SyncAdapter<S> – Generic wrapper that takes an ObjectStore or RefStore and exposes SyncObjectStore / SyncRefStore with &self methods, using an internal Arc<Mutex<S>>. Mutex poisoning is mapped to a Backend error.

The Command Trait

Every operation is encapsulated as a struct that implements the Command trait. This design keeps the library free of side effects and makes it straightforward to integrate with different runtimes.

pub trait Command {
    type Output;
    fn execute(
        &self,
        store: &mut dyn ObjectStore,
        refs: &mut dyn RefStore,
    ) -> Result<Self::Output, VctrlError>;
}

Available Commands

Command	Struct Fields (abbreviated)	Output
`Init`	`author`, `encoder`, `hasher`	`Hash` (initial commit)
`CreateCommit`	`tree_hash`, `parents`, `author`, `committer`, `message`, `encoder`, `hasher`	`Hash` (new commit)
`Checkout`	`tree_hash`	`Vec<(String, Vec<u8>)>`
`Log`	(none)	`Vec<Commit>`
`LogGraph`	`head`	`Vec<GraphCommit>` (includes parent indices)
`DiffCommits`	`old_commit`, `new_commit`	`Vec<DiffEntry>`
`DiffPatch`	`old_tree_hash`, `new_tree_hash`	`Vec<u8>` (binary patch)
`ApplyPatch`	`base_tree_hash`, `patch_data`, `encoder`, `hasher`	`Hash` (new tree)
`CherryPick`	`commit_hash`, `author`, `committer`, `merger`, `resolver`, `encoder`, `hasher`	`Hash` (new commit)
`Revert`	`commit_hash`, `author`, `committer`, `encoder`, `hasher`	`Hash` (revert commit)
`MergeCommand`	`base`, `ours`, `theirs`, `merger`, `resolver`, `encoder`, `hasher`	`Hash` (merged tree)
`MergeBranch`	`branch_name`, `author`, `committer`, `merger`, `resolver`, `encoder`, `hasher`	`Hash` (merge commit)
`OctopusMerge`	`branch_names`, `author`, `committer`, `merger`, `resolver`, `encoder`, `hasher`	`Hash` (merge commit)
`Rebase`	`upstream`, `onto`, `author`, `committer`, `merger`, `resolver`, `encoder`, `hasher`	`Hash` (new HEAD)
`CreateBranch`	`name` (must start with `refs/heads/`), `hash`	`()`
`DeleteBranch`	`name`	`()`
`GetBranch`	`name`	`Option<Hash>`
`SetHead`	`target` (branch name or hash)	`()`
`ListBranches`	(none)	`Vec<(String, Hash, bool)>`
`CreateLightweightTag`	`name`, `target`	`()`
`CreateAnnotatedTag`	`name`, `target`, `tagger`, `message`, `encoder`, `hasher`, optional `signer`	`Hash` (tag object)
`DeleteTag`	`name`	`()`
`ListTags`	(none)	`Vec<String>`
`VerifyCommit`	`commit_hash`, `verifier`, `encoder`, `hasher`	`bool`
`VerifyTag`	`tag_hash`, `verifier`, `encoder`, `hasher`	`bool`
`Describe`	`commit_hash`, `max_commits_to_search`	`Option<String>`
`StashPush`	`tree_hash`, `author`, `message`, `encoder`, `hasher`	`Hash` (stash commit)
`StashPop`	(none)	`Option<Hash>` (tree hash)
`StashList`	(none)	`Vec<(String, Hash)>`
`Annotate` (Blame)	`start_commit`, `path`	`Vec<BlameEntry>`
`Show`	`commit_hash`	`ShowOutput { commit, diff }`
`Fsck`	`encoder`, `hasher`	`Vec<VctrlError>`

All commands are synchronous and return a Result with the appropriate output type.

Diff & Merge

Tree Diffing

The TreeDiff trait is implemented by TreeDiffer. It compares two trees and returns a list of DiffEntry, each with a DiffKind of Added, Removed, or Modified.

pub enum DiffKind {
    Added { new_hash: Hash },
    Removed,
    Modified { old_hash: Hash, new_hash: Hash },
}

Three‑Way Merge

The ThreeWayMerge trait is implemented by ThreeWayMerger. It performs a recursive tree merge and uses a ConflictResolver for blob conflicts.

pub trait ConflictResolver {
    fn resolve(&self, base: &[u8], ours: &[u8], theirs: &[u8]) -> Option<Vec<u8>>;
}

The resolver can be a simple “ours” or “theirs” strategy, a line‑based merger, or any custom logic. When a conflict cannot be resolved, the merge returns a VctrlError::MergeConflict.

Merge Base

Two utility functions assist with merging:

find_merge_base(store, a, b) – returns the best common ancestor, using a BFS limited to 100 000 steps.
is_ancestor(store, ancestor, descendant) – checks fast‑forward conditions.

Additional Components

Reflog

The ReflogStore trait and ReflogEntry struct provide an audit trail of reference updates. MemoryRefStore implements this trait automatically, recording every set_ref.

RevWalk

RevWalk is a timestamp‑ordered iterator over commits. Starting from one or more tips, it yields (Hash, Commit) pairs using a binary heap. It is an efficient way to traverse history in chronological order.

Patch

generate_patch and apply_patch create and apply binary patches between two trees. The patch format is versioned and currently limited to blob changes (tree‑level patches return an error). These operations are exposed as DiffPatch and ApplyPatch commands.

Garbage Collection

mark_reachable – collects the set of all objects reachable from any ref and HEAD.
gc – removes unreachable objects. In FileStore, removal writes a tombstone record so that the object stays deleted across restarts.

Usage Example

Below is a minimal example that initializes a repository, adds a blob and a tree, and creates a commit – all using the in‑memory backends.

use libvctrl::*;

fn main() -> Result<(), VctrlError> {
    let mut store = MemoryStore::new();
    let mut refs = MemoryRefStore::new();

    // Initialize the repository
    let init = Init {
        author: UserID::new("Alice".into(), "alice@example.com".into())?,
        encoder: Box::new(BinaryEncoder),
        hasher: Box::new(Sha512Hasher),
    };
    let root_commit = init.execute(&mut store, &mut refs)?;

    // Create a blob
    let blob_data = b"Hello, libvctrl!";
    let blob = Blob::new(blob_data.to_vec());
    let hasher = Sha512Hasher;
    let blob_hash = hasher.hash_blob(blob_data);
    store.put(&blob_hash, &Object::Blob(blob))?;

    // Build a tree
    let entry = TreeEntry::new("README.md".into(), EntryKind::Blob, blob_hash)?;
    let tree = Tree::new(vec![entry])?;
    let mut buf = Vec::new();
    let encoder = BinaryEncoder;
    encoder.encode_tree(&tree, &mut buf)?;
    let tree_hash = hasher.hash_tree_encoded(&buf);
    store.put(&tree_hash, &Object::Tree(tree))?;

    // Create a commit on top of the initial commit
    let commit_cmd = CreateCommit {
        tree_hash,
        parents: vec![root_commit],
        author: UserID::new("Alice".into(), "alice@example.com".into())?,
        committer: UserID::new("Alice".into(), "alice@example.com".into())?,
        message: "Add README".into(),
        encoder: Box::new(BinaryEncoder),
        hasher: Box::new(Sha512Hasher),
    };
    let new_commit = commit_cmd.execute(&mut store, &mut refs)?;

    println!("New commit: {}", new_commit);
    Ok(())
}

The same pattern can be used with FileStore for persistent storage – just replace MemoryStore::new() with FileStore::open("myrepo.vctrl")?.

Error Handling

All fallible functions return Result<T, VctrlError>. The error type is exhaustive:

pub enum VctrlError {
    Hash(HashError),
    Tree(TreeError),
    NotFound(String),
    InvalidRef(String),
    MergeConflict { entry: String, reason: String },
    Io(std::io::Error),
    Serialization(String),
    Backend(String),
    Other(String),
    Corrupted(String),
    Unsupported(String),
}

There are no hidden panics in the library. Every error path is propagated cleanly.

Minimum Supported Rust Version

libvctrl requires Rust 1.85.0 (stable) or later.

License

Licensed under the MIT License. See the LICENSE file for details.

Repository & Contribution

The source code, full documentation, and issue tracker are available on GitHub:

github.com/mroczect/libvcrtl

Contributions, bug reports, and feature suggestions are welcome. If you are building an application that requires embedded version control, give libvctrl a try – it is ready for real‑world use and open to extension.

Building an Offline Authenticator with Rust and Age Encryption

mroczect — Thu, 06 Aug 2026 13:07:52 +0000

Building an Offline Authenticator with Rust and Age Encryption

I'm building a Rust library called age-auth — a toolkit for creating offline, one‑time password systems where the secret is always encrypted with age (X25519). Think of it as the cryptographic foundation for a super‑secure, offline‑first authenticator app like Google Authenticator, but without ever storing or transmitting the secret in plain text.

In this post I'll walk through why I started the project, the architecture I chose, and how you can use it today.

The Problem

Most OTP apps store the shared secret in plain text (or with weak protection). If someone extracts the app's data, all accounts enrolled in that authenticator are compromised. I wanted a library that forces the secret to be encrypted at rest and only decrypted on‑demand, using modern public‑key cryptography.

The constraints I set for myself:

The user generates an age keypair offline (public key for provisioning, private key for decryption).
The server never sees the private key — it only encrypts a fresh OTP secret to the user's public key.
The user's client library can decrypt the ciphertext and generate TOTP/HOTP codes, all offline.
No hidden network calls, no default configurations, no backdoors.

Crate Architecture

The workspace is split into four focused crates, plus a root re‑export crate:

Crate	Purpose
`libage_auth_handler`	Traits, error types, and validated wrapper types
`libage_crypto`	Age encryption / decryption via librage
`libage_otp`	Pure TOTP (RFC 6238) and HOTP (RFC 4226) engine
`libage_authenticator`	Combines crypto + OTP into a high‑level API
`age_auth`	Re‑exports everything as a single dependency

Each crate can be used independently, so you could just use libage_otp for a non‑encrypted OTP generator, or combine them to build a fully encrypted authenticator.

Strong Typing and Safety First

Every cryptographic parameter is wrapped in a validated newtype from libage_auth_handler. For example:

// Age public key – validated at construction
let recipient = Recipient::new("age1...").unwrap();

// Age secret key – never serialized, validated format
let identity = Identity::new("AGE-SECRET-KEY-...").unwrap();

// Secret data – automatically zeroized on drop
let secret = Secret::new(b"my secret".to_vec());

This eliminates entire classes of bugs — you can't accidentally swap a public key with a private key, or use an invalid Base32 string, because the types enforce it at compile time.

All sensitive containers (Secret, EncryptedPayload) use the zeroize crate. When they go out of scope, the memory is scrubbed.

Errors are unified under a single AuthError enum (backed by thiserror), and there's not a single unwrap() or expect() in production code — all failures propagate as Result<T, AuthError>.

The Offline Flow

Here's a minimal example of the complete workflow:

use age_auth::{AgeAuthenticator, generate_keypair, traits::Authenticator, types::Secret};
use std::io::Cursor;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Create the authenticator
    let auth = AgeAuthenticator::new();

    // 2. Generate a keypair (offline)
    let (recipient, identity) = generate_keypair()?;

    // 3. Provision a Base32 OTP secret
    let secret = Secret::new(b"JBSWY3DPEHPK3PXP".to_vec());
    let encrypted = auth.provision(&recipient, &secret)?;

    // 4. Later, when the user needs a code:
    let mut identity_reader = Cursor::new(identity.as_str().as_bytes());
    let totp_code = auth.generate_totp_from_encrypted(&mut identity_reader, &encrypted)?;

    println!("Your one‑time code is: {}", totp_code);
    Ok(())
}

The secret is never stored in plain text on disk — you keep the encrypted payload anywhere, and only when you present the private key do you get the TOTP code.

Multiple recipients are also supported (provision_multiple), so you can encrypt a secret for several devices at once.

OTP Engine – RFC Compliance

The libage_otp crate implements HOTP and TOTP from scratch, with full test vectors from RFC 4226 and RFC 6238. It supports SHA‑1, SHA‑256, and SHA‑512, with SHA‑256 as the default (because SHA‑1 is legacy). The dynamic truncation is done exactly as specified.

Benchmarks show that a single HOTP generation takes ~442 ns (SHA‑1) to ~1.2 µs (SHA‑512) on a modern CPU, so performance is more than adequate for interactive use.

Development & CI

The project uses a workspace with a custom version management script (scripts/bump_version.sh) that keeps all crates at the same version. GitHub Actions runs formatting, clippy, and tests on every push, and a separate workflow automatically publishes all crates to crates.io when a new tag is pushed.

What's Next?

otpauth:// URL generation so you can scan a QR code directly.
Streaming encryption/decryption for very large secrets.
Fuzz testing to harden the parser and crypto boundaries.
Better documentation on docs.rs.

I'm actively developing this library and welcome feedback, contributions, and real‑world use cases. You can find the code at github.com/mroczect/age-auth and the crates on crates.io.

Do you think an offline‑first authenticator approach like this could improve security in your workflows? Let me know in the comments!

DEV Community: mroczect

libvctrl 2.0.0: A Stable, Production-Ready Version Control Foundation

libvctrl

Overview

Architecture

Three-Layer Design

Workspace Dependency Graph

Internal Module Architecture

Object Lifecycle and Data Flow

Core Features

Contracts Layer (handler)

Implementations Layer (reference)

Cryptography Layer (crypto)

Cross-Cutting Guarantees

Technology Stack

Lint and Safety Configuration

Project Structure

Workspace Layout

SDK Crate Internal Structure

Getting Started

Prerequisites

Installation

As a Dependency (crates.io)

From Source (Workspace)

Configuration

Feature Flags

Structural Limits

Usage

Importing the SDK

Building and Encoding a Blob

Building a Tree with Entries

Building a Commit

Building a Tag

Full Lifecycle: Build, Encode, Hash, Store, Retrieve

Using the Reference Store

Validating Inputs

Accessing Cryptographic Primitives

API Reference

Root-Level Re-exports

Types (from handler)

Traits (from handler)

Implementations (from reference)

Builders (from reference)

Validators (from reference)

Error and Constants

Sub-Modules

BinaryEncoder Method Reference

BinaryDecoder Method Reference

Sha512Hasher Method Reference

MemoryStore Method Reference

MemoryRefStore Method Reference

Binary Wire Format Specification

Blob

Tree

Commit

Tag

Testing

Running Tests

Test Coverage Areas

Contributing

Code Quality Requirements

Architectural Requirements

Local CI Checklist

Future Feature Flags (Guidance)

License

Introducing librage: A Safe, Simple, and Uniform Rust Wrapper for Age Encryption

Introducing librage: A Safe, Simple, and Uniform Rust Wrapper for Age Encryption

The Problem: Great Library, Unfriendly API

Uniform API: Everything Returns LibrageResponse<T>

Feature‑Rich, Minimalist Surface

Quick Example: From Keygen to Decrypted Text

Security Without Headaches

Who Should Use librage?

What’s Next?

Introducing age-credentials: A Backend‑Agnostic Account Engine for the Age Encryption Era

Introducing age-credentials: A Backend‑Agnostic Account Engine for the Age Encryption Era

The Problem: Reinventing Account Management Every Time

Architecture: Traits, Not Assumptions

Strong Typing and Validation

Security by Design

Uniform API: Everything Returns `LibrageResponse<T>`

`Hasher` Trait

`Encoder` / `Decoder` Traits

`ObjectStore` Trait

`RefStore` Trait

Extension Trait `ObjectStoreExt`