Skip to content

Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.

20.9 KB
Raw Blame
use std::collections::BTreeSet;
#[cfg(not(windows))]
use std::fs;
#[cfg(not(windows))]
use std::fs::OpenOptions;
use std::io::Read;
#[cfg(not(windows))]
use std::io::Write;
use std::path::{Path, PathBuf};
use std::sync::Arc;

use base64::Engine as _;
use base64::engine::general_purpose::URL_SAFE_NO_PAD;
use serde::Serialize;
use thiserror::Error;
use zeroize::Zeroizing;

const CAPABILITY_BYTES: usize = 32;
const MAX_CAPABILITY_FILE_BYTES: u64 = 512;

pub(crate) struct SecretText(Zeroizing<String>);

impl SecretText {
    pub(crate) fn generate() -> Result<Self, CpaConfigError> {
        let mut bytes = Zeroizing::new([0_u8; CAPABILITY_BYTES]);
        getrandom::fill(bytes.as_mut()).map_err(|_| CpaConfigError::Random)?;
        Ok(Self(Zeroizing::new(URL_SAFE_NO_PAD.encode(bytes.as_ref()))))
    }

    pub(crate) fn from_owned(value: String) -> Result<Self, CpaConfigError> {
        if value.len() < 32
            || value.len() > 128
            || value.contains(['\r', '\n', '\0'])
            || !value
                .bytes()
                .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_'))
        {
            return Err(CpaConfigError::InvalidCapability);
        }
        Ok(Self(Zeroizing::new(value)))
    }

    pub(crate) fn expose(&self) -> &str {
        self.0.as_str()
    }
}

impl std::fmt::Debug for SecretText {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter.write_str("SecretText([REDACTED])")
    }
}

#[derive(Debug)]
pub(crate) struct InstanceSecrets {
    pub(crate) downstream: Arc<SecretText>,
    pub(crate) management: Arc<SecretText>,
}

impl InstanceSecrets {
    pub(crate) fn generate() -> Result<Self, CpaConfigError> {
        let downstream = SecretText::generate()?;
        let management = SecretText::generate()?;
        if downstream.expose() == management.expose() {
            return Err(CpaConfigError::Random);
        }
        Ok(Self {
            downstream: Arc::new(downstream),
            management: Arc::new(management),
        })
    }

    pub(crate) fn write(&self, path: &Path) -> Result<(), CpaConfigError> {
        let bytes = Zeroizing::new(format!(
            "{}\n{}\n",
            self.downstream.expose(),
            self.management.expose()
        ));
        private_atomic_write(path, bytes.as_bytes())
    }

    pub(crate) fn read(path: &Path) -> Result<Self, CpaConfigError> {
        validate_private_file(path)?;
        #[cfg(windows)]
        let file = crate::windows_private::file(path).map_err(CpaConfigError::Io)?;
        #[cfg(not(windows))]
        let file = fs::File::open(path).map_err(CpaConfigError::Io)?;
        let mut bytes = Zeroizing::new(Vec::new());
        file.take(MAX_CAPABILITY_FILE_BYTES + 1)
            .read_to_end(bytes.as_mut())
            .map_err(CpaConfigError::Io)?;
        if bytes.len() as u64 > MAX_CAPABILITY_FILE_BYTES {
            return Err(CpaConfigError::InvalidCapability);
        }
        let text = Zeroizing::new(
            String::from_utf8(std::mem::take(bytes.as_mut()))
                .map_err(|_| CpaConfigError::InvalidCapability)?,
        );
        let mut lines = text.lines();
        let downstream = SecretText::from_owned(lines.next().unwrap_or_default().to_owned())?;
        let management = SecretText::from_owned(lines.next().unwrap_or_default().to_owned())?;
        if lines.next().is_some() || downstream.expose() == management.expose() {
            return Err(CpaConfigError::InvalidCapability);
        }
        Ok(Self {
            downstream: Arc::new(downstream),
            management: Arc::new(management),
        })
    }
}

