pacman-key 0.4.1

Native Rust interface for managing the pacman keyring on Arch Linux
Documentation
use std::path::Path;

use crate::error::{Error, Result};

/// Validates a keyring name before passing to subprocess.
///
/// Accepted formats:
/// - Alphanumeric characters, hyphens, and underscores only
/// - Must not be empty
/// - Must not start with `-` (pacman-key would parse it as an option)
/// - Must not contain shell metacharacters
///
/// Returns the keyring name on success.
pub fn validate_keyring_name(name: &str) -> Result<&str> {
    if name.is_empty() {
        return Err(Error::InvalidKeyringName {
            name: name.to_string(),
            reason: "keyring name cannot be empty".to_string(),
        });
    }

    if name.starts_with('-') {
        return Err(Error::InvalidKeyringName {
            name: name.to_string(),
            reason: "keyring name must not start with '-'".to_string(),
        });
    }

    if !name
        .chars()
        .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_')
    {
        return Err(Error::InvalidKeyringName {
            name: name.to_string(),
            reason:
                "keyring name must contain only alphanumeric characters, hyphens, or underscores"
                    .to_string(),
        });
    }

    Ok(name)
}

/// Validates a key ID format before passing to subprocess.
///
/// Accepted formats:
/// - 8 hex characters (short key ID, discouraged due to collisions)
/// - 16 hex characters (long key ID)
/// - 40 hex characters (full fingerprint, recommended)
/// - Any of the above with "0x" prefix
///
/// Returns the normalized keyid (uppercase, no prefix) on success.
pub fn validate_keyid(keyid: &str) -> Result<String> {
    if keyid.is_empty() {
        return Err(Error::InvalidKeyId {
            keyid: keyid.to_string(),
            reason: "key ID cannot be empty".to_string(),
        });
    }

    let normalized = keyid
        .strip_prefix("0x")
        .or_else(|| keyid.strip_prefix("0X"))
        .unwrap_or(keyid)
        .to_uppercase();

    if !normalized.chars().all(|c| c.is_ascii_hexdigit()) {
        return Err(Error::InvalidKeyId {
            keyid: keyid.to_string(),
            reason: "key ID must contain only hexadecimal characters".to_string(),
        });
    }

    match normalized.len() {
        8 | 16 | 40 => Ok(normalized),
        len => Err(Error::InvalidKeyId {
            keyid: keyid.to_string(),
            reason: format!("key ID must be 8, 16, or 40 hex characters (got {})", len),
        }),
    }
}

