Skip to content

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

Rust
21.3 KB
Raw Blame
//! Provider authentication material.
//!
//! This module is the narrow boundary between configuration / login flows and
//! provider wire clients. API-key, OAuth-token-file, and token-exchange backed
//! providers extend this layer instead of teaching each provider to read env
//! vars directly.

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

use secrecy::SecretString;

use crate::error::{LlmError, LlmResult};

/// Credential source used for diagnostics and future `auth status` output.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CredentialSource {
    /// Explicit CLI argument, such as `llm-test --api-key`.
    CliOverride,
    /// Process environment variable.
    Environment {
        /// Environment variable name.
        name: &'static str,
    },
    /// On-disk token file under ai-memory's data dir.
    TokenFile,
    /// No credential was supplied.
    NotProvided,
}

/// Auth requirement declared by a provider.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AuthRequirement {
    /// Provider cannot be constructed without an API key.
    RequiredApiKey {
        /// Environment variable operators normally use for this API key.
        env_var: &'static str,
    },
    /// Provider accepts an API key but can also run without one.
    OptionalApiKey {
        /// Environment variable operators normally use for this API key.
        env_var: &'static str,
    },
    /// Provider requires a ChatGPT/Codex OAuth token file.
    OpenAiOAuthToken,
    /// Provider reuses the Codex CLI auth file and delegates refresh to Codex.
    CodexAuthFile,
    /// Provider requires a GitHub token or stored auth for Copilot.
    CopilotToken,
    /// Provider requires an Anthropic OAuth subscription token
    /// (from `claude setup-token`).
    AnthropicOAuthToken,
    /// Provider shells out to the logged-in Cursor Agent CLI.
    CursorCli,
}

/// Resolved Copilot auth inputs.
#[derive(Debug, Clone)]
pub struct CopilotAuth {
    /// Shared auth file under ai-memory's data dir.
    pub token_file: PathBuf,
    /// GitHub user token from env/config, if present.
    pub github_token: Option<SecretString>,
    /// Direct short-lived Copilot API token from env/config, if present.
    pub direct_api_token: Option<SecretString>,
    /// Optional Copilot API base URL override.
    pub api_base_url: Option<String>,
}

/// Resolved, non-secret inputs for the Codex-backed provider.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CodexAuth {
    /// Codex CLI-owned authentication file.
    pub auth_file: PathBuf,
    /// Codex executable used only for delegated refresh.
    pub executable: PathBuf,
}

/// Resolved inputs for the Cursor Agent CLI provider.
///
/// The child process reads untrusted captured session text, so it never
/// inherits the server's environment: [`CursorAuth::new`] keeps only the
/// variables the CLI needs to find its login, locale and network
/// (see [`crate::cursor_agent::cursor_child_env`]).
#[derive(Clone, PartialEq, Eq)]
pub struct CursorAuth {
    /// `agent` binary, or the path in `AI_MEMORY_CURSOR_AGENT`.
    pub executable: PathBuf,
    /// Directory each request's private workspace is created under.
    pub(crate) temp_root: PathBuf,
    /// The allowlisted environment the child runs with, and nothing else.
    pub(crate) child_env: Vec<(OsString, OsString)>,
}

impl CursorAuth {
    /// Resolve Cursor inputs from values captured once at config load.
    ///
    /// `process_env` is the server's environment; only allowlisted entries
    /// are kept. `temp_root` must be absolute; the provider refuses to run
    /// otherwise rather than create a workspace relative to its cwd.
    #[must_use]
    pub fn new(
        executable: impl Into<PathBuf>,
        temp_root: impl Into<PathBuf>,
        process_env: &[(OsString, OsString)],
    ) -> Self {
        Self {
            executable: executable.into(),
            temp_root: temp_root.into(),
            child_env: crate::cursor_agent::cursor_child_env(process_env),
        }
    }

    /// Names of the environment variables the child receives.
    pub fn child_env_names(&self) -> impl Iterator<Item = &OsString> {
        self.child_env.iter().map(|(name, _)| name)
    }
}

impl std::fmt::Debug for CursorAuth {
    // Values stay out of logs: `CURSOR_API_KEY` is allowlisted.
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("CursorAuth")
            .field("executable", &self.executable)
            .field("temp_root", &self.temp_root)
            .field("child_env", &self.child_env_names().collect::<Vec<_>>())
            .finish()
    }
}

