From 9bf8974d235f517b106466bdb5db3eed979674ac Mon Sep 17 00:00:00 2001 From: John Coffey Date: Wed, 18 Nov 2026 15:09:30 -0700 Subject: [PATCH] Secrets from files: INBUXA__FILE (K-S2) INBUXA_RECOVERY_ADMIN and INBUXA_WEBMAIL_CLIENT_SECRET can come instead from a file that INBUXA_RECOVERY_ADMIN_FILE or INBUXA_WEBMAIL_CLIENT_SECRET_FILE names, such as a mounted Kubernetes or Docker secret, so a secret never has to sit in the environment, where anything that can read the process's environment or the pod spec sees it. The relay's INBUXA_RELAY_JOIN_TOKEN takes _FILE the same way. The file's trailing newline is dropped. Both forms set, or a file that can't be read or is empty, stops the server as it starts (boot checks every one), naming the variable and the path, never the secret. The rule lives in types::branding::secret_env_var, its core a pure function the unit tests drive; SECRET_ENV_VARS lists the variables it covers. --- Dockerfile.relay | 3 +- crates/common/src/manager/boot.rs | 6 + crates/common/src/manager/first_party.rs | 20 +++- crates/relay/src/main.rs | 68 +++++++++++- crates/store/src/registry/local.rs | 5 +- crates/types/src/branding.rs | 136 ++++++++++++++++++++++- docs/spec/SPEC.md | 8 ++ docs/spec/features/relay.md | 2 +- 8 files changed, 240 insertions(+), 8 deletions(-) diff --git a/Dockerfile.relay b/Dockerfile.relay index 01660186..380fdebe 100644 --- a/Dockerfile.relay +++ b/Dockerfile.relay @@ -10,7 +10,8 @@ # nothing more, and keeps its state in /var/lib/inbuxa-relay. It sets # INBUXA_RELAY_CONTAINER, so the relay reports selfUpgrade: false and an # upgrade is a new image (RL-29). On its first run it joins with -# INBUXA_RELAY_JOIN_TOKEN. +# INBUXA_RELAY_JOIN_TOKEN, or the token in the file +# INBUXA_RELAY_JOIN_TOKEN_FILE names (a mounted secret). # # Docker Hub images, pulled through Google's mirror, as in Dockerfile. FROM mirror.gcr.io/library/rust:1-alpine3.22 AS builder diff --git a/crates/common/src/manager/boot.rs b/crates/common/src/manager/boot.rs index a156356b..51a84ee7 100644 --- a/crates/common/src/manager/boot.rs +++ b/crates/common/src/manager/boot.rs @@ -113,6 +113,12 @@ enum StoreOp { impl BootManager { pub async fn init() -> Self { + // inbuxa: K-S2: a secret given as INBUXA__FILE that can't be + // read, or given twice, stops the start here, before anything uses it + if let Err(message) = types::branding::check_secret_env_vars() { + eprintln!("Error: {message}"); + std::process::exit(1); + } let mut config_path = std::env::var("CONFIG_PATH").ok(); let mut import_export = StoreOp::None; diff --git a/crates/common/src/manager/first_party.rs b/crates/common/src/manager/first_party.rs index 7d954246..e44b5d28 100644 --- a/crates/common/src/manager/first_party.rs +++ b/crates/common/src/manager/first_party.rs @@ -223,7 +223,23 @@ pub fn front_end_origins(stored: &FrontEnds) -> Vec { /// Whether the environment gives the webmail its secret. `inbuxa:FrontEnds` /// can't set one then: the environment's would be put back at every start. pub fn webmail_secret_from_environment() -> bool { - env("WEBMAIL_CLIENT_SECRET").is_some() + webmail_secret_env().is_some() +} + +/// inbuxa: K-S2: INBUXA_WEBMAIL_CLIENT_SECRET, or the file +/// INBUXA_WEBMAIL_CLIENT_SECRET_FILE names. Boot refuses a bad one, so this +/// only fails if the file went away since; that is reported, and the secret +/// treated as unset. +fn webmail_secret_env() -> Option { + match types::branding::secret_env_var("WEBMAIL_CLIENT_SECRET") { + Ok(secret) => secret + .map(|value| value.trim().to_string()) + .filter(|value| !value.is_empty()), + Err(message) => { + trc::event!(Auth(trc::AuthEvent::Error), Details = message); + None + } + } } fn env(name: &str) -> Option { @@ -254,7 +270,7 @@ pub async fn ensure_first_party_clients(bp: &mut Bootstrap) -> trc::Result<()> { .into_iter() .chain(stored.webmail_url.clone()) .collect(); - let webmail_secret = env("WEBMAIL_CLIENT_SECRET") + let webmail_secret = webmail_secret_env() .map(ClientSecret::Plain) .or_else(|| stored.webmail_secret_hash.clone().map(ClientSecret::Hash)); if !webmail_urls.is_empty() && webmail_secret.is_none() { diff --git a/crates/relay/src/main.rs b/crates/relay/src/main.rs index bc4af630..a40a69ab 100644 --- a/crates/relay/src/main.rs +++ b/crates/relay/src/main.rs @@ -174,13 +174,53 @@ enum Stopped { Upgraded, } +/// inbuxa: K-S2: the join token, from INBUXA_RELAY_JOIN_TOKEN or from the +/// file INBUXA_RELAY_JOIN_TOKEN_FILE names (a mounted secret). Both set, or a +/// file that can't be read or holds nothing, is refused. +fn join_token_from_env() -> Result, String> { + let value = std::env::var("INBUXA_RELAY_JOIN_TOKEN") + .ok() + .filter(|v| !v.trim().is_empty()); + let file = std::env::var("INBUXA_RELAY_JOIN_TOKEN_FILE") + .ok() + .filter(|v| !v.trim().is_empty()); + join_token(value, file, |path| std::fs::read_to_string(path)) +} + +fn join_token( + value: Option, + file: Option, + read: impl Fn(&str) -> std::io::Result, +) -> Result, String> { + match (value, file) { + (Some(_), Some(_)) => Err( + "INBUXA_RELAY_JOIN_TOKEN and INBUXA_RELAY_JOIN_TOKEN_FILE are both set: set one of them" + .into(), + ), + (Some(token), None) => Ok(Some(token)), + (None, Some(path)) => { + let path = path.trim(); + let token = read(path).map_err(|err| { + format!("INBUXA_RELAY_JOIN_TOKEN_FILE: can't read {path}: {err}") + })?; + let token = token.trim(); + if token.is_empty() { + Err(format!("INBUXA_RELAY_JOIN_TOKEN_FILE: {path} is empty")) + } else { + Ok(Some(token.to_string())) + } + } + (None, None) => Ok(None), + } +} + fn run(paths: &Paths, link_listen: SocketAddr, link_allow_any: bool) -> Result { paths.create_dirs().map_err(|e| e.to_string())?; let _lock = RunLock::acquire(paths).map_err(|e| e.to_string())?; let identity = match Identity::load(paths).map_err(|e| e.to_string())? { Some(identity) => identity, - None => match std::env::var("INBUXA_RELAY_JOIN_TOKEN") { - Ok(token) if !token.trim().is_empty() => { + None => match join_token_from_env()? { + Some(token) => { join(paths, &token)?; Identity::load(paths) .map_err(|e| e.to_string())? @@ -411,3 +451,27 @@ fn reset(paths: &Paths, discard_held: bool) -> Result<(), String> { ); Ok(()) } + +#[cfg(test)] +mod join_token_tests { + use super::join_token; + + #[test] + fn the_join_token_comes_from_the_variable_or_its_file() { + let no_file = |_: &str| -> std::io::Result { panic!("no file to read") }; + assert_eq!(join_token(None, None, no_file), Ok(None)); + assert_eq!( + join_token(Some("t".into()), None, no_file), + Ok(Some("t".into())) + ); + assert_eq!( + join_token(None, Some("/run/t".into()), |_| Ok("tok\n".into())), + Ok(Some("tok".into())) + ); + assert!(join_token(Some("t".into()), Some("/run/t".into()), no_file).is_err()); + assert_eq!( + join_token(None, Some("/run/t".into()), |_| Ok("\n".into())), + Err("INBUXA_RELAY_JOIN_TOKEN_FILE: /run/t is empty".into()) + ); + } +} diff --git a/crates/store/src/registry/local.rs b/crates/store/src/registry/local.rs index 23450b2c..6a0a1369 100644 --- a/crates/store/src/registry/local.rs +++ b/crates/store/src/registry/local.rs @@ -41,8 +41,11 @@ impl RegistryStoreInner { .ok() .map(|v| v == "1" || v.eq_ignore_ascii_case("true")) .unwrap_or(false), - env_recovery_admin: types::branding::env_var("RECOVERY_ADMIN") + // inbuxa: K-S2: or from INBUXA_RECOVERY_ADMIN_FILE; boot has + // already refused a bad one (check_secret_env_vars) + env_recovery_admin: types::branding::secret_env_var("RECOVERY_ADMIN") .ok() + .flatten() .and_then(|v| { v.split_once(':') .map(|(a, p)| (a.trim().to_string(), p.trim().to_string())) diff --git a/crates/types/src/branding.rs b/crates/types/src/branding.rs index 22abdda0..d6402458 100644 --- a/crates/types/src/branding.rs +++ b/crates/types/src/branding.rs @@ -85,6 +85,71 @@ pub fn env_var(name: &str) -> Result { found } +/// inbuxa: K-S2: the secrets the server takes from its environment. Each can +/// come instead from a file that `INBUXA__FILE` names (a mounted +/// Kubernetes or Docker secret), so it never has to be in the environment. +pub const SECRET_ENV_VARS: &[&str] = &["RECOVERY_ADMIN", "WEBMAIL_CLIENT_SECRET"]; + +/// inbuxa: K-S2: one of [`SECRET_ENV_VARS`], from `INBUXA_` or from the +/// file `INBUXA__FILE` names. `Ok(None)` when neither is set. Setting +/// both is refused, as is a file that can't be read or holds nothing; the +/// message names the variable and the path, never the secret. +pub fn secret_env_var(name: &str) -> Result, String> { + let value = match env_var(name) { + Ok(value) => Some(value), + Err(std::env::VarError::NotPresent) => None, + Err(std::env::VarError::NotUnicode(_)) => { + return Err(format!("INBUXA_{name} isn't valid UTF-8")); + } + }; + let file = match env_var(&format!("{name}_FILE")) { + Ok(path) => Some(path), + Err(std::env::VarError::NotPresent) => None, + Err(std::env::VarError::NotUnicode(_)) => { + return Err(format!("INBUXA_{name}_FILE isn't valid UTF-8")); + } + }; + resolve_secret(name, value, file, |path| std::fs::read_to_string(path)) +} + +/// Checks every one of [`SECRET_ENV_VARS`] that is set, so a bad `_FILE` +/// stops the server as it starts rather than when the secret is first used. +pub fn check_secret_env_vars() -> Result<(), String> { + SECRET_ENV_VARS + .iter() + .try_for_each(|name| secret_env_var(name).map(|_| ())) +} + +fn resolve_secret( + name: &str, + value: Option, + file: Option, + read: impl Fn(&str) -> std::io::Result, +) -> Result, String> { + let value = value.filter(|value| !value.is_empty()); + let file = file + .map(|path| path.trim().to_string()) + .filter(|path| !path.is_empty()); + match (value, file) { + (Some(_), Some(_)) => Err(format!( + "INBUXA_{name} and INBUXA_{name}_FILE are both set: set one of them" + )), + (Some(value), None) => Ok(Some(value)), + (None, Some(path)) => { + let contents = read(&path) + .map_err(|err| format!("INBUXA_{name}_FILE: can't read {path}: {err}"))?; + // A secret file usually ends in a newline that isn't the secret's + let secret = contents.trim_end_matches(['\n', '\r']); + if secret.is_empty() { + Err(format!("INBUXA_{name}_FILE: {path} is empty")) + } else { + Ok(Some(secret.to_string())) + } + } + (None, None) => Ok(None), + } +} + /// The environment prefix upstream reads. Only ever used to refuse it. const LEGACY_ENV_PREFIX: &str = "STALWART"; @@ -110,7 +175,76 @@ pub use proc_macros::display_version as __display_version; #[cfg(test)] mod tests { - use super::{LEGACY_ENV_PREFIX, legacy_setting}; + use super::{LEGACY_ENV_PREFIX, legacy_setting, resolve_secret}; + + fn read_as(contents: &'static str) -> impl Fn(&str) -> std::io::Result { + move |_| Ok(contents.to_string()) + } + + #[test] + fn a_secret_comes_from_the_variable_or_its_file() { + let none = |_: &str| -> std::io::Result { panic!("no file to read") }; + assert_eq!(resolve_secret("X", None, None, none), Ok(None)); + assert_eq!( + resolve_secret("X", Some("s3cret".into()), None, none), + Ok(Some("s3cret".into())) + ); + // The file's trailing newline isn't part of the secret; other space is + assert_eq!( + resolve_secret("X", None, Some("/run/s".into()), read_as(" s3 cret \r\n\n")), + Ok(Some(" s3 cret ".into())) + ); + // An empty variable counts as unset + assert_eq!( + resolve_secret( + "X", + Some(String::new()), + Some("/run/s".into()), + read_as("f") + ), + Ok(Some("f".into())) + ); + } + + #[test] + fn a_secret_set_twice_or_from_a_bad_file_is_refused_without_showing_it() { + let both = resolve_secret( + "X", + Some("s3cret".into()), + Some("/run/s".into()), + read_as("f"), + ); + assert_eq!( + both, + Err("INBUXA_X and INBUXA_X_FILE are both set: set one of them".into()) + ); + assert_eq!( + resolve_secret("X", None, Some("/run/s".into()), read_as("\n")), + Err("INBUXA_X_FILE: /run/s is empty".into()) + ); + let missing = resolve_secret("X", None, Some("/no/such".into()), |path| { + std::fs::read_to_string(path) + }) + .unwrap_err(); + assert!( + missing.starts_with("INBUXA_X_FILE: can't read /no/such: "), + "{missing}" + ); + } + + #[test] + fn a_secret_file_is_read_from_disk() { + let dir = std::env::temp_dir().join(format!("inbuxa-secret-{}", std::process::id())); + std::fs::create_dir_all(&dir).unwrap(); + let path = dir.join("secret"); + std::fs::write(&path, "from-a-file\n").unwrap(); + let path = path.to_string_lossy().to_string(); + assert_eq!( + resolve_secret("X", None, Some(path), |p| std::fs::read_to_string(p)), + Ok(Some("from-a-file".into())) + ); + std::fs::remove_dir_all(dir).unwrap(); + } #[test] fn the_version_is_cargos_without_the_series_zero() { diff --git a/docs/spec/SPEC.md b/docs/spec/SPEC.md index b2dd5012..28e94539 100644 --- a/docs/spec/SPEC.md +++ b/docs/spec/SPEC.md @@ -282,6 +282,14 @@ Done 2026-09-18: Now a `STALWART_*` name that's set where its `INBUXA_*` one isn't stops the server at startup, naming the variable to rename, so an install moved over from upstream never runs on settings it silently dropped. +- The secrets among them, `RECOVERY_ADMIN` and `WEBMAIL_CLIENT_SECRET` + (`types::branding::SECRET_ENV_VARS`), can come instead from a file that + `INBUXA__FILE` names, such as a mounted Kubernetes or Docker secret, + so they never have to be in the environment (K-S2, 2026-11-18). The file's + trailing newline is dropped. Both set, or a file that can't be read or is + empty, stops the server at startup with the variable and path named, + never the secret. The relay's `INBUXA_RELAY_JOIN_TOKEN` takes `_FILE` the + same way. - The spam filter's blobs moved from `STALWART_SPAM_*` to `INBUXA_SPAM_*` on 2026-09-22; every start moves any left under the old keys (`migration::try_migrate`), so no trained model is orphaned. diff --git a/docs/spec/features/relay.md b/docs/spec/features/relay.md index 102fc807..4c409fb2 100644 --- a/docs/spec/features/relay.md +++ b/docs/spec/features/relay.md @@ -1030,7 +1030,7 @@ Packaging (step 6, RL-31): uid 2001; about 12 MB. It runs as 2001, with `cap_net_bind_service` on the binary and nothing else, sets `INBUXA_RELAY_CONTAINER` (so `selfUpgrade: false`), and joins from `INBUXA_RELAY_JOIN_TOKEN` on its - first run. + first run, or from the file `INBUXA_RELAY_JOIN_TOKEN_FILE` names (K-S2). - A release tag builds it beside the server, on whichever forge builds: `/inbuxa/inbuxa-relay` under the server's tags. Before a tag moves, the amd64 image must print `inbuxa-relay ` and -- 2.54.0