Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
7.9 KB
Raw Blame
//! This install's own root bearer: minted by `init` on a fresh data dir and by
//! `ai-memory auth enable`, stored at `<data_dir>/auth-tokens/default`, and
//! named by `[auth].bearer_token_file` so `Config::load` reads it once.
//!
//! The token is read from that file by the server and every thin client, and
//! copied into the hook credential files (`auth-token`, `auth-header`) that
//! every hook front door already reads. It never goes into a harness config or
//! onto a command line (#552).

use std::path::{Path, PathBuf};

use anyhow::{Context as _, Result};

use ai_memory_mcp::auth::generate_token_hex;

/// Bytes of OS CSPRNG entropy in a generated root bearer: 64 hex characters,
/// the same strength `ai-memory generate-auth-token` prints by default.
const ROOT_TOKEN_BYTES: usize = 32;

/// The root bearer after [`provision_root_token`].
pub(crate) struct RootToken {
    pub(crate) path: PathBuf,
    pub(crate) token: String,
    /// False when an existing token was reused.
    pub(crate) created: bool,
}

/// Reuse the token at `path`, or mint one there (`0600`, atomic) when the file
/// is missing or blank. Reuse is what makes `auth enable` idempotent and keeps
/// a forced `init` from rotating a credential every client already holds.
///
/// # Errors
/// Fails when the OS RNG fails or the file cannot be written.
pub(crate) fn provision_root_token(path: &Path) -> Result<RootToken> {
    if let Some(token) = crate::config::read_trimmed_secret(path) {
        return Ok(RootToken {
            path: path.to_path_buf(),
            token,
            created: false,
        });
    }
    let token = generate_token_hex(ROOT_TOKEN_BYTES)
        .map_err(|e| anyhow::anyhow!("generating the root bearer token: {e}"))?;
    crate::server_profiles::store_root_token(path, &token)
        .with_context(|| format!("writing the root bearer token to {}", path.display()))?;
    Ok(RootToken {
        path: path.to_path_buf(),
        token,
        created: true,
    })
}

/// What [`seed_hook_credential`] found.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum HookCredential {
    /// No hook credential was stored; the root bearer now is.
    Seeded,
    /// The stored hook credential already is the root bearer.
    Current,
    /// A different credential is stored (an `ai-memory api-key` token for
    /// attribution, say). It is left alone.
    KeptOther,
}

/// Give the installed hooks the root bearer through the files they already
/// read when `AI_MEMORY_AUTH_TOKEN` is unset: `<data_dir>/auth-token` and
/// `<data_dir>/auth-header`, both `0600`, the pair `install-hooks --apply`
/// writes. A different stored credential wins and is kept: it was put there
/// on purpose.
///
/// # Errors
/// Propagates write failures.
pub(crate) fn seed_hook_credential(data_dir: &Path, token: &str) -> Result<HookCredential> {
    match crate::config::read_hook_auth_token(data_dir) {
        Some(existing) if existing == token => Ok(HookCredential::Current),
        Some(_) => Ok(HookCredential::KeptOther),
        None => {
            crate::config::store_hook_auth_token(data_dir, token).with_context(|| {
                format!(
                    "writing the hook credential files under {}",
                    data_dir.display()
                )
            })?;
            Ok(HookCredential::Seeded)
        }
    }
}

/// The command `status` and `doctor` name as the fix for an unauthenticated
/// loopback server.
pub(crate) const AUTH_ENABLE_FIX: &str = "ai-memory auth enable";

/// The server's auth posture as `status` and `doctor` report it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
#[serde(rename_all = "snake_case")]
pub(crate) enum AuthPosture {
    /// The server requires a bearer token (or the client sends one).
    Token,
    /// The server answered without a credential on a loopback address: safe
    /// from the network, open to every local process and browser page.
    NoneLoopback,
    /// The server answered without a credential on a non-loopback address.
    None,
}

