atomic-integration-proxy 0.4.0

OAuth/catalog integration proxy (pinned OpenAPI catalog, connections owned by Atomic agents, Atomic v2 request signatures, delegations and frame capabilities) used by Atomic Server and LocalThought
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
use std::env;
use url::Url;

/// Runtime configuration, loaded entirely from environment variables so the
/// server itself stays container-friendly.
///
/// Issue #54 removed the tenant concept. `APP_AUTH_*`, `SERVER_SECRET` and
/// the other tenant-era variables are no longer read; leaving them set is
/// harmless.
#[derive(Clone)]
pub struct Config {
    /// Public URL the proxy is reachable at, e.g. `https://auth.example.com`.
    /// Used for OAuth redirect URLs, and as the origin of the URL covered by
    /// every Atomic v2 request signature and of a capability's `aud`. It must
    /// be exactly what clients use: behind TLS termination the proxy cannot
    /// tell its public scheme or host from the request.
    pub base_url: String,
    pub port: u16,
    /// Secret used to encrypt the short-lived consent and OAuth-binding
    /// cookies. If unset, a random key is generated at startup, so a consent
    /// screen open during a restart has to be started again.
    pub session_secret: Option<String>,
    /// Local file or immutable HTTPS URL listing the pinned OADs and overlays.
    pub catalog_path: String,
    /// PostgreSQL: connections, delegations, runtimes, handoffs and the
    /// single-use record of signed requests.
    pub database_url: String,
    /// Base64url-encoded 32-byte key for sealed provider credentials.
    pub encryption_key: String,
    /// `REVOKED_SUBJECTS`: comma-separated agent ids (any accepted spelling)
    /// refused by the default access policy.
    pub revoked_subjects: Vec<String>,
    /// `ALLOWED_AGENTS`: when set, comma-separated agent ids; the default
    /// access policy admits only these owners.
    pub allowed_agents: Option<Vec<String>>,
    /// `OPERATOR_NAME`: who runs this proxy, as the landing and consent pages
    /// name them. Defaults to [`DEFAULT_OPERATOR_NAME`] when unset or blank.
    pub operator_name: String,
    /// `OPERATOR_URL`: optional absolute http(s) link for the operator's
    /// name on those pages.
    pub operator_url: Option<String>,
    /// `KEY_CHECK_LIMIT_PER_HOUR`: the most API key or token checks the
    /// consent form makes for one client network and platform in any hour.
    /// Defaults to [`DEFAULT_KEY_CHECK_LIMIT_PER_HOUR`]; `0` turns the limit
    /// off.
    pub key_check_limit_per_hour: u32,
    /// `TRUST_FORWARDED_FOR`: where the client address of that limit comes
    /// from. Defaults to [`TrustForwardedFor::None`].
    pub trust_forwarded_for: TrustForwardedFor,
    /// `WEBHOOKS_ENABLED` and the webhook inbox's limits. Off by default.
    pub webhooks: WebhookConfig,
    /// Registered public device clients and the owner approval bridge. Disabled by default.
    pub device: crate::device::DeviceConfig,
}

