feat(modkit): explicit post-install FIPS provider assertion

Signed-off-by: mattgarmon <mjg2790@gmail.com>

Author: mattgarmon

docs/security/SECURITY.md

@@ -470,7 +470,7 @@ See [`examples/cyberware-fips-probe/README.md`](../../examples/cyberware-fips-pr
 
 - **Cyber Ware itself is not on the CMVP Validated Modules list.** The validated modules are Apple corecrypto, AWS-LC FIPS Provider, and Microsoft Windows CNG. Cyber Ware is a *consumer* of those modules.
 - **CMVP OE-coverage is the deployment's responsibility.** A FIPS claim is void if the running OS version is not inside the cert's OE. The macOS runtime gate is fail-closed; Linux + Windows OE coverage is verified manually per release.
-- **`CryptoProvider::fips() = true` is design intent, not a runtime witness.** It asserts that every primitive in the provider routes through a CMVP-validated module by construction. It does *not* prove that the running OS version matches an active CMVP cert OE — that proof comes from the §release-checklist CMVP-cert search.
+- **`CryptoProvider::fips() = true` is a runtime witness, not just design intent.** On macOS it reflects the OE check (`oe::fips_witness_ok`); on Windows, the OS FIPS-mode flag. On Linux, runtime OE-validation is not yet implemented; OE coverage is verified manually per release via the §release-checklist CMVP-cert search.
 - **TLS 1.2 PRF on macOS is not CAVS-listed.** Apple corecrypto exposes generic HMAC primitives but not a CAVS-listed dedicated TLS PRF (unlike `aws-lc-fips`'s `tls_prf::Algorithm`). Consequence: `fips_provider()` on macOS is TLS-1.3-only; customers requiring TLS 1.2 on macOS+FIPS must accept that those connections do not carry a FIPS claim.
 - **JWT signature validation does not go through the FIPS path.** `jsonwebtoken` uses `ring` / non-FIPS `aws-lc-rs` for RSA / ECDSA verification on bearer tokens. Treat tokens as authentication context, not as data covered by the cryptographic claim. Out of scope today; tracked as **TODO-7** in [FIPS PRD §13](fips/PRD.md#13-open-questions). Cleanup is gated by `deny-fips.toml` Phase B promotion.
 - **Non-FIPS crypto crates remain in the final binary on macOS+fips.** `ring` is pulled in transitively by `pingora-rustls`, `pingora-pool`, and `ureq`; non-FIPS `aws-lc-rs` is pulled in by rustls's default feature set; `chacha20` is pulled in by the `rand` ecosystem. These are **not invoked** on the TLS data plane (the installed `CryptoProvider` routes every TLS primitive through the validated module) but the symbols are linked into the binary. Linkage smoke (above) confirms no non-validated shared libraries appear at runtime.

libs/modkit-http/src/tls.rs

@@ -161,9 +161,11 @@ pub enum TlsConfigError {
 
     /// `apply_fips_hardening` rejected the freshly-built `ClientConfig`
     /// because `ClientConfig::fips()` reported `false`. Carries the
-    /// human-readable diagnostic — typically a witness mismatch
-    /// (`cyberware_rustls_corecrypto_provider::oe::fips_witness_ok` on macOS)
-    /// or a missed `init_crypto_provider()` call.
+    /// human-readable diagnostic. Under normal bootstrap flow the
+    /// provider-level witness is already asserted by
+    /// `init_crypto_provider`; this error surfaces per-config issues
+    /// (e.g. missing `require_ems`) or a missed `init_crypto_provider()`
+    /// call.
     #[error("{0}")]
     FipsHardeningFailed(String),
 
@@ -210,10 +212,10 @@ mod fips_test_provider {
 ///   1. forces `require_ems = true` (NIST SP 800-52 Rev. 2 §3.5), and
 ///   2. verifies `config.fips() == true` and returns `Err` otherwise.
 ///
-/// Returning `Err` rather than `panic!` matches the witness contract of
-/// `cyberware-rustls-corecrypto-provider`: an OE mismatch surfaces as a
-/// `fips() == false` witness, and that surfaces here as a recoverable
-/// error rather than process termination.
+/// The bootstrap `assert!` in `init_crypto_provider` is the primary
+/// guard against a non-FIPS provider; this TLS-layer check is
+/// defence-in-depth for per-config settings (`require_ems`, protocol
+/// versions) that also affect `ClientConfig::fips()`.
 fn build_client_config(
     root_store: rustls::RootCertStore,
 ) -> Result<rustls::ClientConfig, TlsConfigError> {
@@ -265,24 +267,22 @@ fn build_client_config(
 ///     `ClientConfig::fips()` to consider TLS 1.2 sessions FIPS-compliant
 ///     when the EMS extension is honoured by the peer).
 ///   * verify the full FIPS chain reports `fips() == true`. If not, return
-///     `Err` rather than panic — the failure mode is recoverable from the
-///     caller's perspective (build a non-FIPS client, surface the error,
-///     etc.). Panic was the previous behaviour; replaced because the
-///     witness rework in `cyberware-rustls-corecrypto-provider` makes
-///     `config.fips() == false` a normal runtime state on unsupported
-///     macOS majors, not a programming error.
+///     `Err` — the bootstrap `assert!` in `init_crypto_provider` already
+///     guarantees the provider reports `fips() == true`, so a failure here
+///     indicates a per-config issue (e.g. missing `require_ems` or
+///     restricted protocol versions) rather than a provider-level problem.
 #[cfg(feature = "fips")]
 fn apply_fips_hardening(cfg: &mut rustls::ClientConfig) -> Result<(), TlsConfigError> {
     cfg.require_ems = true;
     if !cfg.fips() {
         return Err(TlsConfigError::FipsHardeningFailed(
             "TLS ClientConfig does not advertise FIPS after enabling require_ems. \
-             The runtime FIPS witness \
-             (cyberware_rustls_corecrypto_provider::oe::fips_witness_ok on macOS) \
-             is reporting false -- typically because the running macOS major is \
-             outside the active corecrypto CMVP cert OE. \
-             Set CYBERWARE_FIPS_OE_OVERRIDE=1 (CI / pre-release only) to force the \
-             witness to true; never set this in production."
+             The bootstrap assert in init_crypto_provider should have caught a \
+             non-FIPS provider at startup; if you see this error the provider is \
+             FIPS-OK but a per-config setting (protocol versions, require_ems) is \
+             preventing ClientConfig::fips() from reporting true. \
+             If init_crypto_provider was not called, call it before building any \
+             TLS config."
                 .to_owned(),
         ));
     }

libs/modkit/src/bootstrap/crypto.rs

@@ -79,16 +79,20 @@ static INIT_RESULT: OnceLock<Result<(), CryptoProviderError>> = OnceLock::new();
 /// construction (`cyberware_rustls_corecrypto_provider::oe::fips_witness_ok`).
 /// On a macOS major outside the active corecrypto CMVP cert OE, **every**
 /// `fips()` impl in the provider returns `false` and a single
-/// `tracing::warn!` is emitted. There is **no panic** — downstream code
-/// that depends on `ClientConfig::fips()` / `ServerConfig::fips()` must
-/// handle the `false` case explicitly (see
-/// `modkit_http::tls::apply_fips_hardening` for the canonical pattern,
-/// which returns `Err` instead of asserting). The
-/// `CYBERWARE_FIPS_OE_OVERRIDE=1` env-var forces the witness to `true`
+/// `tracing::warn!` is emitted. The post-install witness `assert!` then
+/// **panics** — a misconfigured FIPS build must never silently proceed.
+/// Use `CYBERWARE_FIPS_OE_OVERRIDE=1` to force the witness to `true`
 /// for CI on pre-release macOS — never for production. See the
 /// `cyberware-rustls-corecrypto-provider` README "Runtime FIPS witness" section
 /// and FIPS PRD §8.3.
 ///
+/// Downstream TLS configuration code (`modkit_http::tls::apply_fips_hardening`)
+/// performs its own `config.fips()` check and returns `Err` rather than
+/// panicking — `ClientConfig::fips()` depends on per-config settings
+/// (`require_ems`, protocol versions) beyond the provider itself, so the
+/// TLS-layer check is a defence-in-depth complement to the bootstrap
+/// assertion here.
+///
 /// **Linux / Windows**: runtime OE-validation is not yet implemented; OE
 /// coverage is verified via the release checklist (manual CMVP cert search,
 /// PRD §9.3). Tracked as a follow-up in PRD §10.
@@ -99,6 +103,13 @@ static INIT_RESULT: OnceLock<Result<(), CryptoProviderError>> = OnceLock::new();
 ///   enabled and another rustls provider was installed first.
 /// - [`CryptoProviderError::SystemFipsModeNotEnabled`] on Windows+`fips` when
 ///   the OS is not in system-wide FIPS mode.
+///
+/// # Panics
+///
+/// Panics (via `assert!`) under `--features fips` if the installed crypto
+/// provider does not report `fips() == true`. This is an intentional
+/// fail-closed guard against misconfigured builds (wrong feature flags,
+/// wrong OS, or macOS OE mismatch without the override env-var).
 pub fn init_crypto_provider() -> Result<(), CryptoProviderError> {
     INIT_RESULT
         .get_or_init(|| {
@@ -164,6 +175,18 @@ pub fn init_crypto_provider() -> Result<(), CryptoProviderError> {
                 tracing::info!("FIPS-140-3 crypto provider installed (AWS-LC FIPS module)");
             }
 
+            #[cfg(feature = "fips")]
+            {
+                let Some(provider) = rustls::crypto::CryptoProvider::get_default() else {
+                    unreachable!("provider must be installed at this point");
+                };
+                assert!(
+                    provider.fips(),
+                    "FIPS post-install witness failed: installed provider does not report fips()==true"
+                );
+                tracing::info!("FIPS post-install witness: OK");
+            }
+
             #[cfg(not(feature = "fips"))]
             {
                 if let Err(prev) = rustls::crypto::aws_lc_rs::default_provider().install_default() {