dora_message/

auth.rs

//! Shared-token authentication for coordinator connections.
//!
//! On startup the coordinator generates a random hex token and writes it to
//! a well-known file. The CLI and daemons read this file before connecting
//! and append `?token=<hex>` to the WebSocket URL.

use std::{
    fmt, fs,
    io::Write,
    path::{Path, PathBuf},
};

/// Length of the raw token in bytes (32 bytes = 64 hex chars).
const TOKEN_BYTES: usize = 32;

/// File name used for storing the auth token.
const TOKEN_FILENAME: &str = ".dora-token";

/// Opaque authentication token.
///
/// `PartialEq`/`Eq` are intentionally not derived to prevent accidental
/// non-constant-time comparisons. Use [`constant_time_eq`] instead.
#[derive(Clone)]
pub struct AuthToken(String);

impl AuthToken {
    /// Create a token from a hex string (e.g. read from file or env var).
    pub fn from_hex(hex: impl Into<String>) -> Self {
        Self(hex.into())
    }

    /// Return the hex representation.
    pub fn as_hex(&self) -> &str {
        &self.0
    }
}

impl fmt::Debug for AuthToken {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "AuthToken(***)")
    }
}

/// Constant-time byte comparison to prevent timing side-channel attacks.
pub fn constant_time_eq(a: &[u8], b: &[u8]) -> bool {
    if a.len() != b.len() {
        return false;
    }
    let mut diff = 0u8;
    for (x, y) in a.iter().zip(b.iter()) {
        diff |= x ^ y;
    }
    diff == 0
}

/// Generate a cryptographically random 32-byte token.
pub fn generate_token() -> AuthToken {
    let mut buf = [0u8; TOKEN_BYTES];
    getrandom::fill(&mut buf).expect("failed to generate random bytes");
    let hex: String = buf.iter().map(|b| format!("{b:02x}")).collect();
    AuthToken(hex)
}

/// Compute the token file path for a given working directory.
pub fn token_path(working_dir: &Path) -> PathBuf {
    working_dir.join(TOKEN_FILENAME)
}

/// Return the token path inside the user's config directory
/// (e.g. `~/.config/dora/.dora-token` on Linux).
///
/// Returns `None` if no config directory can be determined.
pub fn config_token_path() -> Option<PathBuf> {
    dirs::config_dir().map(|d| d.join("dora").join(TOKEN_FILENAME))
}

/// Write the token to `<working_dir>/.dora-token` **and** to the user config
/// directory (e.g. `~/.config/dora/.dora-token`).
///
/// On Unix, each file is written to a fresh `0o600` inode that replaces the
/// old one, so the secret is never readable by other users.
pub fn write_token(working_dir: &Path, token: &AuthToken) -> std::io::Result<()> {
    write_token_with_config_copy(
        &token_path(working_dir),
        config_token_path().as_deref(),
        token,
    )
}

fn write_token_with_config_copy(
    path: &Path,
    config_path: Option<&Path>,
    token: &AuthToken,
) -> std::io::Result<()> {
    let result = write_token_to(path, token);

    // Best-effort write to config dir so CLIs in other directories can find
    // it — attempted even if the working-dir write failed.
    if let Some(config_path) = config_path {
        if let Some(parent) = config_path.parent() {
            let _ = fs::create_dir_all(parent);
        }
        if let Err(e) = write_token_to(config_path, token) {
            log::warn!("failed to write token to config dir: {e}");
        }
    }

    result
}