pub struct CpaManagedConfigContract;

impl CpaManagedConfigContract {
    pub fn validate_rendered(bytes: &[u8]) -> Result<(), CpaConfigError> {
        let value: serde_yaml::Value =
            serde_yaml::from_slice(bytes).map_err(CpaConfigError::Yaml)?;
        validate_wire_value(&value)
    }

    pub fn stock_contract_keys() -> BTreeSet<&'static str> {
        TOP_LEVEL_KEYS.into_iter().collect()
    }
}

pub(crate) fn render_managed_config(
    port: u16,
    auth_dir: &Path,
    secrets: &InstanceSecrets,
) -> Result<Vec<u8>, CpaConfigError> {
    if port == 0 || !auth_dir.is_absolute() {
        return Err(CpaConfigError::InvalidConfig);
    }
    let config = WireConfig {
        host: "127.0.0.1",
        port,
        tls: TlsConfig {
            enable: false,
            cert: "",
            key: "",
        },
        remote_management: RemoteManagement {
            allow_remote: false,
            secret_key: secrets.management.expose(),
            disable_control_panel: true,
            disable_auto_update_panel: true,
        },
        auth_dir: auth_dir.to_path_buf(),
        api_keys: vec![secrets.downstream.expose()],
        debug: false,
        logging_to_file: false,
        usage_statistics_enabled: false,
        request_log: false,
        commercial_mode: true,
        websocket_auth: true,
        disable_cooling: true,
        save_cooldown_status: false,
        transient_error_cooldown_seconds: -1,
        disable_claude_cloak_mode: true,
        request_retry: 0,
        max_retry_credentials: 1,
        max_retry_interval: 0,
        force_model_prefix: true,
        quota_exceeded: QuotaExceeded {
            switch_project: false,
            switch_preview_model: false,
            antigravity_credits: false,
        },
        routing: Routing {
            strategy: "fill-first",
            session_affinity: false,
        },
        streaming: Streaming {
            keepalive_seconds: 0,
            bootstrap_retries: 0,
        },
        plugins: Plugins { enabled: false },
    };
    let bytes = serde_yaml::to_string(&config)
        .map_err(CpaConfigError::Yaml)?
        .into_bytes();
    CpaManagedConfigContract::validate_rendered(&bytes)?;
    Ok(bytes)
}

const TOP_LEVEL_KEYS: [&str; 23] = [
    "host",
    "port",
    "tls",
    "remote-management",
    "auth-dir",
    "api-keys",
    "debug",
    "logging-to-file",
    "usage-statistics-enabled",
    "request-log",
    "commercial-mode",
    "ws-auth",
    "disable-cooling",
    "save-cooldown-status",
    "transient-error-cooldown-seconds",
    "disable-claude-cloak-mode",
    "request-retry",
    "max-retry-credentials",
    "max-retry-interval",
    "force-model-prefix",
    "quota-exceeded",
    "routing",
    "streaming",
];