/// Materialized provider credential.
#[derive(Debug, Clone)]
pub enum Credential {
    /// Static API key / bearer secret.
    ApiKey(SecretString),
    /// Path to the OpenAI OAuth token file.
    OpenAiOAuthTokenFile(PathBuf),
    /// Paths needed to reuse Codex CLI authentication.
    Codex(CodexAuth),
    /// GitHub Copilot auth inputs.
    Copilot(CopilotAuth),
    /// Anthropic OAuth subscription token from `claude setup-token`.
    AnthropicOAuthToken(SecretString),
    /// Cursor Agent CLI executable. Login lives in the Cursor app, not here.
    Cursor(CursorAuth),
}

/// Resolved authentication for one provider instance.
#[derive(Debug, Clone)]
pub struct ProviderAuth {
    requirement: AuthRequirement,
    credential: Option<Credential>,
    source: CredentialSource,
}

impl ProviderAuth {
    /// Resolve a required API-key auth method from an environment value.
    #[must_use]
    pub fn required_api_key_from_env(env_var: &'static str, key: Option<SecretString>) -> Self {
        Self::from_api_key(
            AuthRequirement::RequiredApiKey { env_var },
            key,
            CredentialSource::Environment { name: env_var },
        )
    }

    /// Resolve an optional API-key auth method from an environment value.
    #[must_use]
    pub fn optional_api_key_from_env(env_var: &'static str, key: Option<SecretString>) -> Self {
        Self::from_api_key(
            AuthRequirement::OptionalApiKey { env_var },
            key,
            CredentialSource::Environment { name: env_var },
        )
    }

    /// Resolve OpenAI OAuth auth from a token file path.
    #[must_use]
    pub fn openai_oauth_token_file(path: impl Into<PathBuf>) -> Self {
        Self {
            requirement: AuthRequirement::OpenAiOAuthToken,
            credential: Some(Credential::OpenAiOAuthTokenFile(path.into())),
            source: CredentialSource::TokenFile,
        }
    }

    /// Resolve Codex auth from already-resolved auth-file and executable paths.
    #[must_use]
    pub fn codex(auth_file: impl Into<PathBuf>, executable: impl Into<PathBuf>) -> Self {
        Self {
            requirement: AuthRequirement::CodexAuthFile,
            credential: Some(Credential::Codex(CodexAuth {
                auth_file: auth_file.into(),
                executable: executable.into(),
            })),
            source: CredentialSource::TokenFile,
        }
    }

    /// Resolve Copilot auth from a shared token file plus optional env tokens.
    #[must_use]
    pub fn copilot(
        token_file: impl Into<PathBuf>,
        github_token: Option<SecretString>,
        direct_api_token: Option<SecretString>,
        api_base_url: Option<String>,
    ) -> Self {
        Self {
            requirement: AuthRequirement::CopilotToken,
            credential: Some(Credential::Copilot(CopilotAuth {
                token_file: token_file.into(),
                github_token,
                direct_api_token,
                api_base_url,
            })),
            source: CredentialSource::TokenFile,
        }
    }

    /// Resolve Cursor auth from the agent executable and its child inputs.
    #[must_use]
    pub fn cursor(auth: CursorAuth) -> Self {
        Self {
            requirement: AuthRequirement::CursorCli,
            credential: Some(Credential::Cursor(auth)),
            source: CredentialSource::Environment {
                name: "AI_MEMORY_CURSOR_AGENT",
            },
        }
    }

    /// Resolve Anthropic OAuth auth from a subscription token (from `claude setup-token`).
    #[must_use]
    pub fn anthropic_oauth_token(token: Option<SecretString>) -> Self {
        let has_token = token.is_some();
        Self {
            requirement: AuthRequirement::AnthropicOAuthToken,
            credential: token.map(Credential::AnthropicOAuthToken),
            source: if has_token {
                CredentialSource::Environment {
                    name: "ANTHROPIC_OAUTH_TOKEN",
                }
            } else {
                CredentialSource::NotProvided
            },
        }
    }

    fn from_api_key(
        requirement: AuthRequirement,
        key: Option<SecretString>,
        source_if_present: CredentialSource,
    ) -> Self {
        let has_key = key.is_some();
        Self {
            requirement,
            credential: key.map(Credential::ApiKey),
            source: if has_key {
                source_if_present
            } else {
                CredentialSource::NotProvided
            },
        }
    }