/// The webhook inbox (ontola/atomic-plugins#369). Off unless
/// `WEBHOOKS_ENABLED=true`: then, and only then, the proxy creates the inbox
/// tables and runs the inbox sweeper. No webhook route is mounted yet.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct WebhookConfig {
    /// `WEBHOOKS_ENABLED`: `true` turns the inbox on; unset, empty or
    /// `false` leaves it off. Anything else stops the proxy at startup.
    pub enabled: bool,
    /// `WEBHOOK_INBOX_MAX_BYTES`: the deployment's inbox budget in bytes,
    /// payloads plus the stated per-row overhead. Defaults to
    /// [`DEFAULT_WEBHOOK_INBOX_MAX_BYTES`] (1 GiB).
    pub inbox_max_bytes: i64,
    /// `WEBHOOK_INGRESS_LIMIT_PER_ENDPOINT`: failed verifications one
    /// existing endpoint counts per minute, per instance; over it, further
    /// ones get `429` instead of `401`. A delivery that verifies is never
    /// refused for it. Default 600.
    pub ingress_per_endpoint_per_minute: u32,
    /// `WEBHOOK_INGRESS_LIMIT_PER_NETWORK`: refusals one client network (as
    /// `TRUST_FORWARDED_FOR` finds it) may cause per minute, per instance
    /// (not `400` or `408`). Over it, its requests for ids that name no
    /// endpoint get `429`, and at most 2 requests of networks over their
    /// limit may wait for the lookup slot at a time. Default 120.
    pub ingress_per_network_per_minute: u32,
    /// `WEBHOOK_SUBSCRIBE_LIMIT_PER_OWNER`: subscription requests per
    /// connection owner per hour, per instance, counted before the access
    /// check reaches the provider. Default 20.
    pub subscribe_per_owner_per_hour: u32,
}

impl Default for WebhookConfig {
    fn default() -> Self {
        Self {
            enabled: false,
            inbox_max_bytes: DEFAULT_WEBHOOK_INBOX_MAX_BYTES,
            ingress_per_endpoint_per_minute: 600,
            ingress_per_network_per_minute: 120,
            subscribe_per_owner_per_hour: 20,
        }
    }
}

/// The largest value of a webhook rate limit.
const MAX_WEBHOOK_LIMIT: u32 = 100_000;

fn webhook_limit(name: &str, value: Option<&str>, default: u32) -> Result<u32, String> {
    match value.map(str::trim) {
        None | Some("") => Ok(default),
        Some(value) => match value.parse::<u32>() {
            Ok(limit) if (1..=MAX_WEBHOOK_LIMIT).contains(&limit) => Ok(limit),
            _ => Err(format!(
                "{name} must be a whole number from 1 to {MAX_WEBHOOK_LIMIT}"
            )),
        },
    }
}

/// The deployment inbox budget when `WEBHOOK_INBOX_MAX_BYTES` is unset: the
/// plan's 1 GiB pilot value.
pub const DEFAULT_WEBHOOK_INBOX_MAX_BYTES: i64 = 1 << 30;

/// The smallest `WEBHOOK_INBOX_MAX_BYTES` accepted: the owner budget
/// (256 MiB), so one owner's limit can always be reached before the
/// deployment's.
const MIN_WEBHOOK_INBOX_MAX_BYTES: i64 = 256 << 20;

/// The webhook variables as read from the environment, by name.
pub(crate) type WebhookVariables<'a> = &'a dyn Fn(&str) -> Option<String>;

#[cfg(test)]
pub(crate) fn webhook_config(
    enabled: Option<&str>,
    inbox_max_bytes: Option<&str>,
) -> Result<WebhookConfig, String> {
    webhook_config_with(enabled, inbox_max_bytes, &|_| None)
}

