Add standards-based response metadata

Author: eldryoth

CHANGELOG.md

@@ -7,6 +7,40 @@ Fluxheim follows semantic versioning once `1.0.0` is released. Before `1.0.0`,
 minor versions may still change configuration shape, feature names, and runtime
 behavior when the change improves security or project direction.
 
+## 1.7.12 - Unreleased
+
+### Added
+
+- Add opt-in RFC 9211 `Cache-Status` generated from real cache outcomes and
+  low-cardinality RFC 9209 `Proxy-Status` for Fluxheim-generated proxy failures.
+- Add opt-in RFC 9530 SHA-256 `Content-Digest` and `Repr-Digest` generated from
+  final response bytes, with live cache, compression, conditional, `HEAD`, and
+  range-response coverage.
+- Add pinned CI-only OpenSSL-FIPS and rustls/AWS-LC-FIPS proof environments
+  that build and execute the exact profile binary, exercise downstream and
+  verified upstream TLS, reject incompatible policy, and capture provider,
+  compiler, dependency, binary, and image evidence.
+
+### Changed
+
+- Make standards-based response metadata inherit through global, vhost, and
+  route response policies while remaining disabled by default.
+- Strip origin digest fields whenever Fluxheim compression changes response
+  bytes; opt-in digest generation then recomputes fields from the final encoded
+  content.
+- Include the reproducible FIPS-backend image proof in the deep release gate
+  and expose it as a separate manual workflow and test-starter entry.
+
+### Security
+
+- Bound public response-metadata identifiers to Structured Fields token grammar
+  and prevent status output from exposing backend addresses, DNS names,
+  certificate details, cache keys, internal tiers, or arbitrary error text.
+- Suppress `Repr-Digest` instead of guessing when Fluxheim does not hold the
+  complete selected representation, including `HEAD`, `206`, and `304` paths.
+- Keep the FIPS proof containers separate from release images and document that
+  provider evidence is not product-level FIPS validation.
+
 ## 1.7.11 - 2026-07-14
 
 ### Added

README.md

@@ -63,7 +63,7 @@ Fluxheim is licensed under the European Union Public Licence 1.2.
 | Regex path rewrite templates | ✅ | `1.4.1`; `rewrite_template` maps regex routes to safe upstream paths without nginx-style rewrite loops or `if`. |
 | Method-based routing | ✅ | `1.4.1`; optional route `methods = ["GET", "HEAD"]` filters. |
 | HTTPS redirects | ✅ | Optional global HTTP-to-HTTPS redirects with safe Host validation. |
-| Secure headers | ✅ | Request/response policy, opt-in hardening and cross-origin-isolation profiles, typed CSP reporting and modern browser controls, validated request-aware CORS, automatic `Vary`, and bounded `Retry-After`; origin `Server` headers are preserved by default and removed by the hardening profiles. |
+| Secure headers | ✅ | Request/response policy, opt-in hardening and cross-origin-isolation profiles, typed CSP reporting and modern browser controls, validated request-aware CORS, automatic `Vary`, bounded `Retry-After`, and opt-in RFC 9211/9209/9530 response metadata; origin `Server` headers are preserved by default and removed by the hardening profiles. |
 | PHP-FPM applications | ✅ | External php-fpm for existing pools. |
 | Managed PHP-FPM | ✅ | Fluxheim-supervised php-fpm pools for zero-admin WordPress-style deployments. |
 
@@ -352,8 +352,8 @@ Release tags use the same profile/OS suffixes on both registries. The first
 `1.7.x` image tags include `v1.7.0-wolfi`, `v1.7.0-cache-wolfi`,
 `v1.7.0-proxy-wolfi`, `v1.7.0-load-balancer-wolfi`, and `v1.7.0-php-wolfi`;
 follow-up `1.7.x` releases use the same suffix pattern, for example
-`v1.7.11-wolfi`, `v1.7.11-cache-wolfi`, `v1.7.11-proxy-wolfi`,
-`v1.7.11-load-balancer-wolfi`, and `v1.7.11-php-wolfi`.
+`v1.7.12-wolfi`, `v1.7.12-cache-wolfi`, `v1.7.12-proxy-wolfi`,
+`v1.7.12-load-balancer-wolfi`, and `v1.7.12-php-wolfi`.
 
 Release note for `1.5.15`: the signed git tag `v1.5.15` is the canonical code
 tag. The GitHub Release page is published under `v1.5.15-release` because the
@@ -424,13 +424,14 @@ scripts/validate-features.sh proxy,web,tls-rustls,load-balancer
 
 </details>
 
