didbot_config/

lib.rs

//! The sectioned TOML file an operator edits, and its schema.
//!
//! `didbot-pds` grew twenty-one command-line flags before this crate existed,
//! and every epic since has added another. A flag list that long stops being
//! a bootstrap interface: there is no way to see the shape of a deployment
//! at a glance, and a secret cannot travel on one at all: process arguments
//! are world-readable in `/proc/<pid>/cmdline`. This is the file that
//! replaces the list.
//!
//! # The tier this is
//!
//! [`docs/deployment.md`](../../../docs/deployment.md) names three
//! configuration tiers by what they hold, not by what stores them: the
//! operator's repository holds what an agent may do — scope ceilings, admitted
//! apps, collection permissions — and is not reachable on the host at all.
//! Process arguments and this file are the next tier down, reachable by
//! anyone who holds the host, and hold **how the server runs**: bind
//! address, zone, state directory, which DID's policy to read. Local state —
//! caches, refusal records, the emergency stop — is the third.
//!
//! **Nothing in [`Config`] may widen what an agent may do.** A scope, a
//! permission, or an allowlist of apps has no field here, on purpose, even
//! though a config file is the single most tempting place to let one drift
//! in: it is right there, it is already TOML, and it is where an operator is
//! already looking. Those stay in the operator's own repository, per
//! `plan/policy-store.md`, and are read at runtime rather than configured.
//! [`sections::PolicySection`] is the one field this file may hold about
//! policy at all: **which** DID's repository to read, never what that
//! repository is allowed to grant.
//!
//! # Unknown keys refuse startup
//!
//! Every section carries `#[serde(deny_unknown_fields)]`. An ignored key is
//! a setting the operator believes is in force and is not — the same
//! fail-closed reasoning `plan/policy-store.md` applies to a policy version
//! that will not validate. [`Config::load`] and [`Config::parse`] surface
//! the offending key by name, because `toml`'s own deserialization error
//! already names it.
//!
//! # Secrets are paths, never values
//!
//! A field that names a secret holds where the secret lives, not the secret
//! itself. [`check_secret_permissions`] checks that file's own mode and
//! reports — does not refuse — anything readable beyond its owner.
//!
//! No section here names a secret file today, so nothing calls it: the flags
//! it was written for went away with the shared secret they carried.
//! [`sections::TlsSection::cert_source`] is the first field that will need
//! it, once a path to a fixed key pair is something a run reads rather than
//! schema. It is kept because that is a question of when, not whether, and
//! because it is the one place this project writes down what mode a secret
//! file must have.
//!
//! It is not what keeps the secrets this project writes itself safe. Those
//! are created `0600` under a `0700` directory by the crate that owns them,
//! and tightened rather than trusted if they were already on disk — see
//! `didbot_pds::wal`'s `create_dir` and `open_append`, and `didbot-tls`'s
//! certificate store.
//!
//! # Precedence
//!
//! [`precedence()`] is the one place the file, command-line arguments and the
//! environment are resolved against each other: arguments win, then the
//! file, then the environment. See its own doc for why arguments are still
//! highest despite being the leakiest tier.
//!
//! # What is wired today
//!
//! `didbot-pds` reads and applies `[server]`, `[zone]`, `[tls]`, `[blobs]`,
//! `[capacity]`, `[names]`, `[park]`, `[tree]`, `[oidc]`, `[sessions]`,
//! `[credential]`, `[intervals]`, `[disclosure]`, `[operator]`, `[oauth]`,
//! `[relay]`, `[writes]` and `[proxy]`.
//!
//! `[dns]` and `[policy]` are schema: each names a setting whose reader
//! lives in an epic of its own — `plan/dns-providers.md` for provider
//! selection, `plan/policy-store.md` for which DID's records are read as
//! policy — and `plan/config.md` tracks both. A file that sets one parses
//! and validates like any other; an unknown key anywhere in it still
//! refuses startup.

#![forbid(unsafe_code)]

mod precedence;
mod secret;
pub mod sections;

pub use precedence::precedence;
pub use secret::{check_secret_permissions, PermissionWarning};

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

use serde::{Deserialize, Serialize};

use sections::{
    BlobsSection, CapacitySection, CredentialSection, DisclosureSection, DnsSection,
    IntervalsSection, NamesSection, OAuthSection, OidcSection, OperatorSection, ParkSection,
    PolicySection, PoolSection, ProxySection, RelaySection, ServerSection, SessionsSection,
    TlsSection, TreeSection, WritesSection, ZoneSection,
};

