gunnar-crypt 1.6.0

//! `.gunnar-crypt/members`: who the key ring is wrapped to, by each member's
//! USER encryption key (its public half).
//!
//! ```text
//! # gunnar-crypt members v1 — public keys only.
//! alice age1qyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqs3290gq
//! bob age1…
//! recovery age1…
//! ```
//!
//! A **quantum-safe** repository says so in one line, and then lists only
//! `age1pq1…` user keys (age's hybrid ML-KEM-768 + X25519 recipient). That is
//! the default for a new repository ([`Level::NEW`]); a file without the line
//! is classic, as every file was before it existed:
//!
//! ```text
//! # gunnar-crypt members v1 — public keys only.
//! level quantum-safe
//! alice age1pq1…
//! recovery age1pq1…
//! ```
//!
//! One line per user: each user has ONE encryption key ([`crate::userkey`]),
//! whatever they unlock it with. A repository never names an SSH key or a
//! security key: those are the user's unlock METHODS, and adding or removing
//! one changes the user's own wrap on the server, never a repository. The file
//! is plaintext because every member must be able to re-wrap the ring after an
//! add or a removal without asking anyone; a public key reveals nothing.
//!
//! Which keys can be members:
//!
//! * `age1pq1…` — a quantum-safe user key (the default kind), and the ONLY kind
//!   a quantum-safe repository takes.
//! * `age1…` — a user's classic X25519 encryption key (or an offline recovery
//!   key), for a classic repository.
//! * NOT an SSH key (`ssh-ed25519`, `ssh-rsa`, `sk-…`): it is an unlock
//!   method of its owner's encryption key, refused here by name.

/// The first line `gunnar crypt` writes.
pub const HEADER: &str = "# gunnar-crypt members v1 — public keys only; the key ring in .gunnar-crypt/keys is wrapped to every key below.";

/// What kind of public key a member line carries.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum KeyKind {
    /// `ssh-ed25519`
    SshEd25519,
    /// `ssh-rsa`
    SshRsa,
    /// `age1…` (X25519), for recovery keys.
    Age,
    /// `age1pq1…`: age's hybrid ML-KEM-768 + X25519 recipient
    /// (`mlkem768x25519`, c2sp.org/age). Quantum-safe.
    AgePq,
}

impl KeyKind {
    /// The age stanza type a key ring wrapped to this key carries.
    pub fn stanza_type(self) -> &'static str {
        match self {
            KeyKind::SshEd25519 => "ssh-ed25519",
            KeyKind::SshRsa => "ssh-rsa",
            KeyKind::Age => "X25519",
            KeyKind::AgePq => PQ_STANZA,
        }
    }
}

/// The age stanza type of the hybrid post-quantum recipient.
pub const PQ_STANZA: &str = "mlkem768x25519";

/// How the key ring is wrapped: chosen per repository, in the members file.
///
/// **A new repository is quantum-safe** ([`Level::NEW`], owner 2026-10-30,
/// CRYPT-PQ-DEFAULT), and so is a new person's key. A members file WITHOUT a
/// `level` line is classic ([`Level::UNSTATED`]): an existing repository keeps
/// its level, and nothing is migrated. `Level::default()` is [`Level::NEW`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Level {
    /// Wrapped to members' X25519 (`age1…`) encryption keys: a ring harvested
    /// today opens once a quantum computer breaks X25519. The visible opt-out
    /// (`gunnar crypt init --level classic`) for members whose one key is classic.
    Classic,
    /// Wrapped ONLY to age's hybrid ML-KEM-768 + X25519 recipients
    /// (`age1pq1…`): no stanza a quantum computer could open. The default.
    #[default]
    QuantumSafe,
}

impl std::str::FromStr for Level {
    type Err = String;

    /// `classic` or `quantum-safe`, the words of the members file and of
    /// `--level`.
    fn from_str(word: &str) -> Result<Level, String> {
        match word.trim() {
            "classic" => Ok(Level::Classic),
            "quantum-safe" => Ok(Level::QuantumSafe),
            other => Err(format!("{other:?} is not a level: classic or quantum-safe")),
        }
    }
}

impl std::fmt::Display for Level {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.word())
    }
}