fn write_token_to(path: &Path, token: &AuthToken) -> std::io::Result<()> {
    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt;
        // Write a fresh 0600 inode and rename it over `path` instead of
        // reusing an existing file: `mode` only applies on creation, and
        // tightening an existing file's mode does not revoke descriptors
        // other users already hold on it. `create_new` (O_EXCL) also refuses
        // to follow a symlink planted at the temporary path, and the rename
        // replaces a symlink at `path` rather than writing through it.
        let file_name = path
            .file_name()
            .ok_or_else(|| std::io::Error::other("token path has no file name"))?;
        let mut tmp_name = std::ffi::OsString::from(".");
        tmp_name.push(file_name);
        tmp_name.push(format!(".tmp-{}", std::process::id()));
        let tmp = path.with_file_name(tmp_name);
        // A leftover from a crashed write by this pid would block `create_new`.
        let _ = fs::remove_file(&tmp);

        let written = (|| {
            let mut file = fs::OpenOptions::new()
                .write(true)
                .create_new(true)
                .mode(0o600)
                .open(&tmp)?;
            file.write_all(token.as_hex().as_bytes())?;
            file.write_all(b"\n")?;
            fs::rename(&tmp, path)
        })();
        if written.is_err() {
            let _ = fs::remove_file(&tmp);
        }
        written?;
    }
    #[cfg(not(unix))]
    {
        let mut file = fs::File::create(path)?;
        file.write_all(token.as_hex().as_bytes())?;
        file.write_all(b"\n")?;
    }
    Ok(())
}

/// Read the token from `<working_dir>/.dora-token`.
///
/// Returns `None` if the file does not exist.
pub fn read_token(working_dir: &Path) -> std::io::Result<Option<AuthToken>> {
    read_token_from_path(&token_path(working_dir))
}

fn read_token_from_path(path: &Path) -> std::io::Result<Option<AuthToken>> {
    let file = match fs::File::open(path) {
        Ok(f) => f,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
        Err(e) => return Err(e),
    };

    // On Unix, verify ownership/permissions on the *open* fd (fstat) to
    // avoid a TOCTOU race between read and metadata check.
    #[cfg(unix)]
    {
        use std::os::unix::fs::MetadataExt;
        if let Ok(meta) = file.metadata() {
            let uid = unsafe { libc::geteuid() };
            if meta.uid() != uid {
                log::warn!(
                    "ignoring token file {} (owned by uid {}, expected {})",
                    path.display(),
                    meta.uid(),
                    uid
                );
                return Ok(None);
            }
            if meta.mode() & 0o077 != 0 {
                log::warn!(
                    "ignoring token file {} (mode {:o} is too permissive, expected 0600)",
                    path.display(),
                    meta.mode() & 0o777
                );
                return Ok(None);
            }
        }
    }

    let content = std::io::read_to_string(file)?;
    let trimmed = content.trim();
    if trimmed.is_empty() {
        Ok(None)
    } else {
        Ok(Some(AuthToken(trimmed.to_string())))
    }
}

/// Attempt to read the auth token from (in order):
/// 1. `DORA_AUTH_TOKEN` environment variable
/// 2. `<cwd>/.dora-token` file
/// 3. User config directory (e.g. `~/.config/dora/.dora-token`)
///
/// Returns `None` if no token is found.
pub fn discover_token() -> Option<AuthToken> {
    // 1. Environment variable override
    if let Ok(val) = std::env::var("DORA_AUTH_TOKEN")
        && !val.is_empty()
    {
        return Some(AuthToken(val));
    }

    // 2. Token file in current working directory
    if let Ok(cwd) = std::env::current_dir()
        && let Ok(Some(token)) = read_token(&cwd)
    {
        return Some(token);
    }

    // 3. Token file in user config directory
    if let Some(config_path) = config_token_path()
        && let Ok(Some(token)) = read_token_from_path(&config_path)
    {
        return Some(token);
    }

    None
}

/// Kani proof harnesses (`make qa-kani`). Compiled only under `cargo kani`,
/// never in normal builds or tests. See `docs/formal-verification.md`.
#[cfg(kani)]
mod verification {
    use super::constant_time_eq;

    /// Maximum slice length explored by the proofs. Token comparison inputs
    /// are attacker-controlled strings of arbitrary length, but the loop
    /// body is length-uniform, so a small bound suffices to cover all
    /// control-flow paths (equal/unequal lengths, differing byte positions).
    const MAX_LEN: usize = 8;

