ultron-session-core 1.0.0

One session's runtime, shared by every mode through the session worker: the rlm lane (model, provider, system prompt, the single rlm tool), the composition root of its host stack, the format-4 run journal, session naming, Pi read views, and the session actor
Documentation
//! The auth.json credential a request uses (`resolveProviderAuth` over the composed provider auth of
//! `provider-composer.ts`): a stored credential owns its provider. An `api_key` credential's key (its `$VAR` template
//! resolved against the credential's `env`, then the environment) wins over the models.json `apiKey` and the
//! environment; a credential without a usable key falls back to the built-in provider's environment key (a custom
//! provider has none). An `oauth` credential gives its access token, refreshed under the store's lock when it expires
//! within five minutes, for the providers with an OAuth handler; any other credential type leaves the provider
//! unconfigured (no environment fallback).

use crate::RunEnv as Env;
use ai::auth::{AuthContext, AuthOverrides, FileCredentialStore, ProviderAuth};
use serde_json::Value;
use std::path::PathBuf;
use std::sync::Arc;

/// What auth.json says about one provider's request key.
#[derive(Debug, PartialEq)]
pub enum Stored {
    /// No credential stored: models.json and the environment decide.
    Nothing,
    /// The credential owns the provider: this key, or none at all.
    Owns(Option<String>),
}

/// The stored credential of `provider` in the profile's auth.json. A file that is not JSON fails the request the
/// way the TypeScript store's read does.
pub fn stored_key(env: &Env, provider: &str) -> Result<Stored, String> {
    let path = config::paths::AgentPaths::new(env.agent_dir()).auth();
    let Ok(text) = std::fs::read_to_string(&path) else {
        return Ok(Stored::Nothing);
    };
    let data = config::json::parse(&text).map_err(|e| format!("Credential store read failed for {provider}: {e}"))?;
    let Some(credential) = data.get(provider).filter(|c| !c.is_null()).cloned() else {
        return Ok(Stored::Nothing);
    };
    match credential.get("type").and_then(Value::as_str) {
        Some("api_key") => {
            let var = env.var.clone();
            let resolved = config::auth::resolve_stored_api_key(credential, &move |name: &str| var(name))
                .map_err(|e| format!("Credential store read failed for {provider}: {e}"))?;
            let key = resolved
                .as_ref()
                .and_then(|c| c.get("key"))
                .and_then(Value::as_str)
                .filter(|k| !k.is_empty())
                .map(str::to_string);
            // `envApiKeyAuth.resolve`: no stored key, so the built-in provider's ambient key; a custom provider
            // (no inherited auth) is not configured. The credential's own `env` counts first (a Bedrock AWS-profile
            // or Vertex project/location login stores only that).
            let builtin = ai::models::builtin_providers().any(|p| p == provider)
                || crate::lane::registry(env).radius_gateway(provider).is_some();
            let stored_env = string_map(resolved.as_ref().and_then(|c| c.get("env")));
            Ok(Stored::Owns(key.or_else(|| {
                builtin
                    .then(|| crate::lane::env_api_key_over(env, provider, &stored_env))
                    .flatten()
            })))
        }
        Some("oauth") => oauth_auth(env, provider, path, None, &OAuthOptions::for_env(env))
            .map(|auth| Stored::Owns(auth.and_then(|a| a.api_key))),
        _ => Ok(Stored::Owns(None)),
    }
}

/// The credential of `provider`'s stored OAuth credential (`getAuthCredential`: its key or bearer token), refreshed when it has less than `min_validity_ms` (five
/// minutes by default) left; `None` when nothing usable is stored.
pub fn oauth_access(env: &Env, provider: &str, min_validity_ms: Option<f64>) -> Result<Option<String>, String> {
    oauth_access_with(env, provider, min_validity_ms, &OAuthOptions::for_env(env))
}

/// [`oauth_access`] over `options` (the transport token refreshes go through).
pub fn oauth_access_with(
    env: &Env,
    provider: &str,
    min_validity_ms: Option<f64>,
    options: &OAuthOptions,
) -> Result<Option<String>, String> {
    let path = config::paths::AgentPaths::new(env.agent_dir()).auth();
    Ok(oauth_auth(env, provider, path, min_validity_ms, options)?.and_then(|auth| credential_of(&auth)))
}