    /// Override the resolved credential with a CLI-provided API key.
    #[must_use]
    pub fn with_cli_api_key_override(mut self, key: Option<SecretString>) -> Self {
        if let Some(key) = key {
            self.credential = Some(Credential::ApiKey(key));
            self.source = CredentialSource::CliOverride;
        }
        self
    }

    /// Return the declared auth requirement.
    #[must_use]
    pub const fn requirement(&self) -> AuthRequirement {
        self.requirement
    }

    /// Return where the credential came from, if any.
    #[must_use]
    pub const fn source(&self) -> CredentialSource {
        self.source
    }

    /// Extract a required API key, preserving today's missing-env error shape.
    ///
    /// # Errors
    /// Returns [`LlmError::NotConfigured`] with the required env var name when
    /// the provider requires an API key and none was resolved.
    pub fn require_api_key(&self) -> LlmResult<SecretString> {
        match (&self.requirement, &self.credential) {
            (_, Some(Credential::ApiKey(key))) => Ok(key.clone()),
            (_, Some(Credential::OpenAiOAuthTokenFile(_))) => Err(LlmError::NotConfigured(
                "API key credential expected, got openai-oauth token file".into(),
            )),
            (_, Some(Credential::Codex(_))) => Err(LlmError::NotConfigured(
                "API key credential expected, got codex auth file".into(),
            )),
            (_, Some(Credential::Copilot(_))) => Err(LlmError::NotConfigured(
                "API key credential expected, got copilot auth".into(),
            )),
            (_, Some(Credential::AnthropicOAuthToken(_))) => Err(LlmError::NotConfigured(
                "API key credential expected, got anthropic-oauth token".into(),
            )),
            (_, Some(Credential::Cursor(_))) => Err(LlmError::NotConfigured(
                "API key credential expected, got cursor agent CLI".into(),
            )),
            (AuthRequirement::RequiredApiKey { env_var }, None) => {
                Err(LlmError::NotConfigured((*env_var).into()))
            }
            (AuthRequirement::OptionalApiKey { env_var }, None) => {
                Err(LlmError::NotConfigured((*env_var).into()))
            }
            (AuthRequirement::OpenAiOAuthToken, None) => Err(LlmError::NotConfigured(
                "openai-oauth token file missing; run `ai-memory auth login openai-oauth`".into(),
            )),
            (AuthRequirement::CodexAuthFile, None) => Err(LlmError::NotConfigured(
                "codex auth file missing; run `codex login status` and authenticate Codex again"
                    .into(),
            )),
            (AuthRequirement::CopilotToken, None) => Err(LlmError::NotConfigured(
                "copilot auth missing; run `ai-memory auth login copilot` or set COPILOT_GITHUB_TOKEN"
                    .into(),
            )),
            (AuthRequirement::AnthropicOAuthToken, None) => Err(LlmError::NotConfigured(
                "anthropic-oauth token missing; run `claude setup-token` and set \
                 ANTHROPIC_OAUTH_TOKEN (or CLAUDE_CODE_OAUTH_TOKEN)"
                    .into(),
            )),
            (AuthRequirement::CursorCli, None) => Err(LlmError::NotConfigured(
                "cursor agent executable missing; set AI_MEMORY_CURSOR_AGENT or install `agent`"
                    .into(),
            )),
        }
    }

    /// Extract an optional API key.
    #[must_use]
    pub fn optional_api_key(&self) -> Option<SecretString> {
        match &self.credential {
            Some(Credential::ApiKey(key)) => Some(key.clone()),
            Some(
                Credential::OpenAiOAuthTokenFile(_)
                | Credential::Codex(_)
                | Credential::Copilot(_)
                | Credential::AnthropicOAuthToken(_)
                | Credential::Cursor(_),
            )
            | None => None,
        }
    }

