kanade_shared/wire/

server_settings.rs

use serde::{Deserialize, Serialize};

use crate::config::MailSection;

/// Upper bound on [`ServerSettings::agent_prune_days`] (100 years). A
/// value this large already means "effectively never", and it keeps the
/// cleanup task's `now - Duration::days(n)` subtraction comfortably inside
/// `chrono::DateTime`'s representable range — `DateTime - Duration` panics
/// on overflow, and an unbounded `u32` (~11.7 M years) would trip it.
/// Enforced two ways: the PUT handler rejects a larger value, and
/// [`ServerSettings::effective_agent_prune_days`] clamps to it so even a
/// hand-written KV value can never panic the cleanup task.
pub const MAX_AGENT_PRUNE_DAYS: u32 = 36_500;

/// Built-in retention window (days) for the `collections` Object Store —
/// the file bundles a `collect:` job uploads (#219). This is the value the
/// bootstrap creates a fresh bucket with, and the fallback
/// [`ServerSettings::effective_collect_retention_days`] resolves to when the
/// operator hasn't overridden it. Kept here (not just in `bootstrap`) so the
/// wire default and the bucket's initial `max_age` share one source of truth.
pub const DEFAULT_COLLECT_RETENTION_DAYS: u32 = 30;

/// Upper bound on [`ServerSettings::collect_retention_days`] (10 years).
/// Bundles are debugging / audit artifacts, so an operator has no reason to
/// keep them longer than this; the ceiling stops a fat-fingered value from
/// pushing the `collections` Object Store's `max_age` to something absurd.
/// (The bucket's `max_bytes` cap still bounds actual disk regardless.)
/// Enforced by the PUT handler and clamped in
/// [`ServerSettings::effective_collect_retention_days`] so even a
/// hand-written KV value stays sane.
pub const MAX_COLLECT_RETENTION_DAYS: u32 = 3650;

/// Built-in default for [`ServerSettings::session_ttl_hours`] — how long a
/// freshly-minted SPA/CLI login token stays valid when the operator hasn't
/// overridden it. 24h balances "don't re-auth mid-workday" against a
/// bounded window for a leaked token (the DB row is re-checked every
/// request, so `disable` still takes effect immediately regardless).
pub const DEFAULT_SESSION_TTL_HOURS: u32 = 24;

/// Upper bound on [`ServerSettings::session_ttl_hours`] (365 days). Keeps
/// login's `Utc::now() + Duration::hours(n)` comfortably inside `chrono`'s
/// representable range (its nanosecond `i64` caps out ~292 years, so an
/// unclamped `u32` of hours could overflow) and stops an operator pinning a
/// practically-immortal session. Enforced by the PUT handler and clamped in
/// [`ServerSettings::effective_session_ttl_hours`] so even a hand-written
/// KV value stays bounded.
pub const MAX_SESSION_TTL_HOURS: u32 = 8_760;

/// Built-in default for [`ServerSettings::check_status_stale_days`] (#1032②) —
/// how many days a `check_status` row may go without a fresh result before the
/// Compliance view treats it as **stale** and hides it (a PC that stopped
/// running a check: excluded from its target via a dynamic group, decommissioned,
/// or its schedule removed). 30 days is comfortably longer than a typical daily
/// / weekly compliance cadence, so an in-scope PC is never mistakenly hidden,
/// while a genuinely out-of-scope PC's frozen row drops out within the month.
/// A real default (like `collect_retention_days`) so the feature works out of
/// the box; the operator shortens it for prompter hiding or sets `0` to disable.
pub const DEFAULT_CHECK_STATUS_STALE_DAYS: u32 = 30;

/// Upper bound on [`ServerSettings::check_status_stale_days`] (10 years).
/// Staleness is purely a display cutoff (`now - Duration::days(n)` compared to a
/// row's `recorded_at`), so the ceiling just keeps that subtraction inside
/// `chrono::DateTime`'s range and stops an absurd value; enforced by the PUT
/// handler and clamped in [`ServerSettings::effective_check_status_stale_days`].
pub const MAX_CHECK_STATUS_STALE_DAYS: u32 = 3650;

/// Built-in default for [`SupportCode::ttl_minutes`] — how long an unlock
/// grant lasts when the operator hasn't set a per-code window. 15 minutes is
/// about the length of a helpdesk call: long enough that the desk isn't
/// re-typing the code mid-troubleshoot, short enough that a machine left
/// unattended after the call re-locks on its own.
pub const DEFAULT_SUPPORT_UNLOCK_TTL_MINUTES: u32 = 15;

/// Upper bound on [`SupportCode::ttl_minutes`] (8 hours). An unlock grant is
/// standing permission for an end user's machine to run privileged jobs, so
/// it must not outlive a working day even by operator error — a longer window
/// is a `visible_to` targeting decision, not an unlock one. Enforced by the
/// support-code endpoint and clamped in [`SupportCode::effective_ttl_minutes`]
/// so a hand-written KV value stays bounded too.
pub const MAX_SUPPORT_UNLOCK_TTL_MINUTES: u32 = 480;

/// Per-bucket disk caps (MiB) for the five NATS Object Stores, reconciled
/// onto each backing `OBJ_*` stream at backend boot and on save (#1247).
/// `None` (unset) ⇒ the built-in default below, so a blank SPA field
/// preserves the out-of-box budget and a deployment that never opens the
/// Settings page is still capped.
///
/// Why these exist: `agent_releases` / `app_packages` / `scripts` were
/// created with no caps at all, and caps added to code AFTER a bucket
/// existed never reached the live broker (`ensure_object_store` tolerates
/// the 10058 config-drift error rather than reconciling — which is how
/// `OBJ_result_output` grew to 6.76 GB against a nominal 1 GiB cap).
/// The reconcile path (`bootstrap::reconcile_object_store_max_bytes`) makes
/// the configured value actually land, so these defaults are also the
/// **fix** for already-drifted buckets, applied on the first boot after
/// upgrade.
#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq)]
#[serde(default)]
pub struct ObjectStoreCaps {
    /// `result_output` — overflow stdout/stderr blobs. Transport +
    /// replay buffer (the projector derefs within seconds into SQLite),
    /// so this is a runaway-output backstop, not a history budget.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub result_output_mib: Option<u32>,
    /// `agent_releases` — one exe per version (~100 MB each). Sized for
    /// ~20 recent versions.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub agent_releases_mib: Option<u32>,
    /// `app_packages` — operator-curated installers; the largest bucket
    /// in practice (1.5 GB at measurement time, uncapped).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub app_packages_mib: Option<u32>,
    /// `scripts` — manifest script bodies; tiny payloads, so the cap is
    /// a cardinality backstop.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub scripts_mib: Option<u32>,
    /// `collections` — collect-job bundles. Its `max_age` has its own
    /// knob ([`ServerSettings::collect_retention_days`]); this caps the
    /// disk regardless of window.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub collections_mib: Option<u32>,
}

/// Built-in per-bucket caps (MiB) — the values fresh buckets are born
/// with and unset SPA fields resolve to. Total ≈ 13.5 GiB, comfortably
/// inside the broker-wide `max_file_store: 50GB` once the ~5.3 GiB of
/// stream reservations (bootstrap.rs) are accounted for.
pub const DEFAULT_RESULT_OUTPUT_CAP_MIB: u32 = 1024;

/// How long `OBJECT_RESULT_OUTPUT` keeps an overflowed stdout/stderr blob.
///
/// Seven days, not the thirty it used to be, because the blob is redundant
/// almost immediately: the results projector derefs it into the row before
/// the INSERT, so SQLite holds the text and the SPA reads it from there. What
/// the window buys is one thing only — a `-WipeDb` re-projection replays
/// `STREAM_RESULTS` and re-derefs, so an object that has aged out comes back
/// as empty stdout on the rebuilt row.
///
/// Thirty days of copies nobody reads is what pushed the bucket into its cap,
/// and the cap is a hard wall rather than an eviction trigger (#1321): once
/// full, every result over the inline threshold became undeliverable
/// fleet-wide. A week keeps the recovery path useful for any incident anyone
/// is still investigating while cutting the standing volume by ~4x.
///
/// Bounded above by `STREAM_RESULTS`'s own 30-day window in any case: past
/// that there is no message to replay, so a longer object window buys
/// nothing.
pub const DEFAULT_RESULT_OUTPUT_RETENTION_DAYS: u32 = 7;

