mars-server · config

#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum DeploymentEnv {
    #[default]
    Development,
    Staging,
    Production,
}

pub fn parse(raw: &str) -> Self;

pub fn from_env() -> Self;

pub fn as_str(&self) -> &'static str;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum TrustKeyAlgorithm {
    /// Ed25519 verification key encoded as 32-byte hexadecimal.
    Ed25519,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PinnedPublisherKey {
/// Publisher DID controlled by this key.

pub publisher_did: String,
/// Full DID URL, including key fragment.

pub key_id: String,
/// Signature algorithm.

pub algorithm: TrustKeyAlgorithm,
/// Lower- or uppercase hexadecimal encoding of the 32-byte public key.

pub public_key_hex: String
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PinnedPeerKey {
/// Registry DID controlled by this key.

pub peer_did: String,
/// Full DID URL, including key fragment.

pub key_id: String,
/// Signature algorithm.

pub algorithm: TrustKeyAlgorithm,
/// Lower- or uppercase hexadecimal encoding of the 32-byte public key.

pub public_key_hex: String
}

#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct TrustConfig {
/// Override whether at least one publisher pin is required.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub require_pinned_publishers: Option<bool>,
/// Override whether peer pins are required when federation is enabled.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub require_pinned_peers: Option<bool>,
/// Override whether a new HMR/MHR may bootstrap from its embedded key.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub allow_self_signed_bootstrap: Option<bool>,
/// Trusted publisher keys, resolved before registry-stored keys.

#[serde(default)]
pub publisher_keys: Vec<PinnedPublisherKey>,
/// Trusted federation peer keys, resolved before registry-stored keys.

#[serde(default)]
pub peer_keys: Vec<PinnedPeerKey>
}

pub fn requires_pinned_publishers(&self, env: DeploymentEnv) -> bool;

pub fn requires_pinned_peers(&self, env: DeploymentEnv, federation_enabled: bool) -> bool;

pub fn allows_self_signed_bootstrap(&self, env: DeploymentEnv) -> bool;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct AuthConfig {
/// Profiles accepted by the credential registry.

#[serde(default = "default_enabled_auth_profiles")]
pub enabled_profiles: Vec<AuthProfile>,
/// Session lifetime in milliseconds.

#[serde(default = "default_session_ttl_ms")]
pub session_ttl_ms: i64,
/// Challenge lifetime in milliseconds.

#[serde(default = "default_challenge_ttl_ms")]
pub challenge_ttl_ms: i64,
/// Server-pinned SIWS origin. Client requests may omit it or repeat this

/// exact value, but cannot select a different signing origin.

#[serde(default = "default_siws_origin")]
pub expected_siws_origin: String
}

pub fn validate(&self) -> Result<(), crate::ServerError>;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DatabaseConfig {
/// Minimum warm connections retained by the pool.

#[serde(default = "default_min_db_connections")]
pub min_connections: u32,
/// Maximum connections retained by the pool.

#[serde(default = "default_max_db_connections")]
pub max_connections: u32,
/// Maximum wait for a pooled connection.

#[serde(default = "default_db_acquire_timeout_ms")]
pub acquire_timeout_ms: u64,
/// Maximum wait for initial pool establishment.

#[serde(default = "default_db_connect_timeout_ms")]
pub connect_timeout_ms: u64,
/// Maximum idle lifetime for connections above the minimum.

#[serde(default = "default_db_idle_timeout_ms")]
pub idle_timeout_ms: u64,
/// Maximum lifetime for one physical database connection.

#[serde(default = "default_db_max_lifetime_ms")]
pub max_lifetime_ms: u64,
/// PostgreSQL statement timeout installed on every connection.

#[serde(default = "default_db_statement_timeout_ms")]
pub statement_timeout_ms: u64,
/// PostgreSQL lock wait timeout installed on every connection.

#[serde(default = "default_db_lock_timeout_ms")]
pub lock_timeout_ms: u64,
/// PostgreSQL idle-in-transaction timeout installed on every connection.

#[serde(default = "default_db_idle_in_transaction_timeout_ms")]
pub idle_in_transaction_session_timeout_ms: u64,
/// Interval between out-of-band retention cleanup passes.

#[serde(default = "default_db_maintenance_interval_ms")]
pub maintenance_interval_ms: u64
}