fn validate_wire_value(value: &serde_yaml::Value) -> Result<(), CpaConfigError> {
    let map = value.as_mapping().ok_or(CpaConfigError::InvalidConfig)?;
    let keys = map
        .keys()
        .map(|key| key.as_str().ok_or(CpaConfigError::InvalidConfig))
        .collect::<Result<BTreeSet<_>, _>>()?;
    let mut expected = CpaManagedConfigContract::stock_contract_keys();
    expected.insert("plugins");
    if keys != expected {
        return Err(CpaConfigError::InvalidConfig);
    }
    expect_scalar(value, "host", "127.0.0.1")?;
    let port = child(value, "port")
        .as_i64()
        .ok_or(CpaConfigError::InvalidConfig)?;
    let auth_dir = child(value, "auth-dir")
        .as_str()
        .map(Path::new)
        .ok_or(CpaConfigError::InvalidConfig)?;
    if !(1..=i64::from(u16::MAX)).contains(&port) || !auth_dir.is_absolute() {
        return Err(CpaConfigError::InvalidConfig);
    }
    validate_map_exact(child(value, "tls"), &["enable", "cert", "key"])?;
    expect_nested_bool(value, "tls", "enable", false)?;
    expect_nested_scalar(value, "tls", "cert", "")?;
    expect_nested_scalar(value, "tls", "key", "")?;
    expect_bool(value, "debug", false)?;
    expect_bool(value, "logging-to-file", false)?;
    expect_bool(value, "usage-statistics-enabled", false)?;
    expect_bool(value, "request-log", false)?;
    expect_bool(value, "commercial-mode", true)?;
    expect_bool(value, "ws-auth", true)?;
    expect_bool(value, "disable-cooling", true)?;
    expect_bool(value, "save-cooldown-status", false)?;
    expect_integer(value, "transient-error-cooldown-seconds", -1)?;
    expect_bool(value, "disable-claude-cloak-mode", true)?;
    expect_integer(value, "request-retry", 0)?;
    expect_integer(value, "max-retry-credentials", 1)?;
    expect_integer(value, "max-retry-interval", 0)?;
    expect_bool(value, "force-model-prefix", true)?;

    let api_keys = child(value, "api-keys")
        .as_sequence()
        .ok_or(CpaConfigError::InvalidConfig)?;
    let downstream = api_keys
        .first()
        .and_then(serde_yaml::Value::as_str)
        .ok_or(CpaConfigError::InvalidConfig)?;
    if api_keys.len() != 1 || SecretText::from_owned(downstream.to_owned()).is_err() {
        return Err(CpaConfigError::InvalidConfig);
    }
    validate_map_exact(
        child(value, "remote-management"),
        &[
            "allow-remote",
            "secret-key",
            "disable-control-panel",
            "disable-auto-update-panel",
        ],
    )?;
    expect_nested_bool(value, "remote-management", "allow-remote", false)?;
    expect_nested_bool(value, "remote-management", "disable-control-panel", true)?;
    expect_nested_bool(
        value,
        "remote-management",
        "disable-auto-update-panel",
        true,
    )?;
    let management = child(child(value, "remote-management"), "secret-key")
        .as_str()
        .ok_or(CpaConfigError::InvalidConfig)?;
    SecretText::from_owned(management.to_owned())?;
    if management == downstream {
        return Err(CpaConfigError::InvalidConfig);
    }

    validate_map_exact(
        child(value, "quota-exceeded"),
        &[
            "switch-project",
            "switch-preview-model",
            "antigravity-credits",
        ],
    )?;
    for key in [
        "switch-project",
        "switch-preview-model",
        "antigravity-credits",
    ] {
        expect_nested_bool(value, "quota-exceeded", key, false)?;
    }
    validate_map_exact(child(value, "routing"), &["strategy", "session-affinity"])?;
    expect_nested_scalar(value, "routing", "strategy", "fill-first")?;
    expect_nested_bool(value, "routing", "session-affinity", false)?;
    validate_map_exact(
        child(value, "streaming"),
        &["keepalive-seconds", "bootstrap-retries"],
    )?;
    expect_nested_integer(value, "streaming", "keepalive-seconds", 0)?;
    expect_nested_integer(value, "streaming", "bootstrap-retries", 0)?;
    validate_map_exact(child(value, "plugins"), &["enabled"])?;
    expect_nested_bool(value, "plugins", "enabled", false)?;
    Ok(())
}

fn child<'a>(value: &'a serde_yaml::Value, key: &str) -> &'a serde_yaml::Value {
    &value[key]
}

fn validate_map_exact(value: &serde_yaml::Value, expected: &[&str]) -> Result<(), CpaConfigError> {
    let map = value.as_mapping().ok_or(CpaConfigError::InvalidConfig)?;
    let keys = map
        .keys()
        .map(|key| key.as_str().ok_or(CpaConfigError::InvalidConfig))
        .collect::<Result<BTreeSet<_>, _>>()?;
    if keys != expected.iter().copied().collect() {
        return Err(CpaConfigError::InvalidConfig);
    }
    Ok(())
}