/// Upper bound accepted from an operator. Matches `STREAM_RESULTS`'s window —
/// beyond it the messages are gone, so the objects would outlive the only
/// thing that could ask for them.
pub const MAX_RESULT_OUTPUT_RETENTION_DAYS: u32 = 30;
pub const DEFAULT_AGENT_RELEASES_CAP_MIB: u32 = 2048;
pub const DEFAULT_APP_PACKAGES_CAP_MIB: u32 = 5120;
pub const DEFAULT_SCRIPTS_CAP_MIB: u32 = 256;
pub const DEFAULT_COLLECTIONS_CAP_MIB: u32 = 5120;

/// Upper bound per bucket (50 GiB) — the broker-wide `max_file_store`
/// default, so a single bucket can never be configured to eat the whole
/// file store by fat-finger. Enforced by the PUT handler and clamped in
/// the `effective_*` accessors so a hand-written KV value stays bounded.
pub const MAX_OBJECT_STORE_CAP_MIB: u32 = 51_200;

/// Upper bound on the SUM of the five effective bucket caps (45.2 GiB):
/// the broker-wide 50 GiB minus the ~4.8 GiB the streams reserve
/// (INVENTORY 1024 + RESULTS 2048 + EXEC 64 + EVENTS 256 + AUDIT 512 +
/// OBS_EVENTS 512 + NOTIFICATIONS 512 MiB — bootstrap.rs). Without an
/// aggregate bound, five individually-legal caps could total 250 GiB and
/// every `update_stream` would be refused by the broker (10047) — the KV
/// document claiming caps the streams don't have. Enforced by the PUT
/// handler on the merged document.
pub const MAX_OBJECT_STORE_TOTAL_MIB: u32 = 46_272;

impl ObjectStoreCaps {
    fn effective(v: Option<u32>, default: u32) -> u32 {
        v.unwrap_or(default).clamp(1, MAX_OBJECT_STORE_CAP_MIB)
    }

    pub fn effective_result_output_mib(&self) -> u32 {
        Self::effective(self.result_output_mib, DEFAULT_RESULT_OUTPUT_CAP_MIB)
    }
    pub fn effective_agent_releases_mib(&self) -> u32 {
        Self::effective(self.agent_releases_mib, DEFAULT_AGENT_RELEASES_CAP_MIB)
    }
    pub fn effective_app_packages_mib(&self) -> u32 {
        Self::effective(self.app_packages_mib, DEFAULT_APP_PACKAGES_CAP_MIB)
    }
    pub fn effective_scripts_mib(&self) -> u32 {
        Self::effective(self.scripts_mib, DEFAULT_SCRIPTS_CAP_MIB)
    }
    pub fn effective_collections_mib(&self) -> u32 {
        Self::effective(self.collections_mib, DEFAULT_COLLECTIONS_CAP_MIB)
    }

    /// `(bucket, effective cap in MiB)` for every object store, in
    /// bootstrap order — the reconcile loop's input.
    pub fn effective_all(&self) -> [(&'static str, u32); 5] {
        [
            (
                crate::kv::OBJECT_AGENT_RELEASES,
                self.effective_agent_releases_mib(),
            ),
            (
                crate::kv::OBJECT_APP_PACKAGES,
                self.effective_app_packages_mib(),
            ),
            (crate::kv::OBJECT_SCRIPTS, self.effective_scripts_mib()),
            (
                crate::kv::OBJECT_RESULT_OUTPUT,
                self.effective_result_output_mib(),
            ),
            (
                crate::kv::OBJECT_COLLECTIONS,
                self.effective_collections_mib(),
            ),
        ]
    }
}

/// One operator-issued support code — the "裏コマンド" that reveals
/// `client.unlock`-scoped jobs in the Client App (see
/// [`crate::manifest::ClientHint::unlock`]).
///
/// **Only the argon2id hash is stored.** Verification needs no plaintext, so
/// unlike the SMTP password (#884, which must stay in the HKLM registry
/// because SMTP AUTH needs the real string) a support code can live in KV
/// safely — an agent reads the hash to verify a typed code locally, which is
/// what keeps unlocking working while the backend is down, exactly when the
/// desk needs it most.
///
/// The plaintext exists only in transit: the operator types it once into the
/// SPA, the backend hashes it, and no layer ever stores or returns it. The
/// API blanks [`hash`](Self::hash) on the way out too — an operator rotating
/// a code sets a new one, they never read the old one back.
#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq)]
#[serde(default)]
pub struct SupportCode {
    /// The scope this code opens, matched byte-for-byte against a job's
    /// `client.unlock`. Unique within the list; a slug (`[A-Za-z0-9._-]`).
    pub scope: String,
    /// argon2id PHC-format hash of the code. Empty ⇒ **no code configured**
    /// for this scope, which fails closed (nothing can be unlocked with it) —
    /// that's also what an API response looks like, since the hash is blanked
    /// before it leaves the backend.
    #[serde(skip_serializing_if = "String::is_empty")]
    pub hash: String,
    /// Human label for the code (`"ヘルプデスク一次窓口"`), shown in the
    /// Client App's support-mode banner so the user can see which desk opened
    /// their machine. `None` ⇒ the banner falls back to the scope slug.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub label: Option<String>,
    /// How long a grant from this code lasts, in minutes. `None` ⇒
    /// [`DEFAULT_SUPPORT_UNLOCK_TTL_MINUTES`]. Clamped to
    /// `1..=`[`MAX_SUPPORT_UNLOCK_TTL_MINUTES`].
    #[serde(skip_serializing_if = "Option::is_none")]
    pub ttl_minutes: Option<u32>,
    /// Temporarily suspend the code without deleting it (and without having
    /// to re-issue a new secret afterwards) — a disabled code never verifies.
    /// `false` (the default) ⇒ live.
    #[serde(skip_serializing_if = "std::ops::Not::not")]
    pub disabled: bool,
}

impl SupportCode {
    /// The grant window this code mints, in minutes: the configured value if
    /// set, else [`DEFAULT_SUPPORT_UNLOCK_TTL_MINUTES`]. Floored at 1 and
    /// clamped to [`MAX_SUPPORT_UNLOCK_TTL_MINUTES`] so a `0` (which would
    /// mint an already-expired grant, i.e. an unlock that silently does
    /// nothing) or an out-of-band giant value can't reach the grant store.
    pub fn effective_ttl_minutes(&self) -> u32 {
        self.ttl_minutes
            .unwrap_or(DEFAULT_SUPPORT_UNLOCK_TTL_MINUTES)
            .clamp(1, MAX_SUPPORT_UNLOCK_TTL_MINUTES)
    }