pub fn validate(&self) -> Result<(), crate::ServerError>;

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SearchConfig {
/// Maximum lifetime of an issued pagination chain.

#[serde(default = "default_search_cursor_max_age_seconds")]
pub cursor_max_age_seconds: u64,
/// Opt in to the deterministic development/test key.

#[serde(default, skip_serializing_if = "std::ops::Not::not")]
pub use_insecure_test_cursor_key: bool
}

pub fn with_cursor_keys(
        active_cursor_hmac_key: crate::search::SearchCursorKey,
        previous_cursor_hmac_key: Option<crate::search::PreviousSearchCursorKey>,
        cursor_max_age_seconds: u64,
    ) -> Self;

pub fn apply_environment(&mut self) -> Result<(), crate::ServerError>;

pub fn cursor_codec(
        &self,
        env: DeploymentEnv,
    ) -> Result<crate::search::SearchCursorCodec, crate::ServerError>;

pub fn clear_cursor_hmac_keys(&mut self);

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ServerConfig {
/// Deployment environment. Not part of the on-disk config — parsed at

/// startup from the `MARS_ENV` environment variable.

#[serde(skip)]
pub env: DeploymentEnv,
/// Address to bind the HTTP server.

pub listen_addr: SocketAddr,
/// Registry DID (e.g. `"did:oas:registry:mars-1"`).

pub registry_did: String,
/// Maximum entries per discovery query page.

pub max_page_size: u64,
/// Default page size for discovery queries.

pub default_page_size: u64,
/// Search cursor integrity, rotation, and expiry policy.

#[serde(default)]
pub search: SearchConfig,
/// Retention window for authenticated mutation idempotency responses.

#[serde(default = "default_idempotency_ttl_seconds")]
pub idempotency_ttl_seconds: u64,
/// Rate limit configuration.

pub rate_limits: RateLimitConfig,
/// Federation configuration.

pub federation: FederationConfig,
/// Operator trust roots and root-record bootstrap policy.

#[serde(default)]
pub trust: TrustConfig,
/// Authentication adapters and expiry policy.

#[serde(default)]
pub auth: AuthConfig,
/// PostgreSQL connection URL for durable storage.

///

/// **Required in production.** The server refuses to start without this

/// unless `MARS_ALLOW_MEMORY_STORE=1` is set (development/CI only).

///

/// Example: `"postgres://mars:mars@localhost/mars"`

#[serde(skip_serializing_if = "Option::is_none")]
pub database_url: Option<String>,
/// PostgreSQL resource and timeout policy.

#[serde(default)]
pub database: DatabaseConfig,
/// Anchor configuration for on-chain Sigil anchoring.

#[serde(default)]
pub anchor: AnchorServerConfig,
/// Logging level (e.g. `"info"`, `"debug"`, `"warn"`).

#[serde(default = "default_log_level")]
pub log_level: String
}

pub fn env(&self) -> DeploymentEnv;

#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SigilSubmissionMode {
    /// Call Sigil's no-authority simulation endpoint and retain submitted
    /// evidence without broadcasting a transaction.
    #[default]
    Shadow,
    /// Broadcast signed transactions when the emergency switch is enabled.
    Live,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SigilAnchorConfig {
/// Credential-free JSON-RPC endpoint.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub rpc_url: Option<String>,
#[serde(default = "default_sigil_chain_id")]
pub chain_id: String,
/// OAS DID whose registered key authorizes signed anchor transactions.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub sender_did: Option<String>,
/// Environment variable containing the RPC bearer token.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub rpc_token_env: Option<String>,
/// Environment variable containing a 32-byte Ed25519 key in base64url or hex.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub signing_key_env: Option<String>,
#[serde(default = "default_sigil_request_timeout_ms")]
pub request_timeout_ms: u64,
#[serde(default = "default_sigil_connect_timeout_ms")]
pub connect_timeout_ms: u64,
#[serde(default = "default_sigil_finality_timeout_ms")]
pub finality_timeout_ms: u64,
#[serde(default = "default_sigil_max_response_bytes")]
pub max_response_bytes: usize,
#[serde(default = "default_sigil_gas_limit")]
pub gas_limit: u64,
#[serde(default = "default_sigil_gas_price")]
pub gas_price: u64,
#[serde(default)]
pub mode: SigilSubmissionMode,
/// Emergency switch. `false` prevents new live broadcasts while GAL reads,

/// shadow validation, and durable outbox records remain available.

#[serde(default)]
pub submissions_enabled: bool
}

