Skip to content

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

Rust
24.3 KB
Raw Blame
//! `ai-memory auth enable` — require a bearer token on this install's server.
//!
//! The opt-in for installs that predate the new-install default: it does what
//! `init` does on a fresh data dir, then re-points the wiring that already
//! exists at the token. Idempotent, so a second run changes nothing:
//!
//! 1. reuse `[auth].bearer_token_file`'s token, or mint
//!    `<data_dir>/auth-tokens/default` (`0600`);
//! 2. record `bearer_token_file` in `config.toml`, keeping its comments;
//! 3. give the hooks the token through `auth-token` / `auth-header`, the files
//!    every hook front door reads, unless another credential is stored there;
//! 4. re-register every MCP client whose `ai-memory` entry points at this
//!    server, through `install-mcp`: Claude Code gets the session-aware
//!    `mcp-bridge` entry, Codex and Prime Agent a reference to
//!    `$AI_MEMORY_AUTH_TOKEN`, every other client a stdio entry for the
//!    session-less bridge, which reads the token file itself. A client that can
//!    only hold a literal header (ZCode) is listed for a manual change.
//!
//! The token is never printed and never written into a harness config.

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

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

use crate::cli::{AuthEnableArgs, InstallMcpArgs, McpClient, SchemaFlavor};
use crate::commands::install_mcp::{self, mcp_server_url_from_base};
use crate::commands::path_util::display_path;
use crate::config::Config;
use crate::local_auth::{self, HookCredential};
use crate::server_profiles::{self, ProfileName};

/// The MCP entry name `install-mcp` writes by default.
const ENTRY_NAME: &str = "ai-memory";

/// What happened to one client's `ai-memory` MCP entry. Clients without one
/// are not listed.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum Wiring {
    /// Re-registered through `install-mcp` so it reaches the token file.
    Rewired,
    /// The entry targets another server; it is left alone.
    OtherServer(String),
    /// It targets this server but could not be re-registered; the reason
    /// says what to do by hand.
    Manual(String),
}

/// One client's line in the outcome.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct ClientWiring {
    pub(crate) client: McpClient,
    pub(crate) path: PathBuf,
    pub(crate) wiring: Wiring,
}

/// Where each client keeps its MCP config; injectable so tests never touch a
/// real harness config.
pub(crate) type ConfigLocator<'a> = &'a dyn Fn(McpClient) -> Option<PathBuf>;

/// The result of one `auth enable`.
#[derive(Debug)]
pub(crate) struct EnableOutcome {
    /// A bearer was already supplied inline (`AI_MEMORY_AUTH_TOKEN` or
    /// `[auth].bearer_token`); nothing was changed.
    pub(crate) already_inline: bool,
    pub(crate) token_path: PathBuf,
    pub(crate) token_created: bool,
    pub(crate) config_path: PathBuf,
    pub(crate) config_changed: bool,
    pub(crate) hooks: Option<HookCredential>,
    pub(crate) mcp: Vec<ClientWiring>,
}

/// Run `auth enable`.
///
/// # Errors
/// Fails when a server profile named `default` would share the token file,
/// when `servers.toml` or `config.toml` cannot be parsed, or on a failed write.
pub fn run(config: &Config, args: &AuthEnableArgs, config_path: Option<&Path>) -> Result<()> {
    let locate = |client: McpClient| install_mcp::mcp_config_path(client).ok();
    let locator: Option<ConfigLocator<'_>> = (!args.no_mcp).then_some(&locate as _);
    let outcome = enable(config, config_path, locator)?;
    print_outcome(&outcome);
    Ok(())
}

