fix: config UX & security validation (PR2 of bug-audit-v2)

[lesnik512]

Summary

PR2 of the 2026-06-05 bug-audit-v2 plan. Closes six config-layer findings — three UX rough edges (FastAPI app stomping, missing FastStream config fields) and three security validators (root_path escape, insecure OTel exporter, unsafe CORS). All validation happens at __post_init__ time on frozen dataclass configs so the entire instrument lifecycle is unreached on misconfiguration. Sequenced per planning/specs/2026-06-05-bug-audit-v2-sequencing.md; per-task TDD plan at planning/plans/2026-06-05-pr2-config-security.md.

Findings closed

• UX-1 — FastAPIConfig.__post_init__ no longer stomps application.title/debug/version when the user supplies a pre-configured FastAPI() instance. The three assignments moved inside the UnsetType branch so they only apply when lite-bootstrap built the app.
• UX-2 — Added prometheus_collector_registry: CollectorRegistry | None = None to FastStreamConfig. When non-None, FastStreamPrometheusInstrument uses the injected registry (via __post_init__); otherwise the existing per-instance default is preserved. Backward-compatible.
• UX-3 — Added opentelemetry_excluded_urls: list[str] to FastStreamConfig, matching the existing fields on FastAPIConfig/LitestarConfig. _build_excluded_urls already read via getattr fallback so behavior is unchanged; the field is now discoverable.
• SEC-1 — enable_offline_docs validates request.scope["root_path"] through the project's existing is_valid_path allowlist before interpolating into Swagger/Redoc HTML. Invalid paths fall back to empty with a warning. Covers the X-Forwarded-Prefix proxy-header injection vector.
• SEC-2 — Added OpenTelemetryConfig.__post_init__ that emits a warning when opentelemetry_endpoint resolves to a non-local host AND opentelemetry_insecure=True (the unfortunate default). localhost, 127.0.0.1, ::1, and unix:// endpoints are silent. Host parsing handles both host:port (canonical OTLP gRPC) and scheme://host:port, including IPv6 brackets.
• SEC-3 — Added CorsConfig.__post_init__ that raises ConfigurationError when cors_allowed_credentials=True is combined with a wildcard origin ("*" in the list) or a permissive regex (.*, .+). FastAPI's CORSMiddleware silently refuses the combo; Litestar's behavior differs. Validation at config-construction is consistent across frameworks.

Implementation notes

• Two reviewer-driven course corrections during execution:

  • SEC-2's host parser initially used urllib.parse.urlparse + path.split(":")[0] fallback. Verified that this misparses the canonical localhost:4317 OTLP form (urlparse treats localhost as the scheme and yields path='4317'). Fixed by prepending // to schemeless inputs so urlparse always returns a correct hostname. Added parametrized regression tests covering five local forms (localhost:4317, 127.0.0.1:4317, [::1]:4317, http://localhost:4317, https://127.0.0.1:4317) and three remote forms (collector.example.com:4317, http://collector.example.com:4317, grpc://collector.example.com:4317).
  • SEC-3's first landing broke SEC-2's cascade for FastAPIConfig users. CorsConfig precedes OpenTelemetryConfig in FastAPIConfig's MRO; the new CorsConfig.__post_init__ returned early on the default (no credentials) without calling super().__post_init__(), so the OTel warning never fired for FastAPIConfig. Fixed by establishing the cascade invariant: BaseConfig gains a no-op __post_init__ as the terminator; every config-class __post_init__ calls super().__post_init__() after its own logic.

• One subtle Python quirk surfaced: super(FastAPIConfig, self).__post_init__() is required in FastAPIConfig.__post_init__ rather than bare super(). @dataclass(slots=True) replaces the class object after the class body compiles, breaking the compile-time __class__ cell that bare super() relies on. Comment in the code documents the constraint.

Non-blocking follow-ups flagged by the final reviewer

• Parametrize the cascade test across LitestarConfig, FreeConfig, FastStreamConfig for explicit regression coverage of the other framework configs (currently covered transitively via the shared OpenTelemetryConfig.__post_init__, but not directly).
• The OTel warning's stacklevel=2 now lands on lite-bootstrap internals (due to the cascade) rather than user code. Acceptable — the warning text is actionable enough that users can find the offending config.

Test plan

• just test — 175 passed (164 PR1 baseline ↔ unrelated to PR2; PR2 adds 11 new tests on its own pre-PR1 baseline), 100% coverage.
• just lint-ci — clean (ruff, eof-fixer, ty).
• No new warnings in pytest output (silenced the legacy "otl" test-fixture warning via a localhost:4317 swap in test_config.py).
• Each commit is scoped to one finding ID so review/revert can land at the task level; plus one cross-cutting cascade-fix commit at the end.

Sequencing note

PR2 branches off main (NOT off PR1's branch). When PR1 (#108) merges first, PR2 rebases cleanly — they touch overlapping files (opentelemetry_instrument.py, fastapi_bootstrapper.py) but at non-overlapping line ranges. If PR2 merges first, PR1's diff narrows similarly.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...te_bootstrap/bootstrappers/fastapi_bootstrapper.py	100.00% <100.00%> (ø)
...bootstrap/bootstrappers/faststream_bootstrapper.py	100.00% <100.00%> (ø)
lite_bootstrap/helpers/fastapi_helpers.py	100.00% <100.00%> (ø)
lite_bootstrap/instruments/base.py	100.00% <100.00%> (ø)
lite_bootstrap/instruments/cors_instrument.py	100.00% <100.00%> (ø)
..._bootstrap/instruments/opentelemetry_instrument.py	100.00% <100.00%> (ø)
tests/instruments/test_cors_instrument.py	100.00% <100.00%> (ø)
tests/instruments/test_opentelemetry_instrument.py	100.00% <100.00%> (ø)
tests/test_fastapi_bootstrap.py	100.00% <100.00%> (ø)
tests/test_fastapi_offline_docs.py	100.00% <100.00%> (ø)
... and 1 more

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.