/// Validates that a path exists and is valid UTF-8 before passing it to a
/// subprocess. Returns it absolute, so pacman-key and gpg cannot parse a
/// leading `-` as an option.
///
/// The existence check is non-atomic (TOCTOU); the subprocess is the real
/// gate. This only gives a clearer error than a raw gpg failure.
pub fn validate_path(path: &Path) -> Result<String> {
    let s = path.to_str().ok_or_else(|| Error::InvalidPath {
        path: path.display().to_string(),
        reason: "path must be valid UTF-8".to_string(),
    })?;

    if !path.exists() {
        return Err(Error::InvalidPath {
            path: s.to_string(),
            reason: "path does not exist".to_string(),
        });
    }

    std::path::absolute(path)
        .map_err(Error::Command)?
        .into_os_string()
        .into_string()
        .map_err(|_| Error::InvalidPath {
            path: s.to_string(),
            reason: "working directory must be valid UTF-8".to_string(),
        })
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_valid_keyring_names() {
        assert_eq!(validate_keyring_name("archlinux").unwrap(), "archlinux");
        assert_eq!(
            validate_keyring_name("archlinuxarm").unwrap(),
            "archlinuxarm"
        );
        assert_eq!(validate_keyring_name("arch-linux").unwrap(), "arch-linux");
        assert_eq!(validate_keyring_name("arch_linux").unwrap(), "arch_linux");
        assert_eq!(validate_keyring_name("manjaro").unwrap(), "manjaro");
        assert_eq!(validate_keyring_name("test123").unwrap(), "test123");
    }

    #[test]
    fn test_invalid_keyring_name_empty() {
        let err = validate_keyring_name("").unwrap_err();
        assert!(matches!(err, Error::InvalidKeyringName { .. }));
    }

    #[test]
    fn test_invalid_keyring_name_option_like() {
        for name in ["-e", "--gpgdir", "--populate-from"] {
            let err = validate_keyring_name(name).unwrap_err();
            assert!(matches!(err, Error::InvalidKeyringName { .. }));
        }
    }

    #[test]
    fn test_invalid_keyring_name_special_chars() {
        let err = validate_keyring_name("$(whoami)").unwrap_err();
        assert!(matches!(err, Error::InvalidKeyringName { .. }));

        let err = validate_keyring_name("arch;linux").unwrap_err();
        assert!(matches!(err, Error::InvalidKeyringName { .. }));

        let err = validate_keyring_name("arch&linux").unwrap_err();
        assert!(matches!(err, Error::InvalidKeyringName { .. }));

        let err = validate_keyring_name("arch|linux").unwrap_err();
        assert!(matches!(err, Error::InvalidKeyringName { .. }));

        let err = validate_keyring_name("arch`whoami`").unwrap_err();
        assert!(matches!(err, Error::InvalidKeyringName { .. }));

        let err = validate_keyring_name("arch linux").unwrap_err();
        assert!(matches!(err, Error::InvalidKeyringName { .. }));

        let err = validate_keyring_name("arch\nlinux").unwrap_err();
        assert!(matches!(err, Error::InvalidKeyringName { .. }));
    }

    #[test]
    fn test_valid_short_keyid() {
        assert_eq!(validate_keyid("DEADBEEF").unwrap(), "DEADBEEF");
        assert_eq!(validate_keyid("deadbeef").unwrap(), "DEADBEEF");
    }

    #[test]
    fn test_valid_long_keyid() {
        assert_eq!(
            validate_keyid("786C63F330D7CB92").unwrap(),
            "786C63F330D7CB92"
        );
    }

    #[test]
    fn test_valid_fingerprint() {
        assert_eq!(
            validate_keyid("ABAF11C65A2970B130ABE3C479BE3E4300411886").unwrap(),
            "ABAF11C65A2970B130ABE3C479BE3E4300411886"
        );
    }

    #[test]
    fn test_valid_with_0x_prefix() {
        assert_eq!(validate_keyid("0xDEADBEEF").unwrap(), "DEADBEEF");
        assert_eq!(validate_keyid("0XDEADBEEF").unwrap(), "DEADBEEF");
    }

    #[test]
    fn test_invalid_empty() {
        let err = validate_keyid("").unwrap_err();
        assert!(matches!(err, Error::InvalidKeyId { .. }));
    }

    #[test]
    fn test_invalid_non_hex() {
        let err = validate_keyid("DEADBEEG").unwrap_err();
        assert!(matches!(err, Error::InvalidKeyId { .. }));
    }

    #[test]
    fn test_invalid_wrong_length() {
        let err = validate_keyid("DEADBE").unwrap_err();
        assert!(matches!(err, Error::InvalidKeyId { .. }));
    }

    #[test]
    fn test_invalid_contains_spaces() {
        let err = validate_keyid("DEAD BEEF").unwrap_err();
        assert!(matches!(err, Error::InvalidKeyId { .. }));
    }

    #[test]
    fn test_validate_path_exists() {
        let manifest = concat!(env!("CARGO_MANIFEST_DIR"), "/Cargo.toml");
        assert!(validate_path(Path::new(manifest)).is_ok());
        let err = validate_path(Path::new("/nonexistent/pacman-key/xyz")).unwrap_err();
        assert!(matches!(err, Error::InvalidPath { .. }));
    }

    #[test]
    fn test_validate_path_makes_relative_paths_absolute() {
        // cargo runs unit tests from the package root
        let path = validate_path(Path::new("Cargo.toml")).unwrap();
        assert!(Path::new(&path).is_absolute(), "{path}");
        assert!(path.ends_with("/Cargo.toml"), "{path}");
    }
}