diff --git a/conf/nginx.conf b/conf/nginx.conf
index 0ce86a4..c272291 100644
--- a/conf/nginx.conf
+++ b/conf/nginx.conf
@@ -5,51 +5,87 @@ set $api_domain "__DOMAIN__";
 set $files_domain "__DOMAIN__";
 ssl_ecdh_curve secp384r1;
 
-more_set_headers "Access-Control-Allow-Origin: '${allowed_origins}'";
+more_set_headers "X-XSS-Protection: 1; mode=block";
+more_set_headers "X-Content-Type-Options: nosniff";
+more_set_headers "Access-Control-Allow-Origin: ${allowed_origins}";
+more_set_headers "Access-Control-Allow-Credentials: true";
+# more_set_headers "X-Frame-Options: SAMEORIGIN";
+
+# Enable SharedArrayBuffer in Firefox (for .xlsx export)
 more_set_headers "Cross-Origin-Resource-Policy: cross-origin";
 more_set_headers "Cross-Origin-Embedder-Policy: require-corp";
 
+# Insert the path to your CryptPad repository root here
 root __INSTALL_DIR__/;
 index index.html;
 error_page 404 /customize.dist/404.html;
 
+# any static assets loaded with "ver=" in their URL will be cached for a year
 if ($args ~ ver=) {
     set $cacheControl max-age=31536000;
 }
-
+# This rule overrides the above caching directive and makes things somewhat less efficient.
+# We had inverted them as an optimization, but Safari 16 introduced a bug that interpreted
+# some important headers incorrectly when loading these files from cache.
+# This is why we can't have nice things :(
 if ($uri ~ ^(\/|.*\/|.*\.html)$) {
     set $cacheControl no-cache;
 }
 
+# Will not set any header if it is emptystring
 more_set_headers "Cache-Control: $cacheControl";
 
+# CSS can be dynamically set inline, loaded from the same domain, or from $main_domain
 set $styleSrc   "'unsafe-inline' 'self' https://${main_domain}";
 
+# connect-src restricts URLs which can be loaded using script interfaces
+# if you have configured your instance to use a dedicated $files_domain or $api_domain
+# you will need to add them below as: https://${files_domain} and https://${api_domain}
 set $connectSrc "'self' https://${main_domain} blob: wss://${api_domain} https://${sandbox_domain}";
 
+# fonts can be loaded from data-URLs or the main domain
 set $fontSrc    "'self' data: https://${main_domain}";
 
+# images can be loaded from anywhere, though we'd like to deprecate this as it allows the use of images for tracking
 set $imgSrc     "'self' data: blob: https://${main_domain}";
 
+# frame-src specifies valid sources for nested browsing contexts.
+# this prevents loading any iframes from anywhere other than the sandbox domain
 set $frameSrc   "'self' https://${sandbox_domain} blob:";
 
+# specifies valid sources for loading media using video or audio
 set $mediaSrc   "blob:";
 
+# defines valid sources for webworkers and nested browser contexts
+# deprecated in favour of worker-src and frame-src
 set $childSrc   "https://${main_domain}";
 
+# specifies valid sources for Worker, SharedWorker, or ServiceWorker scripts.
+# supercedes child-src but is unfortunately not yet universally supported.
 set $workerSrc  "'self'";
 
+# script-src specifies valid sources for javascript, including inline handlers
 set $scriptSrc  "'self' resource: https://${main_domain}";
 
+# frame-ancestors specifies which origins can embed your CryptPad instance
+# this must include 'self' and your main domain (over HTTPS) in order for CryptPad to work
+# if you have enabled remote embedding via the admin panel then this must be more permissive.
+# note: cryptpad.fr permits web pages served via https: and vector: (element desktop app)
 set $frameAncestors "'self' https://${main_domain}";
+ # set $frameAncestors "'self' https: vector:";
 
 set $unsafe 0;
-
+# the following assets are loaded via the sandbox domain
+# they unfortunately still require exceptions to the sandboxing to work correctly.
 if ($uri ~ ^\/(sheet|doc|presentation)\/inner.html.*$) { set $unsafe 1; }
 if ($uri ~ ^\/common\/onlyoffice\/.*\/.*\.html.*$) { set $unsafe 1; }
 
+# everything except the sandbox domain is a privileged scope, as they might be used to handle keys
 if ($host != $sandbox_domain) { set $unsafe 0; }
-
+ # this iframe is an exception. Office file formats are converted outside of the sandboxed scope
+# because of bugs in Chromium-based browsers that incorrectly ignore headers that are supposed to enable
+# the use of some modern APIs that we require when javascript is run in a cross-origin context.
+# We've applied other sandboxing techniques to mitigate the risk of running WebAssembly in this privileged scope
 if ($uri ~ ^\/unsafeiframe\/inner\.html.*$) { set $unsafe 1; }
 
 # privileged contexts allow a few more rights than unprivileged contexts, though limits are still applied
