crates/gunnar-crypt/src/policy.rs
//! What a server checks on a push to an ENCRYPTED repository.
//!
//! The server holds no key and never decrypts. What it can still do is refuse
//! a push that would put plaintext on it: a clone that was never unlocked, a
//! file added before `gunnar crypt init`, a tool that bypassed the filter.
//! Every blob reachable from the pushed commits must be:
//!
//! | path | must be |
//! |---|---|
//! | `.gitattributes` (root only) | anything — it names the filter and must stay readable |
//! | `.gunnar-crypt/members` | anything — public keys only |
//! | `.gunnar-crypt/keys` | an age file (armored or binary) |
//! | any other path | a gunnar-crypt envelope ([`crate::envelope::is_envelope`]) |
//!
//! Symbolic links are refused outright: git stores a link's target as a blob
//! and never runs a filter on it, so the target would be plaintext. A gitlink
//! (submodule entry) carries no blob and is not checked here; its commit id is
//! visible, which the design document lists among the leaks.
//!
//! **The key ring against the members** ([`check_ring`]): whenever a push
//! changes `.gunnar-crypt/keys` or `.gunnar-crypt/members`, the stanzas in the
//! ring's age header — readable without any key — must match the members file
//! one to one: one stanza per listed key, an `ssh-ed25519`/`ssh-rsa` stanza
//! carrying the tag of a listed key, no type the repository's level does not
//! allow (a quantum-safe repository: `mlkem768x25519` only), and nothing else
//! but the one random `…-grease` stanza age adds to every file. A member who
//! holds the file key could otherwise append a stanza for someone the members
//! file does not name and nobody's unwrap would notice. `X25519` and
//! `mlkem768x25519` stanzas are anonymous by design, so for those the count
//! and the type are what can be checked. The client runs the same check
//! before it accepts a ring (`gunnar crypt unlock`).
//!
//! This is a FORMAT check. It cannot prove that an envelope was sealed under
//! the repository's key (that needs the key); it proves the client ran the
//! filter. A member who deliberately pushes junk that starts with the magic is
//! not stopped, and does not need to be: they could as well push the plaintext
//! to any other server.
use base64::engine::general_purpose::{STANDARD, STANDARD_NO_PAD};
use base64::Engine as _;
use sha2::{Digest as _, Sha256};
use crate::envelope;
use crate::members::{KeyKind, Level, Members};
use crate::paths;
/// The binary age header line.
pub const AGE_BINARY_PREFIX: &[u8] = b"age-encryption.org/v1\n";
/// The armored age header line.
pub const AGE_ARMOR_PREFIX: &[u8] = b"-----BEGIN AGE ENCRYPTED FILE-----";
/// Is `data` an age file (binary or armored)?
pub fn is_age_file(data: &[u8]) -> bool {
let trimmed = trim_leading_ws(data);
data.starts_with(AGE_BINARY_PREFIX) || trimmed.starts_with(AGE_ARMOR_PREFIX)
}
fn trim_leading_ws(mut d: &[u8]) -> &[u8] {
while let [first, rest @ ..] = d {
if first.is_ascii_whitespace() {
d = rest;
} else {
break;
}
}
d
}
/// One blob's verdict.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Refusal {
/// A plaintext blob where an envelope belongs.
Plaintext {
/// The path, as found in the tree.
path: String,
},
/// `.gunnar-crypt/keys` that is not an age file.
KeysNotAge,
/// A symbolic link (its target would be plaintext).
Symlink {
/// The path, as found in the tree.
path: String,
},
/// A quantum-safe repository's key ring carries a stanza a quantum
/// computer could open (an SSH or X25519 wrap).
ClassicalInQuantumSafe {
/// The stanza type.
stanza: String,
},
/// The key ring's stanzas do not match the members file.
RingMismatch(String),
}
impl std::fmt::Display for Refusal {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Refusal::Plaintext { path } => write!(
f,
"{path} is plaintext, and this repository is encrypted: the server stores \
ciphertext only. Run `gunnar crypt unlock` in this clone, then \
`git add --renormalize .` and commit again."
),
Refusal::KeysNotAge => write!(
f,
"{} must be an age file (the key ring wrapped to the members); \
write it with `gunnar crypt`",
paths::KEYS
),
Refusal::Symlink { path } => write!(
f,
"{path} is a symbolic link: git stores a link's target unencrypted, so \
encrypted repositories refuse links"
),
Refusal::ClassicalInQuantumSafe { stanza } => write!(
f,
"{} carries a {stanza} stanza, and this repository is quantum-safe \
(`level quantum-safe` in {}): its key ring is wrapped only to age1pq1… \
(ML-KEM-768 + X25519) keys, because one classical wrap beside them would be \
the weak link. Wrap it to the members' quantum-safe encryption keys (age1pq1…) only",
paths::KEYS,
paths::MEMBERS
),
Refusal::RingMismatch(why) => write!(
f,
"{} does not match {}: {why}. Write both with `gunnar crypt`",
paths::KEYS,
paths::MEMBERS
),
}
}
}
/// What a blob's bytes are, as far as the check cares. A server reads a blob
/// once and checks it under every path that names it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Shape {
/// A gunnar-crypt envelope.
pub envelope: bool,
/// An age file.
pub age: bool,
}
impl Shape {
/// Classify `data`.
pub fn of(data: &[u8]) -> Shape {
Shape {
envelope: envelope::is_envelope(data),
age: is_age_file(data),
}
}
}
/// Check one blob found at `path` (slash-separated, relative to the root).
pub fn check_blob(path: &str, is_symlink: bool, data: &[u8]) -> Result<(), Refusal> {
check(path, is_symlink, Shape::of(data))
}
/// [`check_blob`] for a blob already classified.
pub fn check(path: &str, is_symlink: bool, shape: Shape) -> Result<(), Refusal> {
if is_symlink {
return Err(Refusal::Symlink {
path: path.to_string(),
});
}
// A `.gitattributes` at ANY depth: the client's depth-free `.gitattributes !filter` keeps
// every one plaintext, and git reads them before a clone is unlocked (wiring tracer B
// 2026-10-08: the server allowed the root one only, and refused the rest with advice that
// could not fix it).
let attributes =
path == paths::GITATTRIBUTES || path.ends_with(&format!("/{}", paths::GITATTRIBUTES));
match path {
_ if attributes => Ok(()),
paths::MEMBERS => Ok(()),
paths::KEYS => {
if shape.age {
Ok(())
} else {
Err(Refusal::KeysNotAge)
}
}
_ if shape.envelope => Ok(()),
_ => Err(Refusal::Plaintext {
path: path.to_string(),
}),
}
}
// ── the key ring's age header, read without a key ────────────────────────────
/// The armored age footer line.
const AGE_ARMOR_END: &str = "-----END AGE ENCRYPTED FILE-----";
/// The largest key ring or members file the ring check reads, and a bound on
/// what a hostile push can make anyone parse. A quantum-safe member costs
/// ~2.1 KB of armored ring (and ~2 KB of members file), so this caps a
/// quantum-safe repository at ~2,000 member keys (a classic one at ~28,000).
pub const MAX_SCHEME_FILE: usize = 4 << 20;
/// One recipient stanza of an age header: its type, its arguments and the
/// length of its body. What the server can see of a wrap.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct StanzaHead {
/// The type (`ssh-ed25519`, `X25519`, `mlkem768x25519`, …).
pub tag: String,
/// Its arguments.
pub args: Vec<String>,
/// The decoded body's length.
pub body_len: usize,
}
/// The recipient stanzas of an age file (armored or binary), `None` unless
/// its header parses (c2sp.org/age: `-> type args…`, a base64 body in lines of
/// 64 columns ending with a shorter one, then the `---` MAC line).
pub fn age_stanzas(data: &[u8]) -> Option<Vec<StanzaHead>> {
if data.len() > MAX_SCHEME_FILE {
return None;
}
let binary;
let data = if trim_leading_ws(data).starts_with(AGE_ARMOR_PREFIX) {
let text = std::str::from_utf8(data).ok()?;
let mut b64 = String::new();
let mut inside = false;
for line in text.lines().map(str::trim) {
if line.as_bytes() == AGE_ARMOR_PREFIX {
inside = true;
} else if line == AGE_ARMOR_END {
break;
} else if inside {
b64.push_str(line);
}
}
binary = STANDARD.decode(b64.as_bytes()).ok()?;
&binary[..]
} else {
data
};
let mut lines = data.split(|b| *b == b'\n');
if lines.next()? != b"age-encryption.org/v1" {
return None;
}
let mut stanzas = Vec::new();
let mut line = lines.next()?;
loop {
if line.starts_with(b"--- ") {
return Some(stanzas);
}
let head = std::str::from_utf8(line.strip_prefix(b"-> ")?).ok()?;
let mut words = head.split(' ');
let tag = words.next().filter(|t| !t.is_empty())?.to_string();
let args: Vec<String> = words.map(str::to_string).collect();
if args.iter().any(String::is_empty) {
return None;
}
let mut body = Vec::new();
loop {
let l = lines.next()?;
body.extend_from_slice(l);
if l.len() < 64 {
break;
}
if l.len() > 64 {
return None;
}
}
let body_len = STANDARD_NO_PAD.decode(&body).ok()?.len();
stanzas.push(StanzaHead {
tag,
args,
body_len,
});
line = lines.next()?;
}
}
/// The tag age gives a stanza wrapped to an SSH key (`ssh-ed25519`,
/// `ssh-rsa`): the first 4 bytes of SHA-256 over the key's wire blob, base64.
pub fn ssh_stanza_tag(public_key: &str) -> Option<String> {
let blob = STANDARD
.decode(public_key.split_ascii_whitespace().nth(1)?)
.ok()?;
Some(STANDARD_NO_PAD.encode(&Sha256::digest(&blob)[..4]))
}
/// The one stanza age itself adds to every file it writes: a random type
/// ending in `-grease`, up to four short random arguments and a short random
/// body. It carries no key for anyone and is allowed once, at that size.
fn is_grease(s: &StanzaHead) -> bool {
s.tag.ends_with("-grease")
&& s.tag.len() <= 8 + "-grease".len()
&& s.args.len() <= 4
&& s.args.iter().all(|a| a.len() <= 8)
&& s.body_len < 100
}
/// Is a member stanza the size age writes for its type? (c2sp.org/age: an
/// X25519 share and an ssh-ed25519 share are 32 bytes, an SSH tag 4, a hybrid
/// `enc` 1120; a wrapped file key is 32 bytes, an RSA-OAEP one the modulus.)
fn well_formed(s: &StanzaHead) -> bool {
let len = |i: usize| s.args.get(i).map_or(0, String::len);
match s.tag.as_str() {
"ssh-ed25519" => len(0) == 6 && len(1) == 43 && s.body_len == 32,
"ssh-rsa" => len(0) == 6 && (128..=2048).contains(&s.body_len),
"X25519" => len(0) == 43 && s.body_len == 32,
crate::members::PQ_STANZA => len(0) == 1494 && s.body_len == 32,
_ => false,
}
}
/// ★ **The key ring against the members file**, without a key: see the
/// module documentation. `members` is the text of `.gunnar-crypt/members`,
/// `keys` the bytes of `.gunnar-crypt/keys`.
pub fn check_ring(members: &str, keys: &[u8]) -> Result<(), Refusal> {
for (path, len) in [(paths::MEMBERS, members.len()), (paths::KEYS, keys.len())] {
if len > MAX_SCHEME_FILE {
return Err(Refusal::RingMismatch(format!(
"{path} is larger than {} MiB, which no key ring of gunnar's needs",
MAX_SCHEME_FILE >> 20
)));
}
}
let members = Members::parse(members)
.map_err(|e| Refusal::RingMismatch(format!("{} is not readable ({e})", paths::MEMBERS)))?;
let stanzas = age_stanzas(keys).ok_or(Refusal::KeysNotAge)?;
let level = members.level();
let mut grease = 0;
// What each listed key should put in the header — its stanza type and,
// for an SSH key, its tag — counted, so a large ring is one pass.
let mut expected: std::collections::HashMap<(&'static str, Option<String>), usize> =
std::collections::HashMap::new();
for m in members.entries() {
let tag = match m.kind {
KeyKind::SshEd25519 | KeyKind::SshRsa => ssh_stanza_tag(&m.key),
KeyKind::Age | KeyKind::AgePq => None,
};
*expected.entry((m.kind.stanza_type(), tag)).or_default() += 1;
}
for s in &stanzas {
if is_grease(s) && grease == 0 {
grease += 1;
continue;
}
if level == Level::QuantumSafe && s.tag != crate::members::PQ_STANZA {
return Err(Refusal::ClassicalInQuantumSafe {
stanza: s.tag.clone(),
});
}
if !level.stanza_types().contains(&s.tag.as_str()) {
return Err(Refusal::RingMismatch(format!(
"it carries a {} stanza, which no member key of a {} repository makes",
s.tag,
level.word()
)));
}
let arity = match s.tag.as_str() {
"ssh-ed25519" => 2,
_ => 1,
};
let tag = match s.tag.as_str() {
"ssh-ed25519" | "ssh-rsa" => s.args.first().cloned(),
_ => None,
};
if s.args.len() != arity || !well_formed(s) {
return Err(Refusal::RingMismatch(format!(
"a {} stanza that is not the shape age writes ({} argument(s), a {}-byte body)",
s.tag,
s.args.len(),
s.body_len
)));
}
let left = level
.stanza_types()
.iter()
.find(|t| **t == s.tag)
.and_then(|t| expected.get_mut(&(*t, tag.clone())))
.filter(|n| **n > 0);
let Some(left) = left else {
return Err(Refusal::RingMismatch(match tag {
Some(tag) => format!(
"it is wrapped to an {} key (tag {tag}) that no member line lists",
s.tag
),
None => format!(
"it carries more {} stanzas than the members file lists {} keys",
s.tag, s.tag
),
}));
};
*left -= 1;
}
let missing: usize = expected.values().sum();
if missing > 0 {
let first = members
.entries()
.iter()
.find(|m| {
let tag = match m.kind {
KeyKind::SshEd25519 | KeyKind::SshRsa => ssh_stanza_tag(&m.key),
_ => None,
};
expected
.get(&(m.kind.stanza_type(), tag))
.is_some_and(|n| *n > 0)
})
.map(|m| format!("{}'s {} key", m.name, m.kind.stanza_type()))
.unwrap_or_default();
return Err(Refusal::RingMismatch(format!(
"{missing} member key(s) have no stanza (the first: {first})"
)));
}
Ok(())
}