    /// Whether this entry can ever grant anything: live and carrying a hash.
    /// Both halves fail closed — a blanked (API-redacted) or hand-cleared
    /// hash opens nothing, and neither does a disabled code.
    pub fn is_usable(&self) -> bool {
        !self.disabled && !self.hash.is_empty()
    }
}

/// The agent-readable projection of [`ServerSettings::support_codes`], stored
/// under [`crate::kv::KEY_SUPPORT_CODES`] in `fleet_config`.
///
/// `server_settings` also carries secrets an agent has no business reading
/// (the installer's NATS token, in clear at the KV layer, SMTP relay
/// settings). The support-unlock check needs only the argon2id hashes, so the
/// backend publishes just those here and agents read this instead. Keep it
/// that way: [`Self::from_settings`] copies `support_codes` explicitly rather
/// than cloning the settings and stripping fields, so a field added to
/// `ServerSettings` later can never leak into this document by default.
///
/// Deliberately no `deny_unknown_fields`: a future field must not break
/// agents that predate it.
#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq)]
#[serde(default)]
pub struct SupportCodesProjection {
    pub support_codes: Vec<SupportCode>,
}

impl SupportCodesProjection {
    pub fn from_settings(settings: &ServerSettings) -> Self {
        Self {
            support_codes: settings.support_codes.clone(),
        }
    }
}

/// Self-service agent-installer knobs (`GET /api/agents/installer`) —
/// what the generated ZIP bakes in for a fresh PC. Kept server-side so the
/// restricted "download user" (viewer + the `agent-install` feature only)
/// never chooses — and never sees — these values.
// PartialEq/Eq beyond the minimal derive list: `ServerSettings` derives
// them, so every section must too.
#[derive(Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default)]
pub struct AgentInstallSection {
    /// NATS URL baked into the installer's agent.toml. None → the backend's
    /// own configured `[nats] url`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub nats_url: Option<String>,
    /// NATS token baked into install-agent.ps1. WRITE-ONLY: redacted from
    /// every GET response (GET /api/server-settings is viewer+).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub nats_token: Option<String>,
    /// Read-only indicator computed by redacted() so the SPA can show
    /// "configured" without ever seeing the value. Never accepted from PUT.
    #[serde(skip_deserializing)]
    pub nats_token_set: bool,
    /// Agent-role NATS user baked into the installer next to the token, so a
    /// host installed today already holds the credential the broker will
    /// later require. Shared by every agent by design. WRITE-ONLY exactly
    /// like `nats_token`, and a pair with `nats_password`: the installer
    /// embeds them only when both are present.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub nats_user: Option<String>,
    /// Read-only indicator for `nats_user`, computed by redacted().
    #[serde(skip_deserializing)]
    pub nats_user_set: bool,
    /// Password for `nats_user`. WRITE-ONLY, see `nats_user`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub nats_password: Option<String>,
    /// Read-only indicator for `nats_password`, computed by redacted().
    #[serde(skip_deserializing)]
    pub nats_password_set: bool,
    /// Ask the generated Windows installer to pass `-RequireSignedCommands`
    /// to `deploy-agent.ps1`, so a fresh agent starts enforcing signed
    /// commands from first boot instead of leaving that as a manual
    /// post-install step (#1155/#1165 day-1 gap).
    ///
    /// `None`/`Some(false)` → omitted, matching every other unset knob here.
    /// `Some(true)` is honored by the installer ONLY when this backend also
    /// has a command-signing key configured — see
    /// `agent_installer::resolve_enforcement`. A backend with no key must
    /// never generate an installer that turns on enforcement with an empty
    /// keyring; that request is instead surfaced in the installer's
    /// README.txt rather than silently dropped.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub require_signed_commands: Option<bool>,
}

// Hand-written so a stray `{:?}` / `?settings` in a log line can never
// print the write-only credentials.
impl std::fmt::Debug for AgentInstallSection {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let mask = |v: &Option<String>| v.as_ref().map(|_| "<redacted>");
        f.debug_struct("AgentInstallSection")
            .field("nats_url", &self.nats_url)
            .field("nats_token", &mask(&self.nats_token))
            .field("nats_token_set", &self.nats_token_set)
            .field("nats_user", &mask(&self.nats_user))
            .field("nats_user_set", &self.nats_user_set)
            .field("nats_password", &mask(&self.nats_password))
            .field("nats_password_set", &self.nats_password_set)
            .field("require_signed_commands", &self.require_signed_commands)
            .finish()
    }
}

/// Which authentication the operator expects the broker to apply to every
/// connection. An **expectation**, not a switch: it changes nothing about how
/// any process connects, it only defines which connection reports the
/// backend raises a warning for (see the backend's `nats_auth_findings`).
#[derive(Serialize, Deserialize, Debug, Clone, Copy, Default, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum NatsAuthMode {
    /// One fleet-wide token. Today's shape, and what an unset field means.
    #[default]
    Token,
    /// Per-role NATS users (`authorization { users: [...] }`).
    Users,
}

impl NatsAuthMode {
    pub fn as_str(self) -> &'static str {
        match self {
            NatsAuthMode::Token => "token",
            NatsAuthMode::Users => "users",
        }
    }
}

/// Value stored in the `server_settings` KV bucket under the single key
/// [`crate::kv::KEY_SERVER_SETTINGS`]. Operator-editable, backend-side
/// server configuration that isn't per-agent (so it doesn't belong in
/// `agent_config`'s layered scopes) and isn't a fleet-wide switch every
/// agent watches (so it doesn't belong in `fleet_config`). Managed via
/// the SPA Settings page's "server settings" tab.
///
/// Every field is `Option<_>`: `None` (the default / the JSON value
/// `null` / the field simply absent) means **unset — fall back to the
/// built-in default** ([`ServerSettings::defaults`]), exactly like the
/// agent layered-config scopes. The SPA renders the built-in default as a
/// faint placeholder so a blank field shows what it resolves to, and when
/// a real default is introduced here it appears in the UI (and takes
/// effect for already-deployed-but-unset fleets) for free.
///
/// `#[serde(default)]` on the container keeps the document backward/forward
/// compatible: a freshly-created or missing key decodes to all-`None`
/// (pre-feature behaviour), an older backend reading a newer document
/// ignores unknown fields, and a newer backend reading an older document
/// fills the missing field with `None`. Keep that invariant — never add a
/// field whose `None` doesn't mean "behave as before".
#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq)]
#[serde(default)]
pub struct ServerSettings {
    /// Days a dead agent (one whose heartbeat stopped arriving) may
    /// linger in the `agents` registry before the backend cleanup task
    /// prunes its row.
    ///
    /// `None` (unset) falls back to the built-in default; with no default
    /// configured that resolves to pruning **disabled** (see
    /// [`ServerSettings::effective_agent_prune_days`]). A positive value
    /// makes the cleanup sweep delete rows whose `last_heartbeat` is older
    /// than that many days. The `agents` table is a projection of the
    /// heartbeat stream, so a machine that's merely offline (not gone)
    /// reappears on its next heartbeat (~30s cadence); only
    /// genuinely-retired machines stay gone.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub agent_prune_days: Option<u32>,

    /// Agent group whose members are the trusted **controller-tier**
    /// runners. A job with `tier: controller` (e.g. a `feed:` job that
    /// fetches an external URL) is dispatched ONLY to members of this group;
    /// `None` (unset) means controller-tier jobs run **nowhere** (fail-safe,
    /// so an external fetch never lands on an employee endpoint by accident).
    /// See `crate::manifest::Tier`. `None` ⇒ no controller runners
    /// configured, which is the safe default for a fresh deployment.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub controller_group: Option<String>,

    /// Non-secret SMTP relay settings for outbound email (compliance-alert
    /// notifications, account setup links, …). Lives here (#884) rather than
    /// in `backend.toml` so an operator can edit it from the SPA without
    /// shell access to the host.
    ///
    /// `None` (unset) ⇒ no relay configured, email is a no-op — the in-app
    /// / NATS notification path is unaffected. The SMTP **password is
    /// deliberately not here** (KV is
    /// readable over NATS): it stays sourced from the `MailPassword`
    /// registry secret / `$KANADE_MAIL_PASSWORD` and is combined with these
    /// settings when the backend builds its `Mailer`. Changes take effect on
    /// the **next backend restart** (the backend builds the `Mailer` once at
    /// startup — no live rebuild), which is acceptable per the #884
    /// discussion.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub mail: Option<MailSection>,

    /// Self-service agent-installer knobs — see [`AgentInstallSection`].
    /// `None` (unset) ⇒ the installer falls back to this backend's own
    /// `[nats] url` and embeds no token. The `nats_token` inside is
    /// write-only: [`ServerSettings::redacted`] strips it from every
    /// response and the PUT merge preserves a stored token across a
    /// url-only edit (the same support-code trap: a form round-trip must
    /// never silently clear a secret).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub agent_install: Option<AgentInstallSection>,