/// `getAuthCredential`: the API key, else the token of an `Authorization: Bearer` header (Kimi's OAuth auth).
fn credential_of(auth: &ai::auth::ModelAuth) -> Option<String> {
    if let Some(key) = auth.api_key.as_ref().filter(|k| !k.is_empty()) {
        return Some(key.clone());
    }
    let header = auth
        .headers
        .iter()
        .flatten()
        .find(|(name, _)| name.eq_ignore_ascii_case("authorization"))
        .and_then(|(_, value)| value.clone())?;
    let (scheme, token) = header.split_once(char::is_whitespace)?;
    let token = token.trim_start();
    (scheme.eq_ignore_ascii_case("bearer") && !token.is_empty()).then(|| token.to_string())
}

/// What a stored OAuth credential adds to a request beyond its key (`ModelAuth`): the base URL it names (GitHub
/// Copilot's token proxy endpoint, else its enterprise or individual endpoint) and its headers (Kimi For Coding's
/// `Authorization: Bearer <access>`), refreshed first when the token expires soon; `None` for any other credential.
pub fn oauth_request_auth(env: &Env, provider: &str) -> Option<ai::model_registry::StoredRequestAuth> {
    let path = config::paths::AgentPaths::new(env.agent_dir()).auth();
    let stored = config::auth::read_stored_credential(&path, provider)?;
    if stored.get("type").and_then(Value::as_str) != Some("oauth") {
        return None;
    }
    let auth = oauth_auth(env, provider, path, None, &OAuthOptions::for_env(env))
        .ok()
        .flatten()?;
    Some(ai::model_registry::StoredRequestAuth {
        base_url: auth.base_url,
        headers: auth.headers,
        env: None,
    })
}

/// What `provider`'s resolved auth adds to each request beyond its key: a stored OAuth credential's base URL and
/// headers ([`oauth_request_auth`]), else the api-key auth's headers and env ([`api_key_request_auth`]).
pub fn request_auth(env: &Env, provider: &str) -> Option<ai::model_registry::StoredRequestAuth> {
    if let Some(oauth) = oauth_request_auth(env, provider) {
        return Some(oauth);
    }
    let result = api_key_request_auth(env, provider).ok().flatten()?;
    let request = ai::model_registry::StoredRequestAuth {
        base_url: None,
        headers: result.auth.headers,
        env: result.env.map(|env| env.into_iter().collect()),
    };
    (request.headers.is_some() || request.env.is_some()).then_some(request)
}

/// Whether requests of `provider` need [`request_auth`]: a stored OAuth credential, a provider whose api-key auth
/// adds headers or env (Anthropic, Vertex, Cloudflare), or a stored api-key credential with an `env`.
pub fn has_request_auth(env: &Env, provider: &str) -> bool {
    if ai::auth::builtin_api_key_auth(provider).is_some() {
        return true;
    }
    let path = config::paths::AgentPaths::new(env.agent_dir()).auth();
    config::auth::read_stored_credential(&path, provider).is_some_and(|c| match c.get("type").and_then(Value::as_str) {
        Some("oauth") => true,
        Some("api_key") => c.get("env").and_then(Value::as_object).is_some_and(|e| !e.is_empty()),
        _ => false,
    })
}

/// Whether `provider` authenticates by headers alone with no key (`ANTHROPIC_AUTH_TOKEN`'s bearer, the AI Gateway's
/// `cf-aig-authorization`): its requests carry no API key, and they need none.
pub fn header_owned(env: &Env, provider: &str) -> bool {
    api_key_request_auth(env, provider)
        .ok()
        .flatten()
        .is_some_and(|result| {
            result.auth.api_key.is_none() && result.auth.headers.iter().flatten().any(|(_, value)| value.is_some())
        })
}