impl AuthPosture {
    /// `server_open` is whether the server is known to answer without a
    /// credential.
    pub(crate) fn classify(server_open: bool, server_url: &str) -> Self {
        match (server_open, crate::http_client::is_loopback_url(server_url)) {
            (false, _) => Self::Token,
            (true, true) => Self::NoneLoopback,
            (true, false) => Self::None,
        }
    }

    /// `auth: ...` text, with the fix on the same line when there is one.
    pub(crate) fn line(self) -> String {
        match self {
            Self::Token => "bearer token".to_owned(),
            Self::NoneLoopback => format!("none (loopback) — fix: `{AUTH_ENABLE_FIX}`"),
            Self::None => "none — set AI_MEMORY_AUTH_TOKEN on the server".to_owned(),
        }
    }

    /// The fix command, for JSON output.
    pub(crate) fn fix(self) -> Option<&'static str> {
        matches!(self, Self::NoneLoopback).then_some(AUTH_ENABLE_FIX)
    }
}

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

    #[test]
    fn posture_names_the_fix_only_for_an_open_loopback_server() {
        let open_local = AuthPosture::classify(true, "http://127.0.0.1:49374");
        assert_eq!(open_local, AuthPosture::NoneLoopback);
        assert_eq!(
            open_local.line(),
            "none (loopback) — fix: `ai-memory auth enable`"
        );
        assert_eq!(open_local.fix(), Some("ai-memory auth enable"));
        assert_eq!(
            AuthPosture::classify(true, "http://localhost:49374/"),
            AuthPosture::NoneLoopback
        );
        assert_eq!(
            AuthPosture::classify(true, "https://memory.example"),
            AuthPosture::None
        );
        let closed = AuthPosture::classify(false, "http://127.0.0.1:49374");
        assert_eq!(closed, AuthPosture::Token);
        assert_eq!(closed.fix(), None);
    }

    #[test]
    fn provisioning_mints_once_then_reuses() {
        let dd = tempfile::tempdir().unwrap();
        let path = crate::server_profiles::root_token_path(dd.path());

        let first = provision_root_token(&path).unwrap();
        assert!(first.created);
        assert_eq!(first.token.len(), ROOT_TOKEN_BYTES * 2);
        assert!(first.token.chars().all(|c| c.is_ascii_hexdigit()));

        let second = provision_root_token(&path).unwrap();
        assert!(
            !second.created,
            "an existing token is reused, never rotated"
        );
        assert_eq!(second.token, first.token);

        // A blank file is not a token.
        std::fs::write(&path, "  \n").unwrap();
        let third = provision_root_token(&path).unwrap();
        assert!(third.created);
        assert_ne!(third.token, first.token);
    }

    #[cfg(unix)]
    #[test]
    fn the_root_bearer_is_owner_only() {
        use std::os::unix::fs::PermissionsExt as _;
        let dd = tempfile::tempdir().unwrap();
        let path = crate::server_profiles::root_token_path(dd.path());
        provision_root_token(&path).unwrap();
        let mode = |p: &Path| std::fs::metadata(p).unwrap().permissions().mode() & 0o777;
        assert_eq!(mode(&path), 0o600);
        assert_eq!(mode(path.parent().unwrap()), 0o700);
    }

    #[test]
    fn seeding_never_replaces_a_different_hook_credential() {
        let dd = tempfile::tempdir().unwrap();
        assert_eq!(
            seed_hook_credential(dd.path(), "root").unwrap(),
            HookCredential::Seeded
        );
        assert_eq!(
            crate::config::read_hook_auth_token(dd.path()).as_deref(),
            Some("root")
        );
        assert_eq!(
            seed_hook_credential(dd.path(), "root").unwrap(),
            HookCredential::Current
        );

        crate::config::store_hook_auth_token(dd.path(), "aim_user_key").unwrap();
        assert_eq!(
            seed_hook_credential(dd.path(), "root").unwrap(),
            HookCredential::KeptOther
        );
        assert_eq!(
            crate::config::read_hook_auth_token(dd.path()).as_deref(),
            Some("aim_user_key")
        );
    }
}