    /// Retention window (days) for collected file bundles — the `collect:`
    /// job archives uploaded to the `collections` Object Store (#219).
    ///
    /// Unlike the other fields, this one has a **real built-in default**
    /// ([`DEFAULT_COLLECT_RETENTION_DAYS`], 30 d): `None` (unset) falls back
    /// to it, so a blank field preserves the historical behaviour rather than
    /// disabling retention. A positive value tells the backend to reconcile
    /// the Object Store's `max_age` to that many days (see
    /// `bootstrap::reconcile_collect_retention`), applied at boot and again
    /// whenever this document is saved from the SPA. Clamped to
    /// [`MAX_COLLECT_RETENTION_DAYS`]. The bucket's `max_bytes` cap is
    /// untouched, so extending the window can't make the store grow unbounded.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub collect_retention_days: Option<u32>,

    /// How long `OBJECT_RESULT_OUTPUT` keeps an overflowed stdout/stderr
    /// blob, in days. Absent / null falls back to
    /// [`DEFAULT_RESULT_OUTPUT_RETENTION_DAYS`].
    ///
    /// Unlike `collect_retention_days`, this window is NOT how long the data
    /// survives — the results projector derefs each blob into the row before
    /// the INSERT, so the text lives in SQLite and the SPA reads it from
    /// there regardless. What it bounds is how long a `-WipeDb`
    /// re-projection can still recover that text: replay re-derefs, and an
    /// aged-out object comes back as empty stdout on the rebuilt row.
    ///
    /// So this trades recovery window against standing volume, and volume is
    /// what filled the bucket into its cap (#1321 — a hard wall, not
    /// eviction) and stopped result delivery fleet-wide. Clamped to
    /// [`MAX_RESULT_OUTPUT_RETENTION_DAYS`], which is `STREAM_RESULTS`'s own
    /// window: past it there is no message left to replay.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub result_output_retention_days: Option<u32>,

    /// How many hours a freshly-minted login token (SPA / CLI) stays valid
    /// before the caller must re-authenticate. Read backend-side by the
    /// login handler when it mints the JWT `exp`; changing it affects
    /// **tokens minted after the change**, not already-issued ones.
    ///
    /// Like [`collect_retention_days`](Self::collect_retention_days) this
    /// carries a **real built-in default** ([`DEFAULT_SESSION_TTL_HOURS`],
    /// 24h): `None` (unset) falls back to it, so a blank field resolves to a
    /// usable window rather than an instantly-expired token. Clamped to
    /// `1..=`[`MAX_SESSION_TTL_HOURS`]. The SPA renders `24` as a faint
    /// placeholder on a blank field.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub session_ttl_hours: Option<u32>,

    /// Days a `check_status` row may go without a fresh result before the
    /// Compliance page treats it as **stale** and hides it (#1032②). A PC that
    /// stops running a check — excluded from its target via a dynamic group,
    /// decommissioned, or its schedule removed — stops refreshing its row's
    /// `recorded_at`; once that timestamp is older than this window the row is
    /// omitted from the default `/api/checks` view and its counts, so a machine
    /// no longer in scope stops showing as permanently failing a check it never
    /// runs.
    ///
    /// Like [`collect_retention_days`](Self::collect_retention_days) this carries
    /// a **real built-in default** ([`DEFAULT_CHECK_STATUS_STALE_DAYS`], 30d), so
    /// the feature works with no configuration. `0` **disables** staleness
    /// (every row shown, the pre-feature behaviour); a positive value is the
    /// cutoff, clamped to [`MAX_CHECK_STATUS_STALE_DAYS`]. The row is never
    /// deleted — hiding is non-destructive so history and the compliance-alert
    /// prior-status are preserved.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub check_status_stale_days: Option<u32>,

    /// Per-bucket disk caps (MiB) for the five NATS Object Stores (#1247)
    /// — see [`ObjectStoreCaps`]. `None` (unset) ⇒ every bucket resolves
    /// to its built-in default, so a blank field preserves the out-of-box
    /// budget. Applied to the backing `OBJ_*` streams at backend boot and
    /// whenever this document is saved from the SPA
    /// (`bootstrap::reconcile_object_store_max_bytes`), which is also what
    /// finally delivers caps to buckets created before the caps existed.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub object_store_caps: Option<ObjectStoreCaps>,

    /// The broker authentication mode the operator expects — see
    /// [`NatsAuthMode`]. `None` (unset) is `token`, the behaviour before this
    /// field existed. Read by the backend's connection audit only; no
    /// connection is made differently because of it.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub nats_auth_mode: Option<NatsAuthMode>,

    /// When the **effective** expected mode last changed. Written by the
    /// backend alone, at the moment a save moves the mode, and never taken
    /// from a client: the audit holds its findings back for a short window
    /// after this instant so connections re-establishing under the new mode
    /// are not reported while they converge. A re-save of the same mode (or a
    /// restart) leaves it alone, so the window cannot be extended by saving.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub nats_auth_mode_changed_at: Option<chrono::DateTime<chrono::Utc>>,

    /// Operator-issued support codes — the helpdesk "裏コマンド" that reveals
    /// `client.unlock`-scoped jobs in the Client App. See [`SupportCode`].
    ///
    /// The one non-`Option` field in this document, because a list has an
    /// honest empty state: `[]` (the default) means **no codes configured**,
    /// so every `client.unlock` job stays hidden from everyone — the same
    /// fail-closed "behave as before" the `None`s give the other fields.
    ///
    /// Unlike the rest of the document this is read by **agents** as well as
    /// the backend (each agent verifies a typed code against these hashes
    /// locally, so an unlock still works during a backend outage), and it is
    /// **not** editable through the generic `PUT /api/server-settings` merge:
    /// a secret gets its own set-and-forget endpoint so a redacted document
    /// round-tripping through the SPA form can never blank a live code.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub support_codes: Vec<SupportCode>,
}

impl ServerSettings {
    /// Built-in defaults applied when a field is unset (`None`) in the
    /// stored document. Most fields default to `None` (no fleet-meaningful
    /// default — a blank prune window means "disabled" rather than some
    /// arbitrary number of days). The exceptions carry real defaults so a
    /// blank field still resolves to a sensible value:
    /// [`collect_retention_days`](Self::collect_retention_days)
    /// ([`DEFAULT_COLLECT_RETENTION_DAYS`], preserving the historical 30-day
    /// retention), [`result_output_retention_days`](Self::result_output_retention_days)
    /// ([`DEFAULT_RESULT_OUTPUT_RETENTION_DAYS`], 7 days — deliberately NOT
    /// the historical 30, see that constant) and
    /// [`session_ttl_hours`](Self::session_ttl_hours)
    /// ([`DEFAULT_SESSION_TTL_HOURS`], 24h).
    ///
    /// Exposed via `GET /api/server-settings/defaults` so the SPA renders
    /// these as faint placeholders (mirroring the agent layered-config
    /// page's built-in floor). Introducing a real default is a one-line
    /// change here that automatically shows up in the UI and applies to
    /// every deployment that hasn't overridden the field.
    pub fn defaults() -> Self {
        Self {
            agent_prune_days: None,
            controller_group: None,
            mail: None,
            agent_install: None,
            collect_retention_days: Some(DEFAULT_COLLECT_RETENTION_DAYS),
            result_output_retention_days: Some(DEFAULT_RESULT_OUTPUT_RETENTION_DAYS),
            session_ttl_hours: Some(DEFAULT_SESSION_TTL_HOURS),
            check_status_stale_days: Some(DEFAULT_CHECK_STATUS_STALE_DAYS),
            nats_auth_mode: None,
            nats_auth_mode_changed_at: None,
            // Real per-bucket defaults, so the SPA renders them as faint
            // placeholders and unset deployments are capped out of the box.
            object_store_caps: Some(ObjectStoreCaps {
                result_output_mib: Some(DEFAULT_RESULT_OUTPUT_CAP_MIB),
                agent_releases_mib: Some(DEFAULT_AGENT_RELEASES_CAP_MIB),
                app_packages_mib: Some(DEFAULT_APP_PACKAGES_CAP_MIB),
                scripts_mib: Some(DEFAULT_SCRIPTS_CAP_MIB),
                collections_mib: Some(DEFAULT_COLLECTIONS_CAP_MIB),
            }),
            // No built-in code: a deployment that configures none has no
            // unlockable jobs, which is the only safe default for a secret.
            support_codes: Vec::new(),
        }
    }

