init

Author: jornfranke

backend/Rocket.toml

@@ -16,7 +16,7 @@ content_security_policy = "default-src 'none'; base-uri 'self'; script-src 'self
 content_security_policy_inject_nonce_paths = ["^/$","^/index.html$","^/ui/*"]
 content_security_policy_nonce_headers = ["script-src"]
 content_security_policy_inject_nonce_tags = ["script"]
-permission_policy = "accelerometer=(), ambient-light-sensor=(), autoplay=(), battery=(), camera=(), cross-origin-isolated=(), display-capture=(), document-domain=(), encrypted-media=(), execution-while-not-rendered=(), execution-while-out-of-viewport=(), fullscreen=(), geolocation=(), gyroscope=(), keyboard-map=(), magnetometer=(), microphone=(), midi=(), navigation-override=(), payment=(), picture-in-picture=(), publickey-credentials-get=(), screen-wake-lock=(), sync-xhr=(), usb=(), web-share=(), xr-spatial-tracking=()"
+permissions_policy = "accelerometer=(), ambient-light-sensor=(), autoplay=(), battery=(), camera=(), cross-origin-isolated=(), display-capture=(), document-domain=(), encrypted-media=(), execution-while-not-rendered=(), execution-while-out-of-viewport=(), fullscreen=(), geolocation=(), gyroscope=(), keyboard-map=(), magnetometer=(), microphone=(), midi=(), navigation-override=(), payment=(), picture-in-picture=(), publickey-credentials-get=(), screen-wake-lock=(), sync-xhr=(), usb=(), web-share=(), xr-spatial-tracking=()"
 referrer_policy = "no-referrer"
 cross_origin_embedder_policy = "require-corp; report-to=\"default\""
 cross_origin_opener_policy = "same-origin; report-to=\"default\""

backend/docs/ARCHITECTURE.md