impl Level {
    /// **The level of a new repository and of a new person's key**, unless
    /// asked otherwise: quantum-safe (owner 2026-10-30, CRYPT-PQ-DEFAULT). The
    /// CLI (`gunnar crypt init`, `gunnar crypt key new`) and the console read it
    /// here, so the default lives in one place.
    pub const NEW: Level = Level::QuantumSafe;

    /// The level of a members file without a `level` line: classic, as every
    /// file was before the line existed. An existing repository keeps its level.
    pub const UNSTATED: Level = Level::Classic;

    /// The word in the members file (`level quantum-safe`).
    pub fn word(self) -> &'static str {
        match self {
            Level::Classic => "classic",
            Level::QuantumSafe => "quantum-safe",
        }
    }

    /// Does a key of `kind` belong in a ring of this level?
    pub fn takes(self, kind: KeyKind) -> bool {
        match self {
            Level::Classic => kind == KeyKind::Age,
            Level::QuantumSafe => kind == KeyKind::AgePq,
        }
    }

    /// The age stanza types a key file of this level may carry (besides the
    /// one random `…-grease` stanza age adds to every file).
    pub fn stanza_types(self) -> &'static [&'static str] {
        match self {
            Level::Classic => &["X25519"],
            Level::QuantumSafe => &[PQ_STANZA],
        }
    }
}

/// The HRP of an `age1pq1…` recipient.
const PQ_HRP: &str = "age1pq";
/// The size of an X-Wing (MLKEM768-X25519) encapsulation key.
pub const PQ_PUBLIC_KEY_BYTES: usize = 1216;

/// The length of an `age1pq1…` recipient: the HRP, the separator, 1216 bytes
/// in bech32's 5-bit symbols, and the 6-symbol checksum.
const PQ_KEY_CHARS: usize = PQ_HRP.len() + 1 + (PQ_PUBLIC_KEY_BYTES * 8).div_ceil(5) + 6;

/// Does `key` have the SHAPE of an `age1pq1…` recipient (prefix, length,
/// bech32's lower-case alphabet)? What a build without `pq-keys` checks.
pub fn looks_like_pq_key(key: &str) -> bool {
    const ALPHABET: &str = "qpzry9x8gf2tvdw0s3jn54khce6mua7l";
    let key = key.trim();
    key.len() == PQ_KEY_CHARS
        && key
            .strip_prefix("age1pq1")
            .is_some_and(|data| data.chars().all(|c| ALPHABET.contains(c)))
}

fn pq_key_ok(key: &str) -> bool {
    #[cfg(feature = "pq-keys")]
    {
        pq_public_key_bytes(key).is_some()
    }
    #[cfg(not(feature = "pq-keys"))]
    {
        looks_like_pq_key(key)
    }
}

/// The 1216 key bytes of an `age1pq1…` recipient, `None` unless it is one
/// (bech32 with the right prefix, checksum and length). The format check the
/// SERVER can do; whether the bytes are a valid ML-KEM key is the wrap's.
#[cfg(feature = "pq-keys")]
pub fn pq_public_key_bytes(key: &str) -> Option<Vec<u8>> {
    use bech32::FromBase32 as _;
    let key = key.trim();
    if !key.starts_with("age1pq1") || key.bytes().any(|b| b.is_ascii_uppercase()) {
        return None;
    }
    let (hrp, data, variant) = bech32::decode(key).ok()?;
    if hrp != PQ_HRP || variant != bech32::Variant::Bech32 {
        return None;
    }
    let bytes = Vec::<u8>::from_base32(&data).ok()?;
    (bytes.len() == PQ_PUBLIC_KEY_BYTES).then_some(bytes)
}

/// Why a public key cannot be a recipient.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum KeyRefusal {
    /// A FIDO security-key SSH key (`sk-…`): it can only sign.
    SecurityKeyOnly(String),
    /// A key type age cannot encrypt to (e.g. ECDSA).
    Unsupported(String),
    /// Not a public key line at all.
    Malformed,
    /// Starts like an `age1pq1…` key but is not one.
    MalformedPq,
}