    /// Extract the Anthropic OAuth subscription token.
    ///
    /// # Errors
    /// Returns [`LlmError::NotConfigured`] when no token was resolved.
    pub fn require_anthropic_oauth_token(&self) -> LlmResult<SecretString> {
        match (&self.requirement, &self.credential) {
            (
                AuthRequirement::AnthropicOAuthToken,
                Some(Credential::AnthropicOAuthToken(token)),
            ) => Ok(token.clone()),
            (AuthRequirement::AnthropicOAuthToken, None) => Err(LlmError::NotConfigured(
                "anthropic-oauth token missing; run `claude setup-token` and set \
                 ANTHROPIC_OAUTH_TOKEN (or CLAUDE_CODE_OAUTH_TOKEN)"
                    .into(),
            )),
            _ => Err(LlmError::NotConfigured(
                "anthropic-oauth token credential required".into(),
            )),
        }
    }

    /// Extract the OpenAI OAuth token file path.
    ///
    /// # Errors
    /// Returns [`LlmError::NotConfigured`] if this auth material is not an
    /// OpenAI OAuth token-file credential.
    pub fn require_openai_oauth_token_file(&self) -> LlmResult<&Path> {
        match (&self.requirement, &self.credential) {
            (AuthRequirement::OpenAiOAuthToken, Some(Credential::OpenAiOAuthTokenFile(path))) => {
                Ok(path)
            }
            (AuthRequirement::OpenAiOAuthToken, None) => Err(LlmError::NotConfigured(
                "openai-oauth token file missing; run `ai-memory auth login openai-oauth`".into(),
            )),
            _ => Err(LlmError::NotConfigured(
                "openai-oauth token file credential required".into(),
            )),
        }
    }

    /// Extract the resolved Codex auth inputs.
    ///
    /// # Errors
    /// Returns [`LlmError::NotConfigured`] if this is not Codex auth.
    pub fn require_codex_auth(&self) -> LlmResult<CodexAuth> {
        match (&self.requirement, &self.credential) {
            (AuthRequirement::CodexAuthFile, Some(Credential::Codex(auth))) => Ok(auth.clone()),
            (AuthRequirement::CodexAuthFile, None) => Err(LlmError::NotConfigured(
                "codex auth file missing; run `codex login status` and authenticate Codex again"
                    .into(),
            )),
            _ => Err(LlmError::NotConfigured(
                "codex auth-file credential required".into(),
            )),
        }
    }

    /// Extract the Cursor Agent executable.
    ///
    /// # Errors
    /// Returns [`LlmError::NotConfigured`] if this is not Cursor CLI auth.
    pub fn require_cursor_auth(&self) -> LlmResult<CursorAuth> {
        match (&self.requirement, &self.credential) {
            (AuthRequirement::CursorCli, Some(Credential::Cursor(auth))) => Ok(auth.clone()),
            (AuthRequirement::CursorCli, None) => Err(LlmError::NotConfigured(
                "cursor agent executable missing; set AI_MEMORY_CURSOR_AGENT or install `agent`"
                    .into(),
            )),
            _ => Err(LlmError::NotConfigured(
                "cursor agent credential required".into(),
            )),
        }
    }

    /// Extract Copilot auth inputs.
    ///
    /// # Errors
    /// Returns [`LlmError::NotConfigured`] if this auth material is not a
    /// Copilot credential.
    pub fn require_copilot_auth(&self) -> LlmResult<CopilotAuth> {
        match (&self.requirement, &self.credential) {
            (AuthRequirement::CopilotToken, Some(Credential::Copilot(auth))) => Ok(auth.clone()),
            (AuthRequirement::CopilotToken, None) => Err(LlmError::NotConfigured(
                "copilot auth missing; run `ai-memory auth login copilot` or set COPILOT_GITHUB_TOKEN"
                    .into(),
            )),
            _ => Err(LlmError::NotConfigured(
                "copilot auth credential required".into(),
            )),
        }
    }
}

#[cfg(test)]
mod tests {
    use secrecy::ExposeSecret as _;

    use super::*;

    #[test]
    fn required_api_key_reports_env_name_when_missing() {
        let auth = ProviderAuth::required_api_key_from_env("OPENAI_API_KEY", None);
        let err = auth.require_api_key().unwrap_err();
        assert!(matches!(err, LlmError::NotConfigured(msg) if msg == "OPENAI_API_KEY"));
        assert_eq!(auth.source(), CredentialSource::NotProvided);
    }

    #[test]
    fn required_api_key_returns_secret_when_present() {
        let auth = ProviderAuth::required_api_key_from_env(
            "OPENAI_API_KEY",
            Some(SecretString::from("sk-test")),
        );
        assert_eq!(auth.require_api_key().unwrap().expose_secret(), "sk-test");
        assert_eq!(
            auth.source(),
            CredentialSource::Environment {
                name: "OPENAI_API_KEY"
            }
        );
    }