pub fn validate_for(
        &self,
        env: DeploymentEnv,
        anchoring_enabled: bool,
    ) -> Result<(), crate::ServerError>;

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct AnchorServerConfig {
/// Whether mutations enqueue anchor intents and a registered worker runs.

pub enabled: bool,
/// Whether public discovery requires a confirmed current anchor.

#[serde(default)]
pub required: bool,
#[serde(default = "default_anchor_batch_size")]
pub batch_size: u32,
#[serde(default = "default_anchor_lease_ms")]
pub lease_ms: u64,
#[serde(default = "default_anchor_max_attempts", alias = "retryAttempts")]
pub max_attempts: u32,
#[serde(default = "default_anchor_retry_base_ms")]
pub retry_base_ms: u64,
#[serde(default = "default_anchor_retry_max_ms")]
pub retry_max_ms: u64,
#[serde(default = "default_anchor_jitter_bps")]
pub jitter_bps: u16,
#[serde(default = "default_anchor_confirmation_poll_ms")]
pub confirmation_poll_ms: u64,
/// Time confirmed/abandoned intents remain in the hot outbox before

/// archival. Historical records and receipts remain queryable.

#[serde(default = "default_anchor_terminal_retention_ms")]
pub terminal_retention_ms: u64,
/// Maximum terminal intents moved by one maintenance transaction.

#[serde(default = "default_anchor_terminal_archive_batch_size")]
pub terminal_archive_batch_size: u32,
/// Concrete Sigil integration configuration.

#[serde(default)]
pub sigil: SigilAnchorConfig
}

pub fn validate(&self, env: DeploymentEnv) -> Result<(), crate::ServerError>;

pub fn terminal_retention(&self) -> Result<chrono::Duration, crate::ServerError>;

pub fn worker_config(&self) -> Result<crate::anchor::AnchorWorkerConfig, crate::ServerError>;

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct RateLimitConfig {
/// Max write operations per minute per client.

pub writes_per_minute: u32,
/// Max read operations per minute per client.

pub reads_per_minute: u32,
/// Max discovery queries per minute per client.

pub queries_per_minute: u32,
/// Max authentication operations per minute per network client.

#[serde(default = "default_auth_per_minute")]
pub auth_per_minute: u32,
/// Max WebSocket upgrade attempts per minute per network client.

#[serde(default = "default_websocket_per_minute")]
pub websocket_per_minute: u32,
/// Hard cap on resident client buckets in each limiter.

#[serde(default = "default_max_client_buckets")]
pub max_client_buckets: u32,
/// Inactivity TTL for each client bucket.

#[serde(default = "default_bucket_ttl_seconds")]
pub bucket_ttl_seconds: u64,
/// Proxy networks allowed to supply `Forwarded` or `X-Forwarded-For`.

///

/// Forwarding headers from every other direct peer are ignored.

#[serde(default)]
pub trusted_proxy_cidrs: Vec<ipnet::IpNet>
}

pub fn validate(&self) -> Result<(), crate::ServerError>;

#[derive(Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MtlsConfig {
/// Require a client certificate and private trust root for this peer.

#[serde(default)]
pub enabled: bool,
/// PEM client certificate chain.

#[serde(default, skip_serializing)]
pub certificate_path: Option<PathBuf>,
/// PKCS#8 PEM private key. The loader rejects symlinks and permissive Unix

/// file modes.

#[serde(default, skip_serializing)]
pub private_key_path: Option<PathBuf>,
/// PEM CA certificate used to authenticate the peer.

#[serde(default, skip_serializing)]
pub ca_certificate_path: Option<PathBuf>
}