impl std::fmt::Display for KeyRefusal {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            KeyRefusal::SecurityKeyOnly(t) => write!(
                f,
                "{t} is a security-key (YubiKey/FIDO) SSH key: it can only sign, so nothing \
                 can be encrypted to it. Add an ordinary ed25519 key (ssh-keygen -t ed25519) \
                 for encrypted repositories; keep the security key for login."
            ),
            KeyRefusal::Unsupported(t) => write!(
                f,
                "{t} keys cannot be encryption recipients; use ssh-ed25519 (or ssh-rsa)"
            ),
            KeyRefusal::Malformed => write!(f, "not an SSH or age public key"),
            KeyRefusal::MalformedPq => write!(
                f,
                "not a well-formed age1pq1… key (age's hybrid ML-KEM-768 + X25519 recipient)"
            ),
        }
    }
}
impl std::error::Error for KeyRefusal {}

/// Classify one public key (`<type> <base64> [comment]`, or `age1…`).
pub fn classify(key: &str) -> Result<KeyKind, KeyRefusal> {
    let key = key.trim();
    let ty = key.split_ascii_whitespace().next().unwrap_or("");
    if ty.starts_with("age1pq1") {
        return match (key.split_ascii_whitespace().count(), pq_key_ok(ty)) {
            (1, true) => Ok(KeyKind::AgePq),
            _ => Err(KeyRefusal::MalformedPq),
        };
    }
    if ty.starts_with("age1") && ty.len() > 10 && key.split_ascii_whitespace().count() == 1 {
        return Ok(KeyKind::Age);
    }
    let has_body = key.split_ascii_whitespace().nth(1).is_some();
    match ty {
        "ssh-ed25519" if has_body => Ok(KeyKind::SshEd25519),
        "ssh-rsa" if has_body => Ok(KeyKind::SshRsa),
        t if t.starts_with("sk-") && has_body => Err(KeyRefusal::SecurityKeyOnly(t.to_string())),
        t if (t.starts_with("ecdsa-") || t.starts_with("ssh-dss")) && has_body => {
            Err(KeyRefusal::Unsupported(t.to_string()))
        }
        _ => Err(KeyRefusal::Malformed),
    }
}

/// One line: a member name and one of their public keys.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MemberKey {
    /// The member's gunnar user name (or `recovery`).
    pub name: String,
    /// The public key as written (`ssh-ed25519 AAAA… comment`, or `age1…`).
    pub key: String,
    /// Its kind.
    pub kind: KeyKind,
}

impl MemberKey {
    /// The key's type and body without the comment: what identifies the key.
    pub fn key_id(&self) -> &str {
        key_id(&self.key)
    }
}

fn key_id(key: &str) -> &str {
    let key = key.trim();
    let mut it = key.match_indices(' ');
    match (it.next(), it.next()) {
        (Some(_), Some((second, _))) => &key[..second],
        _ => key,
    }
}

/// Why the members file was refused.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum MembersError {
    /// A line that is not `<name> <public key>`.
    BadLine(usize),
    /// A member name outside `[A-Za-z0-9._@-]`.
    BadName(String),
    /// A key that cannot be a recipient.
    Key(usize, KeyRefusal),
    /// The same key listed twice.
    Duplicate(String),
    /// A `level` line naming no level this version knows.
    BadLevel(String),
    /// An SSH key listed as a member: it is an unlock method of its owner's
    /// encryption key, and a repository is wrapped to that key instead.
    SshKeyIsAMethod {
        /// The member.
        name: String,
    },
    /// A key that does not belong at the file's level: an SSH or `age1…`
    /// key in a quantum-safe repository, or an `age1pq1…` key in a classic one.
    WrongLevel {
        /// The member.
        name: String,
        /// The key's type.
        kind: KeyKind,
        /// The file's level.
        level: Level,
    },
}