/// The request key of a provider whose built-in api-key auth decides it (Anthropic: a stored or models.json key,
/// else `ANTHROPIC_AUTH_TOKEN` with no key, else `ANTHROPIC_OAUTH_TOKEN`/`ANTHROPIC_API_KEY`; Cloudflare: the
/// Workers AI key, none for the AI Gateway, and no key at all, so not configured, without the account or gateway
/// id); `None` for every other provider and when a stored OAuth credential owns the provider.
pub fn resolved_key(env: &Env, provider: &str) -> Result<Option<Option<String>>, String> {
    if !matches!(
        provider,
        "anthropic" | "cloudflare-workers-ai" | "cloudflare-ai-gateway"
    ) {
        return Ok(None);
    }
    let path = config::paths::AgentPaths::new(env.agent_dir()).auth();
    if config::auth::read_stored_credential(&path, provider)
        .filter(|c| !c.is_null())
        .is_some_and(|c| c.get("type").and_then(Value::as_str) != Some("api_key"))
    {
        return Ok(None);
    }
    // An unreadable auth.json fails the request as the store's read does.
    stored_key(env, provider)?;
    Ok(Some(api_key_request_auth(env, provider)?.and_then(|r| r.auth.api_key)))
}

/// `composeApiKeyAuth(...).resolve` (provider-composer.ts) for one request: the stored api-key credential (its key
/// template resolved, with its `env`), else the models.json `apiKey` as the credential's key, else none, resolved by
/// the provider's built-in api-key auth ([`ai::auth::builtin_api_key_auth`]), or for any other provider the stored
/// key with the credential's `env`. `None` when a stored OAuth (or other) credential owns the provider or nothing
/// resolves.
pub fn api_key_request_auth(env: &Env, provider: &str) -> Result<Option<ai::auth::AuthResult>, String> {
    let path = config::paths::AgentPaths::new(env.agent_dir()).auth();
    let stored = config::auth::read_stored_credential(&path, provider).filter(|c| !c.is_null());
    let credential = match stored {
        Some(credential) if credential.get("type").and_then(Value::as_str) == Some("api_key") => {
            let var = env.var.clone();
            let resolved = config::auth::resolve_stored_api_key(credential, &move |name: &str| var(name))
                .map_err(|e| format!("Credential store read failed for {provider}: {e}"))?
                .unwrap_or(Value::Null);
            Some(ai::auth::ApiKeyCredential {
                key: resolved.get("key").and_then(Value::as_str).map(str::to_string),
                env: resolved.get("env").and_then(Value::as_object).map(|env| {
                    env.iter()
                        .filter_map(|(k, v)| Some((k.clone(), v.as_str()?.to_string())))
                        .collect()
                }),
            })
        }
        Some(_) => return Ok(None),
        None => crate::lane::registry(env)
            .api_key(provider, None, &*env.var, None)?
            .map(|key| ai::auth::ApiKeyCredential {
                key: Some(key),
                env: None,
            }),
    };
    let Some(auth) = ai::auth::builtin_api_key_auth(provider) else {
        return Ok(credential.and_then(|c| {
            let key = c.key.filter(|k| !k.is_empty())?;
            Some(ai::auth::AuthResult {
                auth: ai::auth::ModelAuth {
                    api_key: Some(key),
                    ..Default::default()
                },
                env: c.env,
                source: Some("stored credential".into()),
            })
        }));
    };
    let ctx = EnvContext(env.clone());
    ready(auth.resolve(&ctx, credential.as_ref()))
        .unwrap_or_else(|| Err(format!("API key auth for {provider} did not resolve at once")))
}

/// The string members of a credential's `env` object.
fn string_map(value: Option<&Value>) -> std::collections::HashMap<String, String> {
    value
        .and_then(Value::as_object)
        .map(|env| {
            env.iter()
                .filter_map(|(k, v)| Some((k.clone(), v.as_str()?.to_string())))
                .collect()
        })
        .unwrap_or_default()
}

/// The value of a future that is ready on its first poll (the built-in api-key auths read only the environment and
/// the file system); `None` when it is not.
fn ready<T>(future: impl std::future::Future<Output = T>) -> Option<T> {
    let mut future = std::pin::pin!(future);
    match future
        .as_mut()
        .poll(&mut std::task::Context::from_waker(std::task::Waker::noop()))
    {
        std::task::Poll::Ready(value) => Some(value),
        std::task::Poll::Pending => None,
    }
}

/// How an OAuth handler reaches its provider: the transport, and the port a browser login's callback server listens
/// on instead of the registered one (`Some(0)`: any free port; tests).
#[derive(Clone)]
pub struct OAuthOptions {
    pub transport: Arc<dyn ai::Transport>,
    pub callback_port: Option<u16>,
}

