solid_pod_rs/config/schema.rs
1//! `ServerConfig` root + value objects.
2//!
3//! See the bounded-context doc
4//! `docs/design/jss-parity/05-config-platform-context.md` for the
5//! aggregate model. In short: `ServerConfig` is the root, loaded by
6//! [`crate::config::loader::ConfigLoader`] from a precedence-ordered
7//! list of sources, and validated once at the end of the load.
8//!
9//! The struct shapes below are designed so **the same JSS
10//! `config.json` file boots both JSS and solid-pod-rs** — field names
11//! and JSON structure mirror JSS's `config.json` where semantics align.
12
13use serde::{Deserialize, Serialize};
14
15// ---------------------------------------------------------------------------
16// Root aggregate
17// ---------------------------------------------------------------------------
18
19/// Fully resolved server configuration snapshot.
20///
21/// Construct via [`crate::config::loader::ConfigLoader`]; never mutate
22/// after construction. Reload swaps in a new snapshot atomically.
23#[derive(Debug, Clone, Default, Serialize, Deserialize)]
24pub struct ServerConfig {
25 /// HTTP listener settings (host, port, base URL).
26 #[serde(default)]
27 pub server: ServerSection,
28
29 /// Storage backend selection (filesystem or memory).
30 #[serde(default)]
31 pub storage: StorageBackendConfig,
32
33 /// Authentication toggles (NIP-98, Solid-OIDC, DPoP).
34 #[serde(default)]
35 pub auth: AuthConfig,
36
37 /// Solid Notifications channel toggles (WebSocket, Webhook, legacy).
38 #[serde(default)]
39 pub notifications: NotificationsConfig,
40
41 /// Security primitives (SSRF guard, dotfile allowlist, ACL origin).
42 #[serde(default)]
43 pub security: SecurityConfig,
44
45 /// Sprint 11 (row 120-124): operator-facing extras that do not yet
46 /// have first-class sections on `ServerConfig`. The env-var overlay
47 /// writes here (e.g. `JSS_CORS_ALLOWED_ORIGINS`, `JSS_SUBDOMAINS`,
48 /// `JSS_BASE_DOMAIN`, `JSS_IDP_ENABLED`). Binaries consult this map
49 /// until a richer typed section supersedes it.
50 #[serde(default)]
51 pub extras: ExtrasConfig,
52}
53
54/// Flat bag for operator-facing knobs not yet promoted to a typed
55/// section. Each field is `#[serde(default)]` + `skip_serializing_if` so
56/// a pristine `ExtrasConfig` serialises to an empty object.
57#[derive(Debug, Clone, Default, Serialize, Deserialize)]
58#[serde(default)]
59pub struct ExtrasConfig {
60 /// `JSS_CONNEG` — content-negotiation toggle. Default off until
61 /// promoted to its own typed section.
62 #[serde(skip_serializing_if = "Option::is_none")]
63 pub conneg_enabled: Option<bool>,
64
65 /// `JSS_CORS_ALLOWED_ORIGINS` — CSV list. Empty vec means unset.
66 #[serde(skip_serializing_if = "Vec::is_empty")]
67 pub cors_allowed_origins: Vec<String>,
68
69 /// `JSS_MAX_BODY_SIZE` / `JSS_MAX_REQUEST_BODY` — bytes.
70 #[serde(skip_serializing_if = "Option::is_none")]
71 pub max_body_size_bytes: Option<u64>,
72
73 /// `JSS_MAX_ACL_BYTES` — bytes.
74 #[serde(skip_serializing_if = "Option::is_none")]
75 pub max_acl_bytes: Option<u64>,
76
77 /// `JSS_RATE_LIMIT_WRITES_PER_MIN`.
78 #[serde(skip_serializing_if = "Option::is_none")]
79 pub rate_limit_writes_per_min: Option<u64>,
80
81 /// `JSS_SUBDOMAINS` — enable subdomain multi-tenancy.
82 #[serde(skip_serializing_if = "Option::is_none")]
83 pub subdomains_enabled: Option<bool>,
84
85 /// `JSS_BASE_DOMAIN` — authoritative base domain when subdomains
86 /// are on.
87 #[serde(skip_serializing_if = "Option::is_none")]
88 pub base_domain: Option<String>,
89
90 /// `JSS_IDP_ENABLED` — local IdP service toggle.
91 #[serde(skip_serializing_if = "Option::is_none")]
92 pub idp_enabled: Option<bool>,
93
94 /// `JSS_INVITE_ONLY` — restrict new pod registration.
95 #[serde(skip_serializing_if = "Option::is_none")]
96 pub invite_only: Option<bool>,
97
98 /// `JSS_ADMIN_KEY` — operator override token. Never serialise to
99 /// telemetry; this serde pass is solely for config reload symmetry.
100 #[serde(skip_serializing_if = "Option::is_none")]
101 pub admin_key: Option<String>,
102}
103
104// ---------------------------------------------------------------------------
105// HTTP binding
106// ---------------------------------------------------------------------------
107
108/// HTTP listener settings — matches JSS `host`/`port`/`baseUrl`.
109#[derive(Debug, Clone, Serialize, Deserialize)]
110pub struct ServerSection {
111 /// `JSS_HOST`, default `0.0.0.0` (matches JSS default).
112 #[serde(default = "default_host")]
113 pub host: String,
114
115 /// `JSS_PORT`, default `3000` (matches JSS default).
116 #[serde(default = "default_port")]
117 pub port: u16,
118
119 /// `JSS_BASE_URL` — optional; used for pod-URL construction.
120 #[serde(default, skip_serializing_if = "Option::is_none")]
121 pub base_url: Option<String>,
122}
123
124impl Default for ServerSection {
125 fn default() -> Self {
126 Self {
127 host: default_host(),
128 port: default_port(),
129 base_url: None,
130 }
131 }
132}
133
134fn default_host() -> String {
135 "0.0.0.0".to_string()
136}
137
138fn default_port() -> u16 {
139 3000
140}
141
142// ---------------------------------------------------------------------------
143// Storage backend selection
144// ---------------------------------------------------------------------------
145
146/// Tagged storage backend selector — matches JSS's
147/// `{ "type": "fs"|"memory", … }` JSON shape.
148///
149/// `JSS_STORAGE_TYPE` drives the variant; `JSS_STORAGE_ROOT` /
150/// `JSS_ROOT` feeds the `fs` root.
151#[derive(Debug, Clone, Serialize, Deserialize)]
152#[serde(tag = "type", rename_all = "lowercase")]
153pub enum StorageBackendConfig {
154 /// Filesystem backend (JSS default).
155 Fs {
156 #[serde(default = "default_fs_root")]
157 root: String,
158 },
159
160 /// In-memory (ephemeral) backend.
161 Memory,
162}
163
164impl Default for StorageBackendConfig {
165 fn default() -> Self {
166 Self::Fs {
167 root: default_fs_root(),
168 }
169 }
170}
171
172fn default_fs_root() -> String {
173 "./data".to_string()
174}
175
176// ---------------------------------------------------------------------------
177// Auth
178// ---------------------------------------------------------------------------
179
180/// Auth toggles.
181#[derive(Debug, Clone, Serialize, Deserialize)]
182pub struct AuthConfig {
183 /// NIP-98 (Nostr HTTP Auth) — default on; matches `nip98_enabled`
184 /// semantics on the JSS side.
185 #[serde(default = "default_true")]
186 pub nip98_enabled: bool,
187
188 /// Solid-OIDC — `JSS_OIDC_ENABLED` / JSS `idp`.
189 #[serde(default)]
190 pub oidc_enabled: bool,
191
192 /// Issuer URL — `JSS_OIDC_ISSUER` / JSS `idpIssuer`.
193 #[serde(default, skip_serializing_if = "Option::is_none")]
194 pub oidc_issuer: Option<String>,
195
196 /// DPoP replay-cache TTL (seconds).
197 ///
198 /// `JSS_DPOP_REPLAY_TTL_SECONDS`; default 300s.
199 /// [TODO verify JSS]: JSS does not currently expose this knob;
200 /// we add it to parity the Rust side's DPoP replay cache.
201 #[serde(default = "default_dpop_ttl")]
202 pub dpop_replay_ttl_seconds: u64,
203}
204
205impl Default for AuthConfig {
206 fn default() -> Self {
207 Self {
208 nip98_enabled: true,
209 oidc_enabled: false,
210 oidc_issuer: None,
211 dpop_replay_ttl_seconds: default_dpop_ttl(),
212 }
213 }
214}
215
216fn default_true() -> bool {
217 true
218}
219
220fn default_dpop_ttl() -> u64 {
221 300
222}
223
224// ---------------------------------------------------------------------------
225// Notifications
226// ---------------------------------------------------------------------------
227
228/// Solid Notifications channel toggles.
229#[derive(Debug, Clone, Serialize, Deserialize)]
230pub struct NotificationsConfig {
231 /// WebSocketChannel2023 — `JSS_NOTIFICATIONS_WS2023`.
232 #[serde(default = "default_true")]
233 pub ws2023_enabled: bool,
234
235 /// WebhookChannel2023 — `JSS_NOTIFICATIONS_WEBHOOK`.
236 #[serde(default)]
237 pub webhook2023_enabled: bool,
238
239 /// Legacy `solid-0.1` PATCH-based channel — `JSS_NOTIFICATIONS_LEGACY`.
240 ///
241 /// JSS sets this on by default for backwards compatibility; we mirror
242 /// that for drop-in replacement.
243 #[serde(default = "default_true")]
244 pub legacy_solid_01_enabled: bool,
245}
246
247impl Default for NotificationsConfig {
248 fn default() -> Self {
249 Self {
250 ws2023_enabled: true,
251 webhook2023_enabled: false,
252 legacy_solid_01_enabled: true,
253 }
254 }
255}
256
257// ---------------------------------------------------------------------------
258// Security
259// ---------------------------------------------------------------------------
260
261/// Security primitives — SSRF, dotfiles, ACL origin.
262#[derive(Debug, Clone, Serialize, Deserialize)]
263pub struct SecurityConfig {
264 /// Allow outbound requests to RFC 1918 / loopback / link-local —
265 /// `JSS_SSRF_ALLOW_PRIVATE`. Defaults off (production-safe).
266 #[serde(default)]
267 pub ssrf_allow_private: bool,
268
269 /// Explicit allowlist of hosts/CIDRs — `JSS_SSRF_ALLOWLIST`
270 /// (comma-separated in env; JSON array in file).
271 #[serde(default)]
272 pub ssrf_allowlist: Vec<String>,
273
274 /// Explicit denylist — `JSS_SSRF_DENYLIST`.
275 #[serde(default)]
276 pub ssrf_denylist: Vec<String>,
277
278 /// Dotfile allowlist (e.g. `.acl`, `.meta`) —
279 /// `JSS_DOTFILE_ALLOWLIST`.
280 #[serde(default = "default_dotfile_allowlist")]
281 pub dotfile_allowlist: Vec<String>,
282
283 /// ACL-origin lockdown toggle — `JSS_ACL_ORIGIN_ENABLED`.
284 #[serde(default = "default_true")]
285 pub acl_origin_enabled: bool,
286
287 /// Default per-pod byte quota. Zero disables quota enforcement.
288 #[serde(default)]
289 pub default_quota_bytes: u64,
290}
291
292impl Default for SecurityConfig {
293 fn default() -> Self {
294 Self {
295 ssrf_allow_private: false,
296 ssrf_allowlist: Vec::new(),
297 ssrf_denylist: Vec::new(),
298 dotfile_allowlist: default_dotfile_allowlist(),
299 acl_origin_enabled: true,
300 default_quota_bytes: 0,
301 }
302 }
303}
304
305fn default_dotfile_allowlist() -> Vec<String> {
306 vec![
307 ".acl".to_string(),
308 ".meta".to_string(),
309 // JSS commit 32c0db2: allow `.account` for IdP login.
310 ".account".to_string(),
311 ]
312}
313
314// ---------------------------------------------------------------------------
315// Basic validation helpers
316// ---------------------------------------------------------------------------
317
318impl ServerConfig {
319 /// Sanity-check the resolved snapshot. Called once at the end of
320 /// [`crate::config::loader::ConfigLoader::load`].
321 ///
322 /// Returns a human-readable error; `Ok(())` means valid.
323 pub fn validate(&self) -> Result<(), String> {
324 // Port 0 is allowed (means "pick any free port") — don't reject.
325 // But port > u16::MAX isn't representable anyway.
326
327 if self.auth.oidc_enabled && self.auth.oidc_issuer.is_none() {
328 return Err(
329 "auth.oidc_enabled=true but auth.oidc_issuer is not set (set JSS_OIDC_ISSUER)"
330 .to_string(),
331 );
332 }
333
334 Ok(())
335 }
336}