hyprstream_core/account/config.rs
1//! Configuration surface for the account zone (epic #1158, ticket #1162 / A3).
2//!
3//! This is the deployment-facing knob. The `[account]` section names the
4//! delegated zone apex, the zone-scoped DNS-01 credential, the ACME directory
5//! to obtain the wildcard certificate from, and the wildcard address targets.
6//!
7//! ## Sane-degrade, not synthesized default
8//!
9//! A deployment that configures **no** account zone must degrade sanely:
10//! account minting is disabled with a clear error. [`AccountZoneConfig`]
11//! therefore has **no** `Default` zone value — `Default` leaves `zone = None`,
12//! and [`AccountZoneConfig::resolve_zone`] returns
13//! [`AccountZoneError::Unset`] in that state. We must never synthesize a zone
14//! name: a default would silently mint permanent DIDs under a domain the
15//! operator never chose (epic one-way door #1).
16//!
17//! ## TOML
18//!
19//! ```toml
20//! [account]
21//! zone = "acct.example.com"
22//! # Zone-scoped credential: the deployment's DNS provider accepts this and
23//! # only this when writing records under the apex. Format is opaque to
24//! # hyprstream — the product-layer DnsProvider interprets it.
25//! dns01_credential = "ref:secretstore/account-zone-token"
26//! acme_directory = "https://acme-v02.api.letsencrypt.org/directory"
27//! acme_contact = "mailto:ops@example.com"
28//! wildcard_ipv4 = "203.0.113.10"
29//! wildcard_ipv6 = "2001:db8::20"
30//! ```
31
32use std::net::{Ipv4Addr, Ipv6Addr};
33use std::path::PathBuf;
34
35use serde::{Deserialize, Serialize};
36
37use super::zone::{AccountZone, AccountZoneError};
38
39/// The `[account]` configuration section.
40///
41/// `Default` is deliberately the **unconfigured** state (`zone = None`); see the
42/// module docs on sane-degrade.
43#[derive(Debug, Clone, Default, Serialize, Deserialize)]
44pub struct AccountZoneConfig {
45 /// The delegated account-zone apex, e.g. `acct.example.com`. `None` ⇒
46 /// account minting disabled ([`Self::resolve_zone`] errors).
47 #[serde(default)]
48 pub zone: Option<String>,
49
50 /// Enable the authority-owned hosted-account record store for local OAuth
51 /// signing and account-session verification without exposing the public
52 /// account HTTP listener. This remains opt-in; deployments that need public
53 /// `did:web` documents must separately configure [`Self::http`] and its
54 /// wildcard TLS/DNS path.
55 #[serde(default)]
56 pub local_store: bool,
57
58 /// An opaque reference to the zone-scoped DNS-01 credential (e.g.
59 /// `ref:secretstore/...` or an env var name). hyprstream treats this as an
60 /// opaque string; the product-layer [`DnsProvider`](super::dns::DnsProvider)
61 /// implementation interprets it. `None` ⇒ DNS-01 issuance disabled even if
62 /// `zone` is set.
63 #[serde(default)]
64 pub dns01_credential: Option<String>,
65
66 /// ACME directory URL for wildcard issuance. Defaults to Let's Encrypt
67 /// production when `mode = "acme-dns01"` is selected and this is unset.
68 #[serde(default)]
69 pub acme_directory: Option<String>,
70
71 /// ACME contact URI, e.g. `mailto:ops@example.com`.
72 #[serde(default)]
73 pub acme_contact: Option<String>,
74
75 /// IPv4 target for the wildcard A record (`*.<apex>`). `None` ⇒ no A
76 /// record published by hyprstream; the operator may publish one out-of-band.
77 #[serde(default)]
78 pub wildcard_ipv4: Option<Ipv4Addr>,
79
80 /// IPv6 target for the wildcard AAAA record (`*.<apex>`).
81 #[serde(default)]
82 pub wildcard_ipv6: Option<Ipv6Addr>,
83
84 /// Optional credential-free HTTPS listener for the public hosted-account
85 /// DID artifacts. The listener is disabled unless this section is present;
86 /// enabling it requires an explicit account-zone certificate and key.
87 #[serde(default)]
88 pub http: Option<AccountHttpConfig>,
89}
90
91/// Deployment configuration for the separate public hosted-account listener.
92///
93/// This deliberately has no default port or certificate. A deployment must
94/// opt in with all listener material present so an account host can never
95/// silently bind the OAuth listener or fall back to a self-signed certificate.
96#[derive(Debug, Clone, Serialize, Deserialize)]
97pub struct AccountHttpConfig {
98 /// Bind address for the public account-artifact listener.
99 #[serde(default = "default_http_host")]
100 pub host: String,
101
102 /// Bind port for the public account-artifact listener.
103 pub port: u16,
104
105 /// PEM certificate chain covering `*.zone`.
106 pub tls_cert: PathBuf,
107
108 /// PEM private key corresponding to `tls_cert`.
109 pub tls_key: PathBuf,
110}
111
112fn default_http_host() -> String {
113 "0.0.0.0".to_owned()
114}
115
116impl AccountZoneConfig {
117 /// Whether the deployment has configured an account zone at all.
118 pub fn is_configured(&self) -> bool {
119 self.zone
120 .as_deref()
121 .filter(|s| !s.trim().is_empty())
122 .is_some()
123 }
124
125 /// Resolve the configured zone, or return [`AccountZoneError::Unset`].
126 ///
127 /// This is the single entry point the rest of the codebase uses; it never
128 /// invents a zone. Callers should surface the `Unset` error to the operator
129 /// rather than unwrapping.
130 pub fn resolve_zone(&self) -> Result<AccountZone, AccountZoneError> {
131 let Some(raw) = self.zone.as_deref() else {
132 return Err(AccountZoneError::Unset);
133 };
134 let trimmed = raw.trim();
135 if trimmed.is_empty() {
136 return Err(AccountZoneError::Unset);
137 }
138 AccountZone::new(trimmed)
139 }
140
141 /// Whether the DNS-01 issuance path is fully provisioned: a zone **and** a
142 /// zone-scoped credential are present. When false, TLS wildcard issuance is
143 /// skipped with a clear log message (the process keeps running on its
144 /// existing/self-signed cert; account minting surfaces the missing zone).
145 pub fn dns01_ready(&self) -> bool {
146 self.is_configured()
147 && self
148 .dns01_credential
149 .as_deref()
150 .map(|c| !c.trim().is_empty())
151 .unwrap_or(false)
152 }
153}
154
155#[cfg(test)]
156#[allow(clippy::unwrap_used)]
157mod tests {
158 use super::*;
159
160 #[test]
161 fn default_is_unset_and_degrades() {
162 let cfg = AccountZoneConfig::default();
163 assert!(!cfg.is_configured());
164 assert!(matches!(cfg.resolve_zone(), Err(AccountZoneError::Unset)));
165 assert!(!cfg.dns01_ready());
166 assert!(!cfg.local_store);
167 assert!(cfg.http.is_none());
168 }
169
170 #[test]
171 fn empty_zone_string_is_unset() {
172 let cfg = AccountZoneConfig {
173 zone: Some(" ".to_owned()),
174 ..Default::default()
175 };
176 assert!(matches!(cfg.resolve_zone(), Err(AccountZoneError::Unset)));
177 }
178
179 #[test]
180 fn resolves_valid_zone() {
181 let cfg = AccountZoneConfig {
182 zone: Some("acct.example.com".to_owned()),
183 dns01_credential: Some("ref:tok".to_owned()),
184 ..Default::default()
185 };
186 let z = cfg.resolve_zone().unwrap();
187 assert_eq!(z.wildcard_domain(), "*.acct.example.com");
188 assert!(cfg.dns01_ready());
189 }
190
191 #[test]
192 fn dns01_ready_requires_credential() {
193 let cfg = AccountZoneConfig {
194 zone: Some("acct.example.com".to_owned()),
195 ..Default::default()
196 };
197 assert!(!cfg.dns01_ready()); // zone set but no credential
198 }
199
200 #[test]
201 fn dns01_ready_rejects_blank_credential() {
202 // A blank/whitespace credential is not usable; treat as unconfigured so
203 // `require_provisioned` fails closed rather than proceeding (#1182 review).
204 for blank in ["", " ", "\t"] {
205 let cfg = AccountZoneConfig {
206 zone: Some("acct.example.com".to_owned()),
207 dns01_credential: Some(blank.to_owned()),
208 ..Default::default()
209 };
210 assert!(
211 !cfg.dns01_ready(),
212 "blank credential {blank:?} must not be ready"
213 );
214 }
215 }
216
217 #[test]
218 fn toml_roundtrip() {
219 let toml = r#"
220zone = "acct.example.com"
221dns01_credential = "ref:tok"
222acme_contact = "mailto:ops@example.com"
223wildcard_ipv4 = "203.0.113.10"
224"#;
225 let cfg: AccountZoneConfig = toml::from_str(toml).unwrap();
226 assert_eq!(cfg.zone.as_deref(), Some("acct.example.com"));
227 assert_eq!(cfg.wildcard_ipv4, Some("203.0.113.10".parse().unwrap()));
228 assert!(cfg.http.is_none());
229 }
230
231 #[test]
232 fn local_store_is_explicit_and_does_not_enable_http() {
233 let default: AccountZoneConfig = toml::from_str("zone = \"acct.example.com\"").unwrap();
234 assert!(!default.local_store);
235 assert!(default.http.is_none());
236
237 let enabled: AccountZoneConfig =
238 toml::from_str("zone = \"acct.example.com\"\nlocal_store = true\n").unwrap();
239 assert!(enabled.local_store);
240 assert!(enabled.http.is_none());
241 }
242
243 #[test]
244 fn http_listener_requires_explicit_material() {
245 let toml = r#"
246zone = "acct.example.com"
247[http]
248port = 443
249tls_cert = "/run/secrets/account/fullchain.pem"
250tls_key = "/run/secrets/account/key.pem"
251"#;
252 let cfg: AccountZoneConfig = toml::from_str(toml).unwrap();
253 let http = cfg.http.unwrap();
254 assert_eq!(http.host, "0.0.0.0");
255 assert_eq!(http.port, 443);
256 }
257}