/// [`webhook_config`] plus the rate limits, read only when the inbox is on.
pub(crate) fn webhook_config_with(
    enabled: Option<&str>,
    inbox_max_bytes: Option<&str>,
    variable: WebhookVariables<'_>,
) -> Result<WebhookConfig, String> {
    let enabled = match enabled.map(str::trim) {
        None | Some("") | Some("false") => false,
        Some("true") => true,
        Some(_) => return Err("WEBHOOKS_ENABLED must be true or false".into()),
    };
    // Read only when the inbox is on: off, the variable is ignored.
    let inbox_max_bytes = match inbox_max_bytes.map(str::trim).filter(|_| enabled) {
        None | Some("") => DEFAULT_WEBHOOK_INBOX_MAX_BYTES,
        Some(value) => match value.parse::<i64>() {
            Ok(bytes) if bytes >= MIN_WEBHOOK_INBOX_MAX_BYTES => bytes,
            _ => {
                return Err(format!(
                    "WEBHOOK_INBOX_MAX_BYTES must be a whole number of bytes, at least {MIN_WEBHOOK_INBOX_MAX_BYTES}"
                ))
            }
        },
    };
    let defaults = WebhookConfig::default();
    let limit = |name: &str, default: u32| {
        if enabled {
            webhook_limit(name, variable(name).as_deref(), default)
        } else {
            Ok(default)
        }
    };
    Ok(WebhookConfig {
        enabled,
        inbox_max_bytes,
        ingress_per_endpoint_per_minute: limit(
            "WEBHOOK_INGRESS_LIMIT_PER_ENDPOINT",
            defaults.ingress_per_endpoint_per_minute,
        )?,
        ingress_per_network_per_minute: limit(
            "WEBHOOK_INGRESS_LIMIT_PER_NETWORK",
            defaults.ingress_per_network_per_minute,
        )?,
        subscribe_per_owner_per_hour: limit(
            "WEBHOOK_SUBSCRIBE_LIMIT_PER_OWNER",
            defaults.subscribe_per_owner_per_hour,
        )?,
    })
}

/// The key checks one client network may make per platform and hour when
/// `KEY_CHECK_LIMIT_PER_HOUR` is unset. A person entering a key makes one to
/// three.
pub const DEFAULT_KEY_CHECK_LIMIT_PER_HOUR: u32 = 20;

/// Which client address the key-check limit counts against
/// (`TRUST_FORWARDED_FOR`).
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub enum TrustForwardedFor {
    /// `none`: the TCP peer address; every `X-Forwarded-For` is ignored.
    /// Right when nothing sits in front of the proxy, and the default.
    #[default]
    None,
    /// `heroku`, or its synonym `rightmost`: the right-most
    /// `X-Forwarded-For` entry, the one the proxy in front appended (Heroku's
    /// router does; so do Caddy and nginx with
    /// `$proxy_add_x_forwarded_for`); everything to its left came from the
    /// client and is ignored. Only right when every request reaches the
    /// proxy through exactly one such proxy: without it a client can write
    /// that entry itself.
    RightMost,
}

impl std::str::FromStr for TrustForwardedFor {
    type Err = String;

    fn from_str(value: &str) -> Result<Self, String> {
        match value.trim() {
            "" | "none" => Ok(Self::None),
            "heroku" | "rightmost" => Ok(Self::RightMost),
            _ => Err("TRUST_FORWARDED_FOR must be `none`, `heroku` or `rightmost`".into()),
        }
    }
}

/// The highest `KEY_CHECK_LIMIT_PER_HOUR` accepted. Each check may scan the
/// network's slots, so a huge limit makes every key check slow (2,000,000
/// took 640 ms per insert); `0` is the way to turn the limit off.
pub const MAX_KEY_CHECK_LIMIT_PER_HOUR: u32 = 10_000;

/// `KEY_CHECK_LIMIT_PER_HOUR`: unset or blank means
/// [`DEFAULT_KEY_CHECK_LIMIT_PER_HOUR`], `0` means no limit; anything but a
/// whole number from 0 to [`MAX_KEY_CHECK_LIMIT_PER_HOUR`] is refused at
/// startup.
pub(crate) fn key_check_limit(value: Option<&str>) -> Result<u32, String> {
    let invalid = || {
        format!(
            "KEY_CHECK_LIMIT_PER_HOUR must be a whole number from 0 (no limit) to {MAX_KEY_CHECK_LIMIT_PER_HOUR}"
        )
    };
    match value.map(str::trim) {
        None | Some("") => Ok(DEFAULT_KEY_CHECK_LIMIT_PER_HOUR),
        Some(value) => match value.parse::<u32>() {
            Ok(limit) if limit <= MAX_KEY_CHECK_LIMIT_PER_HOUR => Ok(limit),
            _ => Err(invalid()),
        },
    }
}