impl std::fmt::Display for MembersError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            MembersError::BadLine(n) => write!(f, "members line {n} is not `<name> <public key>`"),
            MembersError::BadName(n) => write!(
                f,
                "member name {n:?} may only use letters, digits and . _ @ -"
            ),
            MembersError::Key(n, r) => write!(f, "members line {n}: {r}"),
            MembersError::Duplicate(k) => write!(f, "the key {k} is listed twice"),
            MembersError::BadLevel(l) => write!(
                f,
                "`level {l}` is not a level (classic or quantum-safe); a newer gunnar may know it"
            ),
            MembersError::SshKeyIsAMethod { name } => write!(
                f,
                "{name}'s SSH key cannot be a member key: a repository is wrapped to {name}'s \
                 encryption key (age1…), which the SSH key unlocks. Add {name} with \
                 `gunnar crypt add-member {name} --from-server` (gunnar holds that key's public half)"
            ),
            MembersError::WrongLevel { name, kind, level: Level::QuantumSafe } => write!(
                f,
                "{name}'s {} key cannot be a recipient: this repository is quantum-safe, and an \
                 X25519 key exchange is what a quantum computer breaks. {name} needs a \
                 quantum-safe encryption key (age1pq1…), which `gunnar crypt key new` makes. A \
                 person whose one key is classic is a member of classic repositories only \
                 (`gunnar crypt init --level classic`)",
                kind.stanza_type()
            ),
            MembersError::WrongLevel { name, level: Level::Classic, .. } => write!(
                f,
                "{name}'s age1pq1… encryption key is quantum-safe and this repository is classic; \
                 age never mixes the two in one key ring. `gunnar crypt level quantum-safe` makes \
                 this repository quantum-safe once every member has a quantum-safe key"
            ),
        }
    }
}
impl std::error::Error for MembersError {}

fn valid_name(n: &str) -> bool {
    !n.is_empty()
        && n.len() <= 64
        && n.bytes()
            .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'.' | b'_' | b'@' | b'-'))
}

/// The members file.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Members {
    level: Level,
    entries: Vec<MemberKey>,
}

impl Default for Members {
    fn default() -> Members {
        Members::new()
    }
}

/// Why `gunnar crypt level quantum-safe` cannot re-wrap the repository yet.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UpgradeRefusal {
    /// The members with no quantum-safe (`age1pq1…`) key, in the file's order.
    pub missing: Vec<String>,
    /// A key that was given but cannot be a member (listed twice, malformed).
    pub error: Option<MembersError>,
}

impl std::fmt::Display for UpgradeRefusal {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        if let Some(e) = &self.error {
            return write!(f, "{e}");
        }
        write!(
            f,
            "not quantum-safe yet: {} {} no quantum-safe encryption key (age1pq1…). A quantum-safe \
             repository is wrapped only to such keys, and age never mixes them with classic ones, so \
             EVERY member needs one: give it (`--key NAME=age1pq1…`), or remove the member first \
             (`gunnar crypt remove-member NAME`). Nothing was changed",
            self.missing.join(", "),
            if self.missing.len() == 1 { "has" } else { "have" }
        )
    }
}
impl std::error::Error for UpgradeRefusal {}

impl Members {
    /// An empty list for a NEW repository: at [`Level::NEW`], quantum-safe.
    pub fn new() -> Members {
        Members::at(Level::NEW)
    }

    /// An empty list at `level` (`Members::at(Level::Classic)`: the opt-out).
    pub fn at(level: Level) -> Members {
        Members {
            level,
            entries: Vec::new(),
        }
    }

    /// **The same members, quantum-safe** (`gunnar crypt level quantum-safe`):
    /// every member's key replaced by the `age1pq1…` key `keys` gives for their
    /// name. Refused, naming them, while any member has none (a classic key is
    /// none). A quantum-safe file comes back as it is. The caller rotates the
    /// ring and wraps it to the result.
    pub fn to_quantum_safe(
        &self,
        keys: &std::collections::BTreeMap<String, String>,
    ) -> Result<Members, UpgradeRefusal> {
        if self.level == Level::QuantumSafe {
            return Ok(self.clone());
        }
        let names = self.names();
        let missing: Vec<String> = names
            .iter()
            .filter(|n| {
                !keys
                    .get(**n)
                    .is_some_and(|k| classify(k) == Ok(KeyKind::AgePq))
            })
            .map(|n| n.to_string())
            .collect();
        if !missing.is_empty() {
            return Err(UpgradeRefusal {
                missing,
                error: None,
            });
        }
        let mut up = Members::at(Level::QuantumSafe);
        for n in names {
            up.add(n, &keys[n]).map_err(|e| UpgradeRefusal {
                missing: Vec::new(),
                error: Some(e),
            })?;
        }
        Ok(up)
    }