fn expect_scalar(
    value: &serde_yaml::Value,
    key: &str,
    expected: &str,
) -> Result<(), CpaConfigError> {
    if child(value, key).as_str() != Some(expected) {
        return Err(CpaConfigError::InvalidConfig);
    }
    Ok(())
}

fn expect_bool(value: &serde_yaml::Value, key: &str, expected: bool) -> Result<(), CpaConfigError> {
    if child(value, key).as_bool() != Some(expected) {
        return Err(CpaConfigError::InvalidConfig);
    }
    Ok(())
}

fn expect_integer(
    value: &serde_yaml::Value,
    key: &str,
    expected: i64,
) -> Result<(), CpaConfigError> {
    if child(value, key).as_i64() != Some(expected) {
        return Err(CpaConfigError::InvalidConfig);
    }
    Ok(())
}

fn expect_nested_scalar(
    value: &serde_yaml::Value,
    parent: &str,
    key: &str,
    expected: &str,
) -> Result<(), CpaConfigError> {
    expect_scalar(child(value, parent), key, expected)
}

fn expect_nested_bool(
    value: &serde_yaml::Value,
    parent: &str,
    key: &str,
    expected: bool,
) -> Result<(), CpaConfigError> {
    expect_bool(child(value, parent), key, expected)
}

fn expect_nested_integer(
    value: &serde_yaml::Value,
    parent: &str,
    key: &str,
    expected: i64,
) -> Result<(), CpaConfigError> {
    expect_integer(child(value, parent), key, expected)
}

#[derive(Serialize)]
#[serde(rename_all = "kebab-case")]
struct WireConfig<'a> {
    host: &'a str,
    port: u16,
    tls: TlsConfig<'a>,
    remote_management: RemoteManagement<'a>,
    auth_dir: PathBuf,
    api_keys: Vec<&'a str>,
    debug: bool,
    logging_to_file: bool,
    usage_statistics_enabled: bool,
    request_log: bool,
    commercial_mode: bool,
    #[serde(rename = "ws-auth")]
    websocket_auth: bool,
    disable_cooling: bool,
    save_cooldown_status: bool,
    transient_error_cooldown_seconds: i32,
    disable_claude_cloak_mode: bool,
    request_retry: u8,
    max_retry_credentials: u8,
    max_retry_interval: u8,
    force_model_prefix: bool,
    quota_exceeded: QuotaExceeded,
    routing: Routing<'a>,
    streaming: Streaming,
    plugins: Plugins,
}

#[derive(Serialize)]
struct TlsConfig<'a> {
    enable: bool,
    cert: &'a str,
    key: &'a str,
}

#[derive(Serialize)]
#[serde(rename_all = "kebab-case")]
struct RemoteManagement<'a> {
    allow_remote: bool,
    secret_key: &'a str,
    disable_control_panel: bool,
    disable_auto_update_panel: bool,
}

#[derive(Serialize)]
#[serde(rename_all = "kebab-case")]
struct QuotaExceeded {
    switch_project: bool,
    switch_preview_model: bool,
    antigravity_credits: bool,
}

#[derive(Serialize)]
#[serde(rename_all = "kebab-case")]
struct Routing<'a> {
    strategy: &'a str,
    session_affinity: bool,
}

#[derive(Serialize)]
#[serde(rename_all = "kebab-case")]
struct Streaming {
    keepalive_seconds: u8,
    bootstrap_retries: u8,
}

#[derive(Serialize)]
struct Plugins {
    enabled: bool,
}