-## Current Release: 1.7.11 Zero-Downtime Upgrades
+## Current Release: 1.7.12 Standards Metadata And FIPS Evidence
 
 Fluxheim does not treat every planned idea as stable. The current release line
-is `1.7.11`, the zero-downtime process-upgrade release after the stable
-`1.7.0` through `1.7.10` Wasm milestones. It adds bounded drain, strict
-systemd listener inheritance, readiness-gated native handoff, and a tested
-Podman blue/green pattern behind a stable fronting listener.
+is `1.7.12`, the standards-based response-metadata and reproducible
+FIPS-backend evidence release after the stable Wasm and zero-downtime
+milestones. It adds opt-in RFC 9211 `Cache-Status`, low-cardinality RFC 9209
+`Proxy-Status`, RFC 9530 response digests, and pinned proof environments that
+build and execute the OpenSSL-FIPS and rustls/AWS-LC-FIPS profiles.
 
 - `1.0` is the gateway foundation: vhosts, routes, redirects, static serving,
   proxying, SNI/TLS, safe ACME challenge exceptions, systemd/RPM packaging, and
@@ -494,6 +495,13 @@ Podman blue/green pattern behind a stable fronting listener.
   closes the native HTTP/1 parser audit with validated-only request heads,
   bounded fragmentation-independent chunk decoding, strict request-target and
   authority handling, and ownership-safe critical background supervision.
+- `1.7.12` adds response metadata generated from real runtime outcomes and
+  final response bytes. Cache and proxy status fields remain opt-in and avoid
+  backend topology or arbitrary error strings; digest behavior is live-tested
+  across cache, compression, conditional, `HEAD`, and range responses. Pinned
+  CI-only proof environments build and run both FIPS-capable TLS profiles and
+  capture provider, toolchain, dependency, binary, and image evidence. They are
+  not published FIPS images or a claim that Fluxheim itself is FIPS validated.
 
 Detailed cache behavior, config examples, operational limits, and smoke-test
 coverage are documented in [Cache Backends](docs/cache-backends.md),

crates/fluxheim-config/src/config.rs

@@ -51,7 +51,8 @@ pub use crate::config_header::{
     HeaderPolicyConfig, HeaderValues, PermittedCrossDomainPolicies, RequestHeaderPolicyConfig,
     RequestHeaderPolicyOverlayConfig, ResponseHardeningConfig, ResponseHardeningProfile,
     ResponseHeaderPolicyConfig, ResponseHeaderPolicyOverlayConfig, ResponseHeaderRewriteConfig,
-    ResponseHeaderRewriteRuleConfig, ResponseHstsConfig, ResponsePermissionsPolicyConfig,
+    ResponseHeaderRewriteRuleConfig, ResponseHstsConfig, ResponseMetadataConfig,
+    ResponseMetadataOverlayConfig, ResponsePermissionsPolicyConfig,
     ResponsePermissionsPolicyProfile, VhostHeaderPolicyConfig,
 };
 #[cfg(test)]

crates/fluxheim-config/src/config_header.rs

@@ -9,6 +9,7 @@ pub use crate::config_header_hardening::{
     PermittedCrossDomainPolicies, ResponseHardeningConfig, ResponseHardeningProfile,
     ResponsePermissionsPolicyConfig, ResponsePermissionsPolicyProfile,
 };