pub(crate) fn enable(
    config: &Config,
    config_path: Option<&Path>,
    locate: Option<ConfigLocator<'_>>,
) -> Result<EnableOutcome> {
    let data_dir = &config.data_dir;
    let config_path = config_path.map_or_else(|| data_dir.join("config.toml"), PathBuf::from);
    let token_path = config.auth.token_file_path().map_or_else(
        || server_profiles::root_token_path(data_dir),
        Path::to_path_buf,
    );

    if config.auth.renderable_bearer_token().is_some() {
        return Ok(EnableOutcome {
            already_inline: true,
            token_path,
            token_created: false,
            config_path,
            config_changed: false,
            hooks: None,
            mcp: Vec::new(),
        });
    }

    refuse_a_profile_sharing_the_token(data_dir, &token_path)?;
    let minted = local_auth::provision_root_token(&token_path)?;
    let config_changed = if config.auth.bearer_token_file.is_none() {
        record_token_file(&config_path)?
    } else {
        false
    };
    let hooks = local_auth::seed_hook_credential(data_dir, &minted.token)?;

    let mut enabled = config.clone();
    enabled
        .auth
        .adopt_token_file(minted.path.clone(), minted.token.clone());
    let mcp = locate.map_or_else(Vec::new, |locate| rewire_clients(&enabled, locate));

    Ok(EnableOutcome {
        already_inline: false,
        token_path: minted.path,
        token_created: minted.created,
        config_path,
        config_changed,
        hooks: Some(hooks),
        mcp,
    })
}

/// A registered server profile named `default` reads `auth-tokens/default`
/// too: the hook would then present this server's root bearer to that
/// profile's server.
fn refuse_a_profile_sharing_the_token(data_dir: &Path, token_path: &Path) -> Result<()> {
    let Some(name) = ProfileName::parse(server_profiles::ROOT_TOKEN_NAME) else {
        return Ok(());
    };
    if !server_profiles::profile_shares_root_token(data_dir, &name, Some(token_path)) {
        return Ok(());
    }
    if server_profiles::root_token_name_is_registered(data_dir)
        .context("reading servers.toml to check the `default` profile name")?
    {
        bail!(
            "a server profile named `default` is registered, and its token file is the one \
             `auth enable` would use for this server's root bearer. Re-register that profile \
             under another name (`ai-memory server add <name> ...`, then \
             `ai-memory server remove default`) and run `ai-memory auth enable` again."
        );
    }
    Ok(())
}

/// Set `[auth].bearer_token_file` in the config file, keeping every comment
/// and other key. Creates the file (owner-only) when the install never had
/// one. Returns whether the file changed.
fn record_token_file(config_path: &Path) -> Result<bool> {
    let existing = match std::fs::read_to_string(config_path) {
        Ok(text) => Some(text),
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => None,
        Err(e) => {
            return Err(e).with_context(|| format!("reading {}", display_path(config_path)));
        }
    };
    let mut doc: toml_edit::DocumentMut = existing
        .as_deref()
        .unwrap_or_default()
        .parse()
        .with_context(|| format!("parsing {}", display_path(config_path)))?;
    let auth = doc
        .entry("auth")
        .or_insert_with(|| toml_edit::Item::Table(toml_edit::Table::new()))
        .as_table_like_mut()
        .with_context(|| format!("`auth` in {} is not a table", display_path(config_path)))?;
    if auth.get("bearer_token_file").is_some() {
        return Ok(false);
    }
    auth.insert(
        "bearer_token_file",
        toml_edit::value(server_profiles::ROOT_TOKEN_RELATIVE),
    );

    #[cfg(unix)]
    let mode = {
        use std::os::unix::fs::PermissionsExt as _;
        std::fs::metadata(config_path)
            .ok()
            .map(|meta| meta.permissions().mode())
    };
    if let Some(parent) = config_path.parent() {
        crate::commands::path_util::create_private_dir(parent)
            .with_context(|| format!("creating {}", display_path(parent)))?;
    }
    // The atomic write's temp file is owner-only; an existing config keeps
    // the mode it had (a packaged one may be group-readable on purpose).
    ai_memory_wiki::write_atomic(config_path, doc.to_string().as_bytes())
        .with_context(|| format!("writing {}", display_path(config_path)))?;
    #[cfg(unix)]
    if let Some(mode) = mode {
        use std::os::unix::fs::PermissionsExt as _;
        std::fs::set_permissions(config_path, std::fs::Permissions::from_mode(mode))
            .with_context(|| format!("restoring the mode of {}", display_path(config_path)))?;
    }
    Ok(true)
}

