Skip to content

Commit 9eb07b4

Browse files
danielkovdanielkov
committed
docs: escape html elements, add frontpage
1 parent be4bcf7 commit 9eb07b4

File tree

2 files changed

+97
-29
lines changed

2 files changed

+97
-29
lines changed

‎Cargo.toml

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[package]
22
name = "ntex-helmet"
3-
version = "0.1.1"
3+
version = "0.1.2"
44
edition = "2021"
55
authors = ["Daniel Kovacs <[email protected]>"]
66
description = "HTTP security headers middleware for ntex-web"

‎src/lib.rs

+96-28
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,76 @@
1-
/// Helmet is a collection of HTTP headers that help secure your app by setting various HTTP headers.
2-
///
3-
/// ntex-helmet is a middleware that automatically sets these headers.
4-
///
5-
/// It is based on the [Helmet](https://helmetjs.github.io/) library for Node.js and is highly configurable.
1+
//! Helmet is a collection of HTTP headers that help secure your app by setting various HTTP headers.
2+
//!
3+
//! ntex-helmet is a middleware that automatically sets these headers.
4+
//!
5+
//! It is based on the [Helmet](https://helmetjs.github.io/) library for Node.js and is highly configurable.
6+
//!
7+
//! # Usage
8+
//!
9+
//! ```rust
10+
//! use ntex_helmet::Helmet;
11+
//!
12+
//! #[ntex::main]
13+
//! async fn main() -> std::io::Result<()> {
14+
//! web::HttpServer::new(move || {
15+
//! web::App::new()
16+
//! .wrap(Helmet::default())
17+
//! .service(web::resource("/").to(|| async { "Hello, world!" }))
18+
//! })
19+
//! .bind(("127.0.0.1", 8080))?
20+
//! .run()
21+
//! .await
22+
//! }
23+
//! ```
24+
//!
25+
//! By default Helmet will set the following headers:
26+
//!
27+
//! ```text
28+
//! Content-Security-Policy: default-src 'self'; base-uri 'self'; font-src 'self' https: data:; form-action 'self'; frame-ancestors 'self'; img-src 'self' data:; object-src 'none'; script-src 'self'; script-src-attr 'none'; style-src 'self' https: 'unsafe-inline'; upgrade-insecure-requests
29+
//! Cross-Origin-Opener-Policy: same-origin
30+
//! Cross-Origin-Resource-Policy: same-origin
31+
//! Origin-Agent-Cluster: ?1
32+
//! Referrer-Policy: no-referrer
33+
//! Strict-Transport-Security: max-age=15552000; includeSubDomains
34+
//! X-Content-Type-Options: nosniff
35+
//! X-DNS-Prefetch-Control: off
36+
//! X-Download-Options: noopen
37+
//! X-Frame-Options: sameorigin
38+
//! X-Permitted-Cross-Domain-Policies: none
39+
//! X-XSS-Protection: 0
40+
//! ```
41+
//!
42+
//! This might be a good starting point for most users, but it is highly recommended to spend some time with the documentation for each header, and adjust them to your needs.
43+
//!
44+
//! # Configuration
45+
//!
46+
//! By default if you construct a new instance of `Helmet` it will not set any headers.
47+
//!
48+
//! It is possible to configure `Helmet` to set only the headers you want, by using the `add` method to add headers.
49+
//!
50+
//! ```rust
51+
//! use ntex_helmet::{Helmet, ContentSecurityPolicy, CrossOriginOpenerPolicy};
52+
//!
53+
//! #[ntex::main]
54+
//! async fn main() -> std::io::Result<()> {
55+
//! web::HttpServer::new(move || {
56+
//! web::App::new()
57+
//! .wrap(
58+
//! Helmet::new().add(
59+
//! ContentSecurityPolicy::new()
60+
//! .child_src(vec!["'self'", "https://youtube.com"])
61+
//! .connect_src(vec!["'self'", "https://youtube.com"])
62+
//! .default_src(vec!["'self'", "https://youtube.com"])
63+
//! .font_src(vec!["'self'", "https://youtube.com"]),
64+
//! ),
65+
//! )
66+
//! .add(CrossOriginOpenerPolicy::same_origin_allow_popups())
67+
//! .service(web::resource("/").to(|| async { "Hello, world!" }))
68+
//! })
69+
//! .bind(("127.0.0.1", 8080))?
70+
//! .run()
71+
//! .await
72+
//! }
73+
//!
674
use core::fmt::Display;
775