@@ -163,4 +163,6 @@ pub async fn inventory_handler(
     user: OidcUser,
 ) -> crate::database::Result<Json<Vec<inventory::product::Product>>> {
     ....
-```
+```
+
+The OIDC IdToken, AccessToken, mapped roles are stored encryped and tamperproof in a private cookie in the user's browser. This is important, because otherwise the user may give themselves different roles that they are not authorised for.

backend/docs/CONFIGURE.md

@@ -109,7 +109,7 @@ content_security_policy = "default-src 'none'; base-uri 'self'; script-src 'self
 content_security_policy_inject_nonce_paths = ["^/$","^/index.html$","^/ui/*"]
 content_security_policy_nonce_headers = ["script-src"]
 content_security_policy_inject_nonce_tags = ["script"]
-permission_policy = "accelerometer=(), ambient-light-sensor=(), autoplay=(), battery=(), camera=(), cross-origin-isolated=(), display-capture=(), document-domain=(), encrypted-media=(), execution-while-not-rendered=(), execution-while-out-of-viewport=(), fullscreen=(), geolocation=(), gyroscope=(), keyboard-map=(), magnetometer=(), microphone=(), midi=(), navigation-override=(), payment=(), picture-in-picture=(), publickey-credentials-get=(), screen-wake-lock=(), sync-xhr=(), usb=(), web-share=(), xr-spatial-tracking=()"
+permissions_policy = "accelerometer=(), ambient-light-sensor=(), autoplay=(), battery=(), camera=(), cross-origin-isolated=(), display-capture=(), document-domain=(), encrypted-media=(), execution-while-not-rendered=(), execution-while-out-of-viewport=(), fullscreen=(), geolocation=(), gyroscope=(), keyboard-map=(), magnetometer=(), microphone=(), midi=(), navigation-override=(), payment=(), picture-in-picture=(), publickey-credentials-get=(), screen-wake-lock=(), sync-xhr=(), usb=(), web-share=(), xr-spatial-tracking=()"
 referrer_policy = "no-referrer"
 cross_origin_embedder_policy = "require-corp; report-to=\"default\""
 cross_origin_opener_policy = "same-origin; report-to=\"default\""

backend/src/configuration/config.rs

@@ -1,3 +1,5 @@
+//! Manage application-specific configuration
+
 use std::collections::HashMap;
 
 use rocket::{Build, Rocket, serde::Deserialize};
@@ -30,6 +32,11 @@ pub struct CustomAppHttpHeadersConfig {
     pub content_security_policy_inject_nonce_paths: Option<Vec<String>>,
     pub content_security_policy_inject_nonce_tags: Option<Vec<String>>,
     pub content_security_policy_nonce_headers: Option<Vec<String>>,
+    pub permissions_policy: Option<String>,
+    pub referrer_policy: Option<String>,
+    pub cross_origin_embedder_policy: Option<String>,
+    pub cross_origin_opener_policy: Option<String>,
+    pub cross_origin_resource_policy: Option<String>,
 }
 
 /// Configuration of static file serving
@@ -60,6 +67,9 @@ pub struct Config {
 /// # Arguments
 /// * `config` - Configuration of the Rocket app
 ///
+/// # Returns
+/// Fairing that can be attached using rocket.attach
+///
 pub fn read_security_http_headers_config(config: &Config) -> SecurityHttpHeaders {
     let mut regex_paths = regex::RegexSet::new(Vec::<String>::new()).unwrap();
     match &config
@@ -79,10 +89,28 @@ pub fn read_security_http_headers_config(config: &Config) -> SecurityHttpHeaders
     }
 }
 
+/// Configure static file server for static files (e.g. frontend)
+///
+/// # Arguments
+/// * `rocket` - variable representing a Rocket instance
+/// * `config` - Configuration of the Rocket app
+///
+/// # Returns
+/// rocket representing Rocket instance with static file server configured
+///
 pub fn configure_fileserver(rocket: Rocket<Build>, config: &Config) -> Rocket<Build> {
     rocket.manage(config.app.fileserver.clone())
 }
 
+/// Configure OIDC authentication with Rocket instance
+///
+/// # Arguments
+/// * `rocket` - variable representing a rocket instance
+/// * `config` - Configuration of the Rocket app
+///
+/// # Returns
+/// rocket representing rocket instance with OIDC authentication configured
+///
 pub fn configure_oidc(rocket: Rocket<Build>, config: &Config) -> Rocket<Build> {
     let oidc_flow = read_oidc_config(&config);
     rocket
@@ -94,6 +122,14 @@ pub fn configure_oidc(rocket: Rocket<Build>, config: &Config) -> Rocket<Build> {
         )
 }
 
+/// Reads the OIDC configuration and creates an OIDC client
+///
+/// # Arguments
+/// * `config` - Configuration of the Rocket app
+///
+/// # Returns
+/// OIDC client that should be managed in a state in Rocket
+///
 fn read_oidc_config(config: &Config) -> OidcFlow {
     let issuer_url = match &config.app.oidc.issuer_url {
         Some(issuer_url) => issuer_url,

backend/src/database/mod.rs

@@ -1,3 +1,5 @@
+//! Manage database and create/update schemas
+
 use rocket::fairing::{self};
 use rocket::{Build, Rocket};
 use rocket_db_pools::Database;
@@ -9,6 +11,14 @@ pub struct Db(sqlx::SqlitePool);
 
 pub type Result<T, E = rocket::response::Debug<sqlx::Error>> = std::result::Result<T, E>;
 
+/// Create/update schemas in database
+///
+/// # Arguments
+/// * `rocket` - rocket variable representing the Rocket instance
+///
+/// # Returns
+/// Fairing that can be attached using rocket.attach
+///
 pub async fn run_migrations(rocket: Rocket<Build>) -> fairing::Result {
     match Db::fetch(&rocket) {
         Some(db) => match sqlx::migrate!("db/sqlx/migrations").run(&**db).await {

backend/src/httpfirewall/securityhttpheaders.rs

@@ -1,4 +1,4 @@
-//! Rocket fairing to configure secure HTTP headers, such as content security policies
+//! Rocket fairing to inject HTTP security headers, such as content security policies, into responses
 
 use std::io;
 
@@ -10,12 +10,14 @@ use rocket::http::Status;
 use rocket::{Data, Request, Response};
 use tracing::{Level, event};
 
+// Configuration of Fairing
 #[derive(Clone)]
 pub struct SecurityHttpHeaders {
     pub config: crate::configuration::config::CustomAppConfig,
     pub regex_paths: regex::RegexSet,
 }
 
+// Fairing implementation
 #[rocket::async_trait]
 impl Fairing for SecurityHttpHeaders {
     fn info(&self) -> Info {
@@ -25,12 +27,27 @@ impl Fairing for SecurityHttpHeaders {
         }
     }
 
+    /// Executed on every request (we do not need it, but it is part of the Fairing trait)
+    ///
+    /// # Arguments
+    /// * `self` - Struct Security HTTP Headers
+    /// * `req` - Request object
+    ///
+    ///
     async fn on_request(&self, req: &mut Request<'_>, _: &mut Data<'_>) {
         // do nothing
     }
 
+    /// Executed on every response. We inject here the HTTP Security Headers
+    ///
+    /// # Arguments
+    /// * `self` - Struct Security HTTP Headers
+    /// * `req` - Request object
+    /// * `res` - Response object
+    ///
     async fn on_response<'r>(&self, req: &'r Request<'_>, res: &mut Response<'r>) {
         if (res.status() == Status::Ok) {
+            // Configure Content-Security Policy Header and insert nonces
             let mut body_bytes = res.body_mut().to_bytes().await.unwrap();
             match self.config.clone().httpheaders.content_security_policy {
                 Some(csp) => {
@@ -95,9 +112,48 @@ impl Fairing for SecurityHttpHeaders {
                                 "Configuration: Content-Security-Policy: You did not specify a tag to inject a nonce"
                             ),
                         }
-
                         res.set_raw_header("Content-Security-Policy", csp_value);
                         res.set_sized_body(body_bytes.len(), io::Cursor::new(body_bytes));
+                        // Set other HTTP Security Headers
+                        match self.config.clone().httpheaders.permissions_policy {
+                            Some(permissions_policy) => {
+                                res.set_raw_header("Permissions-Policy", permissions_policy);
+                            }
+                            None => (),
+                        };
+                        match self.config.clone().httpheaders.referrer_policy {
+                            Some(referrer_policy) => {
+                                res.set_raw_header("Referrer-Policy", referrer_policy);
+                            }
+                            None => (),
+                        };
+                        match self.config.clone().httpheaders.cross_origin_embedder_policy {
+                            Some(cross_origin_embedder_policy) => {
+                                res.set_raw_header(
+                                    "Cross-Origin-Embedder-Policy",
+                                    cross_origin_embedder_policy,
+                                );
+                            }
+                            None => (),
+                        };
+                        match self.config.clone().httpheaders.cross_origin_opener_policy {
+                            Some(cross_origin_opener_policy) => {
+                                res.set_raw_header(
+                                    "Cross-Origin-Opener-Policy",
+                                    cross_origin_opener_policy,
+                                );
+                            }
+                            None => (),
+                        };
+                        match self.config.clone().httpheaders.cross_origin_resource_policy {
+                            Some(cross_origin_resource_policy) => {
+                                res.set_raw_header(
+                                    "Cross-Origin-Resource-Policy",
+                                    cross_origin_resource_policy,
+                                );
+                            }
+                            None => (),
+                        };
                     }
                 }
                 None => (),

backend/src/inventory/product.rs

@@ -1,3 +1,5 @@
+//! Business data and logic for products
+
 use rocket::serde::{Deserialize, Serialize};
 
 use rust_decimal::prelude::*;

backend/src/main.rs

@@ -24,7 +24,7 @@ pub mod order;
 pub mod routes;
 pub mod services;
 
-/// Launch endpoints of the web application
+/// Launch our application configured with custom routes, OIDC autentication and static file serving
 #[launch]
 fn rocket() -> _ {
     let rocket = rocket::build()

backend/src/oidc/guard.rs

@@ -1,3 +1,5 @@
+//! Request guard to ensure OIDC authentication to routes in Rocket
+
 use super::oidcflow::{OidcFlow, OidcSessionCookie};
 
 use openidconnect::{ClaimsVerificationError, EndUserUsername, SubjectIdentifier};
@@ -10,13 +12,15 @@ use rocket::{
 use serde::Serialize;
 use tracing::{Level, event};
 
+// Represents an authenticated user in a Rocket route
 #[derive(Serialize)]
 pub struct OidcUser {
     pub subject: SubjectIdentifier,
     pub preferred_username: Option<EndUserUsername>,
     pub mapped_roles: Vec<String>,
 }
 
+// Loads user authentication information from the oidc session cookie
 impl OidcUser {
     fn load_from_session(
         oidc: &OidcFlow,
@@ -45,10 +49,20 @@ impl OidcUser {
     }
 }
 
+// Implementation of the request guard to ensure that the user is authenticated via OIDC
+
 #[rocket::async_trait]
 impl<'r> FromRequest<'r> for OidcUser {
     type Error = ();
 
+    /// Executed for each request on which route the OidcUser is included
+    /// Reads from the cookie the user information including the OIDC token
+    /// If they are not presented then a cookie is added from which route the user came from so the user is redirected there again after authentication
+    ///
+    /// # Arguments
+    /// * `req` - Request object
+    ///
+    ///
     async fn from_request(req: &'r Request<'_>) -> request::Outcome<Self, Self::Error> {
         let mut cookies = req.cookies();
         if let Some(serialized_session) = cookies.get_private("oidc_user_session") {