/// The whole file, one optional table per section.
///
/// A section an operator has not written is a section this binary decides
/// on its own, the same as a flag nobody passed — so every field here is
/// `Option`, and an empty file parses to a `Config` of every section absent
/// rather than an error.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Config {
    /// `[server]` — bind address, port.
    #[serde(default)]
    pub server: Option<ServerSection>,
    /// `[zone]` — the zones accounts are minted under, and who answers for them.
    #[serde(default)]
    pub zone: Option<ZoneSection>,
    /// `[dns]` — provider selection and its zone.
    #[serde(default)]
    pub dns: Option<DnsSection>,
    /// `[tls]` — ACME environment, contact, certificate source.
    #[serde(default)]
    pub tls: Option<TlsSection>,
    /// `[blobs]` — max size, the per-account and total quotas, retention
    /// window.
    #[serde(default)]
    pub blobs: Option<BlobsSection>,
    /// `[capacity]` — how many accounts this deployment may hold.
    #[serde(default)]
    pub capacity: Option<CapacitySection>,
    /// `[[pool]]` — named sources of names: which zones and labels each
    /// holds, and how it makes a name.
    #[serde(default)]
    pub pool: Option<Vec<PoolSection>>,
    /// `[names]` — the naming spec, its fallback, the number encoding
    /// and the hold period.
    #[serde(default)]
    pub names: Option<NamesSection>,
    /// `[park]` — how `bot.did.parkKey` holds a key.
    #[serde(default)]
    pub park: Option<ParkSection>,
    /// `[tree]` — the shape one creator may give the ownership tree.
    #[serde(default)]
    pub tree: Option<TreeSection>,
    /// `[oidc]` — which issuers' tokens are accepted, and how fresh.
    #[serde(default)]
    pub oidc: Option<OidcSection>,
    /// `[sessions]` — sessions minted from a proof.
    #[serde(default)]
    pub sessions: Option<SessionsSection>,
    /// `[credential]` — how long the agent token provisioning mints lasts.
    #[serde(default)]
    pub credential: Option<CredentialSection>,
    /// `[intervals]` — how often each background loop runs.
    #[serde(default)]
    pub intervals: Option<IntervalsSection>,
    /// `[disclosure]` — which `bot.did.*` routes this run has closed.
    #[serde(default)]
    pub disclosure: Option<DisclosureSection>,
    /// `[operator]` — the operator sign-in's session lifetime, and the
    /// grace window an unreachable operator gets.
    #[serde(default)]
    pub operator: Option<OperatorSection>,
    /// `[oauth]` — the scope ceiling, the pending-decision bounds, and the
    /// resolver permission sets are found through.
    #[serde(default)]
    pub oauth: Option<OAuthSection>,
    /// `[policy]` — which DID's records to read as policy.
    #[serde(default)]
    pub policy: Option<PolicySection>,
    /// `[relay]` — which relays an operator's announce reaches.
    #[serde(default)]
    pub relay: Option<RelaySection>,
    /// `[writes]` — how fast one account may write.
    #[serde(default)]
    pub writes: Option<WritesSection>,
    /// `[proxy]` — what one account may spend of `atproto-proxy`.
    #[serde(default)]
    pub proxy: Option<ProxySection>,
}

/// Everything that can go wrong reading a configuration file, each naming
/// the path it came from.
#[derive(Debug, thiserror::Error)]
pub enum ConfigError {
    /// The file could not be read at all — missing, a permissions problem
    /// of its own, or similar.
    #[error("could not read {path}: {source}")]
    Io {
        /// The file that could not be read.
        path: PathBuf,
        /// What the filesystem said.
        #[source]
        source: std::io::Error,
    },
    /// The file was read but is not valid TOML for this schema: a syntax
    /// error, a value of the wrong type, or an unknown key. `toml`'s own
    /// error already names the offending key or line.
    #[error("{path}: {source}")]
    Parse {
        /// The file that failed to parse.
        path: PathBuf,
        /// What `toml` said, including which key or line was the problem.
        #[source]
        source: Box<toml::de::Error>,
    },
}

impl Config {
    /// Reads and parses a configuration file, naming the path in any error.
    pub fn load(path: &Path) -> Result<Config, ConfigError> {
        let text = std::fs::read_to_string(path).map_err(|source| ConfigError::Io {
            path: path.to_owned(),
            source,
        })?;
        Config::parse(&text).map_err(|source| ConfigError::Parse {
            path: path.to_owned(),
            source: Box::new(source),
        })
    }