impl OAuthOptions {
    /// The options of a run in `env`: its proxies (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`) reach the providers.
    pub fn for_env(env: &Env) -> OAuthOptions {
        OAuthOptions {
            transport: Arc::new(ai::ReqwestTransport::for_env(&*env.var, None)),
            callback_port: None,
        }
    }
}

impl Default for OAuthOptions {
    fn default() -> Self {
        OAuthOptions {
            transport: Arc::new(ai::ReqwestTransport::new(None)),
            callback_port: None,
        }
    }
}

/// The OAuth handler of `provider` over `options`: a built-in provider's, or Radius's on the provider's gateway (the
/// built-in `radius`, or a models.json provider with `"oauth": "radius"`); every provider TypeScript signs in with an
/// account (Anthropic, OpenAI Codex, GitHub Copilot, xAI, Kimi For Coding, Meta, OpenRouter, Radius).
pub fn oauth_handler_with(env: &Env, provider: &str, options: &OAuthOptions) -> Option<Arc<dyn ai::auth::OAuthAuth>> {
    let transport = options.transport.clone();
    let clock = ai::oauth_flow::system_clock;
    if let Some((name, gateway)) = crate::lane::registry(env).radius_gateway(provider) {
        let mut radius = ai::oauth_radius::RadiusOAuth::new(&name, &gateway, transport, clock);
        if let Some(port) = options.callback_port {
            radius = radius.with_callback_port(port);
        }
        return Some(Arc::new(radius));
    }
    Some(match provider {
        "xai" => Arc::new(ai::oauth_xai::XaiOAuth { transport, clock }),
        "kimi-coding" => Arc::new(ai::oauth_kimi::KimiCodingOAuth { transport, clock }),
        "meta" => Arc::new(ai::oauth_meta::MetaOAuth { transport, clock }),
        "openrouter" => Arc::new(ai::oauth_openrouter::OpenRouterOAuth { transport }),
        _ => Arc::new(ai::auth::BuiltinOAuth {
            provider: ai::oauth::OAuthProvider::from_id(provider)?,
            transport,
            clock,
            callback_port: options.callback_port,
        }),
    })
}

/// The request auth of a stored OAuth credential (`resolveStoredOAuth`, then `toAuth`: the access token, and a base
/// URL for some providers), refreshed through the provider's token endpoint when it expires soon. Providers without
/// an OAuth handler are not configured by it.
fn oauth_auth(
    env: &Env,
    provider: &str,
    path: PathBuf,
    min_validity_ms: Option<f64>,
    options: &OAuthOptions,
) -> Result<Option<ai::auth::ModelAuth>, String> {
    let Some(oauth) = oauth_handler_with(env, provider, options) else {
        return Ok(None);
    };
    let auth = ProviderAuth {
        api_key: None,
        oauth: Some(oauth),
    };
    let ctx = EnvContext(env.clone());
    let store = FileCredentialStore::new(path);
    // Callers are synchronous and may sit inside a runtime: the resolution runs on its own thread and runtime.
    std::thread::scope(|scope| {
        scope
            .spawn(|| {
                let runtime = tokio::runtime::Builder::new_current_thread()
                    .enable_all()
                    .build()
                    .map_err(|e| e.to_string())?;
                runtime
                    .block_on(ai::auth::resolve_provider_auth(
                        provider,
                        &auth,
                        &store,
                        &ctx,
                        &AuthOverrides {
                            min_oauth_validity_ms: min_validity_ms,
                            ..AuthOverrides::default()
                        },
                    ))
                    .map(|result| result.map(|r| r.auth))
                    .map_err(|e| e.message())
            })
            .join()
            .unwrap_or_else(|_| Err(format!("OAuth auth failed for {provider}")))
    })
}

/// The session's environment as the auth context (`defaultProviderAuthContext` over the injected lookup).
struct EnvContext(Env);

impl AuthContext for EnvContext {
    fn env(&self, name: &str) -> Option<String> {
        (self.0.var)(name).filter(|v| !v.trim().is_empty())
    }

    fn file_exists(&self, path: &str) -> bool {
        match path.strip_prefix('~') {
            Some(rest) => PathBuf::from(format!("{}{rest}", self.0.home.display())).exists(),
            None => PathBuf::from(path).exists(),
        }
    }
}