/// The operator name when `OPERATOR_NAME` is unset: neutral, because the
/// crate does not know who runs it.
pub const DEFAULT_OPERATOR_NAME: &str = "this integration proxy";

/// Where GitHub Pages serves this repository's `overlays/` folder. Every
/// overlay URL in the dated catalogs under `overlays/catalog/` starts with
/// this prefix.
pub const OVERLAYS_PAGES_BASE: &str = "https://ontola.github.io/atomic-plugins/overlays/";

/// The default dated catalog's path under `overlays/`, for tests that read
/// the checked-in copy; `default_catalog_is_the_published_checked_in_catalog`
/// keeps it equal to [`DEFAULT_CATALOG_PATH`]'s.
#[cfg(test)]
pub const DEFAULT_CATALOG_FILE: &str = "catalog/2026-10-02-auth-profiles.json";

/// `overlays/catalog/2026-10-02-auth-profiles.json` as GitHub Pages publishes it from this
/// repository's `main`, used when `CATALOG_PATH` is not set. Unlike the
/// unversioned catalog this replaced, its dated file and selected overlay
/// revisions are immutable; the proxy reads it once, at startup. Shared with
/// tests that need to validate the exact catalog the application would load
/// by default (they read the checked-in copy; see `Catalog::load_checked_in`).
pub const DEFAULT_CATALOG_PATH: &str =
    "https://ontola.github.io/atomic-plugins/overlays/catalog/2026-10-02-auth-profiles.json";

/// Reads a required environment variable and rejects it if unset or blank,
/// so a blank `.env` value fails configuration explicitly instead of being
/// silently accepted (e.g. as a reproducible empty secret).
fn require_env(name: &str) -> Result<String, String> {
    match env::var(name) {
        Ok(value) if !value.is_empty() => Ok(value),
        _ => Err(format!("{name} must be set")),
    }
}

fn list(value: &str) -> Vec<String> {
    value
        .split(',')
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .map(str::to_owned)
        .collect()
}

/// `BASE_URL` must be an absolute http(s) URL without credentials, query or
/// fragment: it is the signed origin, so anything ambiguous is refused at
/// startup rather than failing every signature later.
pub(crate) fn validate_base_url(value: &str) -> Result<String, String> {
    let url = Url::parse(value).map_err(|_| "BASE_URL must be an absolute URL".to_string())?;
    if !matches!(url.scheme(), "https" | "http")
        || url.host_str().is_none()
        || !url.username().is_empty()
        || url.password().is_some()
        || url.query().is_some()
        || url.fragment().is_some()
    {
        return Err(
            "BASE_URL must be an http(s) URL without credentials, query or fragment".into(),
        );
    }
    Ok(value.trim_end_matches('/').to_owned())
}

/// `OPERATOR_NAME`, trimmed; unset or blank means [`DEFAULT_OPERATOR_NAME`].
pub(crate) fn operator_name(value: Option<&str>) -> String {
    match value.map(str::trim) {
        Some(name) if !name.is_empty() => name.to_owned(),
        _ => DEFAULT_OPERATOR_NAME.to_owned(),
    }
}

/// `OPERATOR_URL`, if set: an absolute http(s) URL without credentials. It is
/// rendered as a link, so anything else (`javascript:`, a relative path) is
/// refused at startup.
pub(crate) fn validate_operator_url(value: Option<&str>) -> Result<Option<String>, String> {
    let Some(value) = value.map(str::trim).filter(|value| !value.is_empty()) else {
        return Ok(None);
    };
    let url = Url::parse(value)
        .map_err(|_| "OPERATOR_URL must be an absolute http(s) URL".to_string())?;
    if !matches!(url.scheme(), "https" | "http")
        || url.host_str().is_none()
        || !url.username().is_empty()
        || url.password().is_some()
    {
        return Err("OPERATOR_URL must be an http(s) URL without credentials".into());
    }
    Ok(Some(url.to_string()))
}

