footing 0.1.19

Feature-gated foundations for Rust backend services
Documentation
//! Validated HTTP security-header policy.

use std::time::Duration;

use axum::http::{HeaderMap, HeaderName, HeaderValue};

#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
/// Validated configuration for security headers.
pub struct SecurityHeadersConfig {
    content_type_options: Option<HeaderValue>,
    content_security_policy: Option<HeaderValue>,
    frame_options: Option<HeaderValue>,
    referrer_policy: Option<HeaderValue>,
    cross_origin_opener_policy: Option<HeaderValue>,
    cross_origin_resource_policy: Option<HeaderValue>,
    permissions_policy: Option<HeaderValue>,
    strict_transport_security: Option<HeaderValue>,
}

impl SecurityHeadersConfig {
    #[must_use]
    /// Creates API defaults.
    pub fn api_defaults() -> Self {
        Self {
            content_type_options: Some(HeaderValue::from_static("nosniff")),
            content_security_policy: None,
            frame_options: Some(HeaderValue::from_static("DENY")),
            referrer_policy: Some(HeaderValue::from_static("no-referrer")),
            cross_origin_opener_policy: Some(HeaderValue::from_static("same-origin")),
            cross_origin_resource_policy: Some(HeaderValue::from_static("same-origin")),
            permissions_policy: None,
            strict_transport_security: None,
        }
    }

    #[must_use]
    /// Creates strict API defaults.
    pub fn strict_api_defaults() -> Self {
        Self {
            strict_transport_security: Some(HeaderValue::from_static(
                "max-age=31536000; includeSubDomains",
            )),
            ..Self::api_defaults()
        }
    }

    #[must_use]
    /// Returns the without strict transport security.
    pub fn without_strict_transport_security(mut self) -> Self {
        self.strict_transport_security = None;
        self
    }

    /// Configures strict transport security and returns the updated value.
    pub fn with_strict_transport_security(
        mut self,
        max_age: Duration,
        include_subdomains: bool,
        preload: bool,
    ) -> Result<Self, axum::http::header::InvalidHeaderValue> {
        let mut value = format!("max-age={}", max_age.as_secs());
        if include_subdomains {
            value.push_str("; includeSubDomains");
        }
        if preload {
            value.push_str("; preload");
        }

        self.strict_transport_security = Some(HeaderValue::from_str(&value)?);
        Ok(self)
    }

    #[must_use]
    /// Configures content type options and returns the updated value.
    pub fn with_content_type_options(mut self, value: Option<HeaderValue>) -> Self {
        self.content_type_options = value;
        self
    }

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

    #[must_use]
    /// Configures frame options and returns the updated value.
    pub fn with_frame_options(mut self, value: Option<HeaderValue>) -> Self {
        self.frame_options = value;
        self
    }

    #[must_use]
    /// Configures referrer policy and returns the updated value.
    pub fn with_referrer_policy(mut self, value: Option<HeaderValue>) -> Self {
        self.referrer_policy = value;
        self
    }

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

    #[must_use]
    /// Configures cross origin resource policy and returns the updated value.
    pub fn with_cross_origin_resource_policy(mut self, value: Option<HeaderValue>) -> Self {
        self.cross_origin_resource_policy = value;
        self
    }

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

    #[must_use]
    /// Returns the content type options.
    pub fn content_type_options(&self) -> Option<&HeaderValue> {
        self.content_type_options.as_ref()
    }

    #[must_use]
    /// Returns the content security policy.
    pub fn content_security_policy(&self) -> Option<&HeaderValue> {
        self.content_security_policy.as_ref()
    }

    #[must_use]
    /// Returns the frame options.
    pub fn frame_options(&self) -> Option<&HeaderValue> {
        self.frame_options.as_ref()
    }

    #[must_use]
    /// Returns the referrer policy.
    pub fn referrer_policy(&self) -> Option<&HeaderValue> {
        self.referrer_policy.as_ref()
    }

    #[must_use]
    /// Returns the cross origin opener policy.
    pub fn cross_origin_opener_policy(&self) -> Option<&HeaderValue> {
        self.cross_origin_opener_policy.as_ref()
    }

    #[must_use]
    /// Returns the cross origin resource policy.
    pub fn cross_origin_resource_policy(&self) -> Option<&HeaderValue> {
        self.cross_origin_resource_policy.as_ref()
    }

    #[must_use]
    /// Returns the permissions policy.
    pub fn permissions_policy(&self) -> Option<&HeaderValue> {
        self.permissions_policy.as_ref()
    }

    #[must_use]
    /// Returns the strict transport security.
    pub fn strict_transport_security(&self) -> Option<&HeaderValue> {
        self.strict_transport_security.as_ref()
    }

    /// Applies the configured security headers to a response header map.
    pub fn apply(&self, headers: &mut HeaderMap) {
        insert_header(
            headers,
            HeaderName::from_static("x-content-type-options"),
            &self.content_type_options,
        );
        insert_header(
            headers,
            HeaderName::from_static("content-security-policy"),
            &self.content_security_policy,
        );
        insert_header(
            headers,
            HeaderName::from_static("x-frame-options"),
            &self.frame_options,
        );
        insert_header(
            headers,
            HeaderName::from_static("referrer-policy"),
            &self.referrer_policy,
        );
        insert_header(
            headers,
            HeaderName::from_static("cross-origin-opener-policy"),
            &self.cross_origin_opener_policy,
        );
        insert_header(
            headers,
            HeaderName::from_static("cross-origin-resource-policy"),
            &self.cross_origin_resource_policy,
        );
        insert_header(
            headers,
            HeaderName::from_static("permissions-policy"),
            &self.permissions_policy,
        );
        insert_header(
            headers,
            HeaderName::from_static("strict-transport-security"),
            &self.strict_transport_security,
        );
    }
}

impl Default for SecurityHeadersConfig {
    fn default() -> Self {
        Self::api_defaults()
    }
}

fn insert_header(headers: &mut HeaderMap, name: HeaderName, value: &Option<HeaderValue>) {
    if let Some(value) = value {
        headers.insert(name, value.clone());
    }
}