    /// Parses configuration text directly, for a caller that already has it
    /// (or a test that would rather not touch a filesystem).
    pub fn parse(text: &str) -> Result<Config, toml::de::Error> {
        toml::from_str(text)
    }
}

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

    #[test]
    fn an_empty_file_is_every_section_absent() {
        let config = Config::parse("").unwrap();
        assert_eq!(config, Config::default());
    }

    #[test]
    fn a_known_section_and_field_parse() {
        let config = Config::parse(
            r#"
            [blobs]
            max_blob_bytes = 1048576
            account_quota_bytes = 16777216
            total_quota_bytes = 1073741824

            [disclosure]
            stats = false
            "#,
        )
        .unwrap();
        let blobs = config.blobs.unwrap();
        assert_eq!(blobs.max_blob_bytes, Some(1048576));
        assert_eq!(blobs.account_quota_bytes, Some(16777216));
        assert_eq!(blobs.total_quota_bytes, Some(1073741824));
        let disclosure = config.disclosure.unwrap();
        assert_eq!(disclosure.stats, Some(false));
        assert_eq!(disclosure.list_accounts, None);
    }

    #[test]
    fn the_two_log_retention_keys_parse_under_capacity() {
        let config = Config::parse(
            r#"
            [capacity]
            evaluation_log_retention_days = 7
            write_log_retention_days = 365
            "#,
        )
        .unwrap();
        let capacity = config.capacity.unwrap();
        assert_eq!(capacity.evaluation_log_retention_days, Some(7));
        assert_eq!(capacity.write_log_retention_days, Some(365));
        assert_eq!(capacity.max_accounts, None);
    }

    #[test]
    fn the_agent_token_ttl_key_parses_under_credential() {
        let config = Config::parse("[credential]\nagent_token_ttl_days = 30\n").unwrap();
        let credential = config.credential.unwrap();
        assert_eq!(credential.agent_token_ttl_days, Some(30));
    }

    #[test]
    fn the_eight_proxy_keys_parse_under_proxy() {
        let config = Config::parse(
            r#"
            [proxy]
            calls_per_minute = 120
            burst_calls = 30
            in_flight_per_account = 4
            in_flight_per_tree = 32
            in_flight_total = 64
            target_cache_secs = 60
            target_cache_entries = 256
            app_view = "did:web:api.bsky.app#bsky_appview"
            "#,
        )
        .unwrap();
        let proxy = config.proxy.unwrap();
        assert_eq!(proxy.calls_per_minute, Some(120));
        assert_eq!(proxy.burst_calls, Some(30));
        assert_eq!(proxy.in_flight_per_account, Some(4));
        assert_eq!(proxy.in_flight_per_tree, Some(32));
        assert_eq!(proxy.in_flight_total, Some(64));
        assert_eq!(proxy.target_cache_secs, Some(60));
        assert_eq!(proxy.target_cache_entries, Some(256));
        assert_eq!(
            proxy.app_view.as_deref(),
            Some("did:web:api.bsky.app#bsky_appview")
        );
    }

    #[test]
    fn an_unknown_top_level_key_refuses() {
        let err = Config::parse("nonsense = true").unwrap_err();
        assert!(
            err.to_string().contains("nonsense"),
            "error should name the key: {err}"
        );
    }

    #[test]
    fn an_unknown_key_inside_a_known_section_refuses() {
        let err = Config::parse("[blobs]\nnot_a_real_field = 1").unwrap_err();
        assert!(
            err.to_string().contains("not_a_real_field"),
            "error should name the key: {err}"
        );
    }

    #[test]
    fn a_malformed_value_refuses_naming_the_problem() {
        // `max_blob_bytes` is a u64; a string cannot fill it.
        let err = Config::parse("[blobs]\nmax_blob_bytes = \"lots\"").unwrap_err();
        let message = err.to_string();
        assert!(
            message.contains("max_blob_bytes") || message.contains("invalid type"),
            "error should point at the bad field or its type: {message}"
        );
    }

    #[test]
    fn invalid_toml_syntax_refuses() {
        assert!(Config::parse("this is not = = toml").is_err());
    }

    #[test]
    fn load_names_the_path_on_a_missing_file() {
        let path = Path::new("/nonexistent/path/that/should/not/exist/didbot.toml");
        let err = Config::load(path).unwrap_err();
        assert!(err.to_string().contains("nonexistent"));
    }

    #[test]
    fn load_names_the_path_on_a_malformed_file() {
        let dir = std::env::temp_dir().join(format!(
            "didbot-config-lib-test-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        std::fs::create_dir_all(&dir).unwrap();
        let path = dir.join("didbot.toml");
        std::fs::write(&path, "nonsense = true").unwrap();
        let err = Config::load(&path).unwrap_err();
        let message = err.to_string();
        assert!(message.contains("didbot.toml"));
        assert!(message.contains("nonsense"));
        let _ = std::fs::remove_dir_all(&dir);
    }
}