/// `host[:port]` of an http(s) URL, the port only when it is not the
/// scheme's default. Falls back to the input when it does not parse.
pub(crate) fn public_host(base_url: &str) -> String {
    match Url::parse(base_url) {
        Ok(url) => match (url.host_str(), url.port()) {
            (Some(host), Some(port)) => format!("{host}:{port}"),
            (Some(host), None) => host.to_owned(),
            _ => base_url.to_owned(),
        },
        Err(_) => base_url.to_owned(),
    }
}

impl Config {
    pub fn from_env() -> Result<Self, String> {
        let base_url = validate_base_url(
            &env::var("BASE_URL").unwrap_or_else(|_| "http://localhost:8080".to_string()),
        )?;
        let port = env::var("PORT")
            .ok()
            .and_then(|p| p.parse().ok())
            .unwrap_or(8080);
        // An empty SESSION_SECRET is treated as unset, so it triggers random
        // key generation instead of being hashed into a reproducible,
        // guessable cookie-encryption key.
        let session_secret = env::var("SESSION_SECRET")
            .ok()
            .filter(|value| !value.is_empty());
        let catalog_path =
            env::var("CATALOG_PATH").unwrap_or_else(|_| DEFAULT_CATALOG_PATH.to_string());
        let database_url = require_env("DATABASE_URL").map_err(|_| {
            "DATABASE_URL must be set for connections and replay protection".to_string()
        })?;
        let encryption_key = require_env("ENCRYPTION_KEY")?;
        let revoked_subjects = list(&env::var("REVOKED_SUBJECTS").unwrap_or_default());
        let allowed_agents = env::var("ALLOWED_AGENTS")
            .ok()
            .filter(|value| !value.trim().is_empty())
            .map(|value| list(&value));
        let operator_name = operator_name(env::var("OPERATOR_NAME").ok().as_deref());
        let operator_url = validate_operator_url(env::var("OPERATOR_URL").ok().as_deref())?;
        let key_check_limit_per_hour =
            key_check_limit(env::var("KEY_CHECK_LIMIT_PER_HOUR").ok().as_deref())?;
        let trust_forwarded_for = env::var("TRUST_FORWARDED_FOR")
            .unwrap_or_default()
            .parse()?;
        let webhooks = webhook_config_with(
            env::var("WEBHOOKS_ENABLED").ok().as_deref(),
            env::var("WEBHOOK_INBOX_MAX_BYTES").ok().as_deref(),
            &|name| env::var(name).ok(),
        )?;

        Ok(Self {
            base_url,
            port,
            session_secret,
            catalog_path,
            database_url,
            encryption_key,
            revoked_subjects,
            allowed_agents,
            operator_name,
            operator_url,
            key_check_limit_per_hour,
            trust_forwarded_for,
            webhooks,
            device: crate::device::DeviceConfig::from_env()?,
        })
    }

    /// The origin (`scheme://host[:port]`) of [`Config::base_url`]: a
    /// capability's required `aud`.
    pub fn public_origin(&self) -> String {
        Url::parse(&self.base_url)
            .map(|url| url.origin().ascii_serialization())
            .unwrap_or_else(|_| self.base_url.clone())
    }

    /// `host[:port]` of [`Config::base_url`], as the consent page shows it.
    pub fn public_host(&self) -> String {
        public_host(&self.base_url)
    }

