gunnar_crypt/

lib.rs

//! **Encrypted repositories**: the operator of a gunnar server cannot read a
//! repository's content; only its members can, each with their own
//! encryption key, opened by their SSH key or their security key.
//!
//! The design, the threat model and what still leaks are in
//! `.nornir/encrypted-repos.md`. This crate is the part every door shares:
//!
//! * [`envelope`] — the format of one encrypted file (blob): a 13-byte header
//!   naming the key epoch, then AES-256-SIV over the content. Deterministic on
//!   purpose: the same content under the same key gives the same blob, so git's
//!   clean filter is stable and `git status` stays quiet, and the blob id is a
//!   KEYED id (it depends on the secret key), so nobody without the key can
//!   confirm that a known file is in the repository.
//! * [`keyring`] — the repository's data keys, one per epoch. A rotation adds
//!   an epoch; old epochs stay so members can still read old content.
//! * [`members`] — the plaintext list of members' PUBLIC keys
//!   (`.gunnar-crypt/members`). The key ring is wrapped to every key in it.
//! * [`policy`] — what a server checks on a push to an encrypted repository:
//!   every blob is an envelope, except the three files the scheme itself needs.
//!   It reads formats, never keys.
//! * `userkey` (feature `user-key`) — the USER's encryption key: one key
//!   pair per user (the hybrid `age1pq1…`, quantum-safe, unless the person
//!   asked for a classic age X25519 key), its private half stored on the server only as age files,
//!   one per unlock method: an SSH key file (CLI), a security key's WebAuthn
//!   PRF / FIDO2 hmac-secret output through HKDF-SHA256 (browser and CLI), an
//!   `age1pq1…` key file, or a printed recovery code (age's scrypt).
//! * [`skwrap`] — the text form of a security key's wrap v2 (CRYPT-PQ-SK):
//!   symmetric under HKDF of the PRF output, XChaCha20-Poly1305, quantum-safe.
//!   Format only; the server checks it.
//! * `wrap` (feature `user-key`) — the age wrap of the key ring to every
//!   member's user public key. A repository never names an SSH key or a
//!   security key; adding or removing an unlock method touches no repository.
//!   Feature `pq` adds the quantum-safe user key and ring, `wrap` the SSH
//!   unlock method.
//! * `pq` (feature `pq`) — that hybrid recipient and its identity, until an
//!   age release carries its own.
//!
//! **Quantum-safe is the default** (CRYPT-PQ-DEFAULT, owner 2026-10-30): a new
//! repository ([`members::Members::new`]) and a new key are at
//! [`members::Level::NEW`]; classic is the visible opt-out. A members file
//! without a `level` line stays classic, so an existing repository keeps its
//! level.
//!
//! * [`diff`] (feature `diff`) — line diffs of decrypted content. The server
//!   cannot diff ciphertext and keeps no pre-made diffs; the client does it.
//!
//! **One crate, two targets.** The CLI and the browser console run this same
//! code, native and wasm32: fetch ciphertext → open the user key with an
//! unlock method → unwrap the key ring → open and diff locally → seal before
//! push. The CLI opens the user key with the SSH key file in `~/.ssh` (or a
//! security key over FIDO2 hmac-secret); the browser opens it with a security
//! key (WebAuthn PRF), in the tab, with no helper. `tests/vectors.rs` and
//! `tests/userkey.rs` run the same vectors on both targets.
//!
//! Who links what: gunnar-server takes `default-features = false` (policy and
//! format only; no cipher, no key), the browser console takes `cipher`,
//! `diff`, `user-key` and `pq`, and the CLI takes everything.

#![forbid(unsafe_code)]
#![doc(
    html_logo_url = "https://gunnar.rs/download/gunnar.webp",
    html_favicon_url = "https://gunnar.rs/download/favicon.svg"
)]

/// zeroize, for callers holding key material.
#[cfg(feature = "cipher")]
pub use zeroize;

#[cfg(feature = "diff")]
pub mod diff;
pub mod door;
pub mod envelope;
#[cfg(feature = "cipher")]
pub mod keyring;
pub mod members;
pub mod policy;
#[cfg(feature = "pq")]
pub mod pq;
pub mod skwrap;
#[cfg(feature = "user-key")]
pub mod userkey;
#[cfg(feature = "user-key")]
pub mod wrap;

/// `N` bytes from the OS random source (keys, recovery codes).
#[cfg(feature = "keygen")]
pub fn random_bytes<const N: usize>() -> [u8; N] {
    let mut b = [0u8; N];
    getrandom::getrandom(&mut b).expect("the OS random source is available");
    b
}

/// Open a blob as text: an envelope is opened with `ring`; anything else is
/// returned as it is (history from before `gunnar crypt init` is plaintext).
#[cfg(feature = "cipher")]
pub fn open_blob(ring: &keyring::Keyring, blob: &[u8]) -> Result<Vec<u8>, envelope::OpenError> {
    if envelope::has_magic(blob) {
        envelope::open(ring, blob)
    } else {
        Ok(blob.to_vec())
    }
}

/// The diff between two stored blobs of one path (`None` = the path does not
/// exist on that side), opened with `ring`. What `gunnar crypt diff` prints
/// and what the console shows for an encrypted repository.
#[cfg(all(feature = "cipher", feature = "diff"))]
pub fn diff_blobs(
    ring: &keyring::Keyring,
    old: Option<&[u8]>,
    new: Option<&[u8]>,
) -> Result<diff::FileDiff, envelope::OpenError> {
    let old = old
        .map(|b| open_blob(ring, b))
        .transpose()?
        .unwrap_or_default();
    let new = new
        .map(|b| open_blob(ring, b))
        .transpose()?
        .unwrap_or_default();
    Ok(diff::hunks(
        &String::from_utf8_lossy(&old),
        &String::from_utf8_lossy(&new),
    ))
}

/// Where the scheme's own files live in a repository.
pub mod paths {
    /// The directory of the scheme's files.
    pub const DIR: &str = ".gunnar-crypt";
    /// The key ring, age-encrypted to every member key (armored).
    pub const KEYS: &str = ".gunnar-crypt/keys";
    /// The members and their PUBLIC keys, plaintext.
    pub const MEMBERS: &str = ".gunnar-crypt/members";
    /// git's attributes file: it names the filter, so it must stay plaintext.
    pub const GITATTRIBUTES: &str = ".gitattributes";
}

/// The name of the git filter, diff and merge drivers.
pub const DRIVER: &str = "gunnar-crypt";

/// The `.gitattributes` lines `gunnar crypt init` writes.
///
/// Everything goes through the filter except the scheme's own files, which
/// must stay readable before a clone is unlocked.
pub const GITATTRIBUTES_LINES: &[&str] = &[
    "* filter=gunnar-crypt diff=gunnar-crypt merge=gunnar-crypt",
    ".gitattributes !filter !diff !merge",
    ".gunnar-crypt/** !filter !diff !merge",
];