Janady13/crawler-signal-reference / framework-http-security-headers.md

1# framework-http-security-headers.md 2 3Comprehensive reference for the nine HTTP response headers that establish security guarantees and trust boundaries for a web origin: `Strict-Transport-Security` (HSTS) for transport, `Content-Security-Policy` (CSP) for resource and script control, `X-Frame-Options` for clickjacking defense, `X-Content-Type-Options` for MIME sniffing prevention, `Referrer-Policy` for outbound URL privacy, `Permissions-Policy` for browser capability control, and the cross origin isolation trio `Cross-Origin-Resource-Policy` (CORP), `Cross-Origin-Embedder-Policy` (COEP), and `Cross-Origin-Opener-Policy` (COOP). Built for Bubbles (Debian, Nginx 1.26+, self hosted origin at 169.155.162.118, no Cloudflare or third party CDN in front). Companion to framework-http-caching-headers.md, framework-http-content-headers.md, framework-http-seo-headers.md, UNIVERSAL-RANKING-FRAMEWORK.md, and SEO BUILD REFERENCE v2.4. 4 5Audience: humans configuring nginx, AI assistants generating or repairing nginx config, security auditors, and anyone troubleshooting "CSP blocking my GTM scripts", "site permanently broken after HSTS preload", "clickjacking warning from scanner", or "SharedArrayBuffer not available" anomalies on a self hosted stack. 6 7--- 8 9## TABLE OF CONTENTS 10 111. Definition 122. Why It Matters 133. What This Covers 144. The Defense In Depth Mental Model (read this first) 155. Strict-Transport-Security (HSTS, transport security) 166. Content-Security-Policy (the biggest lever, script and resource control) 177. X-Frame-Options (clickjacking defense, mostly superseded by CSP frame-ancestors) 188. X-Content-Type-Options (MIME sniffing prevention) 199. Referrer-Policy (outbound URL privacy) 2010. Permissions-Policy (browser capability control) 2111. Cross-Origin-Resource-Policy (CORP, who can load this resource) 2212. Cross-Origin-Embedder-Policy (COEP, what this document can embed) 2313. Cross-Origin-Opener-Policy (COOP, what this document can share a window with) 2414. The Cross Origin Isolation Pattern (COEP plus COOP plus CORP) 2515. How These Headers Interact 2616. Asset Class And Use Case Recipes 2717. Bubbles Nginx Reference Block (paste ready) 2818. Audit Checklist (60+ items) 2919. Common Pitfalls 3020. Diagnostic Commands (curl, observatory.mozilla.org, securityheaders.com, browser devtools) 3121. Cross-References 32 33--- 34 35## 1. DEFINITION 36 37Security and trust signal headers tell the browser what it may safely do with a response, what other origins may interact with it, what scripts may execute on it, what capabilities the page may use, and how transport must be secured. They operate as defense in depth: each one closes off a class of attack, and missing any one creates a gap that scanners and attackers will find. The nine headers split into four concerns: 38 39* **Transport**: `Strict-Transport-Security`. It answers "must this origin always be accessed over HTTPS?" 40* **Content execution and embedding**: `Content-Security-Policy`, `X-Frame-Options`, `X-Content-Type-Options`. They answer "what scripts may run, what frames may embed this page, may the browser sniff a different type than declared?" 41* **Privacy and capability**: `Referrer-Policy`, `Permissions-Policy`. They answer "how much referrer information leaks, which device APIs may this page use?" 42* **Cross origin isolation**: `Cross-Origin-Resource-Policy`, `Cross-Origin-Embedder-Policy`, `Cross-Origin-Opener-Policy`. They answer "who may load this resource, what may this document embed, what may share a window with this document?" 43 44Together these nine headers determine the security posture of an origin. Getting any one wrong opens a class of attack: clickjacking, XSS, MIME confusion, referrer leaks, capability abuse, Spectre style side channel attacks, or downgrade to HTTP. Getting them all right earns an A or A+ rating on observatory.mozilla.org and securityheaders.com, which several enterprise procurement processes now require for vendor approval. 45 46--- 47 48## 2. WHY IT MATTERS 49 50Six independent pressures push correct security headers from "polish" to "required infrastructure" in 2025 and forward. 51 52**Enterprise procurement now scans for security headers.** Mid to large enterprises evaluating vendor websites routinely check securityheaders.com and observatory.mozilla.org as part of vendor onboarding. A grade of D or F is a fast path to elimination. An A or A+ is table stakes for credibility in any B2B context. SOC 2 audits, ISO 27001 reviews, and HIPAA risk assessments all include security header checks. 53 54**Search engines and AI crawlers prefer secure origins.** Google has confirmed HTTPS as a ranking signal since 2014 and progressively penalized mixed content. Bing, Perplexity, ClaudeBot, and GPTBot all crawl HTTPS preferentially and treat HTTP origins with suspicion. An origin without HSTS, especially without HSTS preload, signals operational immaturity to ranking systems. 55 56**Browser features are gated on security headers.** Modern web APIs (SharedArrayBuffer, high precision timers, WebAssembly threading, OPFS write access) require cross origin isolation, which requires COEP plus COOP. Sites that need these features (WebAssembly games, video editors, scientific computing apps) cannot function without the right headers. 57 58**XSS is still the number one web vulnerability.** Every OWASP Top 10 list since 2007 has included XSS or its variants. CSP is the single most effective mitigation against the entire class. A site without CSP is one stored XSS away from credential theft, session hijacking, or arbitrary code execution in every visitor's browser. 59 60**Clickjacking is trivial without X-Frame-Options or CSP frame-ancestors.** Any site that can be embedded in an iframe can be clickjacked. The attack overlays the target site in an invisible frame and tricks users into clicking elements they cannot see. Defense is a single header. Failure to set it has caused real money losses (cryptocurrency wallet drains, account takeovers). 61 62**Spectre and similar side channel attacks broke the assumption that cross origin data is opaque.** Before 2018, browsers assumed that an attacker on `evil.com` could not read the pixel data of an image loaded from `bank.com`. Spectre invalidated that assumption. The fix is the cross origin isolation pattern (COEP plus COOP plus CORP), which separates processes so a malicious page cannot reach a victim page's memory via timing attacks. 63 64**Cost of getting it wrong.** Misconfigured security headers produce loud security failures and silent ranking failures. Real examples: 65 66* HSTS preload submitted without testing all subdomains. The internal `admin.example.com` subdomain only served HTTP. After preload, all employee admins lost access for the six months it took to remove the domain from the preload list. 67* CSP rolled out in enforce mode without Report-Only testing. Google Tag Manager started failing silently. Analytics data lost for three weeks before anyone noticed. 68* No X-Frame-Options or CSP frame-ancestors. Attacker built an invisible iframe over the customer portal's withdraw button. Users clicking what looked like a free game button were actually authorizing transfers. 69* No `X-Content-Type-Options: nosniff`. User uploaded a .txt file that contained HTML and JavaScript. Browser sniffed it as HTML, rendered it, ran the script, stole every other user's session cookie. 70* Referrer-Policy unset, default behavior leaks full URL with query string (often containing session tokens, password reset codes, or authentication tokens) to every external image, script, and link. Customer data exposed in third party analytics logs. 71 72All preventable with the rules below. 73 74--- 75 76## 3. WHAT THIS COVERS 77 78Each of the nine headers gets the same six part treatment: 79 801. **What it does**: the canonical RFC or W3C spec plus the practical implication. 812. **Syntax and directives**: every legal value, what it means, and when it is wrong. 823. **How to build it on Bubbles**: paste ready nginx config. 834. **How to verify it**: curl commands plus external scanner checks where applicable. 845. **How to troubleshoot**: the four or five failure modes seen in the field and how to recognize each. 856. **How to fix common breakage**: ordered repair steps. 86 87The cross origin isolation pattern (combining COEP, COOP, and CORP) gets its own dedicated section because the three headers must be tuned together. Asset class recipes are collected in Section 16. 88 89--- 90 91## 4. THE DEFENSE IN DEPTH MENTAL MODEL (READ THIS FIRST) 92 93Security headers form layers. No single header is sufficient. Each layer addresses a different attack class, and defenses are stacked so that bypassing one still leaves the attacker facing the next. Internalize the layer model and every header decision becomes obvious. 94 95``` 96Visitor's browser requests https://example.com/ 97 | 98 v 99==================== TRANSPORT LAYER ==================== 100 | 101 v 102Strict-Transport-Security (HSTS) 103 Force HTTPS only, prevent downgrade attacks 104 Prevent man in the middle attacks on public Wi-Fi 105 | 106 v 107==================== CONTENT EXECUTION LAYER ==================== 108 | 109 v 110Content-Security-Policy 111 Control which scripts may execute 112 Control which origins may be loaded as scripts, styles, images, frames 113 Block inline scripts unless explicitly allowed (via nonce or hash) 114 | 115 v 116X-Content-Type-Options: nosniff 117 Force the declared Content-Type to be authoritative 118 Block MIME confusion attacks 119 | 120 v 121X-Frame-Options (or CSP frame-ancestors) 122 Control whether this page may be embedded in an iframe 123 Block clickjacking 124 | 125 v 126==================== PRIVACY AND CAPABILITY LAYER ==================== 127 | 128 v 129Referrer-Policy 130 Control how much referrer URL is sent to other origins 131 Prevent token and PII leakage via outbound requests 132 | 133 v 134Permissions-Policy 135 Control which browser APIs (camera, mic, geolocation, etc) may be used 136 Prevent third party scripts from abusing capabilities 137 | 138 v 139==================== CROSS ORIGIN ISOLATION LAYER ==================== 140 | 141 v 142Cross-Origin-Resource-Policy (on resources) 143 Control who may load this resource 144Cross-Origin-Embedder-Policy (on documents) 145 Require resources to opt in via CORP or CORS 146Cross-Origin-Opener-Policy (on documents) 147 Isolate browsing context from cross origin windows 148 | 149 v 150 ==> Cross origin isolated state 151 ==> Unlocks SharedArrayBuffer, high precision timers, WebAssembly threading 152 | 153 v 154==================== APPLICATION ==================== 155 | 156 v 157Render page, execute scripts within all the constraints above 158``` 159 160Five rules govern the system: 161 1621. **Stack the layers.** Even if your CSP is bulletproof, set HSTS so the connection cannot be downgraded. Even if HSTS is set, set CSP so XSS cannot execute. The point is overlap. 1632. **Restrict by default, allow by exception.** Every header should start with the most restrictive policy that works. Expand only when a specific feature requires it. 1643. **Test in Report-Only first.** CSP and CORP/COEP/COOP can break sites in subtle ways. Roll out in report only mode, monitor violations for at least a week, then enforce. 1654. **HSTS preload is one way.** Submitting to the preload list is reversible but takes months. Test thoroughly before submitting. 1665. **The `add_header` inheritance trap applies to every security header.** Any `add_header` in a location block wipes parent declarations. Use the snippet include pattern from the start. 167 168A correctly configured security header stack produces an A+ rating on observatory.mozilla.org and securityheaders.com, blocks XSS even if attackers find an injection vector, prevents clickjacking, prevents transport downgrade, controls capability abuse, and isolates the origin from cross origin attacks. The same response, the same protection, every visitor. 169 170--- 171 172## 5. STRICT-TRANSPORT-SECURITY (HSTS, TRANSPORT SECURITY) 173 174### 5.1 What It Does 175 176`Strict-Transport-Security` (HSTS) instructs the browser to access this origin only over HTTPS for a specified duration, ignoring any user attempt to use HTTP and refusing to bypass certificate errors. Defined in RFC 6797. 177 178``` 179Strict-Transport-Security: max-age=31536000 180Strict-Transport-Security: max-age=31536000; includeSubDomains 181Strict-Transport-Security: max-age=63072000; includeSubDomains; preload 182``` 183 184The first time a browser receives the header over HTTPS, it remembers the origin and the max-age. Every subsequent attempt to visit `http://example.com/...` is automatically upgraded to `https://` before the request leaves the browser. Certificate validation errors cannot be clicked through. This prevents downgrade attacks (active man in the middle stripping HTTPS) and stops accidental HTTP requests from leaking anything sensitive. 185 186HSTS only applies to subsequent visits. The very first visit to a new origin is still vulnerable to a downgrade. The **preload list** solves this: browsers ship with a hardcoded list of origins that have HSTS pre activated, so even the first visit is HTTPS only. 187 188### 5.2 Directives 189 190| Directive | Meaning | 191|---|---| 192| `max-age=<seconds>` | How long the browser remembers HSTS for this origin. Required. Common values: `0` (disable), `86400` (1 day, for testing), `2592000` (30 days), `31536000` (1 year), `63072000` (2 years, recommended for preload) | 193| `includeSubDomains` | HSTS applies to every subdomain. Required for preload list. Once enabled with a long max-age, every subdomain must serve HTTPS or it becomes inaccessible | 194| `preload` | Signals consent to be included in the browser preload list. Required for preload list submission. Without preload directive, the preload list submission is rejected | 195 196### 5.3 The Preload List (Permanent Consequences Warning) 197 198The HSTS preload list is maintained by the Chromium project and used by Chrome, Edge, Firefox, Safari, Opera, and Brave. To submit a domain: 199 2001. Serve HSTS on the apex domain over HTTPS with `max-age >= 31536000`, `includeSubDomains`, and `preload`. 2012. Every HTTP request must redirect to HTTPS via 301. 2023. Every subdomain (now and in the future, including `mail.`, `admin.`, `dev.`, `staging.`) must serve HTTPS with a valid certificate. 2034. Submit at https://hstspreload.org/. 2045. Wait weeks to months for inclusion in the next browser release. 205 206**Permanent consequences:** 207 208* Removal takes months after request and is not guaranteed within that timeframe. 209* If any subdomain serves only HTTP after preload, that subdomain is **permanently inaccessible** to every browser that has the preload list cached. 210* Adding a new subdomain that only does HTTP requires a TLS certificate from day one. 211* Internal subdomains used by employees (admin tools, dev environments, monitoring) become inaccessible without HTTPS. 212 213**Bubbles policy:** preload list submission is appropriate for established client production domains. It is **not appropriate** for `thatwebhostingguy.com` (the wildcard subdomain platform) because that platform spins up new subdomains constantly and not all may be production ready. For `thatwebhostingguy.com` use long max-age and includeSubDomains but skip preload. 214 215### 5.4 The Ramp Up Strategy 216 217Do not deploy long max-age HSTS on day one. If something breaks, every browser that visited during that window is locked into the broken state for the full max-age duration. Ramp up: 218 219``` 220# Week 1: testing only 221Strict-Transport-Security: max-age=86400 222 223# Week 2 to 4: short commitment 224Strict-Transport-Security: max-age=2592000; includeSubDomains 225 226# Month 2: medium commitment 227Strict-Transport-Security: max-age=15768000; includeSubDomains 228 229# Month 3+: full commitment, ready for preload 230Strict-Transport-Security: max-age=63072000; includeSubDomains; preload 231``` 232 233At each stage, verify every subdomain works over HTTPS, every internal tool still loads, and there are no certificate issues. Move to the next stage only after the current max-age has fully elapsed. 234 235### 5.5 How To Build It On Bubbles 236 237For an established production site already on HTTPS: 238 239```nginx 240server { 241 listen 443 ssl; 242 listen [::]:443 ssl; 243 http2 on; 244 server_name example.com www.example.com; 245 246 ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; 247 ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; 248 249 # HSTS: 2 years, all subdomains, preload list eligible 250 add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always; 251} 252 253# HTTP server redirects to HTTPS 254server { 255 listen 80; 256 listen [::]:80; 257 server_name example.com www.example.com; 258 return 301 https://$host$request_uri; 259} 260``` 261 262**Critical:** HSTS must be sent ONLY on HTTPS responses. Sending HSTS on an HTTP response is per the spec ignored, but it indicates the server is confused. The HTTP server block above does not include `add_header Strict-Transport-Security`. 263 264For a new site rolling out HSTS for the first time: 265 266```nginx 267# Week 1: short max-age, no preload 268add_header Strict-Transport-Security "max-age=86400" always; 269``` 270 271After verifying everything works, progress through the stages in Section 5.4. 272 273For `thatwebhostingguy.com` wildcard platform (no preload): 274 275```nginx 276server { 277 listen 443 ssl; 278 server_name *.thatwebhostingguy.com thatwebhostingguy.com; 279 add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always; 280 # No preload directive 281} 282``` 283 284### 5.6 How To Verify 285 286```bash 287# 1. Confirm HSTS is sent on HTTPS 288curl -sI https://example.com/ | grep -i strict-transport-security 289# Expected: strict-transport-security: max-age=63072000; includeSubDomains; preload 290 291# 2. Confirm HSTS is NOT sent on HTTP (should be a 301 instead) 292curl -sI http://example.com/ | grep -iE "strict-transport-security|^HTTP|^Location" 293# Expected: HTTP/1.1 301 Moved Permanently 294# Expected: Location: https://example.com/ 295# Expected: NO strict-transport-security header 296 297# 3. Check max-age is at least 1 year (for preload eligibility) 298MAX_AGE=$(curl -sI https://example.com/ | grep -i strict-transport-security | grep -oE "max-age=[0-9]+" | cut -d= -f2) 299echo "max-age = $MAX_AGE seconds = $(echo "$MAX_AGE / 86400" | bc) days" 300 301# 4. Check preload status 302curl -s "https://hstspreload.org/api/v2/status?domain=example.com" | python3 -m json.tool 303 304# 5. Verify every subdomain serves HTTPS (required before preload) 305for sub in www mail admin dev staging api blog; do 306 echo "=== $sub.example.com ===" 307 curl -sI -m 5 "https://$sub.example.com/" 2>&1 | head -1 || echo "FAILED to connect" 308done 309 310# 6. Browser check: visit chrome://net-internals/#hsts and query example.com 311``` 312 313### 5.7 Troubleshooting 314 315**Symptom: HSTS preload submission rejected.** 316Causes: 3171. Missing `preload` directive in the header. Add it. 3182. Missing `includeSubDomains`. Add it. 3193. max-age under 31536000. Increase to at least 31536000. 3204. HTTP does not redirect to HTTPS, or redirects with 302 instead of 301. Fix the HTTP server block. 3215. A subdomain (including one you forgot about) serves only HTTP or has an invalid certificate. Audit all subdomains. 322 323**Symptom: A subdomain became inaccessible after enabling HSTS with includeSubDomains.** 324That subdomain does not serve HTTPS. Either: 3251. Provision a TLS certificate for it immediately. 3262. Disable HSTS includeSubDomains (browsers will pick up the change on their next visit, but only after the current max-age expires). 3273. If you preloaded already, you must remove from the preload list (months long process) or stand up HTTPS for the broken subdomain. 328 329The right answer is almost always option 1: get the certificate. 330 331**Symptom: Old browsers refuse to accept new certificate after expiry.** 332This is HSTS working as designed. With HSTS active, expired or invalid certificates cannot be clicked through. The user must wait until the certificate is renewed or visit a different browser. 333 334For Bubbles: ensure `certbot.timer` is active and tested: 335 336```bash 337systemctl status certbot.timer 338sudo certbot renew --dry-run 339``` 340 341**Symptom: HSTS header appears on HTTP responses.** 342Wrong but harmless per the spec. Browsers ignore HSTS over HTTP. Fix by removing the `add_header` from the HTTP server block. The HTTP server block should only redirect, not set headers. 343 344**Symptom: Removed includeSubDomains but old browsers still enforce it.** 345Browsers honor the cached value for the original max-age duration. The fix is to wait, or to issue a new header with `max-age=0` for a few days, which clears the HSTS state, then re enable with the desired (more permissive) configuration. 346 347### 5.8 How To Fix Common Breakage 348 349**Case: Need to roll back HSTS quickly.** 350Set max-age to 0: 351 352```nginx 353add_header Strict-Transport-Security "max-age=0" always; 354``` 355 356Browsers that revisit pick up the new value and clear their stored HSTS state. Browsers that do not revisit retain the old value until it expires naturally. 357 358If preloaded, max-age=0 alone is insufficient. You must also remove from the preload list, which takes months. 359 360**Case: Subdomain forgotten during preload, now inaccessible.** 361Add HTTPS to the subdomain immediately: 362 363```bash 364sudo certbot --nginx -d forgotten.example.com 365``` 366 367This is faster than removing from the preload list. 368 369**Case: Want to test HSTS without committing.** 370Use the `Strict-Transport-Security-Report-Only` header. Note: this is a draft proposal, not widely supported. Better strategy: use a short max-age (86400 = 1 day) during testing and observe via browser devtools. 371 372--- 373 374## 6. CONTENT-SECURITY-POLICY (THE BIGGEST LEVER, SCRIPT AND RESOURCE CONTROL) 375 376### 6.1 What It Does 377 378`Content-Security-Policy` (CSP) is a declarative allow list of where the browser may load resources from. Defined in W3C CSP Level 3. It controls which scripts may execute, which styles may load, which images and fonts may be fetched, which origins may be embedded in frames, and many other resource boundaries. CSP is the single most effective defense against XSS, the most common web vulnerability class. 379 380``` 381Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-aBc123Xyz' 'strict-dynamic'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; frame-ancestors 'none'; base-uri 'self'; form-action 'self' 382``` 383 384A response with this CSP would: load resources only from same origin by default; allow scripts from same origin AND any inline script with the matching nonce; allow trust to propagate through dynamic script loading; allow same origin styles plus inline styles; allow images from same origin, data URLs, and any HTTPS origin; refuse to be embedded in any frame; restrict `<base>` to same origin; restrict form submission targets to same origin. 385 386CSP is the most powerful and most complex header in this framework. The configuration is per site and almost never trivially copyable between sites. Each origin needs a CSP tuned to its actual resource graph. 387 388### 6.2 Directives 389 390The full directive reference. Each directive controls a resource type or a security behavior. 391 392**Fetch directives (control resource loading by type):** 393 394| Directive | Controls | 395|---|---| 396| `default-src` | Fallback for any fetch directive not explicitly set. Default for all others | 397| `script-src` | JavaScript files and inline scripts | 398| `script-src-elem` | JavaScript loaded via `<script>` elements (more specific than script-src) | 399| `script-src-attr` | Inline event handlers like `onclick=`. Should always be `'none'` | 400| `style-src` | CSS files and inline styles | 401| `style-src-elem` | CSS via `<link>` and `<style>` | 402| `style-src-attr` | Inline `style=` attributes | 403| `img-src` | Images | 404| `font-src` | Web fonts | 405| `connect-src` | XHR, fetch(), WebSocket, EventSource, sendBeacon targets | 406| `media-src` | `<audio>` and `<video>` sources | 407| `object-src` | `<object>`, `<embed>`, `<applet>`. Should always be `'none'` | 408| `frame-src` | `<iframe>` and `<frame>` sources | 409| `child-src` | Worker and frame sources (deprecated; use frame-src and worker-src) | 410| `worker-src` | Web Workers, Shared Workers, Service Workers | 411| `manifest-src` | PWA manifest URL | 412| `prefetch-src` | Prefetched resources (deprecated, removed from spec) | 413 414**Document directives (control page properties):** 415 416| Directive | Controls | 417|---|---| 418| `base-uri` | What `<base href="...">` may set as the base URL. Should always be `'self'` or `'none'` | 419| `sandbox` | Apply iframe sandbox restrictions to the document itself | 420 421**Navigation directives:** 422 423| Directive | Controls | 424|---|---| 425| `form-action` | URLs that forms may submit to | 426| `frame-ancestors` | What origins may embed this page in a frame (replaces X-Frame-Options) | 427 428**Reporting:** 429 430| Directive | Controls | 431|---|---| 432| `report-uri <url>` | URL to send violation reports (legacy) | 433| `report-to <group>` | Reporting API group to send violation reports (modern) | 434 435**Trusted Types:** 436 437| Directive | Controls | 438|---|---| 439| `require-trusted-types-for 'script'` | Requires Trusted Types for DOM XSS sinks | 440| `trusted-types <policy-name>` | Allow listed Trusted Types policies | 441 442### 6.3 Source Values 443 444What can appear inside a directive's value list: 445 446| Value | Meaning | 447|---|---| 448| `'self'` | Same origin (scheme, host, port match) | 449| `'none'` | Nothing allowed | 450| `'unsafe-inline'` | Allow inline scripts and styles. Bypasses most XSS protection. **Avoid** | 451| `'unsafe-eval'` | Allow `eval()`, `setTimeout(string)`, `new Function()`. **Avoid** | 452| `'unsafe-hashes'` | Allow inline event handlers if they match a hash. Niche | 453| `'strict-dynamic'` | Trust propagates from nonce'd/hash'd scripts to scripts they load. The modern best practice | 454| `'nonce-<base64>'` | Allow inline scripts/styles that have this nonce attribute | 455| `'sha256-<base64>'` | Allow inline scripts/styles whose content hashes to this value | 456| `https:` | Any HTTPS origin | 457| `http:` | Any HTTP origin | 458| `data:` | Data URLs (`data:image/png;base64,...`). For images and fonts; **never** for scripts | 459| `blob:` | Blob URLs | 460| `filesystem:` | Filesystem URLs | 461| `mediastream:` | MediaStream URLs | 462| `https://example.com` | Specific origin | 463| `https://*.example.com` | Wildcard host | 464| `https://example.com:8443` | Specific port | 465| `*` | Any origin (use sparingly) | 466 467### 6.4 The Nonce Plus strict-dynamic Pattern (Modern Best Practice) 468 469The single most important CSP pattern in 2026 is `nonce + 'strict-dynamic'` for script-src. It solves the impossible problem of allowing legitimate inline scripts (GTM bootstrap, analytics, custom inline data) without allowing arbitrary attacker injected scripts. 470 471How it works: 472 4731. Server generates a fresh random nonce per response (e.g. 16 random bytes base64 encoded). 4742. Server includes the nonce in the CSP header: `script-src 'nonce-aBc123XyZ' 'strict-dynamic'`. 4753. Server emits inline scripts with the matching nonce attribute: `<script nonce="aBc123XyZ">...</script>`. 4764. Browser allows these scripts. Attacker injected scripts (which do not know the nonce) are blocked. 4775. `'strict-dynamic'` means: any script loaded by a nonce'd script is also trusted, recursively. So GTM (nonce'd) can inject its tags without you having to list every Google domain. 478 479Implementation requires generating the nonce server side. Nginx alone cannot do this; you need a sidecar (FastAPI, Lua via OpenResty, or similar) to inject a fresh nonce into both the header and the HTML body. 480 481FastAPI sidecar example: 482 483```python 484import secrets 485import base64 486from fastapi import FastAPI, Request 487from fastapi.responses import HTMLResponse 488 489app = FastAPI() 490 491@app.get("/") 492async def index(request: Request): 493 nonce = base64.b64encode(secrets.token_bytes(16)).decode() 494 html = f''' 495 <!DOCTYPE html> 496 <html lang="en-US"> 497 <head> 498 <meta charset="utf-8"> 499 <title>Example</title> 500 <script nonce="{nonce}"> 501 // GTM bootstrap with nonce 502 (function(w,d,s,l,i){{w[l]=w[l]||[];w[l].push({{'gtm.start': 503 new Date().getTime(),event:'gtm.js'}});var f=d.getElementsByTagName(s)[0], 504 j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= 505 'https://www.googletagmanager.com/gtm.js?id='+i+dl;j.setAttribute('nonce','{nonce}'); 506 f.parentNode.insertBefore(j,f);}})(window,document,'script','dataLayer','GTM-PM56NF52'); 507 </script> 508 </head> 509 <body>...</body> 510 </html> 511 ''' 512 513 csp = ( 514 f"default-src 'self'; " 515 f"script-src 'nonce-{nonce}' 'strict-dynamic' https: 'unsafe-inline'; " 516 f"style-src 'self' 'unsafe-inline'; " 517 f"img-src 'self' data: https:; " 518 f"font-src 'self'; " 519 f"connect-src 'self' https://*.google-analytics.com https://*.googletagmanager.com; " 520 f"frame-ancestors 'none'; " 521 f"base-uri 'self'; " 522 f"form-action 'self'; " 523 f"object-src 'none'; " 524 f"upgrade-insecure-requests" 525 ) 526 527 return HTMLResponse( 528 content=html, 529 headers={"Content-Security-Policy": csp} 530 ) 531``` 532 533The `'unsafe-inline'` plus `https:` after the nonce is a backward compatibility fallback: older browsers that do not understand `'strict-dynamic'` (none in 2026, but defense in depth) fall back to those values. Browsers that understand `'strict-dynamic'` ignore them. This is the documented pattern from web.dev/strict-csp. 534 535### 6.5 Static Sites Without Server Side Nonce Generation 536 537Pure static sites (no FastAPI sidecar) cannot generate nonces. Three alternatives: 538 539**1. Hash based CSP for known inline scripts.** Compute the SHA256 hash of each inline script at build time, embed the hashes in the CSP header. Only works if scripts never change. GTM does not work this way because its content changes. 540 541```nginx 542add_header Content-Security-Policy "script-src 'self' 'sha256-LjyKKKsXNcXyTtUH3GcRbE2QEm2X3MfFs6ZkPHfZQiM=' https://www.googletagmanager.com" always; 543``` 544 545**2. Origin allow list for everything.** Less secure but simpler to maintain. 546 547```nginx 548add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' https://www.googletagmanager.com https://www.google-analytics.com" always; 549``` 550 551This is what most Bubbles static sites use. `'unsafe-inline'` is not ideal but acceptable given the controlled content of the site. 552 553**3. Move dynamic responses to the FastAPI sidecar.** Pages that need nonce based CSP (logged in areas, dashboards) go through the sidecar; static marketing pages use origin allow list CSP. 554 555### 6.6 Report-Only Mode (Mandatory For First Deploy) 556 557The `Content-Security-Policy-Report-Only` header has identical syntax to `Content-Security-Policy` but does not enforce. Violations are reported to the configured endpoint but resources still load. This is mandatory for the first deploy of any new CSP: it surfaces every violation without breaking the site. 558 559```nginx 560# Report-only during testing 561add_header Content-Security-Policy-Report-Only "default-src 'self'; script-src 'self' 'unsafe-inline'; report-uri /csp-report" always; 562 563location = /csp-report { 564 proxy_pass http://127.0.0.1:9090; 565} 566``` 567 568The FastAPI sidecar receives reports as `application/csp-report` content type: 569 570```python 571@app.post("/csp-report") 572async def csp_report(request: Request): 573 report = await request.json() 574 logging.warning(f"CSP violation: {report}") 575 return Response(status_code=204) 576``` 577 578After at least a week of monitoring with zero unexpected violations, switch from `Content-Security-Policy-Report-Only` to `Content-Security-Policy` (the enforcing variant) and the policy goes live. 579 580### 6.7 The frame-ancestors Directive (Replaces X-Frame-Options) 581 582`frame-ancestors` controls which origins may embed this page in an iframe. It supersedes `X-Frame-Options` and is more flexible (supports multiple origins, wildcards, etc). 583 584``` 585Content-Security-Policy: frame-ancestors 'none' 586Content-Security-Policy: frame-ancestors 'self' 587Content-Security-Policy: frame-ancestors https://partner.example.com 588Content-Security-Policy: frame-ancestors 'self' https://*.example.com 589``` 590 591| Value | Meaning | 592|---|---| 593| `'none'` | No embedding allowed (equivalent to X-Frame-Options: DENY) | 594| `'self'` | Only same origin embedding (equivalent to X-Frame-Options: SAMEORIGIN) | 595| `https://example.com` | Only this specific origin | 596| `https://*.example.com` | Any subdomain of example.com | 597 598Modern browsers respect `frame-ancestors` over `X-Frame-Options` when both are present and conflict. Best practice: set both for belt and suspenders. 599 600### 6.8 The upgrade-insecure-requests Directive 601 602``` 603Content-Security-Policy: upgrade-insecure-requests 604``` 605 606Tells the browser to automatically upgrade any `http://` resource references in the page to `https://`. Useful for fixing mixed content during a slow HTTPS migration. Once all content is on HTTPS, this directive is harmless and can be left in place. 607 608### 6.9 How To Build It On Bubbles 609 610**Minimal CSP for static Bubbles site without third party scripts:** 611 612```nginx 613add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; frame-ancestors 'none'; base-uri 'self'; form-action 'self'; object-src 'none'; upgrade-insecure-requests" always; 614``` 615 616This is locked down. No third party resources. Only inline styles are allowed (which most templates need for theme injection). No inline scripts. 617 618**Standard Bubbles CSP with GTM, GA4, and common third parties:** 619 620```nginx 621add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' https://www.googletagmanager.com https://www.google-analytics.com https://www.googleadservices.com https://googleads.g.doubleclick.net https://connect.facebook.net; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; img-src 'self' data: https: blob:; font-src 'self' data: https://fonts.gstatic.com; connect-src 'self' https://*.google-analytics.com https://*.analytics.google.com https://*.googletagmanager.com https://www.facebook.com; frame-src 'self' https://www.googletagmanager.com https://www.google.com; frame-ancestors 'none'; base-uri 'self'; form-action 'self'; object-src 'none'; upgrade-insecure-requests" always; 622``` 623 624This is the typical Bubbles production CSP. Allows all the common analytics and tag manager domains. Still blocks `object-src` and `frame-ancestors`. 625 626**Strict CSP with nonce (requires FastAPI sidecar):** 627 628```nginx 629location / { 630 proxy_pass http://127.0.0.1:9090; 631 # CSP header is generated by the sidecar per request with a fresh nonce 632 # Nginx does not override 633} 634``` 635 636The sidecar emits the CSP header with the nonce, as shown in Section 6.4. 637 638**Report-Only deployment:** 639 640```nginx 641# First week: report only, see what breaks 642add_header Content-Security-Policy-Report-Only "default-src 'self'; script-src 'self' 'unsafe-inline' https://www.googletagmanager.com; report-uri /csp-report" always; 643 644# After validating: enforce 645# add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' https://www.googletagmanager.com; report-uri /csp-report" always; 646``` 647 648### 6.10 How To Verify 649 650```bash 651# 1. Confirm CSP is sent 652curl -sI https://example.com/ | grep -i content-security-policy 653 654# 2. Pretty print the directive list 655curl -sI https://example.com/ | grep -i content-security-policy | tr ';' '\n' | sed 's/^ */ /' 656 657# 3. Test in Chrome DevTools: 658# Open the site, open DevTools (F12), Console tab 659# Any CSP violations appear in red 660# Network tab: blocked resources show "blocked:csp" in Status 661 662# 4. Use external scanner 663echo "Visit: https://csp-evaluator.withgoogle.com/?csp=https://example.com/" 664 665# 5. Use observatory.mozilla.org 666echo "Visit: https://observatory.mozilla.org/analyze/example.com" 667 668# 6. Verify that 'strict-dynamic' is correctly understood (if used) 669# Look for 'strict-dynamic' in the CSP value 670curl -sI https://example.com/ | grep -i content-security-policy | grep -o "'strict-dynamic'" 671 672# 7. Test that a CSP violation is reported (for Report-Only) 673curl -sX POST https://example.com/csp-report \ 674 -H "Content-Type: application/csp-report" \ 675 -d '{"csp-report":{"document-uri":"https://example.com/","violated-directive":"script-src","blocked-uri":"https://evil.com/script.js"}}' 676# Should return 204 No Content 677``` 678 679### 6.11 Troubleshooting 680 681**Symptom: GTM not loading; console shows "Refused to execute inline script".** 682Cause: CSP `script-src` does not allow GTM's inline bootstrap or its loaded scripts. 683Fix: add `https://www.googletagmanager.com https://www.google-analytics.com` to script-src. If using strict CSP, ensure the GTM snippet has the matching nonce attribute. See Section 6.4. 684 685**Symptom: GA4 events not firing; no console errors but no data in GA.** 686Cause: CSP `connect-src` does not allow the GA endpoint. 687Fix: add `https://*.google-analytics.com https://*.analytics.google.com` to connect-src. Verify with Network tab in DevTools (look for blocked requests to `region1.google-analytics.com` or similar). 688 689**Symptom: External fonts not loading; falls back to system fonts.** 690Cause: CSP `font-src` does not allow the font origin. 691Fix: add the font origin (`https://fonts.gstatic.com` for Google Fonts) to font-src. 692 693**Symptom: Inline event handlers (`<button onclick="...">`) not working.** 694Cause: CSP blocks inline event handlers unless `'unsafe-inline'` or matching hash is allowed for script-src-attr. The modern recommendation is to move these to addEventListener calls in JavaScript. 695Fix: refactor inline handlers to use proper event listeners. Or add `script-src-attr 'unsafe-inline'` (less secure). 696 697**Symptom: Images displaying as broken links; console shows CSP block.** 698Cause: img-src does not allow the image origin. 699Fix: list the origin in img-src. For dynamic images from various CDNs, `img-src 'self' data: https:` is a common permissive value. 700 701**Symptom: Page works in development but breaks in production.** 702Cause: production CSP is stricter than development. Test environments often use permissive CSP for debugging. 703Fix: deploy in Report-Only mode first to surface every violation, fix them, then enforce. 704 705**Symptom: CSP report endpoint receiving millions of reports.** 706Causes: 7071. Browser extensions injecting content trigger spurious violations. Filter reports by `source-file` to exclude extension origins. 7082. A real ongoing XSS attack. Investigate immediately. 7093. A legitimate resource was missed in the policy. Add it. 710 711**Symptom: Header value exceeds size limit.** 712Large CSP with many origins can exceed default header size limits (8 KB nginx default). Either increase the limit: 713 714```nginx 715proxy_buffer_size 16k; 716proxy_buffers 8 16k; 717large_client_header_buffers 4 16k; 718``` 719 720Or simplify the CSP by using wildcards (`https://*.googleapis.com` instead of listing each subdomain). 721 722### 6.12 How To Fix Common Breakage 723 724**Case: GTM works in browser but CSP reports show violations from server side rendering.** 725The SSR pipeline does not include the nonce in script tags. Audit the template engine to ensure nonce attribute is injected on every inline script. 726 727**Case: Need to allow a third party script that loads other scripts dynamically.** 728Use `'strict-dynamic'` pattern (Section 6.4). The first script gets a nonce; any scripts it loads are trusted automatically. 729 730**Case: Site has hundreds of inline event handlers (legacy code).** 731Short term: add `'unsafe-inline'` to script-src-attr. Long term: refactor to addEventListener. 732 733**Case: CSP blocking legitimate AdSense scripts.** 734AdSense requires permissive CSP. The minimum directives needed: 735 736``` 737script-src 'self' 'unsafe-inline' https://pagead2.googlesyndication.com https://*.googleadservices.com https://*.googlesyndication.com https://*.doubleclick.net; 738img-src 'self' data: https:; 739frame-src https://googleads.g.doubleclick.net https://www.google.com; 740connect-src 'self' https://pagead2.googlesyndication.com https://*.googleadservices.com; 741``` 742 743AdSense's full domain list changes occasionally; monitor reports. 744 745**Case: Want to use SharedArrayBuffer but it is undefined.** 746Cross origin isolation required. Implement COEP plus COOP (Section 14). CSP alone does not enable SharedArrayBuffer. 747 748--- 749 750## 7. X-FRAME-OPTIONS (CLICKJACKING DEFENSE, MOSTLY SUPERSEDED BY CSP FRAME-ANCESTORS) 751 752### 7.1 What It Does 753 754`X-Frame-Options` controls whether the browser may render this page inside a `<frame>`, `<iframe>`, `<embed>`, or `<object>`. Defined in RFC 7034. Superseded by CSP `frame-ancestors` for new development, but still widely deployed and respected. 755 756``` 757X-Frame-Options: DENY 758X-Frame-Options: SAMEORIGIN 759``` 760 761The clickjacking attack: attacker creates a page with an invisible iframe pointing at your site, overlaid with decoy elements. User clicks what they think is a button on the attacker's page, actually clicks an authorized action on your site (transfer money, change settings, accept terms). `X-Frame-Options: DENY` prevents the iframe from rendering at all. 762 763### 7.2 Values 764 765| Value | Meaning | 766|---|---| 767| `DENY` | No site (including same origin) may embed this in a frame | 768| `SAMEORIGIN` | Only same origin pages may embed | 769| `ALLOW-FROM <uri>` | Deprecated. Only this specific origin may embed. Not supported in Chrome or Safari; use CSP frame-ancestors instead | 770 771### 7.3 Relationship to CSP frame-ancestors 772 773`frame-ancestors` (in CSP) is more capable. It supports: 774 775* Multiple origins (X-Frame-Options can list only one). 776* Wildcards. 777* Granular path control. 778* Modern browsers respect it over X-Frame-Options when both are present and conflict. 779 780**Bubbles policy:** set both. The redundancy costs nothing and protects against older browsers or misconfigured intermediaries. 781 782### 7.4 How To Build It On Bubbles 783 784For a site that should never be embedded: 785 786```nginx 787add_header X-Frame-Options "DENY" always; 788# CSP equivalent (set both) 789add_header Content-Security-Policy "frame-ancestors 'none'" always; 790``` 791 792For a site that may be embedded by same origin pages (most cases): 793 794```nginx 795add_header X-Frame-Options "SAMEORIGIN" always; 796add_header Content-Security-Policy "frame-ancestors 'self'" always; 797``` 798 799For a site that may be embedded by a specific partner: 800 801```nginx 802# X-Frame-Options cannot do this safely in modern browsers 803# Use CSP frame-ancestors only 804add_header Content-Security-Policy "frame-ancestors 'self' https://partner.example.com" always; 805``` 806 807The Bubbles default in `snippets/common-security-headers.conf`: 808 809```nginx 810add_header X-Frame-Options "SAMEORIGIN" always; 811``` 812 813The CSP equivalent is set in the per site CSP. 814 815### 7.5 How To Verify 816 817```bash 818# 1. Confirm X-Frame-Options is sent 819curl -sI https://example.com/ | grep -i x-frame-options 820# Expected: x-frame-options: SAMEORIGIN 821 822# 2. Test actual frame blocking 823# Create a test HTML file locally: 824cat > /tmp/clickjack-test.html << 'EOF' 825<html><body> 826 <h1>Clickjack test</h1> 827 <iframe src="https://example.com/" width="800" height="600"></iframe> 828</body></html> 829EOF 830 831# Open the file in a browser; the iframe should be blocked or empty 832 833# 3. Verify in DevTools Network tab: the framed request shows "X-Frame-Options block" in Console 834 835# 4. Confirm CSP frame-ancestors agrees 836curl -sI https://example.com/ | grep -i content-security-policy | grep -o "frame-ancestors [^;]*" 837``` 838 839### 7.6 Troubleshooting 840 841**Symptom: Legitimate iframe of own site is blocked.** 842X-Frame-Options is DENY. Change to SAMEORIGIN. 843 844**Symptom: Embedded partner integration blocked.** 845ALLOW-FROM is not supported in Chrome or Safari. Use CSP frame-ancestors instead and remove ALLOW-FROM. 846 847**Symptom: Scanner reports missing X-Frame-Options.** 848Header is not set. Add to common-security-headers.conf and reload. 849 850**Symptom: X-Frame-Options and frame-ancestors disagree.** 851Modern browsers honor frame-ancestors. Older browsers honor X-Frame-Options. Set both to consistent values to avoid version specific behavior. 852 853### 7.7 How To Fix Common Breakage 854 855**Case: Need to allow embedding from a partner site after launch.** 856Update CSP frame-ancestors (X-Frame-Options cannot list specific allowed origins): 857 858```nginx 859add_header Content-Security-Policy "... frame-ancestors 'self' https://partner.example.com; ..." always; 860# Keep X-Frame-Options for older browsers: 861add_header X-Frame-Options "SAMEORIGIN" always; 862``` 863 864The X-Frame-Options says "same origin or nothing" which is more restrictive than frame-ancestors allows, but modern browsers prefer frame-ancestors so the partner can embed. 865 866--- 867 868## 8. X-CONTENT-TYPE-OPTIONS (MIME SNIFFING PREVENTION) 869 870### 8.1 What It Does 871 872`X-Content-Type-Options: nosniff` tells the browser to treat the declared `Content-Type` header as authoritative and not attempt to guess (sniff) the content type from the body bytes. The only valid value is `nosniff`. Defined in WHATWG Fetch specification. 873 874``` 875X-Content-Type-Options: nosniff 876``` 877 878Without nosniff, the browser may sniff content. A response declared `text/plain` containing HTML and JavaScript may be sniffed as HTML and rendered, executing the JavaScript. This is the basis of the user upload XSS attack class discussed in framework-http-content-headers.md Section 9.5. 879 880With nosniff, declared types are honored. A file declared `text/plain` is displayed as text even if the body contains executable HTML. 881 882### 8.2 Why It Is Always Set To nosniff 883 884The header has effectively one purpose: enable nosniff. There is no situation in 2026 where you want MIME sniffing. Always set: 885 886``` 887X-Content-Type-Options: nosniff 888``` 889 890### 8.3 How To Build It On Bubbles 891 892In the shared security header snippet: 893 894```nginx 895# /etc/nginx/snippets/common-security-headers.conf 896add_header X-Content-Type-Options "nosniff" always; 897``` 898 899Included in every location across the Bubbles fleet. 900 901### 8.4 How To Verify 902 903```bash 904# Confirm header is present on every response 905curl -sI https://example.com/ | grep -i x-content-type-options 906# Expected: x-content-type-options: nosniff 907 908# Check across asset types 909for path in / /css/main.css /js/app.js /images/logo.png /downloads/file.pdf; do 910 HEADER=$(curl -sI "https://example.com$path" 2>/dev/null | grep -i x-content-type-options) 911 echo "$path: $HEADER" 912done 913 914# Verify behavior with a deliberately misdeclared file 915# (Test only on a non production site) 916# Create a .txt file containing HTML 917echo '<script>alert("test")</script>' > /var/www/sites/test.example.com/test.txt 918curl -sI https://test.example.com/test.txt | grep -iE "content-type|x-content-type-options" 919# Should show: content-type: text/plain 920# Should show: x-content-type-options: nosniff 921# Browser should display the text, NOT execute the script 922``` 923 924### 8.5 Troubleshooting 925 926**Symptom: Stored XSS via uploaded HTML file.** 927nosniff is missing OR Content-Type is wrong (declared as `text/html` when it should be `application/octet-stream` for downloads). 928Fix: ensure nosniff is set site wide, ensure user uploads are served with `Content-Type: application/octet-stream` and `Content-Disposition: attachment` (see framework-http-content-headers.md Section 9.5). 929 930**Symptom: Old browsers ignoring nosniff.** 931Internet Explorer and very old browsers had inconsistent nosniff support. Not a concern in 2026. 932 933**Symptom: Header missing on some file types.** 934The `add_header` inheritance trap. A location block redeclared headers without including the snippet. Audit: 935 936```bash 937nginx -T 2>/dev/null | grep -B5 "add_header" | grep -B1 "x-content-type-options" | head -50 938``` 939 940### 8.6 How To Fix Common Breakage 941 942**Case: Pen tester reports missing nosniff on some endpoints.** 943Add `include snippets/common-security-headers.conf` to every location that redeclares any add_header. 944 945**Case: A specific file needs sniffing for legacy reasons.** 946This is an antipattern. Fix the underlying Content-Type instead. nosniff should never be removed. 947 948--- 949 950## 9. REFERRER-POLICY (OUTBOUND URL PRIVACY) 951 952### 9.1 What It Does 953 954`Referrer-Policy` controls how much of the current URL (the referrer) is included in the `Referer` HTTP header on outbound requests (links, images, scripts, fetch). Defined in W3C Referrer Policy spec. Critical for privacy because URLs often contain session tokens, password reset codes, search queries, and other sensitive data. 955 956``` 957Referrer-Policy: strict-origin-when-cross-origin 958Referrer-Policy: no-referrer 959Referrer-Policy: same-origin 960``` 961 962The default browser behavior (when no header is set) varies by browser, but most modern browsers default to `strict-origin-when-cross-origin` since 2020. Setting the header explicitly removes the ambiguity. 963 964### 9.2 The Eight Values 965 966| Value | Meaning | 967|---|---| 968| `no-referrer` | Never send Referer. Maximum privacy. Some analytics break | 969| `no-referrer-when-downgrade` | Send full URL except when going from HTTPS to HTTP. Legacy default | 970| `origin` | Send only the origin (`https://example.com`), no path or query | 971| `origin-when-cross-origin` | Send full URL same origin, origin only cross origin | 972| `same-origin` | Send full URL same origin, nothing cross origin | 973| `strict-origin` | Send origin only, except when HTTPS to HTTP (nothing) | 974| `strict-origin-when-cross-origin` | Full URL same origin, origin cross origin, nothing HTTPS to HTTP. **Modern default and recommendation** | 975| `unsafe-url` | Always send full URL. Maximum leakage. Never use | 976 977### 9.3 Why strict-origin-when-cross-origin Is The Right Default 978 979The default value chosen by modern browsers and recommended by web.dev: 980 981* Within your own origin, full URL is sent (useful for analytics and internal tracking). 982* To other HTTPS origins, only your origin is sent (no path, no query, no token leakage). 983* To HTTP origins, nothing is sent (no transport downgrade leakage). 984 985For most sites this is correct. For sites that want even more privacy (e.g. anything healthcare related, anything with strong PII), use `same-origin` (nothing cross origin) or `no-referrer` (nothing ever). 986 987### 9.4 How To Build It On Bubbles 988 989In the shared security header snippet: 990 991```nginx 992# /etc/nginx/snippets/common-security-headers.conf 993add_header Referrer-Policy "strict-origin-when-cross-origin" always; 994``` 995 996For a healthcare or HIPAA aware site, increase to `same-origin`: 997 998```nginx 999add_header Referrer-Policy "same-origin" always; 1000``` 1001 1002For specific high sensitivity pages (password reset, account settings): 1003 1004```nginx 1005location ~ ^/(account|password-reset|verify) { 1006 include snippets/common-security-headers.conf; 1007 add_header Referrer-Policy "no-referrer" always; 1008} 1009``` 1010 1011### 9.5 How To Verify 1012 1013```bash 1014# 1. Confirm header is present 1015curl -sI https://example.com/ | grep -i referrer-policy 1016# Expected: referrer-policy: strict-origin-when-cross-origin 1017 1018# 2. Test actual referrer behavior 1019# Visit your site, click an external link, check the destination's logs 1020# Or use https://httpbin.org/headers as the click target 1021echo "Visit your site, click a link to https://httpbin.org/headers" 1022echo "Check the 'Referer' header in the response" 1023 1024# 3. Verify per page override works 1025curl -sI https://example.com/account | grep -i referrer-policy 1026``` 1027 1028### 9.6 Troubleshooting 1029 1030**Symptom: Analytics platform shows zero referrer data.** 1031Referrer-Policy is set to `no-referrer` or `same-origin`, which is correctly preventing referrer from leaving the origin. 1032Fix: this is by design. If analytics needs cross origin referrer, change to `strict-origin-when-cross-origin` (origin only) or accept the privacy tradeoff. 1033 1034**Symptom: Password reset URL with token appearing in third party logs.** 1035Referrer-Policy not set, or set to `unsafe-url` or `no-referrer-when-downgrade`. The full URL including the token is being leaked. 1036Fix: set to `strict-origin-when-cross-origin` site wide, or to `no-referrer` on the password reset endpoint specifically. 1037 1038**Symptom: Affiliate tracking does not record source.** 1039Affiliate tracking systems rely on the Referer header. If your site sets `no-referrer`, the affiliate link's tracking pixel cannot identify the source. 1040Fix: discuss tradeoffs. The affiliate cannot get full URL data; they can get origin. `strict-origin-when-cross-origin` is the compromise. 1041 1042### 9.7 How To Fix Common Breakage 1043 1044**Case: Need to allow third party affiliates to know which page sent traffic.** 1045Use `origin` or `strict-origin-when-cross-origin`. The affiliate sees your domain but not the specific page. 1046 1047**Case: Want to leak nothing across origins for compliance reasons.** 1048Use `same-origin`. Combine with explicit click handling for affiliate tracking (passing source data in URL parameters rather than relying on Referer). 1049 1050--- 1051 1052## 10. PERMISSIONS-POLICY (BROWSER CAPABILITY CONTROL) 1053 1054### 10.1 What It Does 1055 1056`Permissions-Policy` controls which browser APIs and features may be used on this page, including by third party iframes and scripts. Replaces the older `Feature-Policy` header (same purpose, different syntax). Defined in W3C Permissions Policy spec. 1057 1058``` 1059Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=() 1060Permissions-Policy: geolocation=(self), camera=(self "https://video.example.com") 1061``` 1062 1063The header tells the browser: "even if a script on this page tries to access the camera, refuse unless explicitly allowed". This protects users from third party scripts (analytics, ads, social widgets) silently activating sensitive APIs. 1064 1065### 10.2 Syntax 1066 1067The header value is a comma separated list of directives. Each directive has the form `feature=(<allowlist>)`. The allowlist is a space separated list of origins or special values inside parentheses. 1068 1069``` 1070Permissions-Policy: camera=(), microphone=(self), geolocation=(self "https://maps.example.com") 1071``` 1072 1073Allowlist values: 1074 1075| Value | Meaning | 1076|---|---| 1077| `()` (empty) | Feature disabled everywhere | 1078| `(self)` | Feature allowed only in this document and same origin iframes | 1079| `(*)` | Feature allowed everywhere including cross origin iframes | 1080| `("https://example.com")` | Feature allowed in this origin | 1081| `(self "https://example.com")` | Same origin plus the specified origin | 1082 1083### 10.3 Common Directives 1084 1085The full list is large and growing. Most commonly configured: 1086 1087**Privacy sensitive APIs (lock down by default):** 1088 1089| Directive | Controls | 1090|---|---| 1091| `camera` | Camera access (getUserMedia) | 1092| `microphone` | Microphone access (getUserMedia) | 1093| `geolocation` | Geolocation API | 1094| `payment` | Payment Request API | 1095| `usb` | WebUSB API | 1096| `bluetooth` | Web Bluetooth API | 1097| `serial` | Web Serial API | 1098| `hid` | WebHID API | 1099| `midi` | Web MIDI API | 1100| `magnetometer` | Magnetometer sensor | 1101| `gyroscope` | Gyroscope sensor | 1102| `accelerometer` | Accelerometer sensor | 1103| `ambient-light-sensor` | Ambient light sensor | 1104 1105**Browser features (selectively enable):** 1106 1107| Directive | Controls | 1108|---|---| 1109| `fullscreen` | requestFullscreen() | 1110| `picture-in-picture` | Picture in Picture API | 1111| `autoplay` | Video and audio autoplay | 1112| `clipboard-read` | Clipboard read API | 1113| `clipboard-write` | Clipboard write API | 1114| `notifications` | Web Notifications | 1115| `push` | Push API | 1116| `screen-wake-lock` | Screen Wake Lock API | 1117 1118**Privacy and tracking (block these):** 1119 1120| Directive | Controls | 1121|---|---| 1122| `interest-cohort` | FLoC (deprecated). Set to `()` to opt out historically | 1123| `browsing-topics` | Topics API (FLoC's replacement). Set to `()` to opt out of tracking cohort calculation | 1124| `attribution-reporting` | Attribution Reporting API | 1125| `join-ad-interest-group` | Protected Audience API (FLEDGE) | 1126| `run-ad-auction` | Protected Audience API (FLEDGE) | 1127| `private-aggregation` | Private Aggregation API | 1128 1129**Performance:** 1130 1131| Directive | Controls | 1132|---|---| 1133| `unload` | Allow `unload` event handlers. Setting `()` blocks them, which improves bfcache eligibility and Core Web Vitals | 1134| `sync-xhr` | Synchronous XMLHttpRequest. Setting `()` blocks (recommended) | 1135| `cross-origin-isolated` | Whether the document may be cross origin isolated | 1136 1137### 10.4 The Bubbles Baseline 1138 1139For a typical Bubbles site that does not need camera, mic, or other sensitive APIs: 1140 1141```nginx 1142add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=(), bluetooth=(), serial=(), hid=(), midi=(), magnetometer=(), gyroscope=(), accelerometer=(), ambient-light-sensor=(), browsing-topics=(), interest-cohort=()" always; 1143``` 1144 1145This: 1146 1147* Disables every sensitive device API. 1148* Opts out of FLoC and Topics tracking cohorts. 1149* Leaves general browser features (fullscreen, autoplay, notifications) at default permissive. 1150 1151For a site that uses some features (e.g. video conferencing): 1152 1153```nginx 1154add_header Permissions-Policy "camera=(self), microphone=(self), display-capture=(self), geolocation=(), payment=(), usb=(), bluetooth=()" always; 1155``` 1156 1157For maximum lockdown plus performance optimization: 1158 1159```nginx 1160add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=(), bluetooth=(), browsing-topics=(), interest-cohort=(), unload=(), sync-xhr=()" always; 1161``` 1162 1163### 10.5 How To Build It On Bubbles 1164 1165In the shared security header snippet: 1166 1167```nginx 1168# /etc/nginx/snippets/common-security-headers.conf 1169add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=(), bluetooth=(), browsing-topics=(), interest-cohort=()" always; 1170``` 1171 1172For specific sites with different needs (medical practice using video conferencing, etc), override at the server level: 1173 1174```nginx 1175server { 1176 server_name telehealth.example.com; 1177 1178 # Standard headers minus permissions, since we override 1179 include snippets/common-security-headers-no-permissions.conf; 1180 add_header Permissions-Policy "camera=(self), microphone=(self), display-capture=(self), geolocation=(), payment=(), usb=(), bluetooth=()" always; 1181} 1182``` 1183 1184### 10.6 How To Verify 1185 1186```bash 1187# 1. Confirm header is present 1188curl -sI https://example.com/ | grep -i permissions-policy 1189 1190# 2. Pretty print 1191curl -sI https://example.com/ | grep -i permissions-policy | tr ',' '\n' | sed 's/^ */ /' 1192 1193# 3. Test a blocked API in browser console (DevTools): 1194# navigator.geolocation.getCurrentPosition(p => console.log(p), e => console.error(e)) 1195# Should show error like "Geolocation is blocked by permissions policy" 1196 1197# 4. Check via observatory.mozilla.org or securityheaders.com 1198echo "Visit: https://securityheaders.com/?q=https://example.com/" 1199``` 1200 1201### 10.7 Troubleshooting 1202 1203**Symptom: Feature blocked unexpectedly.** 1204Cause: Permissions-Policy disables it. 1205Fix: add `(self)` or appropriate allowlist to the directive. 1206 1207**Symptom: Console warning "Error with Permissions-Policy header: Origin trial controlled feature not enabled: 'interest-cohort'".** 1208Cause: browser does not recognize `interest-cohort` (it was deprecated). The warning is harmless; the directive is ignored by browsers that do not implement it. 1209Fix: optionally remove `interest-cohort=()` from the header (Topics API replaced FLoC; use `browsing-topics=()`). 1210 1211**Symptom: Browser does not honor a third party iframe's request for camera.** 1212Cause: parent document's Permissions-Policy does not allow camera in cross origin iframes. 1213Fix: explicitly allow: `camera=(self "https://embedded.example.com")`. 1214 1215**Symptom: Header has wrong syntax (old Feature-Policy syntax).** 1216Old syntax: `camera 'none'; microphone 'self'`. New syntax: `camera=(), microphone=(self)`. 1217Fix: convert to new syntax. The two headers can coexist for older browsers but the new syntax is canonical. 1218 1219### 10.8 How To Fix Common Breakage 1220 1221**Case: Browser console warning about unknown Permissions-Policy feature.** 1222Browser does not recognize the feature name (maybe it is too new or too old). Unknown features are ignored, so the warning is harmless. To silence, remove the unknown feature. 1223 1224**Case: Need to allow geolocation on a specific page only.** 1225Override at the location: 1226 1227```nginx 1228location = /find-store { 1229 include snippets/common-security-headers-base.conf; 1230 add_header Permissions-Policy "geolocation=(self), camera=(), microphone=(), payment=(), usb=(), bluetooth=()" always; 1231} 1232``` 1233 1234**Case: Site uses Google Maps which requests geolocation.** 1235Allow geolocation for the Google Maps origin: 1236 1237```nginx 1238add_header Permissions-Policy 'geolocation=(self "https://maps.googleapis.com"), camera=(), microphone=(), payment=()' always; 1239``` 1240 1241--- 1242 1243## 11. CROSS-ORIGIN-RESOURCE-POLICY (CORP, WHO CAN LOAD THIS RESOURCE) 1244 1245### 11.1 What It Does 1246 1247`Cross-Origin-Resource-Policy` (CORP) is set on a resource (image, script, stylesheet, font, JSON) to tell the browser which origins are allowed to load it. Defined in the WHATWG Fetch spec. Part of the cross origin isolation pattern. 1248 1249``` 1250Cross-Origin-Resource-Policy: same-origin 1251Cross-Origin-Resource-Policy: same-site 1252Cross-Origin-Resource-Policy: cross-origin 1253``` 1254 1255CORP differs from CORS: 1256 1257* **CORS** allows a foreign origin to load your resource (you opt them in via response headers). 1258* **CORP** restricts who may load your resource (you opt out cross origin embedding by default). 1259 1260A resource with `Cross-Origin-Resource-Policy: same-origin` cannot be loaded by any other origin, even via `<img src>` or `<script src>`. This blocks Spectre style side channel attacks and resource theft. 1261 1262### 11.2 Values 1263 1264| Value | Meaning | 1265|---|---| 1266| `same-origin` | Only the exact same origin (scheme, host, port) may load this | 1267| `same-site` | Only the same site may load this (different subdomains OK, different sites not) | 1268| `cross-origin` | Any origin may load this (default behavior) | 1269 1270### 11.3 When To Set Each 1271 1272| Resource type | Recommended CORP | 1273|---|---| 1274| Private user content (logged in user's profile photo) | `same-origin` | 1275| Site brand assets used only on the main site | `same-origin` or `same-site` | 1276| Resources you want partner sites to embed (logos, badges) | `cross-origin` | 1277| Public CDN assets used by many sites (fonts, libraries) | `cross-origin` | 1278| Resources that must be loadable when the embedding site has COEP | `cross-origin` (or absent, but absent means the embedder might block via COEP) | 1279 1280### 11.4 How To Build It On Bubbles 1281 1282For private user content: 1283 1284```nginx 1285location /user-content/ { 1286 add_header Cross-Origin-Resource-Policy "same-origin" always; 1287} 1288``` 1289 1290For brand assets restricted to the main site: 1291 1292```nginx 1293location ~* \.(jpg|jpeg|png|webp|svg|woff2)$ { 1294 add_header Cross-Origin-Resource-Policy "same-site" always; 1295} 1296``` 1297 1298For publicly embeddable resources (badges, logos that partners may embed): 1299 1300```nginx 1301location /embed/ { 1302 add_header Cross-Origin-Resource-Policy "cross-origin" always; 1303} 1304``` 1305 1306The Bubbles default for a client site: `same-site` for all assets. This protects against hot linking and Spectre style attacks while allowing legitimate same site usage. 1307 1308### 11.5 How To Verify 1309 1310```bash 1311# 1. Confirm CORP is set 1312curl -sI https://example.com/images/logo.png | grep -i cross-origin-resource-policy 1313 1314# 2. Test that a cross origin embed fails 1315# Create a test page on a different origin attempting to load the asset 1316# Browser console will show: NotSameOriginAfterDefaultedToSameOriginByCoep 1317# Or: blocked:NotSameOrigin 1318 1319# 3. Verify for all asset classes 1320for path in /css/main.css /js/app.js /images/logo.png /fonts/main.woff2; do 1321 HEADER=$(curl -sI "https://example.com$path" 2>/dev/null | grep -i cross-origin-resource-policy) 1322 echo "$path: $HEADER" 1323done 1324``` 1325 1326### 11.6 Troubleshooting 1327 1328**Symptom: External site cannot embed our logo.** 1329CORP is `same-origin` or `same-site`. Either: 13301. Change to `cross-origin` for that specific path if external embedding is desired. 13312. Refuse the embedding by maintaining the current value. 1332 1333**Symptom: Our own embedded resource on a different subdomain blocked.** 1334CORP is `same-origin`. Change to `same-site` to allow subdomains. 1335 1336**Symptom: COEP is enabled, all images blocked.** 1337COEP requires every cross origin resource to opt in via CORP. The blocked images are missing CORP. Either: 13381. Add CORP to the resources. 13392. Use CORS instead. 13403. Switch COEP to `credentialless` mode. 1341 1342### 11.7 How To Fix Common Breakage 1343 1344**Case: CDN fonts blocked after enabling COEP.** 1345Google Fonts (when self hosted from googleapis.com) does not send CORP. Either: 13461. Self host the fonts on Bubbles (recommended for performance anyway). 13472. Use COEP `credentialless` mode. 1348 1349**Case: Want to allow only specific partners to embed.** 1350CORP cannot do origin specific allowlisting. Use CORS instead: `Access-Control-Allow-Origin: https://partner.example.com`. 1351 1352--- 1353 1354## 12. CROSS-ORIGIN-EMBEDDER-POLICY (COEP, WHAT THIS DOCUMENT CAN EMBED) 1355 1356### 12.1 What It Does 1357 1358`Cross-Origin-Embedder-Policy` (COEP) is set on a document and controls how that document may load cross origin resources. Required for cross origin isolation, which unlocks SharedArrayBuffer, high precision timers, and WebAssembly threading. Defined in the WHATWG HTML spec. 1359 1360``` 1361Cross-Origin-Embedder-Policy: require-corp 1362Cross-Origin-Embedder-Policy: credentialless 1363Cross-Origin-Embedder-Policy: unsafe-none 1364``` 1365 1366When COEP is enabled, every cross origin resource the document loads must explicitly opt in via: 1367 1368* CORP (`Cross-Origin-Resource-Policy: cross-origin` or compatible). 1369* CORS (`Access-Control-Allow-Origin: <embedder origin>`). 1370 1371Without opt in, the browser refuses to load the resource. This prevents the embedder from accidentally pulling cross origin data into its process memory. 1372 1373### 12.2 Values 1374 1375| Value | Meaning | 1376|---|---| 1377| `unsafe-none` | Default. No restriction. Cross origin resources load freely | 1378| `require-corp` | Strict. Cross origin resources must opt in via CORP or CORS | 1379| `credentialless` | Lenient. Cross origin requests sent without credentials (no cookies, no client certificates). Easier to adopt than require-corp | 1380 1381### 12.3 require-corp vs credentialless 1382 1383**require-corp** is the original mode. Every cross origin resource (image, script, font, iframe) must send a CORP header or be CORS enabled. This is the most secure but hardest to deploy because every third party (CDN, font provider, image host, ad network) must cooperate. 1384 1385**credentialless** is the newer alternative (Chrome 96+, Firefox 119+). Cross origin resources are loaded without credentials (no cookies). Because the request is anonymous, the resource cannot leak the user's identity, and the browser does not need an explicit opt in from the server. Easier to adopt. 1386 1387**Bubbles recommendation:** start with `credentialless` if cross origin isolation is needed. Move to `require-corp` only if a specific third party requirement (analytics endpoint that needs cookies, etc) demands it. 1388 1389### 12.4 How To Build It On Bubbles 1390 1391For sites that need SharedArrayBuffer or other isolated APIs (rare; mostly WebAssembly applications): 1392 1393```nginx 1394location / { 1395 add_header Cross-Origin-Embedder-Policy "credentialless" always; 1396 add_header Cross-Origin-Opener-Policy "same-origin" always; 1397 # CORP on every served resource 1398} 1399``` 1400 1401For typical sites that do not need isolated APIs: 1402 1403```nginx 1404# Do not set COEP. Default unsafe-none is correct. 1405``` 1406 1407Most Bubbles sites have no need for cross origin isolation. Do not enable COEP unless a specific feature requires it. 1408 1409### 12.5 How To Verify 1410 1411```bash 1412# 1. Check COEP is set 1413curl -sI https://example.com/ | grep -i cross-origin-embedder-policy 1414 1415# 2. Verify cross origin isolation in browser console: 1416# window.crossOriginIsolated 1417# Expected: true (when COEP + COOP set correctly) 1418 1419# 3. Test SharedArrayBuffer availability: 1420# typeof SharedArrayBuffer 1421# Expected: "function" when isolated, "undefined" when not 1422 1423# 4. Check that resources still load (no COEP block errors in console) 1424``` 1425 1426### 12.6 Troubleshooting 1427 1428**Symptom: After enabling COEP, half the images on the page fail to load.** 1429Those images are cross origin without CORP. Either: 14301. Self host the images. 14312. Add CORP to them (requires control of the source server). 14323. Switch to `credentialless` COEP. 1433 1434**Symptom: window.crossOriginIsolated is false despite setting COEP.** 1435COEP requires COOP to be `same-origin` AND for the document not to have been opened by a cross origin opener. Verify both headers are set. 1436 1437**Symptom: Third party scripts fail with NetworkError.** 1438Those scripts' origins do not send CORP, and the script needs credentials so credentialless does not work either. Move the script to your own origin (proxy it), or accept that you cannot have cross origin isolation while using that script. 1439 1440### 12.7 How To Fix Common Breakage 1441 1442**Case: WebAssembly app needs SharedArrayBuffer but it is undefined.** 1443Enable COEP plus COOP: 1444 1445```nginx 1446location /webapp/ { 1447 add_header Cross-Origin-Embedder-Policy "credentialless" always; 1448 add_header Cross-Origin-Opener-Policy "same-origin" always; 1449} 1450``` 1451 1452Verify in console: `crossOriginIsolated === true`. 1453 1454**Case: COEP blocks Google Fonts.** 1455Self host fonts: 1456 1457```bash 1458# Download woff2 files from Google Fonts to /var/www/sites/example.com/fonts/ 1459# Reference locally in CSS 1460``` 1461 1462Or switch to `credentialless`. 1463 1464--- 1465 1466## 13. CROSS-ORIGIN-OPENER-POLICY (COOP, WHAT THIS DOCUMENT CAN SHARE A WINDOW WITH) 1467 1468### 13.1 What It Does 1469 1470`Cross-Origin-Opener-Policy` (COOP) controls whether this document shares a browsing context group with cross origin documents opened via `window.open` or that have opened this document. Required for cross origin isolation. Defined in the WHATWG HTML spec. 1471 1472``` 1473Cross-Origin-Opener-Policy: same-origin 1474Cross-Origin-Opener-Policy: same-origin-allow-popups 1475Cross-Origin-Opener-Policy: unsafe-none 1476``` 1477 1478When COOP is `same-origin`: 1479 1480* If this document opens a cross origin popup via `window.open`, the popup gets a different browsing context group. They cannot communicate via `window.opener`. 1481* If this document was opened by a cross origin window, the opener relationship is severed: `window.opener` is null. 1482* This prevents tab nabbing and reduces side channel attack surface. 1483 1484### 13.2 Values 1485 1486| Value | Meaning | 1487|---|---| 1488| `unsafe-none` | Default. No isolation. Cross origin windows may communicate via window.opener | 1489| `same-origin-allow-popups` | This document is isolated from cross origin openers, but popups it opens can still communicate back | 1490| `same-origin` | Strict isolation. Required for cross origin isolation. No cross origin window communication | 1491 1492### 13.3 How To Build It On Bubbles 1493 1494For typical Bubbles sites (defense against tab nabbing): 1495 1496```nginx 1497add_header Cross-Origin-Opener-Policy "same-origin" always; 1498``` 1499 1500This is included in the standard `snippets/common-security-headers.conf`.