/// Clients `install-mcp --apply` writes a config file for. Pi has no MCP
/// config (its extension reads the hook credential file), and DeepSeek
/// Harness and Hermes Agent are print-only, so none has an entry to
/// re-point. Hermes' entry is a bridge carrying no token, so a new token
/// needs no edit there either.
fn rewirable_clients() -> impl Iterator<Item = McpClient> {
    <McpClient as clap::ValueEnum>::value_variants()
        .iter()
        .copied()
        .filter(|client| !matches!(client, McpClient::Pi | McpClient::Dsh | McpClient::Hermes))
}

/// The endpoint without a `?flavor=` (or any) query, normalised to `/mcp`.
fn bare_endpoint(url: &str) -> String {
    mcp_server_url_from_base(url.split('?').next().unwrap_or(url))
}

/// The schema flavor an existing entry's URL pinned, so re-registering keeps
/// the dialect the operator chose with `--flavor`.
fn pinned_flavor(url: &str) -> Option<SchemaFlavor> {
    let query = url.split_once('?')?.1;
    <SchemaFlavor as clap::ValueEnum>::value_variants()
        .iter()
        .copied()
        .find(|flavor| {
            query
                .split('&')
                .any(|pair| pair == format!("flavor={}", flavor.marker()))
        })
}

/// Re-register every client whose `ai-memory` entry targets this server. One
/// client failing never stops the others: it is reported as manual.
fn rewire_clients(config: &Config, locate: ConfigLocator<'_>) -> Vec<ClientWiring> {
    let ours = bare_endpoint(&config.server_url);
    let mut outcome = Vec::new();
    for client in rewirable_clients() {
        let Some(path) = locate(client) else {
            continue;
        };
        let wiring = match install_mcp::existing_entry_endpoint(client, &path, ENTRY_NAME) {
            Ok(None) => continue,
            Err(e) => Wiring::Manual(format!("{e:#}")),
            Ok(Some(url)) if bare_endpoint(&url) != ours => Wiring::OtherServer(url),
            Ok(Some(url)) => match rewire(config, client, &path, &ours, pinned_flavor(&url)) {
                Ok(()) => Wiring::Rewired,
                Err(e) => Wiring::Manual(format!("{e:#}")),
            },
        };
        outcome.push(ClientWiring {
            client,
            path,
            wiring,
        });
    }
    outcome
}

fn rewire(
    config: &Config,
    client: McpClient,
    path: &Path,
    url: &str,
    flavor: Option<SchemaFlavor>,
) -> Result<()> {
    let args = InstallMcpArgs {
        client,
        server_url: Some(url.to_owned()),
        name: ENTRY_NAME.to_owned(),
        auth_token: None,
        apply: true,
        config_file: Some(path.to_path_buf()),
        session_aware: false,
        flavor,
        token_env_var: false,
        stdio_bridge: false,
        bridge_data_dir: None,
    };
    // Name the OpenCode major version outright: both share one file, and
    // probing `opencode --version` here would pick one for both locations.
    let dialect = match client {
        McpClient::OpenCode => Some(ai_memory_workstream::OpenCodeDialect::V1),
        McpClient::OpenCode2 => Some(ai_memory_workstream::OpenCodeDialect::V2),
        _ => None,
    };
    install_mcp::run_with_opencode_dialect(config, args, dialect)
}

