footing 0.5.1

Feature-gated foundations for Rust backend services
Documentation
use std::time::Duration;

use axum::http::HeaderValue;
use serde::{Deserialize, Serialize};

use crate::settings::{SettingsIssues, SettingsValidationError};

use super::super::{policy::DEFAULT_HSTS_MAX_AGE, security::SecurityHeadersConfig};

#[cfg_attr(feature = "tier", derive(tier::TierConfig))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(default, deny_unknown_fields)]
#[non_exhaustive]
/// Serializable settings for security headers.
pub struct SecurityHeadersSettings {
    /// Whether security response headers are emitted.
    pub enabled: bool,
    /// HTTP Strict Transport Security configuration.
    pub strict_transport_security: StrictTransportSecuritySettings,
    /// Value of `Cross-Origin-Opener-Policy`, or `None` to omit it.
    pub cross_origin_opener_policy: Option<String>,
    /// Value of `Content-Security-Policy`, or `None` to omit it.
    pub content_security_policy: Option<String>,
    /// Value of `Permissions-Policy`, or `None` to omit it.
    pub permissions_policy: Option<String>,
}

#[cfg_attr(feature = "tier", derive(tier::TierConfig))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(default, deny_unknown_fields)]
#[non_exhaustive]
/// Serializable settings for strict transport security.
pub struct StrictTransportSecuritySettings {
    /// Whether the HSTS header is emitted.
    pub enabled: bool,
    #[serde(with = "crate::settings::human_duration")]
    /// Browser HSTS retention duration.
    /// Must be at least one second when HSTS and security headers are enabled.
    pub max_age: Duration,
    /// Whether HSTS also applies to subdomains.
    pub include_subdomains: bool,
    /// Whether to request inclusion in browser preload lists.
    pub preload: bool,
}

impl Default for SecurityHeadersSettings {
    fn default() -> Self {
        Self {
            enabled: true,
            strict_transport_security: StrictTransportSecuritySettings::default(),
            cross_origin_opener_policy: Some("same-origin".to_owned()),
            content_security_policy: None,
            permissions_policy: None,
        }
    }
}

impl Default for StrictTransportSecuritySettings {
    fn default() -> Self {
        Self {
            enabled: false,
            max_age: DEFAULT_HSTS_MAX_AGE,
            include_subdomains: true,
            preload: false,
        }
    }
}

impl SecurityHeadersSettings {
    #[must_use]
    /// Creates disabled.
    pub const fn disabled() -> Self {
        Self {
            enabled: false,
            strict_transport_security: StrictTransportSecuritySettings {
                enabled: false,
                max_age: DEFAULT_HSTS_MAX_AGE,
                include_subdomains: true,
                preload: false,
            },
            cross_origin_opener_policy: None,
            content_security_policy: None,
            permissions_policy: None,
        }
    }

    #[must_use]
    /// Configures enabled and returns the updated value.
    pub const fn with_enabled(mut self, enabled: bool) -> Self {
        self.enabled = enabled;
        self
    }

    #[must_use]
    /// Configures strict transport security and returns the updated value.
    pub const fn with_strict_transport_security(
        mut self,
        strict_transport_security: StrictTransportSecuritySettings,
    ) -> Self {
        self.strict_transport_security = strict_transport_security;
        self
    }

    #[must_use]
    /// Configures cross origin opener policy and returns the updated value.
    pub fn with_cross_origin_opener_policy(mut self, value: Option<impl Into<String>>) -> Self {
        self.cross_origin_opener_policy = value.map(Into::into);
        self
    }

    #[must_use]
    /// Configures content security policy and returns the updated value.
    pub fn with_content_security_policy(mut self, value: Option<impl Into<String>>) -> Self {
        self.content_security_policy = value.map(Into::into);
        self
    }

    #[must_use]
    /// Configures permissions policy and returns the updated value.
    pub fn with_permissions_policy(mut self, value: Option<impl Into<String>>) -> Self {
        self.permissions_policy = value.map(Into::into);
        self
    }

    pub(in crate::http::layers) fn build_at(
        &self,
        path: &str,
    ) -> Result<Option<SecurityHeadersConfig>, SettingsValidationError> {
        let mut issues = SettingsIssues::new();
        if self.enabled && self.strict_transport_security.enabled {
            issues.require(
                self.strict_transport_security.max_age.as_secs() > 0,
                format!("{path}.strict_transport_security.max_age"),
                "must be at least one second when strict transport security is enabled",
            );
        }
        let opener_policy = optional_header_value(
            format!("{path}.cross_origin_opener_policy"),
            self.cross_origin_opener_policy.as_deref(),
        );
        let content_policy = optional_header_value(
            format!("{path}.content_security_policy"),
            self.content_security_policy.as_deref(),
        );
        let permissions_policy = optional_header_value(
            format!("{path}.permissions_policy"),
            self.permissions_policy.as_deref(),
        );
        for result in [&opener_policy, &content_policy, &permissions_policy] {
            if let Err(error) = result {
                issues.extend(error.clone());
            }
        }
        issues.into_result()?;
        if !self.enabled {
            return Ok(None);
        }
        let mut config = SecurityHeadersConfig::api_defaults()
            .with_cross_origin_opener_policy(opener_policy?)
            .with_content_security_policy(content_policy?)
            .with_permissions_policy(permissions_policy?);
        if self.strict_transport_security.enabled {
            config = config
                .with_strict_transport_security(
                    self.strict_transport_security.max_age,
                    self.strict_transport_security.include_subdomains,
                    self.strict_transport_security.preload,
                )
                .map_err(|_| {
                    SettingsValidationError::single(
                        format!("{path}.strict_transport_security"),
                        "must be a valid HTTP header value",
                    )
                })?;
        }
        Ok(Some(config))
    }
}

impl StrictTransportSecuritySettings {
    #[must_use]
    /// Creates a new instance.
    pub const fn new(
        enabled: bool,
        max_age: Duration,
        include_subdomains: bool,
        preload: bool,
    ) -> Self {
        Self {
            enabled,
            max_age,
            include_subdomains,
            preload,
        }
    }

    #[must_use]
    /// Creates disabled.
    pub const fn disabled() -> Self {
        Self {
            enabled: false,
            max_age: DEFAULT_HSTS_MAX_AGE,
            include_subdomains: true,
            preload: false,
        }
    }

    #[must_use]
    /// Creates enabled.
    pub const fn enabled(max_age: Duration) -> Self {
        Self {
            enabled: true,
            max_age,
            include_subdomains: true,
            preload: false,
        }
    }

    #[must_use]
    /// Configures include subdomains and returns the updated value.
    pub const fn with_include_subdomains(mut self, include_subdomains: bool) -> Self {
        self.include_subdomains = include_subdomains;
        self
    }

    #[must_use]
    /// Configures preload and returns the updated value.
    pub const fn with_preload(mut self, preload: bool) -> Self {
        self.preload = preload;
        self
    }
}

fn optional_header_value(
    path: String,
    value: Option<&str>,
) -> Result<Option<HeaderValue>, SettingsValidationError> {
    value
        .map(str::trim)
        .map(HeaderValue::from_str)
        .transpose()
        .map_err(|_| SettingsValidationError::single(path, "must be a valid HTTP header value"))
}