Skip to main content

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}