1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
//! Validated HTTP security-header policy.
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 security headers for JSON APIs.
///
/// Emits `nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer`
/// and same-origin opener/resource policies. CSP, Permissions-Policy and
/// HSTS are left unset. The opener policy prevents cross-origin OAuth popup
/// callbacks; use `with_cross_origin_opener_policy(None)` when cross-origin
/// popup communication is required.
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]
/// Adds one year of HSTS, including subdomains, to [`Self::api_defaults`].
/// Use only when the application and all subdomains are served over HTTPS.
/// HSTS preload is not requested.
pub fn strict_api_defaults() -> Self {
Self {
strict_transport_security: Some(HeaderValue::from_static(
"max-age=31536000; includeSubDomains",
)),
..Self::api_defaults()
}
}
#[must_use]
/// Removes HSTS from this policy, leaving other headers unchanged.
///
/// This leaves an application's existing response header untouched and does
/// not revoke a browser's stored policy. To request revocation over HTTPS,
/// use [`Self::with_strict_transport_security`] with zero seconds.
pub fn without_strict_transport_security(mut self) -> Self {
self.strict_transport_security = None;
self
}
/// Configures HSTS with an exact, nonnegative number of seconds.
///
/// Send this header only over HTTPS. Zero emits `max-age=0`, requesting
/// removal of the browser's stored HSTS policy for the current host, as
/// specified by [RFC 6797](https://www.rfc-editor.org/rfc/rfc6797.html#section-6.1.1).
/// Omitting the header does not send that revocation instruction.
///
/// ```
/// use footing::http::SecurityHeadersConfig;
///
/// let headers = SecurityHeadersConfig::default()
/// .with_strict_transport_security(31_536_000, true, false);
/// let revocation = headers.with_strict_transport_security(0, false, false);
/// assert_eq!(revocation.strict_transport_security().unwrap(), "max-age=0");
/// ```
#[must_use]
#[expect(
clippy::expect_used,
reason = "fixed ASCII directives and decimal u64 digits form a valid header value"
)]
pub fn with_strict_transport_security(
mut self,
max_age_seconds: u64,
include_subdomains: bool,
preload: bool,
) -> Self {
let mut value = format!("max-age={max_age_seconds}");
if include_subdomains {
value.push_str("; includeSubDomains");
}
if preload {
value.push_str("; preload");
}
self.strict_transport_security =
Some(HeaderValue::try_from(value).expect("HSTS directives are header-safe ASCII"));
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());
}
}