phoebus_os/installer-rs/crates/phoebus-installer/src/ai_setup.rs
2026-09-24 18:03:31 -07:00

346 lines
12 KiB
Rust

//! 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<String>,
pub provider: Option<String>,
pub model: Option<String>,
pub endpoint: Option<String>,
pub api_key_file: Option<PathBuf>,
pub opencode_server: Option<String>,
pub opencode_provider: Option<String>,
pub opencode_model: Option<String>,
pub opencode_password_file: Option<PathBuf>,
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<PathBuf>,
pub opencode_password_file: Option<PathBuf>,
pub no_sandbox: bool,
}
fn env_var(use_env: bool, name: &str) -> Option<String> {
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<PathBuf> {
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 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);
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,
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<Option<SecretString>> {
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<Option<SecretString>> {
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<Box<dyn ModelTransport + 'e>> {
match self.backend {
AiBackend::OpenCode => {
let password = self.load_opencode_password()?;
Ok(Box::new(
ExecOpenCodeTransport::new(
exec,
self.opencode_server.clone(),
self.opencode_provider.clone(),
self.opencode_model.clone(),
)
.with_auth(password),
))
}
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<PathBuf>) -> 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,
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 <redacted>"
);
// 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 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());
}
}