pub(crate) fn ensure_private_dir(path: &Path) -> Result<PathBuf, CpaConfigError> {
    if !path.is_absolute() {
        return Err(CpaConfigError::InvalidPrivatePath);
    }
    #[cfg(windows)]
    {
        drop(crate::windows_private::directory(path).map_err(CpaConfigError::Io)?);
        return Ok(path.to_owned());
    }
    #[cfg(not(windows))]
    {
        let mut builder = fs::DirBuilder::new();
        builder.recursive(true);
        #[cfg(unix)]
        {
            use std::os::unix::fs::DirBuilderExt;
            builder.mode(0o700);
        }
        builder.create(path).map_err(CpaConfigError::Io)?;
        validate_private_dir(path)?;
        path.canonicalize().map_err(CpaConfigError::Io)
    }
}

pub(crate) fn private_atomic_write(path: &Path, bytes: &[u8]) -> Result<(), CpaConfigError> {
    crate::request_context::io_check().map_err(CpaConfigError::Io)?;
    #[cfg(windows)]
    {
        return crate::windows_private::write(path, bytes).map_err(CpaConfigError::Io);
    }
    #[cfg(not(windows))]
    {
        let parent = path.parent().ok_or(CpaConfigError::InvalidPrivatePath)?;
        validate_private_dir(parent)?;
        let suffix = SecretText::generate()?;
        let temp_path = parent.join(format!(".write-{}.tmp", suffix.expose()));
        let mut options = OpenOptions::new();
        options.write(true).create_new(true);
        set_private_file_create_mode(&mut options);
        let result = (|| {
            let mut file = options.open(&temp_path).map_err(CpaConfigError::Io)?;
            file.write_all(bytes).map_err(CpaConfigError::Io)?;
            file.sync_all().map_err(CpaConfigError::Io)?;
            validate_private_file(&temp_path)?;
            crate::request_context::io_check().map_err(CpaConfigError::Io)?;
            fs::rename(&temp_path, path).map_err(CpaConfigError::Io)?;
            validate_private_file(path)
        })();
        if result.is_err() {
            let _ = fs::remove_file(&temp_path);
        }
        result
    }
}

#[cfg(unix)]
fn validate_private_dir(path: &Path) -> Result<(), CpaConfigError> {
    let metadata = fs::symlink_metadata(path).map_err(CpaConfigError::Io)?;
    if !metadata.is_dir() || metadata.file_type().is_symlink() {
        return Err(CpaConfigError::InsecurePermissions);
    }
    Ok(())
}

#[cfg(not(any(unix, windows)))]
fn validate_private_dir(path: &Path) -> Result<(), CpaConfigError> {
    let metadata = fs::symlink_metadata(path).map_err(CpaConfigError::Io)?;
    if !metadata.is_dir() || metadata.file_type().is_symlink() {
        return Err(CpaConfigError::InsecurePermissions);
    }
    Ok(())
}

#[cfg(unix)]
fn set_private_file_create_mode(options: &mut OpenOptions) {
    use std::os::unix::fs::OpenOptionsExt as _;
    options.mode(0o600);
}

#[cfg(not(any(unix, windows)))]
fn set_private_file_create_mode(_options: &mut OpenOptions) {}

#[cfg(unix)]
pub(crate) fn validate_private_file(path: &Path) -> Result<(), CpaConfigError> {
    use std::os::unix::fs::MetadataExt as _;
    let metadata = fs::symlink_metadata(path).map_err(CpaConfigError::Io)?;
    if !metadata.is_file() || metadata.file_type().is_symlink() || metadata.nlink() != 1 {
        return Err(CpaConfigError::InsecurePermissions);
    }
    Ok(())
}

#[cfg(windows)]
pub(crate) fn validate_private_file(path: &Path) -> Result<(), CpaConfigError> {
    drop(crate::windows_private::file(path).map_err(CpaConfigError::Io)?);
    Ok(())
}