876
use ntex::{
@@ -863,15 +931,15 @@ impl Header for XPoweredBy {
863931
///
864932
/// # Directives
865933
///
866-
/// - child-src: Defines valid sources for web workers and nested browsing contexts loaded using elements such as <frame> and <iframe>.
934+
/// - child-src: Defines valid sources for web workers and nested browsing contexts loaded using elements such as `<frame>` and `<iframe>`.
867935
/// - connect-src: Applies to XMLHttpRequest (AJAX), WebSocket or EventSource. If not allowed the browser emulates a 400 HTTP status code.
868936
/// - default-src: The default-src is the default policy for loading content such as JavaScript, Images, CSS, Font's, AJAX requests, Frames, HTML5 Media. See the list of directives to see which values are allowed as default.
869937
/// - font-src: Defines valid sources for fonts loaded using @font-face.
870-
/// - frame-src: Defines valid sources for nested browsing contexts loading using elements such as <frame> and <iframe>.
938+
/// - frame-src: Defines valid sources for nested browsing contexts loading using elements such as `<frame>` and `<iframe>`.
871939
/// - img-src: Defines valid sources of images and favicons.
872940
/// - manifest-src: Specifies which manifest can be applied to the resource.
873-
/// - media-src: Defines valid sources for loading media using the <audio> and <video> elements.
874-
/// - object-src: Defines valid sources for the <object>, <embed>, and <applet> elements.
941+
/// - media-src: Defines valid sources for loading media using the `<audio>` and `<video>` elements.
942+
/// - object-src: Defines valid sources for the `<object>`, `<embed>`, and `<applet>` elements.
875943
/// - prefetch-src: Specifies which referrer to use when fetching the resource.
876944
/// - script-src: Defines valid sources for JavaScript.
877945
/// - script-src-elem: Defines valid sources for JavaScript inline event handlers.
@@ -880,10 +948,10 @@ impl Header for XPoweredBy {
880948
/// - style-src-elem: Defines valid sources for stylesheets inline event handlers.
881949
/// - style-src-attr: Defines valid sources for stylesheets inline event handlers.
882950
/// - worker-src: Defines valid sources for Worker, SharedWorker, or ServiceWorker scripts.
883-
/// - base-uri: Restricts the URLs which can be used in a document's <base> element.
951+
/// - base-uri: Restricts the URLs which can be used in a document's `<base>` element.
884952
/// - sandbox: Enables a sandbox for the requested resource similar to the iframe sandbox attribute. The sandbox applies a same origin policy, prevents popups, plugins and script execution is blocked. You can keep the sandbox value empty to keep all restrictions in place, or add values: allow-forms allow-same-origin allow-scripts allow-popups, allow-modals, allow-orientation-lock, allow-pointer-lock, allow-presentation, allow-popups-to-escape-sandbox, allow-top-navigation, allow-top-navigation-by-user-activation.
885953
/// - form-action: Restricts the URLs which can be used as the target of a form submissions from a given context.
886-
/// - frame-ancestors: Specifies valid parents that may embed a page using <frame>, <iframe>, <object>, <embed>, or <applet>.
954+
/// - frame-ancestors: Specifies valid parents that may embed a page using `<frame>`, `<iframe>`, `<object>`, `<embed>`, or `<applet>`.
887955
/// - report-to: Enables reporting of violations.
888956
/// - require-trusted-types-for: Specifies which trusted types are required by a resource.
889957
/// - trusted-types: Specifies which trusted types are defined by a resource.
@@ -910,15 +978,15 @@ pub enum ContentSecurityPolicyDirective<'a> {
910978
DefaultSrc(Vec<&'a str>),
911979
/// Defines valid sources for fonts loaded using @font-face.
912980
FontSrc(Vec<&'a str>),
913-
/// Defines valid sources for nested browsing contexts loading using elements such as <frame> and <iframe>.
981+
/// Defines valid sources for nested browsing contexts loading using elements such as `<frame>` and `<iframe>`.
914982
FrameSrc(Vec<&'a str>),
915983
/// Defines valid sources of images and favicons.
916984
ImgSrc(Vec<&'a str>),
917985
/// Specifies which manifest can be applied to the resource.
918986
ManifestSrc(Vec<&'a str>),
919-
/// Defines valid sources for loading media using the <audio> and <video> elements.
987+
/// Defines valid sources for loading media using the `<audio>` and `<video>` elements.
920988
MediaSrc(Vec<&'a str>),
921-
/// Defines valid sources for the <object>, <embed>, and <applet> elements.
989+
/// Defines valid sources for the `<object>`, `<embed>`, and `<applet>` elements.
922990
ObjectSrc(Vec<&'a str>),
923991
/// Specifies which referrer to use when fetching the resource.
924992
PrefetchSrc(Vec<&'a str>),
@@ -937,14 +1005,14 @@ pub enum ContentSecurityPolicyDirective<'a> {
9371005
/// Defines valid sources for Worker, SharedWorker, or ServiceWorker scripts.
9381006
WorkerSrc(Vec<&'a str>),
9391007
// Document directives
940-
/// Restricts the URLs which can be used in a document's <base> element.
1008+
/// Restricts the URLs which can be used in a document's `<base>` element.
9411009
BaseUri(Vec<&'a str>),
9421010
/// Enables a sandbox for the requested resource similar to the iframe sandbox attribute. The sandbox applies a same origin policy, prevents popups, plugins and script execution is blocked. You can keep the sandbox value empty to keep all restrictions in place, or add values: allow-forms allow-same-origin allow-scripts allow-popups, allow-modals, allow-orientation-lock, allow-pointer-lock, allow-presentation, allow-popups-to-escape-sandbox, allow-top-navigation, allow-top-navigation-by-user-activation.
9431011
Sandbox(Vec<&'a str>),
9441012
// Navigation directives
9451013
/// Restricts the URLs which can be used as the target of a form submissions from a given context.
9461014
FormAction(Vec<&'a str>),
947-
/// Specifies valid parents that may embed a page using <frame>, <iframe>, <object>, <embed>, or <applet>.
1015+
/// Specifies valid parents that may embed a page using `<frame>`, `<iframe>`, `<object>`, `<embed>`, or `<applet>`.
9481016
FrameAncestors(Vec<&'a str>),
9491017
// Reporting directives
9501018
/// Enables reporting of violations.
@@ -961,7 +1029,7 @@ pub enum ContentSecurityPolicyDirective<'a> {
9611029
}
9621030

9631031
impl<'a> ContentSecurityPolicyDirective<'a> {
964-
/// child-src: Defines valid sources for web workers and nested browsing contexts loaded using elements such as <frame> and <iframe>.
1032+
/// child-src: Defines valid sources for web workers and nested browsing contexts loaded using elements such as `<frame>`` and `<iframe>`.
9651033
pub fn child_src(values: Vec<&'a str>) -> Self {
9661034
Self::ChildSrc(values)
9671035
}
@@ -981,7 +1049,7 @@ impl<'a> ContentSecurityPolicyDirective<'a> {
9811049
Self::FontSrc(values)
9821050
}
9831051

984-
/// frame-src: Defines valid sources for nested browsing contexts loading using elements such as <frame> and <iframe>.
1052+
/// frame-src: Defines valid sources for nested browsing contexts loading using elements such as `<frame>` and `<iframe>`.
9851053
pub fn frame_src(values: Vec<&'a str>) -> Self {
9861054
Self::FrameSrc(values)
9871055
}
@@ -996,12 +1064,12 @@ impl<'a> ContentSecurityPolicyDirective<'a> {
9961064
Self::ManifestSrc(values)
9971065
}
9981066

999-
/// media-src: Defines valid sources for loading media using the <audio> and <video> elements.
1067+
/// media-src: Defines valid sources for loading media using the `<audio>` and `<video>` elements.
10001068
pub fn media_src(values: Vec<&'a str>) -> Self {
10011069
Self::MediaSrc(values)
10021070
}
10031071

1004-
/// object-src: Defines valid sources for the <object>, <embed>, and <applet> elements.
1072+
/// object-src: Defines valid sources for the `<object>`, `<embed>`, and `<applet>` elements.
10051073
pub fn object_src(values: Vec<&'a str>) -> Self {
10061074
Self::ObjectSrc(values)
10071075
}
@@ -1046,7 +1114,7 @@ impl<'a> ContentSecurityPolicyDirective<'a> {
10461114
Self::WorkerSrc(values)
10471115
}
10481116

1049-
/// base-uri: Restricts the URLs which can be used in a document's <base> element.
1117+
/// base-uri: Restricts the URLs which can be used in a document's `<base>` element.
10501118
pub fn base_uri(values: Vec<&'a str>) -> Self {
10511119
Self::BaseUri(values)
10521120
}
@@ -1061,7 +1129,7 @@ impl<'a> ContentSecurityPolicyDirective<'a> {
10611129
Self::FormAction(values)
10621130
}
10631131

1064-
/// frame-ancestors: Specifies valid parents that may embed a page using <frame>, <iframe>, <object>, <embed>, or <applet>.
1132+
/// frame-ancestors: Specifies valid parents that may embed a page using `<frame>`, `<iframe>`, `<object>`, `<embed>`, or `<applet>`.
10651133
pub fn frame_ancestors(values: Vec<&'a str>) -> Self {
10661134
Self::FrameAncestors(values)
10671135
}
@@ -1219,7 +1287,7 @@ impl<'a> ContentSecurityPolicy<'a> {
12191287
self
12201288
}
12211289

1222-
/// child-src: Defines valid sources for web workers and nested browsing contexts loaded using elements such as <frame> and <iframe>.
1290+
/// child-src: Defines valid sources for web workers and nested browsing contexts loaded using elements such as `<frame>` and `<iframe>`.
12231291
pub fn child_src(self, values: Vec<&'a str>) -> Self {
12241292
self.directive(ContentSecurityPolicyDirective::child_src(values))
12251293
}
@@ -1239,7 +1307,7 @@ impl<'a> ContentSecurityPolicy<'a> {
12391307
self.directive(ContentSecurityPolicyDirective::font_src(values))
12401308
}
12411309

1242-
/// frame-src: Defines valid sources for nested browsing contexts loading using elements such as <frame> and <iframe>.
1310+
/// frame-src: Defines valid sources for nested browsing contexts loading using elements such as `<frame>` and `<iframe>`.
12431311
pub fn frame_src(self, values: Vec<&'a str>) -> Self {
12441312
self.directive(ContentSecurityPolicyDirective::frame_src(values))
12451313
}
@@ -1254,12 +1322,12 @@ impl<'a> ContentSecurityPolicy<'a> {
12541322
self.directive(ContentSecurityPolicyDirective::manifest_src(values))
12551323
}
12561324

1257-
/// media-src: Defines valid sources for loading media using the <audio> and <video> elements.
1325+
/// media-src: Defines valid sources for loading media using the `<audio>` and `<video>` elements.
12581326
pub fn media_src(self, values: Vec<&'a str>) -> Self {
12591327
self.directive(ContentSecurityPolicyDirective::media_src(values))
12601328
}
12611329

1262-
/// object-src: Defines valid sources for the <object>, <embed>, and <applet> elements.
1330+
/// object-src: Defines valid sources for the `<object>`, `<embed>`, and `<applet>` elements.
12631331
pub fn object_src(self, values: Vec<&'a str>) -> Self {
12641332
self.directive(ContentSecurityPolicyDirective::object_src(values))
12651333
}
@@ -1304,7 +1372,7 @@ impl<'a> ContentSecurityPolicy<'a> {
13041372
self.directive(ContentSecurityPolicyDirective::worker_src(values))
13051373
}
13061374

1307-
/// base-uri: Restricts the URLs which can be used in a document's <base> element.
1375+
/// base-uri: Restricts the URLs which can be used in a document's `<base>` element.
13081376
pub fn base_uri(self, values: Vec<&'a str>) -> Self {
13091377
self.directive(ContentSecurityPolicyDirective::base_uri(values))
13101378
}
@@ -1319,7 +1387,7 @@ impl<'a> ContentSecurityPolicy<'a> {
13191387
self.directive(ContentSecurityPolicyDirective::form_action(values))
13201388
}
13211389

1322-
/// frame-ancestors: Specifies valid parents that may embed a page using <frame>, <iframe>, <object>, <embed>, or <applet>.
1390+
/// frame-ancestors: Specifies valid parents that may embed a page using `<frame>`, `<iframe>`, `<object>`, `<embed>`, or `<applet>`.
13231391
pub fn frame_ancestors(self, values: Vec<&'a str>) -> Self {
13241392
self.directive(ContentSecurityPolicyDirective::frame_ancestors(values))
13251393
}

0 commit comments

Comments
 (0)