//! Shared provider configuration and credential handling for `sys` and the //! desktop assistant. //! //! Both surfaces use this module to resolve which model backend to use, where //! the endpoint/model live, and how to load the credential reference safely, //! so the two cannot drift apart again. Credentials are only ever read from a //! mode-0600 file (or an environment-provided path) and are registered with the //! executor's redactor before any transport use. A key never travels through //! QML, a model prompt, a command line or conversation history. use std::path::{Path, PathBuf}; use phoebus_ai::provider::{ModelTransport, ProviderKind}; use phoebus_core::{AiBackend, AiConfig, SecretString}; use phoebus_executor::ai::CurlTransport; use phoebus_executor::error::{ExecError, Result}; use phoebus_executor::exec::Exec; use phoebus_executor::opencode_client::ExecOpenCodeTransport; /// Caller-supplied overrides (CLI flags or GUI settings). `None` means "fall /// back to the environment or the installed configuration". #[derive(Debug, Clone, Default)] pub struct AiOverrides { pub backend: Option, pub provider: Option, pub model: Option, pub endpoint: Option, pub api_key_file: Option, pub opencode_server: Option, pub opencode_provider: Option, pub opencode_model: Option, pub opencode_password_file: Option, /// Permit plain `http` to a non-loopback OpenCode server (explicit opt-in). pub opencode_insecure_http: bool, pub no_sandbox: bool, /// When true, environment variables are consulted between the explicit /// override and the installed configuration. pub use_environment: bool, } /// Fully resolved provider settings. No secret value is held here, only the /// path to the mode-0600 credential file. #[derive(Debug, Clone)] pub struct ResolvedAi { pub backend: AiBackend, pub provider: ProviderKind, pub endpoint: String, pub model: String, pub opencode_server: String, pub opencode_provider: String, pub opencode_model: String, pub api_key_file: Option, pub opencode_password_file: Option, pub opencode_insecure_http: bool, pub no_sandbox: bool, } fn env_var(use_env: bool, name: &str) -> Option { if !use_env { return None; } std::env::var(name).ok().filter(|s| !s.trim().is_empty()) } /// A well-known per-user credential location used when nothing is configured. /// Only returned when the file already exists, so the absence of a key is not /// turned into an error for providers (like a local model) that need none. fn default_credential_file() -> Option { let base = std::env::var("XDG_CONFIG_HOME") .ok() .filter(|s| !s.trim().is_empty()) .map(PathBuf::from) .or_else(|| { std::env::var("HOME") .ok() .map(|h| PathBuf::from(h).join(".config")) })?; let path = base.join("phoebus").join("ai.key"); if path.is_file() { Some(path) } else { None } } /// Resolve the provider configuration from explicit overrides, the /// environment (when enabled) and the installed `assistant.conf`. pub fn resolve(_root: &Path, ov: &AiOverrides, conf: Option<&AiConfig>) -> ResolvedAi { let backend = ov .backend .clone() .or_else(|| env_var(ov.use_environment, "PHOEBUS_AI_BACKEND")) .or_else(|| conf.map(|c| c.backend.as_str().to_string())) .and_then(|s| AiBackend::parse(&s)) .unwrap_or(AiBackend::Direct); let mut provider = ov .provider .clone() .or_else(|| env_var(ov.use_environment, "PHOEBUS_AI_PROVIDER")) .or_else(|| conf.map(|c| c.provider.clone())) .and_then(|s| ProviderKind::parse(&s)) .unwrap_or(ProviderKind::None); // The OpenCode backend adapts OpenAI-shaped requests to the agent // server protocol; `Local` is the established adapter kind (the guided // install review uses it). Without this, `sys ask --ai-backend opencode` // resolves no provider and fails with "no AI provider selected" even // though server, provider and model are all configured. if backend == AiBackend::OpenCode && provider == ProviderKind::None { provider = ProviderKind::Local; } let opencode_server = ov .opencode_server .clone() .or_else(|| env_var(ov.use_environment, "PHOEBUS_OPENCODE_SERVER")) .or_else(|| conf.map(|c| c.opencode_server.clone())) .unwrap_or_default(); let opencode_provider = ov .opencode_provider .clone() .or_else(|| env_var(ov.use_environment, "PHOEBUS_OPENCODE_PROVIDER")) .or_else(|| conf.map(|c| c.opencode_provider.clone())) .unwrap_or_default(); let opencode_model = ov .opencode_model .clone() .or_else(|| env_var(ov.use_environment, "PHOEBUS_OPENCODE_MODEL")) .or_else(|| conf.map(|c| c.opencode_model.clone())) .unwrap_or_default(); let endpoint = ov .endpoint .clone() .or_else(|| env_var(ov.use_environment, "PHOEBUS_AI_ENDPOINT")) .or_else(|| { conf.map(|c| c.endpoint.clone()) .filter(|s| !s.trim().is_empty()) }) .filter(|s| !s.trim().is_empty()) .unwrap_or_else(|| { if backend == AiBackend::OpenCode { opencode_server.clone() } else { provider.endpoint().to_string() } }); let model = ov .model .clone() .or_else(|| env_var(ov.use_environment, "PHOEBUS_AI_MODEL")) .or_else(|| conf.map(|c| c.model.clone())) .unwrap_or_default(); let api_key_file = ov .api_key_file .clone() .or_else(|| env_var(ov.use_environment, "PHOEBUS_AI_API_KEY_FILE").map(PathBuf::from)) .or_else(|| { conf.map(|c| c.direct_credential_file.clone()) .filter(|s| !s.trim().is_empty()) .map(PathBuf::from) }) // Default authorized-provider location: a per-user 0600 file. Used // only when it already exists, so a local model needs no key. .or_else(default_credential_file); let opencode_password_file = ov .opencode_password_file .clone() .or_else(|| { env_var(ov.use_environment, "PHOEBUS_OPENCODE_PASSWORD_FILE").map(PathBuf::from) }) .or_else(|| { conf.map(|c| c.opencode_credential_file.clone()) .filter(|s| !s.trim().is_empty()) .map(PathBuf::from) }); ResolvedAi { backend, provider, endpoint, model, opencode_server, opencode_provider, opencode_model, api_key_file, opencode_password_file, opencode_insecure_http: ov.opencode_insecure_http || env_var(ov.use_environment, "PHOEBUS_OPENCODE_INSECURE_HTTP").as_deref() == Some("1"), no_sandbox: ov.no_sandbox, } } impl ResolvedAi { /// Whether the resolved backend is usable at all. pub fn is_configured(&self) -> bool { match self.backend { AiBackend::OpenCode => { !self.opencode_server.trim().is_empty() && !self.opencode_provider.trim().is_empty() && !self.opencode_model.trim().is_empty() } AiBackend::Direct => self.provider != ProviderKind::None, } } /// Load the direct-provider key, explaining clearly when it is missing or /// inaccessible. The value is registered with the redactor by the transport. pub fn load_direct_key(&self, exec: &Exec) -> Result> { match &self.api_key_file { Some(path) => { let key = phoebus_executor::ai::load_api_key(path).map_err(|e| { ExecError::operation( "ai", "load provider credential", format!( "could not load the provider API key from {}: {e}", path.display() ), ) })?; exec.register_secret(&key); Ok(Some(key)) } None => Ok(None), } } pub fn load_opencode_password(&self) -> Result> { match &self.opencode_password_file { Some(path) => Ok(Some(phoebus_executor::ai::load_api_key(path)?)), None => Ok(None), } } /// Build a transport for this configuration. The direct provider gets the /// OS-level sandbox unless explicitly disabled; the OpenCode agent server /// is a different trust boundary and keeps its own transport. pub fn transport<'e>(&self, exec: &'e Exec) -> Result> { match self.backend { AiBackend::OpenCode => { let password = self.load_opencode_password()?; // The OpenCode agent is a standard transport: it runs in the // same OS-level sandbox as the direct provider unless the // operator disabled it, and a network server is allowed (https, // or plain http only with an explicit opt-in). let mut transport = ExecOpenCodeTransport::new( exec, self.opencode_server.clone(), self.opencode_provider.clone(), self.opencode_model.clone(), ) .with_auth(password); if self.opencode_insecure_http { transport = transport.allow_insecure_http(); } if !self.no_sandbox { transport = transport.sandboxed(); } Ok(Box::new(transport)) } AiBackend::Direct => { let key = self.load_direct_key(exec)?; if self.provider.requires_key() && key.is_none() { return Err(ExecError::operation( "ai", "load provider credential", format!( "provider `{}` requires an API key file (api_key_file in \ assistant.conf, PHOEBUS_AI_API_KEY_FILE, or --ai-api-key-file)", self.provider.as_str() ), )); } let direct = CurlTransport::new(exec, key); if self.no_sandbox { Ok(Box::new(direct)) } else { Ok(Box::new(direct.sandboxed())) } } } } } #[cfg(test)] mod tests { use super::*; use phoebus_core::Redactor; use phoebus_executor::command::RecordingRunner; use phoebus_executor::Logger; fn make_exec() -> Exec { let path = tempfile::tempdir().unwrap().keep(); let logger = Logger::open(path.join("l.log"), Redactor::new(), false); Exec::new( Box::new(RecordingRunner::new()), logger, false, path.join("root"), path, ) } fn resolved(provider: ProviderKind, key_file: Option) -> ResolvedAi { ResolvedAi { backend: AiBackend::Direct, provider, endpoint: "https://example.invalid/v1/chat/completions".into(), model: "m".into(), opencode_server: String::new(), opencode_provider: String::new(), opencode_model: String::new(), api_key_file: key_file, opencode_password_file: None, opencode_insecure_http: false, no_sandbox: true, } } #[test] fn credential_loads_from_a_0600_file_and_is_redacted() { use std::os::unix::fs::PermissionsExt; let dir = tempfile::tempdir().unwrap(); let key = dir.path().join("ai.key"); std::fs::write(&key, "sk-synthetic-secret\n").unwrap(); std::fs::set_permissions(&key, std::fs::Permissions::from_mode(0o600)).unwrap(); let exec = make_exec(); let resolved = resolved(ProviderKind::DeepSeek, Some(key)); let secret = resolved.load_direct_key(&exec).unwrap().unwrap(); assert_eq!(secret.expose(), "sk-synthetic-secret"); // Registered with the process redactor, so it cannot be logged. assert_eq!( exec.redactor().redact("bearer sk-synthetic-secret"), "bearer " ); // A transport can be built without the key touching argv or QML. assert!(resolved.transport(&exec).is_ok()); } #[test] fn an_inaccessible_credential_is_reported_clearly() { use std::os::unix::fs::PermissionsExt; let dir = tempfile::tempdir().unwrap(); let key = dir.path().join("ai.key"); std::fs::write(&key, "wide-open\n").unwrap(); std::fs::set_permissions(&key, std::fs::Permissions::from_mode(0o644)).unwrap(); let exec = make_exec(); let resolved = resolved(ProviderKind::DeepSeek, Some(key)); let err = resolved.load_direct_key(&exec).unwrap_err().to_string(); assert!(err.contains("could not load the provider API key"), "{err}"); } #[test] fn opencode_backend_defaults_to_the_local_adapter_kind() { let ov = AiOverrides { backend: Some("opencode".into()), provider: None, model: None, endpoint: None, api_key_file: None, opencode_server: Some("http://127.0.0.1:4096".into()), opencode_provider: Some("opencode-go".into()), opencode_model: Some("muse-spark-1.3-contributor".into()), opencode_password_file: None, opencode_insecure_http: false, no_sandbox: true, use_environment: false, }; let resolved = resolve(std::path::Path::new("/"), &ov, None); assert_eq!(resolved.backend, AiBackend::OpenCode); assert_eq!(resolved.provider, ProviderKind::Local); assert!(resolved.is_configured()); // An explicit direct provider is still honored, never overwritten. let ov2 = AiOverrides { provider: Some("deepseek".into()), ..ov }; let resolved2 = resolve(std::path::Path::new("/"), &ov2, None); assert_eq!(resolved2.provider, ProviderKind::DeepSeek); } #[test] fn a_keyed_provider_without_a_credential_fails_closed() { let exec = make_exec(); let err = resolved(ProviderKind::DeepSeek, None) .transport(&exec) .err() .expect("a keyed provider without a credential must fail") .to_string(); assert!(err.contains("requires an API key"), "{err}"); // A local model needs no key. assert!(resolved(ProviderKind::Local, None).transport(&exec).is_ok()); } }