fix: typed config — single source of defaults, load-time validation, key hygiene

[erskingardner]

Summary

Configuration correctness was enforced ad hoc, in three scattered ways, so misconfiguration failed silently at runtime instead of loudly at load. This centralizes it, per the #215 tracker design.

Single source of defaults (#171)

Dropped the set_default(...) ladder in base_config_builder. The serde default_* fns (backed by the existing DEFAULT_* consts) are now the only place a default lives. The builder seeds each top-level section as an empty table so try_deserialize still reaches those serde defaults when a section is absent from every source (verified with an empty-TOML test). Env-override behavior (TRANSPONDER_* parsing, comma-list handling, ambient-var skipping, non-Unicode redaction) is byte-compatible.

Typed fields, validated at load

• NonZeroUsize / reject-zero for max_rate_limit_cache_size, max_dedup_cache_size, max_tokens_per_event ([LOW] server.max_tokens_per_event = 0 (and max_dedup_cache_size = 0) bypass ServerConfig::validate() — silent push outage / silent default swap #149, [LOW] RateLimiter::new silently coerces max_entries = 0 to the 100,000 default instead of surfacing the misconfiguration #166). The downstream RateLimitConfig, TokenRateLimitConfig, and ReplayProtectionConfig now carry NonZeroUsize, so the silent fallbacks at rate_limiter.rs (.unwrap_or(DEFAULT_MAX_SIZE)) and the dedup NonZeroUsize::new().unwrap_or() in events.rs are deleted — a zero is rejected at load with a named-field error.
• max_concurrent_event_processing keeps the Semaphore::MAX_PERMITS upper bound (from fix: validate event processing concurrency cap #211) and the documented 0 → 1 clamp in event_processing_permits.
• enum LogFormat { Json, Pretty } ([LOW] logging.format = "off" silently disables ALL logging and ignores logging.level — an undocumented format value that causes a total log blackout #150, [LOW] Invalid logging.format silently falls back to default formatter #142) with a hand-written Deserialize that rejects unknown values (including the undocumented off blackout arm) with a message pointing at logging.level = "off". init_logging's match is now exhaustive over the enum.
• health.bind_address is parsed as SocketAddr in AppConfig::validate ([LOW] health.bind_address is never validated at config load — a typo silently disables the health/readiness/metrics server while the process runs #167), even when the health server is disabled, so a hostname or out-of-range port is rejected at startup.
• Relay URLs ([MEDIUM] Onion relay URLs bypass all URL validation — a plaintext ws:// entry in relays.onion defeats the wss-only TLS enforcement, and typo'd .onion URLs are silently dropped #122, [LOW] inbox_relay_event_is_current compares raw config strings and uses events.first(), causing spurious kind-10050 republishing and possibly skipping needed updates #124): validate_relay_config now validates the onion list symmetrically with clearnet — each entry must parse (via nostr-sdk RelayUrl) as ws:///wss:// with a .onion host. inbox_relay_event_is_current normalizes both sides through RelayUrl before comparing and selects the newest kind-10050 event by created_at instead of events.first().

Key-file hygiene (#146)

On unix, before reading private_key_file, the file is stat'd; if its mode grants group/other read (mode & 0o077 != 0) the server refuses to start, mirroring the 0600 the generate path enforces.

Private key out of the config Value tree (#156)

server.private_key (inline TOML and TRANSPONDER_SERVER_PRIVATE_KEY) is resolved through a dedicated Zeroizing path — extracted from the parsed TOML document (and env iterator) before the rest of the config reaches the config crate — so the secret never lands in the crate's un-zeroized Value tree. Precedence (env > file config) is unchanged. Docs now recommend private_key_file.

#196 rider — not needed

The metrics.enabled && !health.enabled load-time warning was planned as a rider, but PR #230 (merged into master while this was in flight) landed the structural fix: /metrics is now served on health.bind_address whenever metrics are enabled, independent of health.enabled, and the health server emits its own targeted warning at bind time. A separate warning here would be redundant and factually wrong (metrics ARE now exposed), so it was dropped after merging master.

Breaking for invalid configs

Existing deployments with valid configs load identically. Only previously-silently-tolerated invalid configs now fail at startup:

• server.max_dedup_cache_size = 0 — was silently swapped for the 100k default; now rejected.
• server.max_rate_limit_cache_size = 0 — was silently swapped for 100k per limiter; now rejected.
• server.max_tokens_per_event = 0 — was a total silent push outage (every event failed token parsing); now rejected.
• logging.format = "off" — silently disabled ALL logging (including errors); now rejected with a message pointing to logging.level = "off".
• logging.format = <typo> (e.g. "jsno") — silently fell back to the default formatter; now rejected.
• health.bind_address = <non-SocketAddr> (e.g. "localhost:8080" or "127.0.0.1:99999") — was accepted and only failed to bind at runtime; now rejected at load.
• relays.onion entry that is not a ws:///wss:// URL with a .onion host (e.g. a plaintext clearnet ws:// URL, a bare host, or a misspelled suffix) — was added blindly / silently dropped at connect; now rejected at load (only when the tor feature is enabled; without it the existing "requires tor feature" error fires first).
• private_key_file with group/world-readable permissions (mode & 0o077 != 0) — was loaded silently; now refuses to start.

Testing

cargo fmt --check clean; cargo clippy --all-targets -- -D warnings zero (also with --features tor); cargo test --bin transponder all pass (603 default / 606 with tor); cargo check --all-targets --features tor clean. The config.rs test module was extended with a test for every new validation branch, and new tests were added in client.rs (onion validation, inbox normalization, newest-event selection) and main.rs (key-file permission check, LogFormat init).

Fixes #171
Fixes #167
Fixes #166
Fixes #149
Fixes #150
Fixes #142
Fixes #122
Fixes #124
Fixes #146
Fixes #156

Part of #215.

🤖 Generated with Claude Code

---

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 17 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0d6fca41-31af-4ebd-8b25-41bf56f2ab8f

📥 Commits

Reviewing files that changed from the base of the PR and between 9ea7d39 and 5eab028.

📒 Files selected for processing (9)

• CHANGELOG.md
• README.md
• config/default.toml
• config/production.toml.example
• src/config.rs
• src/main.rs
• src/nostr/client.rs
• src/nostr/events.rs
• src/rate_limiter.rs

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/typed-config

---

_{Comment @coderabbitai help to get the list of available commands.}

[stage-review]

Ready to review this PR? Stage has broken it down into 7 individual chapters for you:

	Title
1	Centralize configuration defaults on serde functions
2	Enforce NonZeroUsize for cache and token limits
3	Introduce LogFormat enum and validate logging
4	Validate health bind address and relay URLs
5	Improve inbox relay change detection
6	Secure private key handling and file permissions
7	Update documentation and remaining integration

_{Chapters generated by Stage for commit 5eab028 on Jul 5, 2026 12:55pm UTC.}

[github-actions]

✅ Code Coverage Report

Metric	Value
Line Coverage	96.73%
Lines Covered	15627 / 16156
Change from master	+0.17% ✅

View detailed coverage

Download the coverage-html artifact from this workflow run to view the detailed coverage report.

Or run locally:

cargo llvm-cov --html
open target/llvm-cov/html/index.html