#[cfg(not(any(unix, windows)))]
pub(crate) fn validate_private_file(path: &Path) -> Result<(), CpaConfigError> {
    let metadata = fs::symlink_metadata(path).map_err(CpaConfigError::Io)?;
    if !metadata.is_file() || metadata.file_type().is_symlink() {
        return Err(CpaConfigError::InsecurePermissions);
    }
    Ok(())
}

#[derive(Debug, Error)]
pub enum CpaConfigError {
    #[error("CPA managed configuration is invalid or permits internal routing")]
    InvalidConfig,
    #[error("CPA capability generation failed")]
    Random,
    #[error("CPA local capability is malformed")]
    InvalidCapability,
    #[error("CPA private path is not absolute")]
    InvalidPrivatePath,
    #[error("CPA state/config path is not a safe regular file or directory")]
    InsecurePermissions,
    #[error("CPA state/config I/O failed: {0}")]
    Io(std::io::Error),
    #[error("CPA managed YAML could not be encoded or decoded: {0}")]
    Yaml(serde_yaml::Error),
}

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

    #[test]
    fn managed_config_has_one_local_capability_and_no_provider_key_sections() {
        let temp = tempfile::tempdir().unwrap();
        let auth = temp.path().join("auth");
        ensure_private_dir(&auth).unwrap();
        let secrets = InstanceSecrets::generate().unwrap();
        let bytes = render_managed_config(18080, &auth, &secrets).unwrap();
        let text = String::from_utf8(bytes.clone()).unwrap();
        assert!(!text.contains("codex-api-key"));
        assert!(!text.contains("claude-api-key"));
        assert!(!text.contains("openai-compatibility"));
        CpaManagedConfigContract::validate_rendered(&bytes).unwrap();
    }

    #[test]
    fn managed_config_rejects_retry_or_non_loopback_drift() {
        let temp = tempfile::tempdir().unwrap();
        let auth = temp.path().join("auth");
        ensure_private_dir(&auth).unwrap();
        let secrets = InstanceSecrets::generate().unwrap();
        let bytes = render_managed_config(18081, &auth, &secrets).unwrap();
        let retry = String::from_utf8(bytes.clone())
            .unwrap()
            .replace("request-retry: 0", "request-retry: 1");
        assert!(CpaManagedConfigContract::validate_rendered(retry.as_bytes()).is_err());
        let remote = String::from_utf8(bytes)
            .unwrap()
            .replace("host: 127.0.0.1", "host: 0.0.0.0");
        assert!(CpaManagedConfigContract::validate_rendered(remote.as_bytes()).is_err());
    }

    #[test]
    fn managed_config_rejects_insecure_transport_and_capability_aliasing() {
        let temp = tempfile::tempdir().unwrap();
        let auth = temp.path().join("auth");
        ensure_private_dir(&auth).unwrap();
        let secrets = InstanceSecrets::generate().unwrap();
        let bytes = render_managed_config(18082, &auth, &secrets).unwrap();
        let text = String::from_utf8(bytes).unwrap();
        for drift in [
            text.replace("port: 18082", "port: 0"),
            text.replace("enable: false", "enable: true"),
            text.replace(secrets.management.expose(), secrets.downstream.expose()),
        ] {
            assert!(CpaManagedConfigContract::validate_rendered(drift.as_bytes()).is_err());
        }
    }

    #[test]
    fn capability_file_is_bounded_and_round_trips_without_debug_exposure() {
        let temp = tempfile::tempdir().unwrap();
        #[cfg(not(windows))]
        let root = ensure_private_dir(temp.path()).unwrap();
        #[cfg(windows)]
        let root = ensure_private_dir(&temp.path().join("private")).unwrap();
        let path = root.join("capability");
        let secrets = InstanceSecrets::generate().unwrap();
        secrets.write(&path).unwrap();
        let loaded = InstanceSecrets::read(&path).unwrap();
        assert_eq!(loaded.downstream.expose(), secrets.downstream.expose());
        assert_eq!(format!("{:?}", loaded.downstream), "SecretText([REDACTED])");
    }
}