    /// OAuth callback and credential variable names are deterministic from the
    /// catalog platform name, e.g. `google-calendar` becomes
    /// `OAUTH_GOOGLE_CALENDAR_CLIENT_ID` and `/oauth/google-calendar/callback`.
    pub fn provider_env_prefix(provider: &str) -> Result<String, String> {
        if provider.is_empty()
            || !provider
                .bytes()
                .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
        {
            return Err(
                "provider names may contain only lowercase letters, digits, and hyphens"
                    .to_string(),
            );
        }
        Ok(format!(
            "OAUTH_{}",
            provider.replace('-', "_").to_ascii_uppercase()
        ))
    }
}

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

    #[test]
    fn provider_names_produce_predictable_environment_prefixes() {
        assert_eq!(
            Config::provider_env_prefix("google-calendar").unwrap(),
            "OAUTH_GOOGLE_CALENDAR"
        );
        assert!(Config::provider_env_prefix("Google Calendar").is_err());
    }

    #[test]
    fn require_env_rejects_missing_and_blank_values() {
        let name = "INTEGRATION_PROXY_TEST_REQUIRE_ENV_VAR";
        env::remove_var(name);
        assert!(require_env(name).is_err());
        env::set_var(name, "");
        assert!(require_env(name).is_err());
        env::set_var(name, "a-value");
        assert_eq!(require_env(name).unwrap(), "a-value");
        env::remove_var(name);
    }

    #[test]
    fn base_url_is_the_signed_origin_and_must_be_unambiguous() {
        assert_eq!(
            validate_base_url("https://proxy.example/").unwrap(),
            "https://proxy.example"
        );
        assert_eq!(
            validate_base_url("http://localhost:8080").unwrap(),
            "http://localhost:8080"
        );
        for invalid in [
            "proxy.example",
            "ftp://proxy.example",
            "https://u:p@proxy.example",
            "https://proxy.example?x=1",
            "https://proxy.example#x",
        ] {
            assert!(validate_base_url(invalid).is_err(), "{invalid}");
        }
        let config = Config {
            base_url: "https://proxy.example:8443/prefix".into(),
            port: 0,
            session_secret: None,
            catalog_path: String::new(),
            database_url: String::new(),
            encryption_key: String::new(),
            revoked_subjects: vec![],
            allowed_agents: None,
            operator_name: DEFAULT_OPERATOR_NAME.into(),
            operator_url: None,
            key_check_limit_per_hour: 0,
            trust_forwarded_for: TrustForwardedFor::None,
            webhooks: WebhookConfig::default(),
            device: Default::default(),
        };
        assert_eq!(config.public_origin(), "https://proxy.example:8443");
        assert_eq!(config.public_host(), "proxy.example:8443");
        assert_eq!(public_host("https://proxy.example"), "proxy.example");
        assert_eq!(public_host("http://127.0.0.1:8080"), "127.0.0.1:8080");
    }

    #[test]
    fn webhooks_are_off_unless_enabled_explicitly() {
        assert_eq!(
            webhook_config(None, None).unwrap(),
            WebhookConfig::default()
        );
        assert!(!WebhookConfig::default().enabled);
        assert_eq!(WebhookConfig::default().inbox_max_bytes, 1 << 30);
        assert!(!webhook_config(Some(""), None).unwrap().enabled);
        assert!(!webhook_config(Some("false"), None).unwrap().enabled);
        assert!(webhook_config(Some("true"), None).unwrap().enabled);
        for invalid in ["1", "yes", "TRUE", "on"] {
            assert!(webhook_config(Some(invalid), None).is_err(), "{invalid}");
        }
        assert_eq!(
            webhook_config(Some("true"), Some("536870912"))
                .unwrap()
                .inbox_max_bytes,
            512 << 20
        );
        for invalid in ["0", "-1", "1e9", "268435455", "lots"] {
            assert!(
                webhook_config(Some("true"), Some(invalid)).is_err(),
                "{invalid}"
            );
            // Off, the budget is not read at all.
            assert_eq!(
                webhook_config(None, Some(invalid)).unwrap(),
                WebhookConfig::default()
            );
        }
    }

    #[test]
    fn webhook_rate_limits_are_bounded_and_read_only_when_enabled() {
        let vars = |pairs: &'static [(&'static str, &'static str)]| {
            move |name: &str| {
                pairs
                    .iter()
                    .find(|(k, _)| *k == name)
                    .map(|(_, v)| v.to_string())
            }
        };
        let config = webhook_config_with(Some("true"), None, &|_| None).unwrap();
        assert_eq!(
            (
                config.ingress_per_endpoint_per_minute,
                config.ingress_per_network_per_minute,
                config.subscribe_per_owner_per_hour
            ),
            (600, 120, 20)
        );
        let set = vars(&[
            ("WEBHOOK_INGRESS_LIMIT_PER_ENDPOINT", "1000"),
            ("WEBHOOK_INGRESS_LIMIT_PER_NETWORK", "30"),
            ("WEBHOOK_SUBSCRIBE_LIMIT_PER_OWNER", "5"),
        ]);
        let config = webhook_config_with(Some("true"), None, &set).unwrap();
        assert_eq!(config.ingress_per_endpoint_per_minute, 1000);
        assert_eq!(config.ingress_per_network_per_minute, 30);
        assert_eq!(config.subscribe_per_owner_per_hour, 5);
        for invalid in ["0", "-1", "100001", "lots", "1.5"] {
            let bad = move |name: &str| {
                (name == "WEBHOOK_INGRESS_LIMIT_PER_NETWORK").then(|| invalid.to_string())
            };
            assert!(
                webhook_config_with(Some("true"), None, &bad).is_err(),
                "{invalid}"
            );
            // Off, nothing is read.
            assert_eq!(
                webhook_config_with(None, None, &bad).unwrap(),
                WebhookConfig::default()
            );
        }
    }

    #[test]
    fn operator_name_defaults_to_a_neutral_phrase() {
        assert_eq!(operator_name(None), DEFAULT_OPERATOR_NAME);
        assert_eq!(operator_name(Some("  ")), DEFAULT_OPERATOR_NAME);
        assert_eq!(operator_name(Some(" Atomic Data ")), "Atomic Data");
    }

    #[test]
    fn operator_url_is_optional_and_must_be_a_plain_http_url() {
        assert_eq!(validate_operator_url(None).unwrap(), None);
        assert_eq!(validate_operator_url(Some(" ")).unwrap(), None);
        assert_eq!(
            validate_operator_url(Some("https://atomic.place")).unwrap(),
            Some("https://atomic.place/".into())
        );
        for invalid in [
            "atomic.place",
            "javascript:alert(1)",
            "data:text/html,x",
            "https://u:p@atomic.place",
        ] {
            assert!(validate_operator_url(Some(invalid)).is_err(), "{invalid}");
        }
    }

    #[test]
    fn the_key_check_limit_defaults_to_twenty_and_zero_turns_it_off() {
        assert_eq!(key_check_limit(None).unwrap(), 20);
        assert_eq!(key_check_limit(Some(" ")).unwrap(), 20);
        assert_eq!(key_check_limit(Some("0")).unwrap(), 0);
        assert_eq!(key_check_limit(Some(" 50 ")).unwrap(), 50);
        assert_eq!(key_check_limit(Some("10000")).unwrap(), 10_000);
        for invalid in ["-1", "twenty", "1.5", "10001", "2000000", "99999999999"] {
            let error = key_check_limit(Some(invalid)).unwrap_err();
            assert!(
                error.contains("0 (no limit) to 10000"),
                "{invalid}: {error}"
            );
        }
    }

    #[test]
    fn forwarded_for_is_trusted_only_when_named() {
        assert_eq!("".parse(), Ok(TrustForwardedFor::None));
        assert_eq!("none".parse(), Ok(TrustForwardedFor::None));
        assert_eq!(" heroku ".parse(), Ok(TrustForwardedFor::RightMost));
        assert_eq!("rightmost".parse(), Ok(TrustForwardedFor::RightMost));
        for invalid in ["Heroku", "true", "all", "x-forwarded-for"] {
            assert!(invalid.parse::<TrustForwardedFor>().is_err(), "{invalid}");
        }
    }

    #[test]
    fn lists_are_comma_separated_and_trimmed() {
        assert_eq!(list(" a, b ,,c "), vec!["a", "b", "c"]);
        assert!(list("").is_empty());
    }
}