@@ -57,6 +93,7 @@ if ($unsafe) {
     set $scriptSrc "'self' 'unsafe-eval' 'unsafe-inline' resource: https://${main_domain}";
 }
 
+# Finally, set all the rules you composed above.
 more_set_headers "Content-Security-Policy: default-src 'none'; child-src $childSrc; worker-src $workerSrc; media-src $mediaSrc; style-src $styleSrc; script-src $scriptSrc; connect-src $connectSrc; font-src $fontSrc; img-src $imgSrc; frame-src $frameSrc; frame-ancestors $frameAncestors";
 
 location ^~ /cryptpad_websocket {
@@ -74,23 +111,36 @@ location ^~ /cryptpad_websocket {
 location ^~ /customize.dist/ {
     # This is needed in order to prevent infinite recursion between /customize/ and the root
 }
-
+# try to load customizeable content via /customize/ and fall back to the default content
+# located at /customize.dist/
+# This is what allows you to override behaviour.
 location ^~ /customize/ {
     rewrite ^/customize/(.*)$ $1 break;
     try_files /customize/$uri /customize.dist/$uri;
 }
 
+# /api/config is loaded once per page load and is used to retrieve
+# the caching variable which is applied to every other resource
+# which is loaded during that session.
 location ~ ^/api/.*$ {
     proxy_pass http://127.0.0.1:__PORT__;
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header Host $host;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_hide_header Cross-Origin-Resource-Policy;
+
+    # These settings prevent both NGINX and the API server
+    # from setting the same headers and creating duplicates
+    proxy_hide_header "Cross-Origin-Resource-Policy";
     more_set_headers "Cross-Origin-Resource-Policy: cross-origin";
-    proxy_hide_header Cross-Origin-Embedder-Policy;
+    proxy_hide_header "Cross-Origin-Embedder-Policy";
     more_set_headers "Cross-Origin-Embedder-Policy: require-corp";
 }
 
+# Requests for blobs and blocks are now proxied to the API server
+# This simplifies NGINX path configuration in the event they are being hosted in a non-standard location
+# or with odd unexpected permissions. Serving blobs in this manner also means that it will be possible to
+# enforce access control for them, though this is not yet implemented.
+# Access control (via TOTP 2FA) has been added to blocks, so they can be handled with the same directives.
 location ~ ^/(blob|block)/.*$ {
     if ($request_method = 'OPTIONS') {
         more_set_headers "Access-Control-Allow-Origin: ${allowed_origins}";
@@ -102,17 +152,23 @@ location ~ ^/(blob|block)/.*$ {
         more_set_headers "Content-Length: 0";
         return 204;
     }
-    more_set_headers "X-Content-Type-Options: nosniff";
-    more_set_headers "Cache-Control: max-age=31536000'";
-    more_set_headers "Access-Control-Allow-Origin: ${allowed_origins}";
-    more_set_headers "Access-Control-Allow-Methods: 'GET, POST, OPTIONS'";
-    more_set_headers "Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Content-Range,Range,Content-Length";
-    more_set_headers "Access-Control-Expose-Headers: DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Content-Range,Range,Content-Length";
-    try_files $uri =404;
+    # Since we are proxying to the API server these headers can get duplicated
+    # so we hide them
+    proxy_hide_header 'X-Content-Type-Options';
+    proxy_hide_header 'Access-Control-Allow-Origin';
+    proxy_hide_header 'Permissions-Policy';
+    proxy_hide_header 'X-XSS-Protection';
+    proxy_hide_header 'Cross-Origin-Resource-Policy';
+    proxy_hide_header 'Cross-Origin-Embedder-Policy';
+    proxy_pass http://127.0.0.1:__PORT__;
 }
 
+# The nodejs server has some built-in forwarding rules to prevent
+# URLs like /pad from resulting in a 404. This simply adds a trailing slash
+# to a variety of applications.
 location ~ ^/(register|login|recovery|settings|user|pad|drive|poll|slide|code|whiteboard|file|media|profile|contacts|todo|filepicker|debug|kanban|sheet|support|admin|notifications|teams|calendar|presentation|doc|form|report|convert|checkup|diagram)$ {
     rewrite ^(.*)$ $1/ redirect;
 }
 
+# Finally, serve anything the above exceptions don't govern.
 try_files /customize/www/$uri /customize/www/$uri/index.html /www/$uri /www/$uri/index.html /customize/$uri;