    #[test]
    fn cli_override_takes_precedence() {
        let auth = ProviderAuth::required_api_key_from_env(
            "OPENAI_API_KEY",
            Some(SecretString::from("env-key")),
        )
        .with_cli_api_key_override(Some(SecretString::from("cli-key")));

        assert_eq!(auth.require_api_key().unwrap().expose_secret(), "cli-key");
        assert_eq!(auth.source(), CredentialSource::CliOverride);
    }

    #[test]
    fn optional_api_key_allows_absence() {
        let auth = ProviderAuth::optional_api_key_from_env("LLM_API_KEY", None);
        assert!(auth.optional_api_key().is_none());
        assert_eq!(auth.source(), CredentialSource::NotProvided);
    }

    #[test]
    fn openai_oauth_token_file_round_trips_path() {
        let auth = ProviderAuth::openai_oauth_token_file("/tmp/oauth_token.json");
        assert_eq!(auth.source(), CredentialSource::TokenFile);
        assert_eq!(
            auth.require_openai_oauth_token_file().unwrap(),
            Path::new("/tmp/oauth_token.json")
        );
    }

    #[test]
    fn copilot_auth_round_trips_inputs() {
        let auth = ProviderAuth::copilot(
            "/tmp/auth.json",
            Some(SecretString::from("ghu-test")),
            None,
            Some("https://api.example.test".into()),
        );
        let copilot = auth.require_copilot_auth().unwrap();
        assert_eq!(copilot.token_file, Path::new("/tmp/auth.json"));
        assert_eq!(copilot.github_token.unwrap().expose_secret(), "ghu-test");
        assert_eq!(
            copilot.api_base_url.as_deref(),
            Some("https://api.example.test")
        );
    }

    #[test]
    fn anthropic_oauth_token_round_trips_secret_and_reports_env_source() {
        let auth = ProviderAuth::anthropic_oauth_token(Some(SecretString::from("oauth-tok-test")));
        assert_eq!(
            auth.source(),
            CredentialSource::Environment {
                name: "ANTHROPIC_OAUTH_TOKEN"
            }
        );
        assert_eq!(
            auth.require_anthropic_oauth_token()
                .unwrap()
                .expose_secret(),
            "oauth-tok-test"
        );
        assert_eq!(auth.requirement(), AuthRequirement::AnthropicOAuthToken);
    }

    #[test]
    fn anthropic_oauth_token_absent_returns_not_configured() {
        let auth = ProviderAuth::anthropic_oauth_token(None);
        assert_eq!(auth.source(), CredentialSource::NotProvided);
        let err = auth.require_anthropic_oauth_token().unwrap_err();
        assert!(
            matches!(err, LlmError::NotConfigured(ref msg) if msg.contains("ANTHROPIC_OAUTH_TOKEN")),
            "unexpected error: {err}"
        );
    }

    #[test]
    fn require_api_key_rejects_anthropic_oauth_credential() {
        let auth = ProviderAuth::anthropic_oauth_token(Some(SecretString::from("tok")));
        let err = auth.require_api_key().unwrap_err();
        assert!(
            matches!(err, LlmError::NotConfigured(ref msg) if msg.contains("anthropic-oauth token")),
            "unexpected error: {err}"
        );
    }

    #[test]
    fn optional_api_key_returns_none_for_anthropic_oauth_credential() {
        let auth = ProviderAuth::anthropic_oauth_token(Some(SecretString::from("tok")));
        assert!(auth.optional_api_key().is_none());
    }

    #[test]
    fn codex_auth_round_trips_only_resolved_paths() {
        let auth = ProviderAuth::codex("/tmp/.codex/auth.json", "/opt/codex/bin/codex");
        let codex = auth.require_codex_auth().unwrap();

        assert_eq!(auth.requirement(), AuthRequirement::CodexAuthFile);
        assert_eq!(auth.source(), CredentialSource::TokenFile);
        assert_eq!(codex.auth_file, Path::new("/tmp/.codex/auth.json"));
        assert_eq!(codex.executable, Path::new("/opt/codex/bin/codex"));
        assert!(!format!("{codex:?}").contains("token"));
    }
}