pub fn validate(&self) -> Result<(), crate::ServerError>;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct FederationPeerConfig {
/// Canonical OAS `service` DID expected in signed responses.

pub peer_did: String,
/// HTTPS base URL.

pub endpoint: String,
/// Narrow CIDRs permitted to resolve to non-public addresses.

#[serde(default)]
pub allow_private_cidrs: Vec<ipnet::IpNet>,
/// Persisted agreements that authorize traffic with this peer.

#[serde(default)]
pub agreement_ids: Vec<String>,
/// Optional fail-closed client certificate configuration.

#[serde(default)]
pub mtls: MtlsConfig
}

#[must_use]
pub fn new(peer_did: impl Into<String>, endpoint: impl Into<String>) -> Self;

pub const MAX_FEDERATION_DISCOVERY_PEERS: u32;

pub const MAX_FEDERATION_DISCOVERY_COST: u64;

#[derive(Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct FederationConfig {
/// Whether federation is enabled.

pub enabled: bool,
/// Sync interval in seconds.

pub sync_interval_secs: u64,
/// Maximum entries per sync batch.

pub max_sync_batch: u32,
/// Identity-bound peers contacted by workers and discovery fanout.

#[serde(default)]
pub peers: Vec<FederationPeerConfig>,
/// Durable bilateral agreement documents.

#[serde(default)]
pub agreements: Vec<mars_protocol::federation::FederationAgreement>,
/// Maximum peers synchronized concurrently.

#[serde(default = "default_federation_max_concurrency")]
pub max_concurrency: u32,
/// End-to-end request timeout.

#[serde(default = "default_federation_request_timeout_ms")]
pub request_timeout_ms: u64,
/// TCP/TLS establishment timeout.

#[serde(default = "default_federation_connect_timeout_ms")]
pub connect_timeout_ms: u64,
/// Maximum accepted envelope clock difference.

#[serde(default = "default_federation_clock_skew_seconds")]
pub clock_skew_seconds: u64,
/// Durable replay nonce retention.

#[serde(default = "default_federation_nonce_ttl_seconds")]
pub nonce_ttl_seconds: u64,
/// Failed attempts before a peer's breaker opens.

#[serde(default = "default_federation_breaker_threshold")]
pub breaker_failure_threshold: u32,
/// Breaker cooldown before one half-open probe.

#[serde(default = "default_federation_breaker_cooldown_ms")]
pub breaker_cooldown_ms: u64,
/// Initial exponential retry delay.

#[serde(default = "default_federation_retry_base_ms")]
pub retry_base_ms: u64,
/// Maximum exponential retry delay.

#[serde(default = "default_federation_retry_max_ms")]
pub retry_max_ms: u64,
/// Symmetric retry jitter in basis points.

#[serde(default = "default_federation_jitter_bps")]
pub jitter_bps: u16,
/// Enable bounded peer discovery fanout.

#[serde(default)]
pub discovery_enabled: bool,
/// Maximum peers queried for one federated discovery request.

#[serde(default = "default_federation_discovery_fanout")]
pub discovery_fanout: u32,
/// Per-peer discovery deadline.

#[serde(default = "default_federation_discovery_timeout_ms")]
pub discovery_timeout_ms: u64,
/// Maximum results requested from each peer before local merge.

#[serde(default = "default_federation_discovery_results")]
pub discovery_max_results_per_peer: u32,
/// Maximum remote result slots consumed by one federated discovery call.

///

/// Cost is computed before fanout as selected peers multiplied by

/// `discoveryMaxResultsPerPeer`.

#[serde(default = "default_federation_discovery_max_cost")]
pub discovery_max_cost: u64,
/// Sender key DID URL. Public metadata, safe to serialize.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub signing_key_id: Option<String>,
/// Protected path containing exactly one 32-byte seed, encoded as

/// canonical unpadded base64url. Never serialized.

#[serde(default, skip_serializing)]
pub signing_key_path: Option<PathBuf>,
/// Environment variable holding the same canonical secret. Never

/// serialized. Exactly one path/environment source may be selected.

#[serde(default, skip_serializing)]
pub signing_key_env: Option<String>
}

pub fn validate(&self) -> Result<(), crate::ServerError>;