    /// Functional correctness: `constant_time_eq` agrees with `==` on all
    /// slice pairs up to `MAX_LEN`, including length mismatches and the
    /// empty slice. Also proves the function never panics on these inputs.
    #[kani::proof]
    #[kani::unwind(9)] // MAX_LEN + 1
    fn constant_time_eq_matches_slice_equality() {
        let a: [u8; MAX_LEN] = kani::any();
        let b: [u8; MAX_LEN] = kani::any();
        let a_len: usize = kani::any();
        let b_len: usize = kani::any();
        kani::assume(a_len <= MAX_LEN);
        kani::assume(b_len <= MAX_LEN);
        assert_eq!(
            constant_time_eq(&a[..a_len], &b[..b_len]),
            a[..a_len] == b[..b_len]
        );
    }
}

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

    #[test]
    fn generate_token_is_64_hex_chars() {
        let token = generate_token();
        assert_eq!(token.as_hex().len(), 64);
        assert!(token.as_hex().chars().all(|c| c.is_ascii_hexdigit()));
    }

    #[test]
    fn generate_tokens_are_unique() {
        let a = generate_token();
        let b = generate_token();
        assert_ne!(a.as_hex(), b.as_hex());
    }

    #[test]
    fn write_and_read_token() {
        let dir = tempfile::tempdir().unwrap();

        let token = generate_token();
        write_token(dir.path(), &token).unwrap();

        let read_back = read_token(dir.path()).unwrap().unwrap();
        assert_eq!(token.as_hex(), read_back.as_hex());
    }

    #[cfg(unix)]
    #[test]
    fn write_token_tightens_an_existing_permissive_file() {
        use std::os::unix::fs::PermissionsExt;

        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join(".dora-token");
        std::fs::write(&path, "stale token that is longer than the new one\n").unwrap();
        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644)).unwrap();

        // Another user who opened the loose file earlier keeps their fd.
        let mut early_reader = std::fs::File::open(&path).unwrap();

        let token = generate_token();
        write_token_to(&path, &token).unwrap();

        let mut seen = String::new();
        std::io::Read::read_to_string(&mut early_reader, &mut seen).unwrap();
        assert!(
            !seen.contains(token.as_hex()),
            "a descriptor opened before the write must not see the new secret"
        );

        let mode = std::fs::metadata(&path).unwrap().permissions().mode() & 0o777;
        assert_eq!(mode, 0o600, "the secret must not stay world-readable");
        let read_back = read_token_from_path(&path).unwrap();
        assert_eq!(
            read_back.map(|t| t.as_hex().to_owned()),
            Some(token.as_hex().to_owned())
        );
    }

    #[test]
    fn config_token_path_returns_some() {
        // Should return a path on any system with a home directory
        let path = config_token_path();
        if let Some(p) = &path {
            assert!(p.ends_with("dora/.dora-token"));
        }
    }

    #[test]
    fn write_token_creates_config_dir_copy() {
        let dir = tempfile::tempdir().unwrap();
        let token = generate_token();
        write_token(dir.path(), &token).unwrap();

        // Config dir copy is best-effort; just verify the working-dir copy works
        let read_back = read_token(dir.path()).unwrap().unwrap();
        assert_eq!(token.as_hex(), read_back.as_hex());
    }

    #[test]
    fn config_copy_is_written_even_if_the_working_dir_write_fails() {
        let dir = tempfile::tempdir().unwrap();
        let unwritable = dir.path().join("missing-dir").join(".dora-token");
        let config = dir.path().join("config").join(".dora-token");

        let token = generate_token();
        assert!(write_token_with_config_copy(&unwritable, Some(&config), &token).is_err());
        let read_back = read_token_from_path(&config).unwrap().unwrap();
        assert_eq!(read_back.as_hex(), token.as_hex());
    }

    #[test]
    fn constant_time_eq_works() {
        assert!(constant_time_eq(b"hello", b"hello"));
        assert!(!constant_time_eq(b"hello", b"world"));
        assert!(!constant_time_eq(b"hello", b"hell"));
        assert!(!constant_time_eq(b"", b"x"));
        assert!(constant_time_eq(b"", b""));
    }
}