    /// The caps document with every bucket resolved: stored values where
    /// set, built-in defaults elsewhere, each clamped to
    /// `1..=MAX_OBJECT_STORE_CAP_MIB` so an out-of-band KV write can't
    /// reach the broker unsanitised.
    pub fn effective_object_store_caps(&self) -> ObjectStoreCaps {
        let c = self.object_store_caps.clone().unwrap_or_default();
        ObjectStoreCaps {
            result_output_mib: Some(c.effective_result_output_mib()),
            agent_releases_mib: Some(c.effective_agent_releases_mib()),
            app_packages_mib: Some(c.effective_app_packages_mib()),
            scripts_mib: Some(c.effective_scripts_mib()),
            collections_mib: Some(c.effective_collections_mib()),
        }
    }

    /// The live code for `scope`, or `None` when the scope has no code, its
    /// code is disabled, or the hash was blanked (an API-redacted document).
    /// Every caller of this is a gate, so all three cases fail closed.
    pub fn support_code(&self, scope: &str) -> Option<&SupportCode> {
        self.support_codes
            .iter()
            .find(|c| c.scope == scope && c.is_usable())
    }

    /// The same document with every support-code hash blanked — what an HTTP
    /// response is allowed to contain. Scope / label / TTL stay visible so
    /// the SPA can list and manage the codes; the secret material never
    /// leaves the backend, not even to an operator-authenticated caller.
    /// (`GET /api/server-settings` is viewer+, so an unredacted document
    /// would hand every read-only account an offline-crackable hash.)
    ///
    /// Same treatment for `agent_install.nats_token`: it is a live broker
    /// credential baked into installer ZIPs, so it never leaves the backend
    /// either — the response carries only `nats_token_set` (computed HERE,
    /// never accepted from a client) so the SPA can render "configured".
    /// `nats_user` / `nats_password` get the same `*_set` treatment.
    #[must_use]
    pub fn redacted(mut self) -> Self {
        for c in &mut self.support_codes {
            c.hash.clear();
        }
        if let Some(ai) = self.agent_install.as_mut() {
            ai.nats_token_set = ai.nats_token.is_some();
            ai.nats_token = None;
            ai.nats_user_set = ai.nats_user.is_some();
            ai.nats_user = None;
            ai.nats_password_set = ai.nats_password.is_some();
            ai.nats_password = None;
        }
        self
    }

    /// The configured controller-tier runner group, trimmed, or `None` when
    /// unset / blank. `None` ⇒ controller-tier jobs run nowhere (fail-safe).
    pub fn effective_controller_group(&self) -> Option<&str> {
        self.controller_group
            .as_deref()
            .map(str::trim)
            .filter(|g| !g.is_empty())
    }

    /// The effective dead-agent prune window in days: the stored value if
    /// set, else the built-in default, else `0` (= pruning disabled). The
    /// final `unwrap_or(0)` is the absent-everywhere floor, not a
    /// user-facing default — the cleanup task treats `0` as "don't prune".
    ///
    /// Clamped to [`MAX_AGENT_PRUNE_DAYS`] so the cleanup task's
    /// `now - Duration::days(n)` can never overflow `DateTime` (and panic
    /// the task), even if a value larger than the PUT handler allows was
    /// written to the KV out-of-band.
    pub fn effective_agent_prune_days(&self) -> u32 {
        self.agent_prune_days
            .or(Self::defaults().agent_prune_days)
            .unwrap_or(0)
            .min(MAX_AGENT_PRUNE_DAYS)
    }

    /// The effective collect-bundle retention window in days: the stored
    /// value if set, else the built-in default ([`DEFAULT_COLLECT_RETENTION_DAYS`]).
    /// Floored at 1 and clamped to [`MAX_COLLECT_RETENTION_DAYS`] so an
    /// out-of-band KV write can't reach the Object Store `max_age` unsanitised.
    /// The floor matters specifically because NATS treats `max_age: 0` as
    /// **unlimited** retention, not "evict immediately": a stray `0` would
    /// silently make bundles never expire (defeating the auto-expire intent),
    /// so we coerce it to the shortest real window (1 day) instead. The PUT
    /// handler already rejects `0` / over-cap, so this is the belt-and-braces
    /// path for a hand-edited KV value.
    pub fn effective_collect_retention_days(&self) -> u32 {
        self.collect_retention_days
            .or(Self::defaults().collect_retention_days)
            .unwrap_or(DEFAULT_COLLECT_RETENTION_DAYS)
            .clamp(1, MAX_COLLECT_RETENTION_DAYS)
    }

    /// The effective `result_output` retention window in days: the stored
    /// value if set, else the built-in default. Floored at 1 and clamped to
    /// [`MAX_RESULT_OUTPUT_RETENTION_DAYS`] so a hand-written KV value can
    /// neither disable retention outright nor outlive the stream it exists
    /// to serve.
    pub fn effective_result_output_retention_days(&self) -> u32 {
        self.result_output_retention_days
            .or(Self::defaults().result_output_retention_days)
            .unwrap_or(DEFAULT_RESULT_OUTPUT_RETENTION_DAYS)
            .clamp(1, MAX_RESULT_OUTPUT_RETENTION_DAYS)
    }

    /// The effective login-token lifetime in hours: the stored value if
    /// set, else the built-in [`DEFAULT_SESSION_TTL_HOURS`]. Floored at 1
    /// and clamped to [`MAX_SESSION_TTL_HOURS`] so a zero/absent/out-of-band
    /// value can never mint an already-expired or overflow-inducing token.
    /// The PUT handler already rejects `0` / over-cap, so this is the
    /// belt-and-braces path for a hand-edited KV value.
    pub fn effective_session_ttl_hours(&self) -> u32 {
        self.session_ttl_hours
            .or(Self::defaults().session_ttl_hours)
            .unwrap_or(DEFAULT_SESSION_TTL_HOURS)
            .clamp(1, MAX_SESSION_TTL_HOURS)
    }

    /// The expected broker authentication mode, with unset resolved to
    /// [`NatsAuthMode::Token`].
    pub fn effective_nats_auth_mode(&self) -> NatsAuthMode {
        self.nats_auth_mode.unwrap_or_default()
    }