+pub use crate::config_header_metadata::{ResponseMetadataConfig, ResponseMetadataOverlayConfig};
 pub use crate::config_header_response::{
     ResponseHeaderPolicyConfig, ResponseHeaderPolicyOverlayConfig, ResponseHeaderRewriteConfig,
     ResponseHeaderRewriteRuleConfig, ResponseHstsConfig,

crates/fluxheim-config/src/config_header_metadata.rs

@@ -0,0 +1,128 @@
+use serde::{Deserialize, Serialize};
+
+use crate::config::ConfigError;
+
+const MAX_RESPONSE_METADATA_IDENTIFIER_BYTES: usize = 64;
+
+#[derive(Debug, Clone, Default, Eq, PartialEq, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct ResponseMetadataConfig {
+    #[serde(default)]
+    pub identifier: Option<String>,
+    #[serde(default)]
+    pub cache_status: bool,
+    #[serde(default)]
+    pub proxy_status: bool,
+    #[serde(default)]
+    pub content_digest: bool,
+    #[serde(default)]
+    pub repr_digest: bool,
+}
+
+impl ResponseMetadataConfig {
+    pub(crate) fn validate(&self, field: &'static str) -> Result<(), ConfigError> {
+        if (self.cache_status || self.proxy_status)
+            && self
+                .identifier
+                .as_deref()
+                .is_none_or(|identifier| !structured_field_token(identifier))
+        {
+            return Err(ConfigError::InvalidResponseHeaderValue { field });
+        }
+        Ok(())
+    }
+
+    pub fn apply_overlay(&mut self, overlay: &ResponseMetadataOverlayConfig) {
+        if let Some(identifier) = &overlay.identifier {
+            self.identifier = identifier.clone();
+        }
+        if let Some(cache_status) = overlay.cache_status {
+            self.cache_status = cache_status;
+        }
+        if let Some(proxy_status) = overlay.proxy_status {
+            self.proxy_status = proxy_status;
+        }
+        if let Some(content_digest) = overlay.content_digest {
+            self.content_digest = content_digest;
+        }
+        if let Some(repr_digest) = overlay.repr_digest {
+            self.repr_digest = repr_digest;
+        }
+    }
+}
+
+#[derive(Debug, Clone, Default, Eq, PartialEq, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct ResponseMetadataOverlayConfig {
+    #[serde(default)]
+    pub identifier: Option<Option<String>>,
+    #[serde(default)]
+    pub cache_status: Option<bool>,
+    #[serde(default)]
+    pub proxy_status: Option<bool>,
+    #[serde(default)]
+    pub content_digest: Option<bool>,
+    #[serde(default)]
+    pub repr_digest: Option<bool>,
+}
+
+impl ResponseMetadataOverlayConfig {
+    pub(crate) fn validate(&self, field: &'static str) -> Result<(), ConfigError> {
+        if self
+            .identifier
+            .as_ref()
+            .and_then(Option::as_deref)
+            .is_some_and(|identifier| !structured_field_token(identifier))
+        {
+            return Err(ConfigError::InvalidResponseHeaderValue { field });
+        }
+        Ok(())
+    }
+}
+
+fn structured_field_token(value: &str) -> bool {
+    if value.is_empty() || value.len() > MAX_RESPONSE_METADATA_IDENTIFIER_BYTES {
+        return false;
+    }
+    value.bytes().enumerate().all(|(index, byte)| {
+        if index == 0 {
+            byte.is_ascii_alphabetic() || byte == b'*'
+        } else {
+            byte.is_ascii_alphanumeric()
+                || matches!(
+                    byte,
+                    b'!' | b'#'
+                        | b'$'
+                        | b'%'
+                        | b'&'
+                        | b'\''
+                        | b'*'
+                        | b'+'
+                        | b'-'
+                        | b'.'
+                        | b'^'
+                        | b'_'
+                        | b'`'
+                        | b'|'
+                        | b'~'
+                        | b':'
+                        | b'/'
+                )
+        }
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::structured_field_token;
+
+    #[test]
+    fn metadata_identifier_uses_structured_field_token_grammar() {
+        assert!(structured_field_token("edge-gateway"));
+        assert!(structured_field_token("edge.example:8443"));
+        assert!(!structured_field_token(""));
+        assert!(!structured_field_token("9edge"));
+        assert!(!structured_field_token("edge gateway"));
+        assert!(!structured_field_token("edge,other"));
+    }
+}

crates/fluxheim-config/src/config_header_response.rs

@@ -9,6 +9,7 @@ use crate::config_header_hardening::{
     PermittedCrossDomainPolicies, ResponseHardeningConfig, ResponsePermissionsPolicyConfig,
     validate_reporting_endpoints,
 };
+use crate::config_header_metadata::{ResponseMetadataConfig, ResponseMetadataOverlayConfig};
 use crate::config_header_validation::{
     combined_header_set, combined_header_unset, merge_header_mutations,
     validate_cookie_domain_rewrite_rules, validate_cookie_path_rewrite_rules,
@@ -24,6 +25,8 @@ pub struct ResponseHeaderPolicyConfig {
     #[serde(default)]
     pub hardening: ResponseHardeningConfig,
     #[serde(default)]
+    pub metadata: ResponseMetadataConfig,
+    #[serde(default)]
     pub strict_transport_security: Option<String>,
     #[serde(default)]
     pub hsts: Option<ResponseHstsConfig>,
@@ -70,6 +73,7 @@ impl Default for ResponseHeaderPolicyConfig {
         Self {
             enabled: true,
             hardening: ResponseHardeningConfig::default(),
+            metadata: ResponseMetadataConfig::default(),
             strict_transport_security: None,
             hsts: None,
             content_security_policy: None,
@@ -96,6 +100,7 @@ impl Default for ResponseHeaderPolicyConfig {
 
 impl ResponseHeaderPolicyConfig {
     pub(crate) fn validate(&self) -> Result<(), ConfigError> {
+        self.metadata.validate("headers.response.metadata")?;
         validate_optional_header_value(
             "headers.response.strict_transport_security",
             self.strict_transport_security.as_deref(),
@@ -161,6 +166,7 @@ impl ResponseHeaderPolicyConfig {
         if let Some(hardening) = &overlay.hardening {
             self.hardening = hardening.clone();
         }
+        self.metadata.apply_overlay(&overlay.metadata);
         if let Some(value) = &overlay.strict_transport_security {
             self.strict_transport_security = value.clone();
         }
@@ -304,6 +310,8 @@ pub struct ResponseHeaderPolicyOverlayConfig {
     #[serde(default)]
     pub hardening: Option<ResponseHardeningConfig>,
     #[serde(default)]
+    pub metadata: ResponseMetadataOverlayConfig,
+    #[serde(default)]
     pub strict_transport_security: Option<Option<String>>,
     #[serde(default)]
     pub hsts: Option<Option<ResponseHstsConfig>>,
@@ -347,6 +355,7 @@ pub struct ResponseHeaderPolicyOverlayConfig {
 
 impl ResponseHeaderPolicyOverlayConfig {
     pub(crate) fn validate(&self) -> Result<(), ConfigError> {
+        self.metadata.validate("vhosts.headers.response.metadata")?;
         validate_optional_header_value(
             "vhosts.headers.response.strict_transport_security",
             self.strict_transport_security

crates/fluxheim-config/src/config_tests_headers.rs

@@ -1,5 +1,7 @@
 #[path = "config_tests_headers_generic.rs"]
 mod generic;
+#[path = "config_tests_headers_metadata.rs"]
+mod metadata;
 #[path = "config_tests_headers_request.rs"]
 mod request;
 #[path = "config_tests_headers_response.rs"]

crates/fluxheim-config/src/config_tests_headers_metadata.rs

@@ -0,0 +1,80 @@
+use super::super::*;
+use crate::{ResponseMetadataConfig, ResponseMetadataOverlayConfig};
+
+#[test]
+fn parses_opt_in_response_metadata_policy() {
+    let config: Config = toml::from_str(
+        r#"
+            [headers.response.metadata]
+            identifier = "edge-gateway"
+            cache_status = true
+            proxy_status = true
+            content_digest = true
+            repr_digest = true
+        "#,
+    )
+    .unwrap();
+
+    let metadata = &config.headers.response.metadata;
+    assert_eq!(metadata.identifier.as_deref(), Some("edge-gateway"));
+    assert!(metadata.cache_status);
+    assert!(metadata.proxy_status);
+    assert!(metadata.content_digest);
+    assert!(metadata.repr_digest);
+    config.validate().unwrap();
+}
+
+#[test]
+fn rejects_status_metadata_without_deployment_identifier() {
+    let config: Config = toml::from_str(
+        r#"
+            [headers.response.metadata]
+            proxy_status = true
+        "#,
+    )
+    .unwrap();
+
+    assert!(matches!(
+        config.validate(),
+        Err(ConfigError::InvalidResponseHeaderValue {
+            field: "headers.response.metadata"
+        })
+    ));
+}
+
+#[test]
+fn response_metadata_overlay_inherits_identifier_and_overrides_fields() {
+    let mut base = ResponseMetadataConfig {
+        identifier: Some("edge-gateway".to_owned()),
+        cache_status: true,
+        ..ResponseMetadataConfig::default()
+    };
+    base.apply_overlay(&ResponseMetadataOverlayConfig {
+        cache_status: Some(false),
+        content_digest: Some(true),
+        ..ResponseMetadataOverlayConfig::default()
+    });
+
+    assert_eq!(base.identifier.as_deref(), Some("edge-gateway"));
+    assert!(!base.cache_status);
+    assert!(base.content_digest);
+}
+
+#[test]
+fn rejects_non_token_response_metadata_identifier() {
+    let config: Config = toml::from_str(
+        r#"
+            [headers.response.metadata]
+            identifier = "edge gateway"
+            cache_status = true
+        "#,
+    )
+    .unwrap();
+
+    assert!(matches!(
+        config.validate(),
+        Err(ConfigError::InvalidResponseHeaderValue {
+            field: "headers.response.metadata"
+        })
+    ));
+}

crates/fluxheim-config/src/lib.rs

@@ -31,6 +31,7 @@ pub mod config_geoip;
 pub mod config_header;
 pub mod config_header_cors;
 pub mod config_header_hardening;
+pub mod config_header_metadata;
 pub mod config_header_response;
 pub mod config_header_validation;
 pub mod config_http;