    /// Parse the file.
    pub fn parse(text: &str) -> Result<Members, MembersError> {
        let mut m = Members::at(Level::UNSTATED);
        // The level comes first in meaning, wherever its line is: every key
        // is checked against it.
        for line in text.lines().map(str::trim) {
            let mut words = line.split_ascii_whitespace();
            if let (Some("level"), Some(word), None) = (words.next(), words.next(), words.next()) {
                if !word.starts_with("ssh-") && !word.starts_with("age1") {
                    m.level = match word {
                        "classic" => Level::Classic,
                        "quantum-safe" => Level::QuantumSafe,
                        other => return Err(MembersError::BadLevel(other.to_string())),
                    };
                }
            }
        }
        for (i, line) in text.lines().enumerate() {
            let line = line.trim();
            if line.is_empty() || line.starts_with('#') {
                continue;
            }
            let Some((name, key)) = line.split_once(char::is_whitespace) else {
                return Err(MembersError::BadLine(i + 1));
            };
            if name == "level" && matches!(key.trim(), "classic" | "quantum-safe") {
                continue;
            }
            m.add(name, key.trim()).map_err(|e| match e {
                MembersError::Key(_, r) => MembersError::Key(i + 1, r),
                other => other,
            })?;
        }
        Ok(m)
    }

    /// The repository's level: how its key ring is wrapped.
    pub fn level(&self) -> Level {
        self.level
    }

    /// Change the level. Refused while a listed key does not belong at the
    /// new one (an upgrade replaces the keys: [`Members::to_quantum_safe`]).
    pub fn set_level(&mut self, level: Level) -> Result<(), MembersError> {
        if let Some(e) = self.entries.iter().find(|e| !level.takes(e.kind)) {
            return Err(MembersError::WrongLevel {
                name: e.name.clone(),
                kind: e.kind,
                level,
            });
        }
        self.level = level;
        Ok(())
    }

    /// Keep only the keys `keep` says yes to.
    pub fn retain(&mut self, keep: impl FnMut(&MemberKey) -> bool) {
        self.entries.retain(keep);
    }

    /// The text form.
    pub fn to_text(&self) -> String {
        let mut s = String::from(HEADER);
        s.push('\n');
        if self.level != Level::Classic {
            s.push_str("level ");
            s.push_str(self.level.word());
            s.push('\n');
        }
        for e in &self.entries {
            s.push_str(&e.name);
            s.push(' ');
            s.push_str(e.key.trim());
            s.push('\n');
        }
        s
    }

    /// Add one key for `name`. Refuses keys that cannot be recipients and a
    /// key already listed.
    pub fn add(&mut self, name: &str, key: &str) -> Result<(), MembersError> {
        if !valid_name(name) {
            return Err(MembersError::BadName(name.to_string()));
        }
        let kind = classify(key).map_err(|r| match r {
            KeyRefusal::SecurityKeyOnly(_) => MembersError::SshKeyIsAMethod {
                name: name.to_string(),
            },
            r => MembersError::Key(0, r),
        })?;
        if matches!(kind, KeyKind::SshEd25519 | KeyKind::SshRsa) {
            return Err(MembersError::SshKeyIsAMethod {
                name: name.to_string(),
            });
        }
        if !self.level.takes(kind) {
            return Err(MembersError::WrongLevel {
                name: name.to_string(),
                kind,
                level: self.level,
            });
        }
        let id = key_id(key);
        if self.entries.iter().any(|e| e.key_id() == id) {
            return Err(MembersError::Duplicate(id.to_string()));
        }
        self.entries.push(MemberKey {
            name: name.to_string(),
            key: key.trim().to_string(),
            kind,
        });
        Ok(())
    }

    /// Remove every key of `name`; returns how many were removed.
    pub fn remove(&mut self, name: &str) -> usize {
        let before = self.entries.len();
        self.entries.retain(|e| e.name != name);
        before - self.entries.len()
    }

    /// Every line.
    pub fn entries(&self) -> &[MemberKey] {
        &self.entries
    }

    /// Member names, in first-seen order, each once.
    pub fn names(&self) -> Vec<&str> {
        let mut v: Vec<&str> = Vec::new();
        for e in &self.entries {
            if !v.contains(&e.name.as_str()) {
                v.push(&e.name);
            }
        }
        v
    }

    /// Is `name` a member?
    pub fn contains(&self, name: &str) -> bool {
        self.entries.iter().any(|e| e.name == name)
    }

    /// No keys at all?
    pub fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }
}