fn print_outcome(outcome: &EnableOutcome) {
    if outcome.already_inline {
        println!(
            "auth: already required by AI_MEMORY_AUTH_TOKEN or [auth].bearer_token; nothing changed."
        );
        return;
    }
    println!(
        "auth: bearer token {} at {} (owner-only)",
        if outcome.token_created {
            "generated"
        } else {
            "kept"
        },
        display_path(&outcome.token_path)
    );
    println!(
        "config: {} {}",
        if outcome.config_changed {
            "recorded [auth].bearer_token_file in"
        } else {
            "already names the token file:"
        },
        display_path(&outcome.config_path)
    );
    match outcome.hooks {
        Some(HookCredential::Seeded) => {
            println!("hooks: given the token through the hook credential files");
        }
        Some(HookCredential::Current) => println!("hooks: already use the token"),
        Some(HookCredential::KeptOther) => println!(
            "hooks: another credential is stored for them and was kept; re-run \
             `ai-memory install-hooks --agent <agent> --apply` to switch them to this token"
        ),
        None => {}
    }
    for line in &outcome.mcp {
        let client = format!("{:?}", line.client);
        match &line.wiring {
            Wiring::Rewired => println!(
                "mcp {client}: re-registered in {} so it reads the token without holding it",
                display_path(&line.path)
            ),
            Wiring::OtherServer(url) => {
                println!("mcp {client}: targets {url}, another server; left unchanged");
            }
            Wiring::Manual(reason) => {
                println!("mcp {client}: needs a manual change: {reason}");
            }
        }
    }
    println!("Restart the ai-memory server for it to require the token.");
}

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

    fn config_in(data_dir: &Path) -> Config {
        Config::load_with_runtime_env(
            None,
            Some(data_dir.to_path_buf()),
            crate::config::RuntimeEnv::default(),
        )
        .unwrap()
    }

    /// The pre-default config `init` wrote: a token pepper and comments, no
    /// bearer.
    fn pre_a1_install(data_dir: &Path) {
        std::fs::create_dir_all(data_dir).unwrap();
        std::fs::write(
            data_dir.join("config.toml"),
            "# operator comment\nlog_level = \"info\"\n\n[auth]\n# keep me\nsecure_cookie = false\ntoken_pepper = \"pp\"\n",
        )
        .unwrap();
    }

    /// Every file under `root`, read as text where it is text.
    fn files_under(root: &Path) -> Vec<(PathBuf, String)> {
        let mut out = Vec::new();
        let mut stack = vec![root.to_path_buf()];
        while let Some(dir) = stack.pop() {
            for entry in std::fs::read_dir(&dir).unwrap() {
                let path = entry.unwrap().path();
                if path.is_dir() {
                    stack.push(path);
                } else if let Ok(text) = std::fs::read_to_string(&path) {
                    out.push((path, text));
                }
            }
        }
        out
    }

    /// Every client `rewire_clients` considers, each wired the pre-default way
    /// (`install-mcp --apply`, no token) into its own file under `home`.
    fn wire_every_client_over_http(home: &Path, url: &str) -> Vec<(McpClient, PathBuf)> {
        let open = Config::default();
        rewirable_clients()
            .map(|client| {
                let ext = if matches!(client, McpClient::Codex | McpClient::Grok) {
                    "toml"
                } else {
                    "json"
                };
                let path = home.join(format!("{client:?}.{ext}"));
                rewire(&open, client, &path, url, None)
                    .unwrap_or_else(|e| panic!("pre-default {client:?} install: {e:#}"));
                (client, path)
            })
            .collect()
    }

    fn locator(files: &[(McpClient, PathBuf)]) -> impl Fn(McpClient) -> Option<PathBuf> + '_ {
        move |client| {
            files
                .iter()
                .find(|(c, _)| *c == client)
                .map(|(_, path)| path.clone())
        }
    }

    /// `auth enable` on a pre-default install: token minted, the key recorded
    /// with the operator's comments intact, the hooks given the token, and
    /// every client whose entry points at this server re-registered (ZCode,
    /// which only takes a literal header, listed as manual). Run twice, the
    /// second run changes nothing, and the token appears in no harness config.
    #[test]
    fn enable_twice_is_idempotent_and_leaks_the_token_into_no_harness_config() {
        let tmp = tempfile::tempdir().unwrap();
        let data_dir = tmp.path().join("data");
        let home = tmp.path().join("home");
        std::fs::create_dir_all(&home).unwrap();
        pre_a1_install(&data_dir);
        let files = wire_every_client_over_http(&home, "http://127.0.0.1:49374/mcp");
        let locate = locator(&files);

        let first = enable(&config_in(&data_dir), None, Some(&locate)).unwrap();
        assert!(first.token_created);
        assert!(first.config_changed);
        assert_eq!(first.hooks, Some(HookCredential::Seeded));
        assert_eq!(first.mcp.len(), files.len(), "{:?}", first.mcp);
        for line in &first.mcp {
            match line.client {
                McpClient::Zcode => assert!(
                    matches!(&line.wiring, Wiring::Manual(reason) if reason.contains("ZCode")),
                    "{line:?}"
                ),
                _ => assert_eq!(line.wiring, Wiring::Rewired, "{line:?}"),
            }
        }

        let token = crate::config::read_trimmed_secret(&first.token_path).unwrap();
        let config_text = std::fs::read_to_string(data_dir.join("config.toml")).unwrap();
        assert!(config_text.contains("# operator comment"), "{config_text}");
        assert!(config_text.contains("# keep me"), "{config_text}");
        assert!(
            config_text.contains("token_pepper = \"pp\""),
            "{config_text}"
        );
        assert!(
            config_text.contains("bearer_token_file = \"auth-tokens/default\""),
            "{config_text}"
        );
        let claude = &files
            .iter()
            .find(|(c, _)| *c == McpClient::ClaudeCode)
            .unwrap()
            .1;
        let entry: serde_json::Value =
            serde_json::from_str(&std::fs::read_to_string(claude).unwrap()).unwrap();
        let entry = &entry["mcpServers"]["ai-memory"];
        assert_eq!(entry["type"], "stdio");
        assert_eq!(entry["args"][0], "mcp-bridge");
        assert!(entry.get("env").is_none(), "no token env: {entry}");
        let cursor = &files
            .iter()
            .find(|(c, _)| *c == McpClient::Cursor)
            .unwrap()
            .1;
        let entry: serde_json::Value =
            serde_json::from_str(&std::fs::read_to_string(cursor).unwrap()).unwrap();
        assert_eq!(
            entry["mcpServers"]["ai-memory"]["args"][1],
            "--no-session-id"
        );
        assert_eq!(
            config_in(&data_dir).auth.bearer_token.as_deref(),
            Some(token.as_str())
        );
        let after_first: Vec<String> = files
            .iter()
            .map(|(_, path)| std::fs::read_to_string(path).unwrap())
            .collect();

        let second = enable(&config_in(&data_dir), None, Some(&locate)).unwrap();
        assert!(!second.token_created);
        assert!(!second.config_changed);
        assert_eq!(second.hooks, Some(HookCredential::Current));
        assert_eq!(second.mcp, first.mcp);
        assert_eq!(
            crate::config::read_trimmed_secret(&second.token_path),
            Some(token.clone())
        );
        assert_eq!(
            std::fs::read_to_string(data_dir.join("config.toml")).unwrap(),
            config_text
        );
        for ((client, path), before) in files.iter().zip(&after_first) {
            assert_eq!(
                &std::fs::read_to_string(path).unwrap(),
                before,
                "{client:?} changed on the second run"
            );
        }

        for (path, text) in files_under(&home) {
            assert!(
                !text.contains(&token),
                "token leaked into {}",
                path.display()
            );
        }
        // Compare canonical paths: the token path comes from the canonical
        // data dir, which differs from the walked temp path on macOS
        // (`/var` -> `/private/var`) and Windows (`\\?\` and 8.3 names).
        let canonical = |p: &Path| std::fs::canonicalize(p).unwrap_or_else(|_| p.to_path_buf());
        let allowed_paths = [
            canonical(&first.token_path),
            canonical(&crate::config::hook_auth_token_path_in(&data_dir)),
            canonical(&crate::config::hook_auth_header_path_in(&data_dir)),
        ];
        for (path, text) in files_under(&data_dir) {
            let allowed = allowed_paths.contains(&canonical(&path));
            assert!(
                allowed || !text.contains(&token),
                "token copied to an unexpected file {}",
                path.display()
            );
        }
    }

    /// Control: an entry for a remote server keeps its destination.
    #[test]
    fn enable_leaves_an_entry_for_another_server_alone() {
        let tmp = tempfile::tempdir().unwrap();
        let data_dir = tmp.path().join("data");
        pre_a1_install(&data_dir);
        let files = wire_every_client_over_http(tmp.path(), "https://team.example/mcp");
        let before: Vec<String> = files
            .iter()
            .map(|(_, path)| std::fs::read_to_string(path).unwrap())
            .collect();
        let locate = locator(&files);

        let outcome = enable(&config_in(&data_dir), None, Some(&locate)).unwrap();
        assert_eq!(outcome.mcp.len(), files.len());
        for line in &outcome.mcp {
            assert!(
                matches!(&line.wiring, Wiring::OtherServer(url) if url.starts_with("https://team.example/mcp")),
                "{line:?}"
            );
        }
        for ((client, path), before) in files.iter().zip(&before) {
            assert_eq!(
                &std::fs::read_to_string(path).unwrap(),
                before,
                "{client:?}"
            );
        }
    }

    /// A registered profile named `default` would read the same file as the
    /// root bearer and present it to its own server: refused before anything
    /// is written.
    #[test]
    fn enable_refuses_while_a_default_profile_would_share_the_token() {
        let tmp = tempfile::tempdir().unwrap();
        let data_dir = tmp.path().join("data");
        pre_a1_install(&data_dir);
        let default = ProfileName::parse("default").unwrap();
        server_profiles::add(
            &data_dir,
            &default,
            "https://team.example",
            &[],
            Some("team"),
        )
        .unwrap();

        let err = enable(&config_in(&data_dir), None, None).unwrap_err();
        assert!(format!("{err:#}").contains("named `default`"), "{err:#}");
        assert_eq!(
            server_profiles::read_token(&data_dir, &default).as_deref(),
            Some("team"),
            "the profile's own token is untouched"
        );
        assert!(
            !std::fs::read_to_string(data_dir.join("config.toml"))
                .unwrap()
                .contains("bearer_token_file")
        );

        // Control: another profile name does not conflict.
        server_profiles::remove(&data_dir, &default).unwrap();
        let team = ProfileName::parse("team").unwrap();
        server_profiles::add(&data_dir, &team, "https://team.example", &[], Some("team")).unwrap();
        assert!(enable(&config_in(&data_dir), None, None).is_ok());
    }

    /// An inline bearer is already enforcement; `auth enable` adds nothing.
    #[test]
    fn enable_with_an_inline_bearer_changes_nothing() {
        let tmp = tempfile::tempdir().unwrap();
        let data_dir = tmp.path().join("data");
        pre_a1_install(&data_dir);
        let mut config = config_in(&data_dir);
        config.auth.bearer_token = Some("inline".into());

        let outcome = enable(&config, None, None).unwrap();
        assert!(outcome.already_inline);
        assert!(!server_profiles::root_token_path(&data_dir).exists());
        assert!(crate::config::read_hook_auth_token(&data_dir).is_none());
    }

    /// An install that never had a config file gets one, owner-only.
    #[test]
    fn enable_without_a_config_file_creates_one() {
        let tmp = tempfile::tempdir().unwrap();
        let data_dir = tmp.path().join("data");
        std::fs::create_dir_all(&data_dir).unwrap();

        enable(&config_in(&data_dir), None, None).unwrap();
        let loaded = config_in(&data_dir);
        assert!(loaded.auth.bearer_token.is_some());
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt as _;
            let mode = std::fs::metadata(data_dir.join("config.toml"))
                .unwrap()
                .permissions()
                .mode();
            assert_eq!(mode & 0o777, 0o600);
        }
    }
}