    /// The effective check-staleness window in days: the stored value if set,
    /// else the built-in [`DEFAULT_CHECK_STATUS_STALE_DAYS`]. **`0` means
    /// disabled** (no row is ever hidden as stale) — deliberately NOT floored to
    /// 1 (unlike collect/session), because 0 is a meaningful "show everything"
    /// value here, the same convention as [`agent_prune_days`](Self::agent_prune_days).
    /// Clamped to [`MAX_CHECK_STATUS_STALE_DAYS`] so an out-of-band KV write
    /// can't overflow the `now - Duration::days(n)` cutoff math.
    pub fn effective_check_status_stale_days(&self) -> u32 {
        self.check_status_stale_days
            .or(Self::defaults().check_status_stale_days)
            .unwrap_or(DEFAULT_CHECK_STATUS_STALE_DAYS)
            .min(MAX_CHECK_STATUS_STALE_DAYS)
    }
}

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

    #[test]
    fn default_is_unset() {
        assert_eq!(ServerSettings::default().agent_prune_days, None);
    }

    #[test]
    fn unset_resolves_to_disabled() {
        // No stored value + no built-in default ⇒ effective 0 (disabled).
        assert_eq!(ServerSettings::default().effective_agent_prune_days(), 0);
    }

    #[test]
    fn stored_value_wins_over_default() {
        let s = ServerSettings {
            agent_prune_days: Some(30),
            ..Default::default()
        };
        assert_eq!(s.effective_agent_prune_days(), 30);
    }

    #[test]
    fn effective_clamps_to_max() {
        // An out-of-band KV write larger than the PUT cap must not reach
        // the cleanup task unclamped (else its DateTime subtraction panics).
        let s = ServerSettings {
            agent_prune_days: Some(u32::MAX),
            ..Default::default()
        };
        assert_eq!(s.effective_agent_prune_days(), MAX_AGENT_PRUNE_DAYS);
    }

    #[test]
    fn round_trips_through_json() {
        let s = ServerSettings {
            agent_prune_days: Some(30),
            ..Default::default()
        };
        let json = serde_json::to_string(&s).unwrap();
        assert_eq!(json, r#"{"agent_prune_days":30}"#);
        let back: ServerSettings = serde_json::from_str(&json).unwrap();
        assert_eq!(back, s);
    }

    #[test]
    fn unset_serialises_to_empty_object() {
        // `skip_serializing_if` keeps an all-unset doc minimal; it must
        // round-trip back to all-`None`.
        let s = ServerSettings::default();
        let json = serde_json::to_string(&s).unwrap();
        assert_eq!(json, "{}");
        let back: ServerSettings = serde_json::from_str(&json).unwrap();
        assert_eq!(back, s);
    }

    #[test]
    fn explicit_null_decodes_to_unset() {
        let s: ServerSettings = serde_json::from_str(r#"{"agent_prune_days":null}"#).unwrap();
        assert_eq!(s.agent_prune_days, None);
    }

    #[test]
    fn empty_object_decodes_to_default() {
        // A freshly-created key (or one written by an older backend that
        // didn't know this field) must read back as the pre-feature
        // behaviour, not fail to decode.
        let s: ServerSettings = serde_json::from_str("{}").unwrap();
        assert_eq!(s, ServerSettings::default());
    }

    #[test]
    fn controller_group_effective_trims_and_blank_is_unset() {
        assert_eq!(ServerSettings::default().effective_controller_group(), None);
        let s = ServerSettings {
            controller_group: Some("  feed-runners ".into()),
            ..Default::default()
        };
        assert_eq!(s.effective_controller_group(), Some("feed-runners"));
        // A blank/whitespace value reads as unset (fail-safe: no runner).
        let blank = ServerSettings {
            controller_group: Some("   ".into()),
            ..Default::default()
        };
        assert_eq!(blank.effective_controller_group(), None);
    }

    #[test]
    fn controller_group_round_trips_and_omits_when_unset() {
        let s = ServerSettings {
            controller_group: Some("infra".into()),
            ..Default::default()
        };
        let json = serde_json::to_string(&s).unwrap();
        assert_eq!(json, r#"{"controller_group":"infra"}"#);
        assert_eq!(serde_json::from_str::<ServerSettings>(&json).unwrap(), s);
        // Unset controller_group is omitted (skip_serializing_if).
        assert_eq!(
            serde_json::to_string(&ServerSettings::default()).unwrap(),
            "{}"
        );
    }

    #[test]
    fn mail_round_trips_and_omits_when_unset() {
        use crate::config::{MailEncryption, MailSection};

        // Unset mail is omitted (skip_serializing_if) — a mail-less doc
        // stays minimal and decodes back to `None`.
        assert_eq!(
            serde_json::to_string(&ServerSettings::default()).unwrap(),
            "{}"
        );

        let s = ServerSettings {
            mail: Some(MailSection {
                host: "smtp.example.com".into(),
                port: 587,
                encryption: MailEncryption::Starttls,
                from: "kanade-noreply@example.com".into(),
                username: Some("kanade-noreply".into()),
            }),
            ..Default::default()
        };
        let json = serde_json::to_string(&s).unwrap();
        // Encryption serialises lowercase; the password is never present.
        assert!(json.contains(r#""encryption":"starttls""#), "json: {json}");
        assert!(!json.contains("password"), "password must never serialise");
        assert_eq!(serde_json::from_str::<ServerSettings>(&json).unwrap(), s);
    }

    #[test]
    fn mail_defaults_to_unset() {
        assert_eq!(ServerSettings::default().mail, None);
        // A doc written before this field existed (no `mail` key) decodes
        // to `None` — email stays a no-op, the pre-feature behaviour.
        let s: ServerSettings = serde_json::from_str(r#"{"agent_prune_days":7}"#).unwrap();
        assert_eq!(s.mail, None);
        assert_eq!(s.agent_prune_days, Some(7));
    }

    #[test]
    fn collect_retention_unset_resolves_to_builtin_default() {
        // Blank (the derived Default) must preserve the historical 30-day
        // window, not disable retention.
        assert_eq!(ServerSettings::default().collect_retention_days, None);
        assert_eq!(
            ServerSettings::default().effective_collect_retention_days(),
            DEFAULT_COLLECT_RETENTION_DAYS,
        );
        // The defaults() document surfaces the real default so the SPA can
        // render it as a placeholder.
        assert_eq!(
            ServerSettings::defaults().collect_retention_days,
            Some(DEFAULT_COLLECT_RETENTION_DAYS),
        );
    }

    #[test]
    fn collect_retention_stored_value_wins() {
        let s = ServerSettings {
            collect_retention_days: Some(90),
            ..Default::default()
        };
        assert_eq!(s.effective_collect_retention_days(), 90);
    }

    #[test]
    fn collect_retention_effective_clamps_out_of_band_writes() {
        // A hand-written KV value past the PUT cap (or 0) must be clamped so
        // the reconciled Object Store max_age stays sane.
        let big = ServerSettings {
            collect_retention_days: Some(u32::MAX),
            ..Default::default()
        };
        assert_eq!(
            big.effective_collect_retention_days(),
            MAX_COLLECT_RETENTION_DAYS,
        );
        let zero = ServerSettings {
            collect_retention_days: Some(0),
            ..Default::default()
        };
        assert_eq!(zero.effective_collect_retention_days(), 1);
    }

    #[test]
    fn result_output_retention_defaults_to_a_week_not_the_old_month() {
        // The built-in default IS the fix: existing buckets were born at 30
        // days and reconcile down to this. If someone raises it back the
        // bucket grows again, so the value is pinned rather than left to the
        // constant's own definition.
        assert_eq!(DEFAULT_RESULT_OUTPUT_RETENTION_DAYS, 7);
        assert_eq!(
            ServerSettings::default().effective_result_output_retention_days(),
            7
        );
    }

    #[test]
    fn result_output_retention_is_capped_by_the_stream_it_serves() {
        // Beyond STREAM_RESULTS' own window there is no message left to
        // replay, so a longer object window keeps blobs nothing can ask for.
        assert_eq!(MAX_RESULT_OUTPUT_RETENTION_DAYS, 30);
        let big = ServerSettings {
            result_output_retention_days: Some(u32::MAX),
            ..Default::default()
        };
        assert_eq!(
            big.effective_result_output_retention_days(),
            MAX_RESULT_OUTPUT_RETENTION_DAYS
        );
        // …and 0 is floored rather than disabling retention, which would put
        // the bucket straight back to unbounded growth.
        let zero = ServerSettings {
            result_output_retention_days: Some(0),
            ..Default::default()
        };
        assert_eq!(zero.effective_result_output_retention_days(), 1);
    }

    #[test]
    fn collect_retention_round_trips_and_omits_when_unset() {
        let s = ServerSettings {
            collect_retention_days: Some(90),
            ..Default::default()
        };
        let json = serde_json::to_string(&s).unwrap();
        assert_eq!(json, r#"{"collect_retention_days":90}"#);
        assert_eq!(serde_json::from_str::<ServerSettings>(&json).unwrap(), s);
        // Unset is omitted so a blank doc stays minimal.
        assert!(
            !serde_json::to_string(&ServerSettings::default())
                .unwrap()
                .contains("collect_retention_days")
        );
    }

    #[test]
    fn session_ttl_unset_resolves_to_builtin_default() {
        // Blank (the derived Default) must resolve to the 24h default rather
        // than 0 (which would mint already-expired tokens).
        assert_eq!(ServerSettings::default().session_ttl_hours, None);
        assert_eq!(
            ServerSettings::default().effective_session_ttl_hours(),
            DEFAULT_SESSION_TTL_HOURS,
        );
        // The defaults() document surfaces the real default so the SPA can
        // render it as a placeholder.
        assert_eq!(
            ServerSettings::defaults().session_ttl_hours,
            Some(DEFAULT_SESSION_TTL_HOURS),
        );
    }

    #[test]
    fn session_ttl_stored_value_wins() {
        let s = ServerSettings {
            session_ttl_hours: Some(72),
            ..Default::default()
        };
        assert_eq!(s.effective_session_ttl_hours(), 72);
    }

    #[test]
    fn session_ttl_effective_clamps_out_of_band_writes() {
        // An out-of-band 0 must floor to 1 (else `now + 0h` is an
        // instantly-expired token); a value past the cap clamps down so
        // login's date math can't overflow.
        let zero = ServerSettings {
            session_ttl_hours: Some(0),
            ..Default::default()
        };
        assert_eq!(zero.effective_session_ttl_hours(), 1);
        let huge = ServerSettings {
            session_ttl_hours: Some(u32::MAX),
            ..Default::default()
        };
        assert_eq!(huge.effective_session_ttl_hours(), MAX_SESSION_TTL_HOURS);
    }

    #[test]
    fn session_ttl_round_trips_and_omits_when_unset() {
        let s = ServerSettings {
            session_ttl_hours: Some(48),
            ..Default::default()
        };
        let json = serde_json::to_string(&s).unwrap();
        assert_eq!(json, r#"{"session_ttl_hours":48}"#);
        assert_eq!(serde_json::from_str::<ServerSettings>(&json).unwrap(), s);
        // Unset is omitted so a blank doc stays minimal.
        assert!(
            !serde_json::to_string(&ServerSettings::default())
                .unwrap()
                .contains("session_ttl_hours")
        );
    }

    #[test]
    fn check_stale_unset_resolves_to_builtin_default() {
        // Blank (the derived Default) resolves to the 30-day default — ON out
        // of the box, so the feature works without configuration.
        assert_eq!(ServerSettings::default().check_status_stale_days, None);
        assert_eq!(
            ServerSettings::default().effective_check_status_stale_days(),
            DEFAULT_CHECK_STATUS_STALE_DAYS,
        );
        // defaults() surfaces the real default for the SPA placeholder.
        assert_eq!(
            ServerSettings::defaults().check_status_stale_days,
            Some(DEFAULT_CHECK_STATUS_STALE_DAYS),
        );
    }

    #[test]
    fn check_stale_zero_disables() {
        // Explicit 0 means "disable staleness" (show everything) — NOT floored
        // to 1 like collect/session; same convention as agent_prune_days.
        let s = ServerSettings {
            check_status_stale_days: Some(0),
            ..Default::default()
        };
        assert_eq!(s.effective_check_status_stale_days(), 0);
    }

    #[test]
    fn check_stale_stored_value_wins_and_clamps() {
        let s = ServerSettings {
            check_status_stale_days: Some(7),
            ..Default::default()
        };
        assert_eq!(s.effective_check_status_stale_days(), 7);
        let big = ServerSettings {
            check_status_stale_days: Some(u32::MAX),
            ..Default::default()
        };
        assert_eq!(
            big.effective_check_status_stale_days(),
            MAX_CHECK_STATUS_STALE_DAYS,
        );
    }

    #[test]
    fn check_stale_round_trips_and_omits_when_unset() {
        let s = ServerSettings {
            check_status_stale_days: Some(14),
            ..Default::default()
        };
        let json = serde_json::to_string(&s).unwrap();
        assert_eq!(json, r#"{"check_status_stale_days":14}"#);
        assert_eq!(serde_json::from_str::<ServerSettings>(&json).unwrap(), s);
        assert!(
            !serde_json::to_string(&ServerSettings::default())
                .unwrap()
                .contains("check_status_stale_days")
        );
    }

    #[test]
    fn support_codes_absent_by_default_and_omitted_from_the_wire() {
        // The pre-feature document must round-trip byte-identically: no
        // `support_codes` key, so an older backend / agent reading it sees
        // exactly what it saw before, and nothing is unlockable.
        let s = ServerSettings::default();
        assert!(s.support_codes.is_empty());
        assert_eq!(serde_json::to_string(&s).unwrap(), "{}");
        assert!(s.support_code("support").is_none());
    }

    #[test]
    fn support_code_lookup_fails_closed() {
        let s = ServerSettings {
            support_codes: vec![
                SupportCode {
                    scope: "support".into(),
                    hash: "$argon2id$v=19$m=19456,t=2,p=1$c2FsdA$aGFzaA".into(),
                    label: Some("ヘルプデスク".into()),
                    ..Default::default()
                },
                SupportCode {
                    scope: "admin".into(),
                    hash: "$argon2id$v=19$m=19456,t=2,p=1$c2FsdA$aGFzaA".into(),
                    disabled: true,
                    ..Default::default()
                },
                SupportCode {
                    // Hash blanked — what an API-redacted document looks like.
                    // It must never be treated as a live code.
                    scope: "blank".into(),
                    ..Default::default()
                },
            ],
            ..Default::default()
        };
        assert!(s.support_code("support").is_some());
        assert!(s.support_code("admin").is_none(), "disabled must not match");
        assert!(
            s.support_code("blank").is_none(),
            "blank hash must not match"
        );
        assert!(s.support_code("nope").is_none());
    }

    #[test]
    fn redacted_blanks_hashes_but_keeps_the_roster() {
        // The SPA still needs to see WHICH scopes exist (to list / rotate /
        // delete them); it must never see the hash.
        let s = ServerSettings {
            support_codes: vec![SupportCode {
                scope: "support".into(),
                hash: "$argon2id$secret".into(),
                label: Some("ヘルプデスク".into()),
                ttl_minutes: Some(30),
                disabled: false,
            }],
            ..Default::default()
        };
        let json = serde_json::to_string(&s.redacted()).unwrap();
        assert!(!json.contains("argon2"), "wire leaked the hash: {json}");
        assert!(!json.contains("hash"), "wire leaked the hash key: {json}");
        assert!(json.contains("\"scope\":\"support\""), "wire: {json}");
        assert!(json.contains("\"ttl_minutes\":30"), "wire: {json}");
    }

    #[test]
    fn support_code_ttl_clamps() {
        let unset = SupportCode::default();
        assert_eq!(
            unset.effective_ttl_minutes(),
            DEFAULT_SUPPORT_UNLOCK_TTL_MINUTES
        );
        // 0 would mint an already-expired grant (an unlock that silently
        // does nothing) — floored to the shortest real window instead.
        let zero = SupportCode {
            ttl_minutes: Some(0),
            ..Default::default()
        };
        assert_eq!(zero.effective_ttl_minutes(), 1);
        let huge = SupportCode {
            ttl_minutes: Some(u32::MAX),
            ..Default::default()
        };
        assert_eq!(huge.effective_ttl_minutes(), MAX_SUPPORT_UNLOCK_TTL_MINUTES);
    }

    #[test]
    fn accepts_unknown_fields_for_forward_compat() {
        // A newer backend may have added knobs this build doesn't know;
        // decoding must drop them rather than error.
        let json = r#"{"agent_prune_days":7,"some_future_knob":true}"#;
        let s: ServerSettings = serde_json::from_str(json).unwrap();
        assert_eq!(s.agent_prune_days, Some(7));
    }

    #[test]
    fn object_store_caps_unset_resolves_to_builtin_defaults() {
        // Blank doc ⇒ every bucket capped at its built-in default — the
        // out-of-box fix for uncapped / drifted buckets (#1247).
        let s = ServerSettings::default();
        assert_eq!(s.object_store_caps, None);
        let c = s.effective_object_store_caps();
        assert_eq!(c.result_output_mib, Some(DEFAULT_RESULT_OUTPUT_CAP_MIB));
        assert_eq!(c.agent_releases_mib, Some(DEFAULT_AGENT_RELEASES_CAP_MIB));
        assert_eq!(c.app_packages_mib, Some(DEFAULT_APP_PACKAGES_CAP_MIB));
        assert_eq!(c.scripts_mib, Some(DEFAULT_SCRIPTS_CAP_MIB));
        assert_eq!(c.collections_mib, Some(DEFAULT_COLLECTIONS_CAP_MIB));
    }

    #[test]
    fn object_store_caps_partial_override_keeps_other_defaults() {
        let s = ServerSettings {
            object_store_caps: Some(ObjectStoreCaps {
                app_packages_mib: Some(8192),
                ..Default::default()
            }),
            ..Default::default()
        };
        let c = s.effective_object_store_caps();
        assert_eq!(c.app_packages_mib, Some(8192));
        assert_eq!(c.scripts_mib, Some(DEFAULT_SCRIPTS_CAP_MIB));
    }

    #[test]
    fn object_store_caps_clamps_out_of_band_writes() {
        let s = ServerSettings {
            object_store_caps: Some(ObjectStoreCaps {
                result_output_mib: Some(0),
                app_packages_mib: Some(u32::MAX),
                ..Default::default()
            }),
            ..Default::default()
        };
        let c = s.effective_object_store_caps();
        // 0 floors to 1 MiB — NATS treats max_bytes: 0 as unlimited, the
        // exact failure mode this feature exists to remove.
        assert_eq!(c.result_output_mib, Some(1));
        assert_eq!(c.app_packages_mib, Some(MAX_OBJECT_STORE_CAP_MIB));
    }

    #[test]
    fn object_store_caps_round_trips_and_omits_when_unset() {
        let s = ServerSettings {
            object_store_caps: Some(ObjectStoreCaps {
                scripts_mib: Some(512),
                ..Default::default()
            }),
            ..Default::default()
        };
        let json = serde_json::to_string(&s).unwrap();
        assert_eq!(json, r#"{"object_store_caps":{"scripts_mib":512}}"#);
        assert_eq!(serde_json::from_str::<ServerSettings>(&json).unwrap(), s);
        assert!(
            !serde_json::to_string(&ServerSettings::default())
                .unwrap()
                .contains("object_store_caps")
        );
    }

    #[test]
    fn agent_install_defaults_to_unset_and_omits_when_unset() {
        assert_eq!(ServerSettings::default().agent_install, None);
        assert_eq!(ServerSettings::defaults().agent_install, None);
        // A doc written before this field existed decodes to `None` — the
        // installer then falls back to the backend's own [nats] url, the
        // pre-feature behaviour.
        let s: ServerSettings = serde_json::from_str(r#"{"agent_prune_days":7}"#).unwrap();
        assert_eq!(s.agent_install, None);
        assert!(
            !serde_json::to_string(&ServerSettings::default())
                .unwrap()
                .contains("agent_install")
        );
    }

    #[test]
    fn agent_install_round_trips() {
        let s = ServerSettings {
            agent_install: Some(AgentInstallSection {
                nats_url: Some("nats://broker.corp:4222".into()),
                nats_token: Some("s3cret".into()),
                nats_token_set: false,
                require_signed_commands: None,
                ..Default::default()
            }),
            ..Default::default()
        };
        let json = serde_json::to_string(&s).unwrap();
        assert_eq!(
            json,
            r#"{"agent_install":{"nats_url":"nats://broker.corp:4222","nats_token":"s3cret","nats_token_set":false,"nats_user_set":false,"nats_password_set":false}}"#
        );
        assert_eq!(serde_json::from_str::<ServerSettings>(&json).unwrap(), s);
    }

    #[test]
    fn agent_install_require_signed_commands_round_trips() {
        let s = ServerSettings {
            agent_install: Some(AgentInstallSection {
                require_signed_commands: Some(true),
                ..Default::default()
            }),
            ..Default::default()
        };
        let json = serde_json::to_string(&s).unwrap();
        assert_eq!(
            json,
            r#"{"agent_install":{"nats_token_set":false,"nats_user_set":false,"nats_password_set":false,"require_signed_commands":true}}"#
        );
        assert_eq!(serde_json::from_str::<ServerSettings>(&json).unwrap(), s);
    }

    #[test]
    fn agent_install_token_set_is_never_accepted_from_the_wire() {
        // `skip_deserializing`: a client sending nats_token_set gets it
        // dropped, so the indicator can only ever come from redacted()
        // looking at the real stored token — never from a claim.
        let s: ServerSettings = serde_json::from_str(
            r#"{"agent_install":{"nats_url":"nats://b:4222","nats_token_set":true}}"#,
        )
        .unwrap();
        let ai = s.agent_install.unwrap();
        assert!(!ai.nats_token_set);
        assert_eq!(ai.nats_url.as_deref(), Some("nats://b:4222"));
    }

    #[test]
    fn redacted_strips_the_install_token_but_reports_its_presence() {
        // GET /api/server-settings is viewer+, so the stored NATS token must
        // never survive redacted() — not even to an operator. The boolean is
        // all the SPA gets to render "configured".
        let with_token = ServerSettings {
            agent_install: Some(AgentInstallSection {
                nats_url: Some("nats://broker.corp:4222".into()),
                nats_token: Some("s3cret".into()),
                nats_token_set: false,
                require_signed_commands: None,
                ..Default::default()
            }),
            ..Default::default()
        };
        let redacted = with_token.redacted();
        let ai = redacted.agent_install.as_ref().unwrap();
        assert_eq!(ai.nats_token, None, "token must not survive redacted()");
        assert!(ai.nats_token_set);
        // The URL is not a secret — it stays.
        assert_eq!(ai.nats_url.as_deref(), Some("nats://broker.corp:4222"));
        // And on the wire the token key is gone entirely (not null).
        let json = serde_json::to_string(&redacted).unwrap();
        assert!(!json.contains("s3cret"), "wire leaked the token: {json}");
        assert!(!json.contains("nats_token\""), "wire: {json}");
        assert!(json.contains(r#""nats_token_set":true"#), "wire: {json}");

        // No token configured → indicator false, nothing to strip.
        let sans_token = ServerSettings {
            agent_install: Some(AgentInstallSection {
                nats_url: Some("nats://broker.corp:4222".into()),
                ..Default::default()
            }),
            ..Default::default()
        }
        .redacted();
        let ai = sans_token.agent_install.as_ref().unwrap();
        assert!(!ai.nats_token_set);
    }

    #[test]
    fn redacted_strips_the_user_pair_but_reports_presence() {
        let redacted = ServerSettings {
            agent_install: Some(AgentInstallSection {
                nats_user: Some("agent-u".into()),
                nats_password: Some("p@ss'w0rd".into()),
                ..Default::default()
            }),
            ..Default::default()
        }
        .redacted();
        let ai = redacted.agent_install.as_ref().unwrap();
        assert_eq!(ai.nats_user, None);
        assert_eq!(ai.nats_password, None);
        assert!(ai.nats_user_set && ai.nats_password_set);
        let json = serde_json::to_string(&redacted).unwrap();
        assert!(!json.contains("agent-u"), "wire leaked the user: {json}");
        assert!(!json.contains("w0rd"), "wire leaked the password: {json}");
        assert!(json.contains(r#""nats_user_set":true"#), "wire: {json}");
        assert!(json.contains(r#""nats_password_set":true"#), "wire: {json}");
    }

    #[test]
    fn user_pair_flags_are_never_accepted_from_the_wire() {
        let s: ServerSettings = serde_json::from_str(
            r#"{"agent_install":{"nats_user_set":true,"nats_password_set":true}}"#,
        )
        .unwrap();
        let ai = s.agent_install.unwrap();
        assert!(!ai.nats_user_set && !ai.nats_password_set);
    }

    #[test]
    fn debug_never_prints_the_credentials() {
        let ai = AgentInstallSection {
            nats_token: Some("tok-secret".into()),
            nats_user: Some("user-secret".into()),
            nats_password: Some("pw-secret".into()),
            ..Default::default()
        };
        let dbg = format!("{ai:?}");
        for needle in ["tok-secret", "user-secret", "pw-secret"] {
            assert!(!dbg.contains(needle), "Debug leaked {needle}: {dbg}");
        }
    }
}