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

1# framework-http-cors-headers.md 2 3Comprehensive reference for the five HTTP response headers that implement Cross Origin Resource Sharing (CORS): `Access-Control-Allow-Origin`, `Access-Control-Allow-Methods`, `Access-Control-Allow-Headers`, `Access-Control-Expose-Headers`, and `Access-Control-Max-Age`. Includes the companion `Access-Control-Allow-Credentials` header and the preflight OPTIONS request flow that ties all of them together. 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, framework-http-security-headers.md, framework-http-performance-headers.md, UNIVERSAL-RANKING-FRAMEWORK.md, and SEO BUILD REFERENCE v2.4. 4 5Audience: humans configuring nginx CORS, AI assistants generating or repairing CORS config, frontend engineers diagnosing "blocked by CORS policy" console errors, security auditors checking for permissive origin reflection vulnerabilities, and anyone troubleshooting "preflight failing", "credentials with wildcard", "custom header rejected", or "JavaScript cannot read response header" 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 CORS Request Flow Mental Model (read this first) 155. Access-Control-Allow-Origin (who may read this response) 166. Access-Control-Allow-Methods (which HTTP methods are allowed cross origin) 177. Access-Control-Allow-Headers (which request headers may be sent) 188. Access-Control-Expose-Headers (which response headers JavaScript may read) 199. Access-Control-Max-Age (how long the preflight is cached) 2010. Access-Control-Allow-Credentials (the critical companion) 2111. The Preflight Request Lifecycle 2212. How These Headers Interact 2313. Asset Class And Use Case Recipes 2414. Bubbles Nginx Reference Block (paste ready) 2515. Audit Checklist (50+ items) 2616. Common Pitfalls 2717. Diagnostic Commands (curl, browser DevTools, CORS testers) 2818. Cross-References 29 30--- 31 32## 1. DEFINITION 33 34CORS headers tell browsers which cross origin sites are allowed to read responses from this origin and what they are allowed to do. The browser enforces the rules; the server only declares them. Without explicit CORS opt in, the browser's same origin policy blocks reading any cross origin response, even if the request itself succeeded. Defined by the WHATWG Fetch standard. 35 36The five headers split into three concerns: 37 38* **Permission**: `Access-Control-Allow-Origin`, `Access-Control-Allow-Credentials`. They answer "may this origin read me, and may credentials accompany the request?" 39* **Capability negotiation**: `Access-Control-Allow-Methods`, `Access-Control-Allow-Headers`, `Access-Control-Expose-Headers`. They answer "what verbs may be used, what request headers are permitted, what response headers may JavaScript read?" 40* **Performance**: `Access-Control-Max-Age`. It answers "how long may the browser cache this preflight permission grant?" 41 42CORS is a one way conversation initiated by the browser, not a security mechanism the browser can be told to ignore. A server saying "allow everyone" does not make CORS less secure; it makes it less restrictive. The browser still enforces the boundary. The defense in depth here is on the requesting page's origin, not on the responding origin. 43 44--- 45 46## 2. WHY IT MATTERS 47 48Six independent pressures push correct CORS configuration from "afterthought" to "required infrastructure" in 2025 and forward. 49 50**Modern frontends are multi origin by default.** A typical Bubbles client site might serve HTML from `example.com`, fonts from `fonts.gstatic.com`, analytics from `googletagmanager.com`, AdSense from `pagead2.googlesyndication.com`, and a FastAPI sidecar JSON endpoint from `api.example.com`. Every one of those cross origin requests requires CORS approval at the destination. Misconfigure any of them and the feature breaks silently with only a console error to debug. 51 52**Wildcard plus credentials is a permanent footgun.** The combination `Access-Control-Allow-Origin: *` with `Access-Control-Allow-Credentials: true` is **rejected by every modern browser**. The browser refuses to honor the credentials. This breaks login flows, authenticated API calls, and CSRF tokens. The fix requires either dropping credentials or explicitly enumerating origins, often via dynamic Origin reflection (which itself is dangerous if done wrong). 53 54**Origin reflection without validation is the most common CORS vulnerability.** "Just echo back whatever Origin the browser sent" is the lazy fix for "I need to allow many origins". It opens the door to credential theft from any attacker controlled site. Every CORS related CVE in the last five years has involved unvalidated origin reflection. Security scanners specifically test for this. 55 56**Preflight requests double your API latency if cache is missing.** Without `Access-Control-Max-Age` (or with the default 5 seconds), every API call from a single page application triggers an OPTIONS preflight before the actual request. A 100 ms API turns into 200 ms of perceived latency. Browser cache caps vary (Chrome 7200 seconds, Firefox 86400 seconds, Safari 300 seconds), so the server should send the maximum useful value. 57 58**Custom headers are common and easy to break.** Any frontend that adds `Authorization`, `X-Requested-With`, `X-CSRF-Token`, or any application specific header to a cross origin request triggers a preflight. The server must list those exact header names in `Access-Control-Allow-Headers`. Forgetting one breaks the entire request with a confusing error. 59 60**JavaScript cannot read most response headers by default.** Even when CORS allows the request, the requesting JavaScript can only read seven "safe" response headers (`Cache-Control`, `Content-Language`, `Content-Type`, `Expires`, `Last-Modified`, `Pragma`, `Content-Length`) unless the server explicitly lists others in `Access-Control-Expose-Headers`. This means custom headers like `X-Total-Count` (used for pagination), `Server-Timing`, or rate limit headers are invisible to the frontend until the server opts in. 61 62**Cost of getting it wrong.** Misconfigured CORS produces silent UX failures and serious security incidents. Real examples: 63 64* Login form on `app.example.com` posts to `api.example.com`. API responds with `Access-Control-Allow-Origin: *` and `Access-Control-Allow-Credentials: true`. Browser refuses, login fails. Users blame the site. 65* Frontend code reads `X-Total-Count` for pagination. Server sends the header but does not list it in `Access-Control-Expose-Headers`. JavaScript sees `undefined`. Pagination breaks for cross origin clients. 66* Server reflects `Origin` header back as `Access-Control-Allow-Origin` without validation. Attacker on `evil.com` makes authenticated request, reads the response, exfiltrates user data. 67* API call latency doubles after migration to a separate API subdomain because every request now preflights and `Max-Age` was forgotten. 68* OPTIONS preflight returns 200 with no CORS headers because `if ($request_method = OPTIONS)` was used inside a location that also has `proxy_pass`. The combination is one of the nginx if pitfalls that produces unexpected behavior. 69 70All preventable with the rules below. 71 72--- 73 74## 3. WHAT THIS COVERS 75 76Each of the five primary headers gets the same six part treatment: 77 781. **What it does**: the canonical Fetch standard definition plus the practical implication. 792. **Syntax and values**: every legal value, what it means, and when it is wrong. 803. **How to build it on Bubbles**: paste ready nginx config, plus FastAPI sidecar code where the upstream is the natural emitter. 814. **How to verify it**: curl commands that simulate preflight and actual requests. 825. **How to troubleshoot**: the four or five failure modes seen in the field and how to recognize each. 836. **How to fix common breakage**: ordered repair steps. 84 85The companion `Access-Control-Allow-Credentials` header gets its own dedicated section because it changes the rules for several other headers. The preflight request lifecycle is documented separately because understanding it is essential for correct configuration. 86 87--- 88 89## 4. THE CORS REQUEST FLOW MENTAL MODEL (READ THIS FIRST) 90 91Every cross origin request in the browser runs through this decision tree. Internalize it and every CORS header decision becomes obvious. 92 93``` 94JavaScript on https://app.example.com calls fetch("https://api.example.com/data", {...}) 95 | 96 v 97Browser examines the request 98 | 99 v 100Is this a "simple" request? 101 * Method is GET, HEAD, or POST 102 * No custom headers beyond the safe list 103 * Content-Type is text/plain, application/x-www-form-urlencoded, or multipart/form-data 104 | | 105 YES NO 106 | | 107 v v 108Send actual request immediately Send OPTIONS preflight first 109with Origin: https://app.example.com with: 110 | - Origin: https://app.example.com 111 | - Access-Control-Request-Method: PUT 112 | - Access-Control-Request-Headers: authorization, x-csrf 113 | | 114 | v 115 | Server responds to OPTIONS with: 116 | - Access-Control-Allow-Origin: <origin> 117 | - Access-Control-Allow-Methods: ... 118 | - Access-Control-Allow-Headers: ... 119 | - Access-Control-Max-Age: 7200 120 | - Status 204 No Content (or 200) 121 | | 122 | v 123 | Browser checks: 124 | - Does Allow-Origin match the page's origin? 125 | - Is the requested method in Allow-Methods? 126 | - Are all requested headers in Allow-Headers? 127 | | | 128 | YES NO 129 | | | 130 | | v 131 | | Block actual request 132 | | Console error 133 | v 134 | Cache preflight result for Max-Age seconds 135 | Send actual request 136 | | 137 v v 138======================================================================== 139Both paths converge on the actual request and response 140======================================================================== 141 | 142 v 143Server receives actual request, processes, responds 144 Response includes: 145 - Access-Control-Allow-Origin: <origin> 146 - Access-Control-Allow-Credentials: true (if applicable) 147 - Access-Control-Expose-Headers: x-total-count, server-timing (if needed) 148 - Vary: Origin (if Allow-Origin is not "*") 149 | 150 v 151Browser checks: 152 - Does Allow-Origin match this page's origin? 153 | | 154 YES NO 155 | | 156 v v 157JavaScript sees Block response from JavaScript 158the response Throw TypeError: Failed to fetch 159 | (the actual response was received but is hidden) 160 v 161JavaScript can read safe response headers 162JavaScript can read any header listed in Access-Control-Expose-Headers 163JavaScript CANNOT read other headers (Set-Cookie, internal headers, etc) 164``` 165 166Five rules govern the system: 167 1681. **The browser enforces CORS, not the server.** The server only declares. If the server says "anyone may read", the browser still applies its rules to whoever asked. 1692. **Preflight asks permission; actual request collects the data.** They are separate HTTP exchanges. Both must carry correct CORS response headers. 1703. **Wildcard and credentials are mutually exclusive.** Browser refuses the combination. Either drop credentials or name the origin explicitly. 1714. **Vary: Origin is required for dynamic origin allow lists.** Without it, intermediate caches and the browser's own cache may serve a response approved for one origin to a different origin. 1725. **Custom request and response headers must be explicitly allowed and exposed.** Defaults cover only the basic web. Anything custom requires opt in by name. 173 174A correctly configured CORS stack lets approved origins read responses fully (including custom headers), blocks unapproved origins decisively, caches preflight permissions to minimize OPTIONS overhead, and never reflects origins without validation. 175 176--- 177 178## 5. ACCESS-CONTROL-ALLOW-ORIGIN (WHO MAY READ THIS RESPONSE) 179 180### 5.1 What It Does 181 182`Access-Control-Allow-Origin` tells the browser which origin (the protocol plus host plus port) is allowed to read the response from JavaScript. Without this header, the response is blocked from cross origin JavaScript regardless of HTTP status. 183 184``` 185Access-Control-Allow-Origin: * 186Access-Control-Allow-Origin: https://app.example.com 187Access-Control-Allow-Origin: null 188``` 189 190This header is the foundation of CORS. Every CORS enabled response must include it. The browser compares the value against the page's origin. If they match (or the value is `*` and credentials are not in use), JavaScript may read the response. Otherwise, the response is blocked even though it was received. 191 192### 5.2 Values 193 194| Value | Meaning | 195|---|---| 196| `*` | Any origin may read. Cannot be combined with credentials. Suitable for public APIs and public assets | 197| `<origin>` | A single specific origin: scheme, host, optional port. Example: `https://app.example.com`. Compatible with credentials | 198| `null` | The literal string "null". Used for sandboxed iframes and file:// URLs. Rarely the right choice | 199 200**Important: only one origin per header.** Unlike `Access-Control-Allow-Methods` (comma separated list), `Access-Control-Allow-Origin` accepts exactly one value. To support multiple origins, the server must dynamically reflect the requesting origin (with validation) or send a different value per request. 201 202### 5.3 The Dynamic Reflection Pattern (For Multiple Allowed Origins) 203 204The Bubbles canonical pattern for supporting multiple specific origins: 205 206```nginx 207http { 208 # Define allowed origins 209 map $http_origin $cors_origin { 210 default ""; 211 "~^https://(app\.|admin\.)?example\.com$" "$http_origin"; 212 "~^https://partner\.example\.com$" "$http_origin"; 213 "~^https://staging\.example\.com$" "$http_origin"; 214 } 215} 216 217server { 218 location /api/ { 219 # Only set the header when the origin matches 220 if ($cors_origin) { 221 add_header Access-Control-Allow-Origin $cors_origin always; 222 add_header Vary "Origin" always; 223 } 224 } 225} 226``` 227 228The map directive validates the origin against the allow list. If the request's `Origin` header matches one of the patterns, `$cors_origin` is set to that origin value and reflected back. If it does not match, `$cors_origin` is empty and no CORS header is added (effectively rejecting the cross origin request). 229 230**Vary: Origin is essential.** Because the response varies based on the request's Origin header, every cache between the server and client must understand that responses are not interchangeable across origins. Without Vary, a cached response approved for `app.example.com` might be served to a browser on `evil.com`. 231 232### 5.4 The Reflection Vulnerability 233 234The naive version of "support multiple origins" is to reflect whatever the browser sends, with no validation: 235 236```nginx 237# DANGEROUS: do not do this 238add_header Access-Control-Allow-Origin $http_origin always; 239add_header Access-Control-Allow-Credentials "true" always; 240``` 241 242This says "whoever you are, you may read my responses with credentials". An attacker hosting JavaScript on `evil.com` can now make authenticated requests to this API from a victim's browser and read the responses, exfiltrating any data the victim has access to. Every CORS related CVE in the last several years involves this pattern or a variant. 243 244**The fix:** always validate the origin against an explicit allow list (Section 5.3). Never reflect blindly. 245 246### 5.5 How To Build It On Bubbles 247 248**Public API for any origin:** 249 250```nginx 251location /api/public/ { 252 add_header Access-Control-Allow-Origin "*" always; 253 # No credentials, no need for Vary 254} 255``` 256 257**Same origin only (effectively no CORS):** 258 259```nginx 260location /api/private/ { 261 # No Access-Control-Allow-Origin header 262 # Browser blocks cross origin requests by default 263} 264``` 265 266**Specific single origin:** 267 268```nginx 269location /api/ { 270 add_header Access-Control-Allow-Origin "https://app.example.com" always; 271 add_header Vary "Origin" always; 272} 273``` 274 275**Multiple specific origins (the Bubbles canonical pattern):** 276 277```nginx 278# In nginx.conf http context 279map $http_origin $cors_origin { 280 default ""; 281 "~^https://(app\.|admin\.|api\.)?example\.com$" "$http_origin"; 282 "~^https://partner\.example\.com$" "$http_origin"; 283} 284 285# In server block location 286location /api/ { 287 if ($cors_origin) { 288 add_header Access-Control-Allow-Origin $cors_origin always; 289 add_header Vary "Origin" always; 290 } 291} 292``` 293 294**FastAPI sidecar with proper validation:** 295 296```python 297from fastapi import FastAPI, Request, Response 298from fastapi.middleware.cors import CORSMiddleware 299 300app = FastAPI() 301 302# FastAPI's built in middleware handles the allow list correctly 303app.add_middleware( 304 CORSMiddleware, 305 allow_origins=[ 306 "https://app.example.com", 307 "https://admin.example.com", 308 "https://partner.example.com", 309 ], 310 allow_credentials=True, 311 allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"], 312 allow_headers=["Content-Type", "Authorization", "X-CSRF-Token"], 313 expose_headers=["X-Total-Count", "Server-Timing"], 314 max_age=7200, 315) 316``` 317 318When using the FastAPI middleware approach, nginx should not add CORS headers itself; it would conflict with the upstream. Either nginx handles CORS OR the upstream does, not both. 319 320### 5.6 How To Verify 321 322```bash 323# 1. Simulate a CORS request with an Origin header 324curl -sI -H "Origin: https://app.example.com" https://api.example.com/data | grep -iE "access-control|^vary" 325 326# Expected: 327# access-control-allow-origin: https://app.example.com 328# vary: Origin 329 330# 2. Test from a disallowed origin 331curl -sI -H "Origin: https://evil.com" https://api.example.com/data | grep -i access-control-allow-origin 332# Expected: no access-control-allow-origin header 333 334# 3. Verify wildcard public API 335curl -sI -H "Origin: https://anything.com" https://api.example.com/public/data | grep -i access-control-allow-origin 336# Expected: access-control-allow-origin: * 337 338# 4. Confirm Vary: Origin when reflecting 339curl -sI -H "Origin: https://app.example.com" https://api.example.com/data | grep -i vary 340# Expected: vary: Origin (or contains Origin) 341 342# 5. Test in browser DevTools 343# Open DevTools Console on https://app.example.com: 344# fetch("https://api.example.com/data").then(r => r.json()).then(console.log) 345# Network tab: check Access-Control-Allow-Origin in response 346# Console: should NOT show "blocked by CORS policy" 347``` 348 349### 5.7 Troubleshooting 350 351**Symptom: Console error "blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present".** 352Causes ranked by frequency: 3531. The header is not being set. Verify with curl. 3542. The header is being set on the actual request response but not on the preflight OPTIONS response. Both must have it. See Section 11. 3553. The origin sent by the browser does not match the allow list (typo, missing port, http vs https mismatch). 3564. An upstream is overriding the value back to empty. 357 358**Symptom: Header present in curl but browser still shows CORS error.** 3591. Browser hard cached a previous failed preflight. Clear cache or test in incognito. 3602. The actual request returned a non 2xx status. Browser treats it as a CORS failure even if the headers are correct, in some cases. 3613. The Origin value in the curl test does not match what the browser sends. Verify by looking at the Origin in DevTools Network tab. 362 363**Symptom: "The value of the 'Access-Control-Allow-Origin' header in the response must not be the wildcard '*' when the request's credentials mode is 'include'".** 364Wildcard plus credentials is rejected. See Section 10. 365 366**Symptom: Origin reflection returns wrong value (browser blocks).** 3671. The reflection is happening but with the wrong case (`origin` vs `Origin` in the regex). 3682. The map directive does not match. Test the regex with curl against a sample origin. 3693. The `if ($cors_origin)` check is inside a nested location that does not see the map variable. Move to the outer scope. 370 371**Symptom: Cache serves response approved for origin A to a request from origin B.** 372`Vary: Origin` is missing. Add it whenever `Access-Control-Allow-Origin` is anything other than `*`. 373 374### 5.8 How To Fix Common Breakage 375 376**Case: Login fails with "wildcard plus credentials" error.** 377Replace wildcard with specific origin reflection: 378 379```nginx 380map $http_origin $cors_origin { 381 default ""; 382 "~^https://app\.example\.com$" "$http_origin"; 383} 384 385location /api/auth/ { 386 if ($cors_origin) { 387 add_header Access-Control-Allow-Origin $cors_origin always; 388 add_header Access-Control-Allow-Credentials "true" always; 389 add_header Vary "Origin" always; 390 } 391} 392``` 393 394**Case: New partner integration needs API access.** 395Add their origin to the map: 396 397```nginx 398map $http_origin $cors_origin { 399 default ""; 400 "~^https://(app\.|admin\.)?example\.com$" "$http_origin"; 401 "~^https://partner\.example\.com$" "$http_origin"; 402 "~^https://new-partner\.example\.com$" "$http_origin"; # added 403} 404``` 405 406`nginx -t && systemctl reload nginx`. The new partner can immediately make CORS requests. 407 408**Case: Security scan flags origin reflection without validation.** 409The current config uses `$http_origin` directly. Replace with a map based allow list (Section 5.3 and 5.5). 410 411--- 412 413## 6. ACCESS-CONTROL-ALLOW-METHODS (WHICH HTTP METHODS ARE ALLOWED CROSS ORIGIN) 414 415### 6.1 What It Does 416 417`Access-Control-Allow-Methods` lists which HTTP methods the actual request may use. Sent in the preflight response. The browser checks the requested method (announced via `Access-Control-Request-Method`) against this list and blocks the actual request if absent. 418 419``` 420Access-Control-Allow-Methods: GET, POST, OPTIONS 421Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS 422Access-Control-Allow-Methods: * 423``` 424 425This header only matters on preflight (OPTIONS) responses. It is ignored on actual request responses. 426 427### 6.2 Values 428 429The value is a comma separated list of HTTP method names. 430 431| Value | Meaning | 432|---|---| 433| `GET, POST, PUT, DELETE, PATCH, OPTIONS` | Specific allowed methods. Comma separated | 434| `*` | Any method. Cannot be combined with credentials. Recently supported in most browsers | 435| (absent) | No methods explicitly allowed. The browser may still permit "simple" methods (GET, HEAD, POST) | 436 437**Always include OPTIONS** if you support preflight, even though OPTIONS is the preflight method itself. Some browsers expect it in the allow list. 438 439### 6.3 How To Build It On Bubbles 440 441For a typical REST API: 442 443```nginx 444location /api/ { 445 if ($request_method = OPTIONS) { 446 add_header Access-Control-Allow-Origin $cors_origin always; 447 add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, PATCH, OPTIONS" always; 448 add_header Access-Control-Allow-Headers "Content-Type, Authorization, X-CSRF-Token" always; 449 add_header Access-Control-Max-Age "7200" always; 450 add_header Access-Control-Allow-Credentials "true" always; 451 add_header Vary "Origin" always; 452 return 204; 453 } 454 # actual request handling 455 proxy_pass http://127.0.0.1:9090; 456} 457``` 458 459The `if ($request_method = OPTIONS)` pattern is **one of the explicitly safe uses** of nginx `if` because it combines `if` with `return`, not with `proxy_pass`. The nginx `if` antipattern warning applies only to combinations with content handlers. 460 461For a read only public API: 462 463```nginx 464location /api/public/ { 465 if ($request_method = OPTIONS) { 466 add_header Access-Control-Allow-Origin "*" always; 467 add_header Access-Control-Allow-Methods "GET, HEAD, OPTIONS" always; 468 add_header Access-Control-Max-Age "86400" always; 469 return 204; 470 } 471} 472``` 473 474### 6.4 How To Verify 475 476```bash 477# 1. Simulate a preflight 478curl -sI -X OPTIONS \ 479 -H "Origin: https://app.example.com" \ 480 -H "Access-Control-Request-Method: PUT" \ 481 -H "Access-Control-Request-Headers: Authorization" \ 482 https://api.example.com/data 483 484# Expected response: 485# HTTP/2 204 486# access-control-allow-origin: https://app.example.com 487# access-control-allow-methods: GET, POST, PUT, DELETE, PATCH, OPTIONS 488# access-control-allow-headers: Content-Type, Authorization, X-CSRF-Token 489# access-control-max-age: 7200 490 491# 2. Verify PUT is allowed 492curl -sI -X OPTIONS \ 493 -H "Origin: https://app.example.com" \ 494 -H "Access-Control-Request-Method: PUT" \ 495 https://api.example.com/data | grep -i access-control-allow-methods 496# Look for PUT in the response 497 498# 3. Test that DELETE works (after preflight passes) 499curl -X DELETE -H "Origin: https://app.example.com" https://api.example.com/data/123 | head 500``` 501 502### 6.5 Troubleshooting 503 504**Symptom: "Method PUT is not allowed by Access-Control-Allow-Methods".** 505The OPTIONS preflight response does not include PUT in the allow list. 506Fix: add the method to the list. 507 508**Symptom: Methods listed but browser still blocks.** 5091. The methods are listed on the actual request response, not the preflight. Add to OPTIONS specifically. 5102. The list contains a typo or wrong case. 5113. The method is allowed but a required header is not (check Allow-Headers separately). 512 513**Symptom: OPTIONS returns 405 Method Not Allowed.** 514The location does not handle OPTIONS. Add the `if ($request_method = OPTIONS)` block as shown in Section 6.3. 515 516### 6.6 How To Fix Common Breakage 517 518**Case: Need to add PATCH method for partial updates.** 519Add PATCH to the list: 520 521```nginx 522add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, PATCH, OPTIONS" always; 523``` 524 525Reload nginx. Browsers cache preflights, so existing tabs may need a refresh. 526 527**Case: API endpoint is read only.** 528Restrict to read methods: 529 530```nginx 531add_header Access-Control-Allow-Methods "GET, HEAD, OPTIONS" always; 532``` 533 534--- 535 536## 7. ACCESS-CONTROL-ALLOW-HEADERS (WHICH REQUEST HEADERS MAY BE SENT) 537 538### 7.1 What It Does 539 540`Access-Control-Allow-Headers` lists which request headers the actual request may include. Sent in the preflight response. The browser checks the requested headers (announced via `Access-Control-Request-Headers`) against this list and blocks the actual request if any are not allowed. 541 542``` 543Access-Control-Allow-Headers: Content-Type, Authorization 544Access-Control-Allow-Headers: Content-Type, Authorization, X-CSRF-Token, X-Requested-With 545Access-Control-Allow-Headers: * 546``` 547 548### 7.2 The Always Allowed Headers 549 550These headers are always allowed without being listed (they belong to the "CORS safelisted request headers"): 551 552* `Accept` 553* `Accept-Language` 554* `Content-Language` 555* `Content-Type` (only with values `text/plain`, `application/x-www-form-urlencoded`, or `multipart/form-data`) 556* `Range` 557 558Any other request header (`Authorization`, `Content-Type: application/json`, `X-CSRF-Token`, etc) triggers a preflight and must appear in `Access-Control-Allow-Headers`. 559 560### 7.3 Values 561 562The value is a comma separated list of header names. Case insensitive. 563 564| Value | Meaning | 565|---|---| 566| `Content-Type, Authorization` | Specific allowed custom request headers | 567| `*` | Any header. Cannot be combined with credentials (since 2021+) | 568| (absent) | Only the safelisted headers allowed | 569 570### 7.4 How To Build It On Bubbles 571 572For a typical API with Authorization and CSRF protection: 573 574```nginx 575location /api/ { 576 if ($request_method = OPTIONS) { 577 add_header Access-Control-Allow-Headers "Content-Type, Authorization, X-CSRF-Token, X-Requested-With" always; 578 # ... other CORS preflight headers ... 579 return 204; 580 } 581} 582``` 583 584For an API that accepts custom application headers: 585 586```nginx 587location /api/ { 588 if ($request_method = OPTIONS) { 589 add_header Access-Control-Allow-Headers "Content-Type, Authorization, X-CSRF-Token, X-Tenant-ID, X-Request-ID, X-Client-Version" always; 590 return 204; 591 } 592} 593``` 594 595### 7.5 How To Verify 596 597```bash 598# 1. Simulate preflight requesting custom headers 599curl -sI -X OPTIONS \ 600 -H "Origin: https://app.example.com" \ 601 -H "Access-Control-Request-Method: POST" \ 602 -H "Access-Control-Request-Headers: authorization, content-type, x-csrf-token" \ 603 https://api.example.com/data | grep -i access-control-allow-headers 604 605# Expected: access-control-allow-headers: Content-Type, Authorization, X-CSRF-Token 606 607# 2. Test with a header NOT in the list 608curl -sI -X OPTIONS \ 609 -H "Origin: https://app.example.com" \ 610 -H "Access-Control-Request-Method: POST" \ 611 -H "Access-Control-Request-Headers: x-secret-header" \ 612 https://api.example.com/data 613 614# Browser would block; nginx still returns 204 with the configured allow list 615# (browser does the enforcement, not nginx) 616``` 617 618### 7.6 Troubleshooting 619 620**Symptom: "Request header field X-Custom-Header is not allowed by Access-Control-Allow-Headers in preflight response".** 621The header is not in the allow list. Add it. 622 623**Symptom: Authorization header rejected despite being listed.** 6241. Header name typo. Check exact spelling (case insensitive but spelling matters). 6252. The preflight is going to a different location than the actual request. Both must have CORS headers. 6263. An intermediate is stripping the header before it reaches the configured CORS handler. 627 628**Symptom: Browser sends preflight even for simple POST.** 629The Content-Type is `application/json` (which is not in the safelisted list). This is correct browser behavior. Configure preflight handling. 630 631### 7.7 How To Fix Common Breakage 632 633**Case: Adding a new custom header to API requests.** 634Add it to the allow list: 635 636```nginx 637add_header Access-Control-Allow-Headers "Content-Type, Authorization, X-CSRF-Token, X-New-Header" always; 638``` 639 640Reload nginx. Browsers with cached preflights will preflight again on next request after cache expires. 641 642**Case: Want to be permissive about headers (development/internal API).** 643Use the wildcard if credentials are not required: 644 645```nginx 646add_header Access-Control-Allow-Headers "*" always; 647``` 648 649Or enumerate liberally. Note: with credentials enabled, wildcard does not work; you must list every header. 650 651--- 652 653## 8. ACCESS-CONTROL-EXPOSE-HEADERS (WHICH RESPONSE HEADERS JAVASCRIPT MAY READ) 654 655### 8.1 What It Does 656 657`Access-Control-Expose-Headers` lists which response headers the requesting JavaScript may read via the Fetch API or XMLHttpRequest. Without this header, only the "safelisted" response headers are visible to JavaScript. Sent on the actual response (not preflight). 658 659``` 660Access-Control-Expose-Headers: X-Total-Count 661Access-Control-Expose-Headers: X-Total-Count, X-RateLimit-Limit, X-RateLimit-Remaining, Server-Timing 662Access-Control-Expose-Headers: * 663``` 664 665### 8.2 The Always Visible Headers 666 667These response headers are always readable from JavaScript on a CORS response: 668 669* `Cache-Control` 670* `Content-Language` 671* `Content-Length` 672* `Content-Type` 673* `Expires` 674* `Last-Modified` 675* `Pragma` 676 677**Everything else is invisible to JavaScript unless listed in Expose-Headers.** Common headers that surprise developers by being invisible: 678 679* `Authorization` (response side) 680* `Location` (after a 3xx redirect) 681* `Set-Cookie` (always invisible to script; this is a security feature, cannot be exposed) 682* `X-Total-Count` and any pagination headers 683* `X-RateLimit-*` headers 684* `Server-Timing` 685* `ETag` (counterintuitively, this is NOT in the safelist; must be exposed) 686* `Link` 687* Custom application headers 688 689### 8.3 Values 690 691| Value | Meaning | 692|---|---| 693| `<header>, <header>` | Specific headers JavaScript may read | 694| `*` | Any header. Cannot be combined with credentials | 695| (absent) | Only safelisted headers visible | 696 697### 8.4 How To Build It On Bubbles 698 699For pagination plus rate limiting plus Server-Timing: 700 701```nginx 702location /api/ { 703 if ($request_method = OPTIONS) { 704 # Preflight handling 705 return 204; 706 } 707 708 # Actual request: expose custom response headers 709 add_header Access-Control-Allow-Origin $cors_origin always; 710 add_header Access-Control-Expose-Headers "X-Total-Count, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Server-Timing, ETag, Link" always; 711 add_header Vary "Origin" always; 712 add_header Access-Control-Allow-Credentials "true" always; 713 714 proxy_pass http://127.0.0.1:9090; 715} 716``` 717 718For a FastAPI sidecar with CORS middleware: 719 720```python 721app.add_middleware( 722 CORSMiddleware, 723 allow_origins=["https://app.example.com"], 724 allow_credentials=True, 725 expose_headers=[ 726 "X-Total-Count", 727 "X-RateLimit-Limit", 728 "X-RateLimit-Remaining", 729 "X-RateLimit-Reset", 730 "Server-Timing", 731 "ETag", 732 "Link", 733 ], 734 max_age=7200, 735) 736``` 737 738### 8.5 How To Verify 739 740```bash 741# 1. Confirm header is on actual responses 742curl -sI -H "Origin: https://app.example.com" https://api.example.com/users | grep -iE "access-control-expose|x-total" 743 744# Expected: 745# access-control-expose-headers: X-Total-Count, Server-Timing, ETag 746# x-total-count: 1247 747 748# 2. Test in browser DevTools 749# Console on https://app.example.com: 750# fetch("https://api.example.com/users", {credentials: "include"}) 751# .then(r => { 752# console.log("Total:", r.headers.get("X-Total-Count")); 753# console.log("Rate limit:", r.headers.get("X-RateLimit-Remaining")); 754# }) 755# Without Expose-Headers: both show null 756# With Expose-Headers listing them: both show actual values 757``` 758 759### 8.6 Troubleshooting 760 761**Symptom: JavaScript reads response.headers.get("X-Total-Count") and gets null.** 762The header is on the response but not exposed. Add it to `Access-Control-Expose-Headers`. 763 764**Symptom: ETag returns null in JavaScript despite being in response.** 765ETag is NOT in the default safelist (despite being common). Must be explicitly exposed. 766 767**Symptom: Set-Cookie cannot be read from JavaScript.** 768By design. The browser never exposes Set-Cookie to script regardless of CORS configuration. This is a fundamental security boundary, not a CORS issue. 769 770**Symptom: Expose-Headers wildcard does not work.** 7711. The wildcard is being used with credentials (not allowed). Drop credentials or enumerate headers. 7722. Older browser (some still treat `*` as a literal header name in this context). Enumerate for safety. 773 774### 8.7 How To Fix Common Breakage 775 776**Case: Pagination component cannot read total count.** 777The server sends `X-Total-Count: 1247` but JavaScript sees null. Add to expose list: 778 779```nginx 780add_header Access-Control-Expose-Headers "X-Total-Count, Link" always; 781``` 782 783Frontend code now reads `response.headers.get("X-Total-Count")` successfully. 784 785**Case: RUM library cannot read Server-Timing.** 786Same fix: add `Server-Timing` to the expose list. 787 788--- 789 790## 9. ACCESS-CONTROL-MAX-AGE (HOW LONG THE PREFLIGHT IS CACHED) 791 792### 9.1 What It Does 793 794`Access-Control-Max-Age` tells the browser how long to cache the preflight (OPTIONS) response. While the cache is valid, the browser skips the preflight and sends the actual request directly. Sent in the OPTIONS preflight response. 795 796``` 797Access-Control-Max-Age: 7200 798Access-Control-Max-Age: 86400 799``` 800 801Without this header, browsers apply a default of 5 seconds, which means every API call from a single page application triggers a preflight after the cache expires. This doubles perceived latency for every cross origin request. 802 803### 9.2 Browser Caps 804 805Browsers enforce their own upper limits, capping whatever the server sends: 806 807| Browser | Max value honored | 808|---|---| 809| Firefox | 86400 (24 hours) | 810| Chromium (v76+) | 7200 (2 hours) | 811| Safari | 600 (10 minutes) | 812 813For maximum benefit across all browsers, send `Access-Control-Max-Age: 86400`. Firefox uses the full day, Chrome caps to 2 hours, Safari to 10 minutes. The server side cost of being generous is zero. 814 815### 9.3 What The Preflight Cache Stores 816 817The cached entry is keyed on: 818 819* URL (or the request path). 820* Origin (the requesting page's origin). 821* Combination of `Access-Control-Request-Method` and `Access-Control-Request-Headers` from the preflight. 822 823A change in any of these triggers a fresh preflight. So a single page that makes both GET and POST requests with different headers will preflight twice. 824 825### 9.4 How To Build It On Bubbles 826 827In the preflight handler: 828 829```nginx 830location /api/ { 831 if ($request_method = OPTIONS) { 832 add_header Access-Control-Allow-Origin $cors_origin always; 833 add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always; 834 add_header Access-Control-Allow-Headers "Content-Type, Authorization, X-CSRF-Token" always; 835 add_header Access-Control-Max-Age "86400" always; # 24 hours, browsers cap as needed 836 add_header Access-Control-Allow-Credentials "true" always; 837 add_header Vary "Origin" always; 838 return 204; 839 } 840} 841``` 842 843For a high traffic API, Max-Age is one of the cheapest performance wins available. 844 845### 9.5 How To Verify 846 847```bash 848# 1. Confirm Max-Age in preflight response 849curl -sI -X OPTIONS \ 850 -H "Origin: https://app.example.com" \ 851 -H "Access-Control-Request-Method: POST" \ 852 https://api.example.com/data | grep -i access-control-max-age 853# Expected: access-control-max-age: 86400 854 855# 2. Verify browser caches the preflight 856# In Chrome DevTools Network panel: 857# Make a cross origin request, observe OPTIONS preflight 858# Make the same request again within 2 hours, observe NO OPTIONS preflight 859# After 2 hours, observe preflight again 860 861# 3. Test that changing the method invalidates cache 862# OPTIONS for GET cached 863# Then POST: new OPTIONS preflight (different method) 864``` 865 866### 9.6 Troubleshooting 867 868**Symptom: Every API call triggers an OPTIONS preflight despite Max-Age.** 8691. Max-Age is missing or set to 0. Check the preflight response. 8702. The request varies (different method, different custom header each time). Each unique combination preflights separately. 8713. Browser cache cleared between requests. 8724. The page was opened in a private/incognito window with disabled cache. 873 874**Symptom: Preflight cache works in Firefox but not Chrome.** 875Chrome caps Max-Age at 7200 (2 hours). After 2 hours, preflight happens again regardless of server value. 876 877**Symptom: Preflight cache works for one URL but not for similar URLs.** 878The cache is per URL (or per path depending on implementation). Two endpoints that share the same allow list still each get their own cached preflight. 879 880### 9.7 How To Fix Common Breakage 881 882**Case: Single page app feels slow on cross origin API calls.** 883Confirm Max-Age is set: 884 885```bash 886curl -sI -X OPTIONS \ 887 -H "Origin: https://app.example.com" \ 888 -H "Access-Control-Request-Method: POST" \ 889 https://api.example.com/users | grep -i max-age 890``` 891 892If missing or low, set to 86400: 893 894```nginx 895add_header Access-Control-Max-Age "86400" always; 896``` 897 898API latency on cached preflights drops by half (one round trip eliminated per request). 899 900--- 901 902## 10. ACCESS-CONTROL-ALLOW-CREDENTIALS (THE CRITICAL COMPANION) 903 904### 10.1 What It Does 905 906`Access-Control-Allow-Credentials` tells the browser that the response is allowed to be read even when the request was made with credentials (cookies, HTTP authentication, client TLS certificates). Without this header (or with value `false`), JavaScript that made a `fetch(url, {credentials: "include"})` call cannot read the response, and the browser refuses to send cookies in the first place. 907 908``` 909Access-Control-Allow-Credentials: true 910``` 911 912Only `true` is a meaningful value. Setting to `false` is equivalent to omitting. 913 914### 10.2 The Wildcard Prohibition 915 916When `Access-Control-Allow-Credentials: true` is set, **all CORS headers must use specific values, not wildcards**. The browser strictly enforces this: 917 918| Header | With credentials | Without credentials | 919|---|---|---| 920| Access-Control-Allow-Origin | Specific origin only | Specific or `*` | 921| Access-Control-Allow-Methods | Specific methods only | Specific or `*` | 922| Access-Control-Allow-Headers | Specific headers only | Specific or `*` | 923| Access-Control-Expose-Headers | Specific headers only | Specific or `*` | 924 925Combining `*` with `true` causes the browser to refuse the response entirely with an error. 926 927### 10.3 When To Use Credentials 928 929* **Use credentials** when the API requires authentication via cookies or HTTP auth and the request comes from a browser based application on a different origin. 930* **Do not use credentials** for public APIs, third party widgets, or anonymous data endpoints. 931 932The browser only sends credentials when the calling code explicitly requests them: 933 934```javascript 935fetch("https://api.example.com/data", { credentials: "include" }) 936``` 937 938Without `credentials: "include"`, the browser does not send cookies and does not require `Access-Control-Allow-Credentials` from the server. 939 940### 10.4 How To Build It On Bubbles 941 942For an authenticated API used by a frontend on a different origin: 943 944```nginx 945map $http_origin $cors_origin { 946 default ""; 947 "~^https://app\.example\.com$" "$http_origin"; 948} 949 950location /api/ { 951 if ($request_method = OPTIONS) { 952 if ($cors_origin) { 953 add_header Access-Control-Allow-Origin $cors_origin always; 954 add_header Access-Control-Allow-Credentials "true" always; 955 add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always; 956 add_header Access-Control-Allow-Headers "Content-Type, Authorization, X-CSRF-Token" always; 957 add_header Access-Control-Max-Age "86400" always; 958 add_header Vary "Origin" always; 959 return 204; 960 } 961 return 204; # generic OPTIONS response for non allow listed origins 962 } 963 964 # Actual request 965 if ($cors_origin) { 966 add_header Access-Control-Allow-Origin $cors_origin always; 967 add_header Access-Control-Allow-Credentials "true" always; 968 add_header Vary "Origin" always; 969 } 970 proxy_pass http://127.0.0.1:9090; 971} 972``` 973 974### 10.5 How To Verify 975 976```bash 977# 1. Confirm Allow-Credentials on both preflight and actual 978curl -sI -X OPTIONS -H "Origin: https://app.example.com" \ 979 -H "Access-Control-Request-Method: POST" \ 980 https://api.example.com/data | grep -i access-control-allow-credentials 981 982curl -sI -H "Origin: https://app.example.com" \ 983 https://api.example.com/data | grep -i access-control-allow-credentials 984 985# Both should show: access-control-allow-credentials: true 986 987# 2. Verify wildcard is NOT used 988curl -sI -H "Origin: https://app.example.com" \ 989 https://api.example.com/data | grep -i access-control-allow-origin 990# Should show specific origin, NOT * 991 992# 3. Test in browser with credentials 993# Console on https://app.example.com: 994# fetch("https://api.example.com/data", {credentials: "include"}) 995# .then(r => console.log(r.status)) 996# Should succeed and return JSON 997``` 998 999### 10.6 Troubleshooting 1000 1001**Symptom: "The value of the 'Access-Control-Allow-Origin' header in the response must not be the wildcard '*' when the request's credentials mode is 'include'".** 1002Server is sending `*` for origin while also setting credentials. Replace wildcard with specific origin reflection. 1003 1004**Symptom: Cookie not sent on cross origin request despite credentials: include.** 10051. Server is not sending `Access-Control-Allow-Credentials: true`. 10062. Cookie does not have `SameSite=None; Secure` attribute (required for cross site cookies in modern browsers). 10073. Site is on HTTP, not HTTPS (SameSite=None requires Secure which requires HTTPS). 1008 1009**Symptom: Set-Cookie response header sent but browser does not store cookie.** 10101. Same as above (SameSite=None; Secure required). 10112. Server's `Access-Control-Allow-Credentials` is missing or false. 10123. Cookie's Domain attribute does not include the requesting origin. 1013 1014### 10.7 How To Fix Common Breakage 1015 1016**Case: Cross origin login fails to set session cookie.** 1017Three things must align: 1018 10191. Server sets `Access-Control-Allow-Credentials: true` and specific Allow-Origin. 10202. Cookie is set with `SameSite=None; Secure`. 10213. Frontend uses `credentials: "include"` in fetch. 1022 1023```python 1024# FastAPI example 1025from fastapi.responses import JSONResponse 1026 1027@app.post("/api/login") 1028async def login(...): 1029 response = JSONResponse({"status": "ok"}) 1030 response.set_cookie( 1031 key="session", 1032 value=session_token, 1033 max_age=3600, 1034 secure=True, # required for SameSite=None 1035 httponly=True, 1036 samesite="none", # required for cross site 1037 ) 1038 return response 1039``` 1040 1041```javascript 1042// Frontend 1043fetch("https://api.example.com/login", { 1044 method: "POST", 1045 credentials: "include", // critical 1046 body: JSON.stringify({...}) 1047}); 1048``` 1049 1050```nginx 1051# Nginx 1052location /api/login { 1053 if ($cors_origin) { 1054 add_header Access-Control-Allow-Origin $cors_origin always; 1055 add_header Access-Control-Allow-Credentials "true" always; 1056 add_header Vary "Origin" always; 1057 } 1058 proxy_pass http://127.0.0.1:9090; 1059} 1060``` 1061 1062--- 1063 1064## 11. THE PREFLIGHT REQUEST LIFECYCLE 1065 1066The OPTIONS preflight is the single most misunderstood part of CORS. A full walkthrough: 1067 1068### 11.1 When Does A Preflight Happen 1069 1070A preflight is triggered for any "non simple" request. A simple request meets ALL of these: 1071 1072* Method is GET, HEAD, or POST (other methods preflight). 1073* Request headers are limited to the safelisted set (custom headers preflight). 1074* If POST, Content-Type is `text/plain`, `application/x-www-form-urlencoded`, or `multipart/form-data` (`application/json` preflights). 1075 1076Practically, **almost every modern API call triggers a preflight** because: 1077 1078* JSON APIs use `Content-Type: application/json` (not safelisted). 1079* Authenticated APIs use `Authorization` header (not safelisted). 1080* REST APIs use PUT, PATCH, DELETE (not safelisted methods). 1081 1082### 11.2 The Preflight Request 1083 1084The browser sends an OPTIONS request with these special headers: 1085 1086``` 1087OPTIONS /api/users/123 HTTP/2 1088Host: api.example.com 1089Origin: https://app.example.com 1090Access-Control-Request-Method: PUT 1091Access-Control-Request-Headers: authorization, content-type 1092``` 1093 1094* `Origin`: which origin is asking. 1095* `Access-Control-Request-Method`: which method the actual request will use. 1096* `Access-Control-Request-Headers`: which custom headers the actual request will include. 1097 1098### 11.3 The Preflight Response 1099 1100The server must respond with the CORS headers granting permission: 1101 1102``` 1103HTTP/2 204 1104Access-Control-Allow-Origin: https://app.example.com 1105Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS 1106Access-Control-Allow-Headers: Content-Type, Authorization, X-CSRF-Token 1107Access-Control-Allow-Credentials: true 1108Access-Control-Max-Age: 7200 1109Vary: Origin 1110``` 1111 1112Status 204 (No Content) is preferred. 200 also works. The response body is ignored. 1113 1114### 11.4 What The Browser Does Next 1115 11161. **Match check.** Browser verifies: 1117 * `Allow-Origin` matches the page's origin (or is `*` without credentials). 1118 * Requested method is in `Allow-Methods`. 1119 * All requested headers are in `Allow-Headers`. 1120 11212. **If all match:** browser caches the result for `Max-Age` seconds, then sends the actual request. 1122 11233. **If any does not match:** browser blocks the actual request, fires a CORS error, and the JavaScript catches a `TypeError: Failed to fetch`. No actual request is sent. 1124 1125### 11.5 The Actual Request 1126 1127If preflight passed, the browser sends the actual request: 1128 1129``` 1130PUT /api/users/123 HTTP/2 1131Host: api.example.com 1132Origin: https://app.example.com 1133Authorization: Bearer abc... 1134Content-Type: application/json 1135 1136{"name": "Joseph"} 1137``` 1138 1139Note: `Origin` is included on the actual request too, not just preflight. 1140 1141The server processes the request and returns the response with CORS headers (the response side ones, not the preflight ones): 1142 1143``` 1144HTTP/2 200 1145Access-Control-Allow-Origin: https://app.example.com 1146Access-Control-Allow-Credentials: true 1147Access-Control-Expose-Headers: X-Total-Count, ETag 1148Vary: Origin 1149Content-Type: application/json 1150ETag: "abc123" 1151X-Total-Count: 1 1152... 1153``` 1154 1155### 11.6 The Nginx Pattern 1156 1157The full nginx CORS handler combining preflight and actual: 1158 1159```nginx 1160location /api/ { 1161 # Preflight handling 1162 if ($request_method = OPTIONS) { 1163 add_header Access-Control-Allow-Origin $cors_origin always; 1164 add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, PATCH, OPTIONS" always; 1165 add_header Access-Control-Allow-Headers "Content-Type, Authorization, X-CSRF-Token" always; 1166 add_header Access-Control-Allow-Credentials "true" always; 1167 add_header Access-Control-Max-Age "86400" always; 1168 add_header Vary "Origin" always; 1169 add_header Content-Length 0; 1170 add_header Content-Type "text/plain charset=UTF-8"; 1171 return 204; 1172 } 1173 1174 # Actual request handling 1175 if ($cors_origin) { 1176 add_header Access-Control-Allow-Origin $cors_origin always; 1177 add_header Access-Control-Allow-Credentials "true" always; 1178 add_header Access-Control-Expose-Headers "X-Total-Count, Server-Timing, ETag" always; 1179 add_header Vary "Origin" always; 1180 } 1181 proxy_pass http://127.0.0.1:9090; 1182} 1183``` 1184 1185The `if` for OPTIONS plus `return` is **safe**. The `if` for `$cors_origin` followed by `add_header` plus `proxy_pass` is also safe because `if` here only conditions on `add_header`, not on `proxy_pass`. The dangerous combination is `if` with content handlers like `proxy_pass` directly inside the `if` block. 1186 1187### 11.7 How To Verify The Whole Flow 1188 1189```bash 1190# Step 1: simulate preflight 1191echo "=== PREFLIGHT ===" 1192curl -sI -X OPTIONS \ 1193 -H "Origin: https://app.example.com" \ 1194 -H "Access-Control-Request-Method: PUT" \ 1195 -H "Access-Control-Request-Headers: authorization, content-type" \ 1196 https://api.example.com/users/123 1197 1198# Expected response with all preflight CORS headers, status 204 1199 1200# Step 2: simulate actual request 1201echo "=== ACTUAL ===" 1202curl -sI -X PUT \ 1203 -H "Origin: https://app.example.com" \ 1204 -H "Authorization: Bearer test" \ 1205 -H "Content-Type: application/json" \ 1206 https://api.example.com/users/123 1207 1208# Expected response with actual response CORS headers 1209``` 1210 1211--- 1212 1213## 12. HOW THESE HEADERS INTERACT 1214 1215The CORS headers form a coherent permission grant. Several specific interactions matter. 1216 1217### 12.1 The Wildcard And Credentials Mutual Exclusion 1218 1219The single most important rule. With `Access-Control-Allow-Credentials: true`, all of these must be specific: 1220 1221* `Access-Control-Allow-Origin`: cannot be `*`. 1222* `Access-Control-Allow-Methods`: cannot be `*`. 1223* `Access-Control-Allow-Headers`: cannot be `*`. 1224* `Access-Control-Expose-Headers`: cannot be `*`. 1225 1226Without credentials, wildcards work everywhere. 1227 1228### 12.2 Vary: Origin Is Required For Dynamic Origin 1229 1230Whenever `Access-Control-Allow-Origin` is set based on the request's Origin header (not hardcoded), `Vary: Origin` must be set so caches do not cross contaminate. 1231 1232```nginx 1233if ($cors_origin) { 1234 add_header Access-Control-Allow-Origin $cors_origin always; 1235 add_header Vary "Origin" always; # ESSENTIAL 1236} 1237``` 1238 1239### 12.3 Preflight Headers vs Actual Response Headers 1240 1241The preflight response and the actual response carry different sets of CORS headers: 1242 1243| Header | On preflight (OPTIONS) | On actual response | 1244|---|---|---| 1245| Access-Control-Allow-Origin | Yes | Yes | 1246| Access-Control-Allow-Credentials | Yes | Yes | 1247| Access-Control-Allow-Methods | Yes | (ignored) | 1248| Access-Control-Allow-Headers | Yes | (ignored) | 1249| Access-Control-Max-Age | Yes | (ignored) | 1250| Access-Control-Expose-Headers | (ignored) | Yes | 1251| Vary: Origin | Yes | Yes | 1252 1253Some headers matter only on preflight, some only on actual. Setting them all on both responses is harmless and simpler to configure. 1254 1255### 12.4 Cache-Control On Preflight Responses 1256 1257The browser caches the preflight response according to `Max-Age`. Browser cache may also be governed by `Cache-Control` for some implementations. Set both: 1258 1259```nginx 1260if ($request_method = OPTIONS) { 1261 add_header Access-Control-Max-Age "86400" always; 1262 add_header Cache-Control "public, max-age=86400" always; 1263 return 204; 1264} 1265``` 1266 1267### 12.5 Authorization Header And Preflight 1268 1269Any request with `Authorization` header triggers a preflight because Authorization is not safelisted. This means JWT based API calls always preflight. Combine with `Max-Age` to mitigate. 1270 1271### 12.6 CORS And Service Workers 1272 1273Service workers can intercept fetch requests and modify CORS behavior. If the page has a service worker, debugging CORS gets harder because the network panel may show different headers than the actual server response. Unregister the service worker during CORS debugging. 1274 1275--- 1276 1277## 13. ASSET CLASS AND USE CASE RECIPES 1278 1279Paste ready blocks per scenario. 1280 1281### 13.1 Public read only API (no credentials) 1282 1283```nginx 1284location /api/public/ { 1285 if ($request_method = OPTIONS) { 1286 add_header Access-Control-Allow-Origin "*" always; 1287 add_header Access-Control-Allow-Methods "GET, HEAD, OPTIONS" always; 1288 add_header Access-Control-Max-Age "86400" always; 1289 return 204; 1290 } 1291 1292 add_header Access-Control-Allow-Origin "*" always; 1293 proxy_pass http://127.0.0.1:9090; 1294} 1295``` 1296 1297### 13.2 Authenticated API with specific frontend origin 1298 1299```nginx 1300# http context 1301map $http_origin $cors_origin { 1302 default ""; 1303 "~^https://app\.example\.com$" "$http_origin"; 1304} 1305 1306# server context 1307location /api/ { 1308 if ($request_method = OPTIONS) { 1309 add_header Access-Control-Allow-Origin $cors_origin always; 1310 add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, PATCH, OPTIONS" always; 1311 add_header Access-Control-Allow-Headers "Content-Type, Authorization, X-CSRF-Token" always; 1312 add_header Access-Control-Allow-Credentials "true" always; 1313 add_header Access-Control-Max-Age "86400" always; 1314 add_header Vary "Origin" always; 1315 return 204; 1316 } 1317 1318 if ($cors_origin) { 1319 add_header Access-Control-Allow-Origin $cors_origin always; 1320 add_header Access-Control-Allow-Credentials "true" always; 1321 add_header Access-Control-Expose-Headers "X-Total-Count, Server-Timing, ETag, Link" always; 1322 add_header Vary "Origin" always; 1323 } 1324 proxy_pass http://127.0.0.1:9090; 1325} 1326``` 1327 1328### 13.3 Multi tenant API with several frontend origins 1329 1330```nginx 1331map $http_origin $cors_origin { 1332 default ""; 1333 "~^https://(app\.|admin\.|partner\.)?example\.com$" "$http_origin"; 1334 "~^https://staging\.example\.com$" "$http_origin"; 1335 "~^https://localhost(:[0-9]+)?$" "$http_origin"; # dev only 1336} 1337``` 1338 1339### 13.4 Embeddable widget for any partner 1340 1341```nginx 1342location /widget/ { 1343 if ($request_method = OPTIONS) { 1344 add_header Access-Control-Allow-Origin "*" always; 1345 add_header Access-Control-Allow-Methods "GET, OPTIONS" always; 1346 add_header Access-Control-Max-Age "86400" always; 1347 return 204; 1348 } 1349 1350 add_header Access-Control-Allow-Origin "*" always; 1351 add_header Access-Control-Expose-Headers "X-Widget-Version" always; 1352 # No credentials, so wildcard origin is fine 1353} 1354``` 1355 1356### 13.5 Web fonts on a CDN subdomain 1357 1358```nginx 1359server { 1360 server_name fonts.example.com; 1361 1362 location ~* \.(woff2|woff|ttf|otf)$ { 1363 add_header Access-Control-Allow-Origin "*" always; 1364 add_header Cross-Origin-Resource-Policy "cross-origin" always; 1365 add_header Cache-Control "public, max-age=31536000, immutable" always; 1366 } 1367} 1368``` 1369 1370Fonts loaded from a different origin require CORS even though they are not "scripted". The `<link rel="preload" as="font">` element and `@font-face` rules both invoke CORS mode. 1371 1372### 13.6 Images served from a different origin 1373 1374```nginx 1375location ~* \.(jpg|jpeg|png|webp|avif)$ { 1376 add_header Access-Control-Allow-Origin "*" always; 1377 add_header Cache-Control "public, max-age=2592000" always; 1378} 1379``` 1380 1381Required if the page uses `crossorigin` attribute on `<img>` or if the image is accessed via `<canvas>` (canvas tainting). 1382 1383### 13.7 Same origin only (no CORS at all) 1384 1385```nginx 1386location /api/internal/ { 1387 # No CORS headers 1388 # Browser blocks all cross origin access by default 1389 proxy_pass http://127.0.0.1:9090; 1390} 1391``` 1392 1393This is appropriate when there is no legitimate cross origin caller. 1394 1395### 13.8 Development mode with permissive localhost 1396 1397```nginx 1398map $http_origin $cors_origin { 1399 default ""; 1400 "~^https?://localhost(:[0-9]+)?$" "$http_origin"; 1401 "~^https?://127\.0\.0\.1(:[0-9]+)?$" "$http_origin"; 1402 "~^https://app\.example\.com$" "$http_origin"; # production 1403} 1404``` 1405 1406Allows http://localhost:5173 (Vite), http://localhost:3000 (Next.js dev), etc, in addition to production. 1407 1408### 13.9 FastAPI sidecar handling CORS entirely 1409 1410```python 1411from fastapi import FastAPI 1412from fastapi.middleware.cors import CORSMiddleware 1413 1414app = FastAPI() 1415 1416app.add_middleware( 1417 CORSMiddleware, 1418 allow_origins=[ 1419 "https://app.example.com", 1420 "https://admin.example.com", 1421 "http://localhost:5173", 1422 ], 1423 allow_credentials=True, 1424 allow_methods=["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"], 1425 allow_headers=["Content-Type", "Authorization", "X-CSRF-Token"], 1426 expose_headers=["X-Total-Count", "Server-Timing", "ETag"], 1427 max_age=7200, 1428) 1429``` 1430 1431When using FastAPI's middleware, nginx should pass through without adding its own CORS headers: 1432 1433```nginx 1434location /api/ { 1435 # Do NOT add CORS headers here; the upstream handles them 1436 proxy_pass http://127.0.0.1:9090; 1437 proxy_set_header Host $host; 1438 proxy_set_header X-Forwarded-Proto $scheme; 1439} 1440``` 1441 1442Mixing nginx and FastAPI CORS produces duplicate headers, which browsers reject. 1443 1444### 13.10 Bubbles cross subdomain pattern 1445 1446For thatwebhostingguy.com wildcard subdomains that need to call back to the main domain: 1447 1448```nginx 1449server { 1450 server_name api.thatdeveloperguy.com; 1451 1452 map $http_origin $cors_origin { 1453 default ""; 1454 "~^https://[a-z0-9-]+\.thatwebhostingguy\.com$" "$http_origin"; 1455 "~^https://[a-z0-9-]+\.thatdeveloperguy\.com$" "$http_origin"; 1456 "~^https://thatdeveloperguy\.com$" "$http_origin"; 1457 } 1458 1459 location / { 1460 if ($request_method = OPTIONS) { 1461 add_header Access-Control-Allow-Origin $cors_origin always; 1462 add_header Access-Control-Allow-Methods "GET, POST, OPTIONS" always; 1463 add_header Access-Control-Allow-Headers "Content-Type" always; 1464 add_header Access-Control-Max-Age "86400" always; 1465 add_header Vary "Origin" always; 1466 return 204; 1467 } 1468 1469 if ($cors_origin) { 1470 add_header Access-Control-Allow-Origin $cors_origin always; 1471 add_header Vary "Origin" always; 1472 } 1473 proxy_pass http://127.0.0.1:9090; 1474 } 1475} 1476``` 1477 1478--- 1479 1480## 14. BUBBLES NGINX REFERENCE BLOCK (PASTE READY) 1481 1482The complete CORS stanza, layered with the previous five frameworks. 1483 1484```nginx 1485# /etc/nginx/nginx.conf (http context) 1486http { 1487 # CORS origin allow list (define once, use site by site) 1488 map $http_origin $cors_origin { 1489 default ""; 1490 "~^https://(app\.|admin\.)?example\.com$" "$http_origin"; 1491 "~^https://partner\.example\.com$" "$http_origin"; 1492 } 1493} 1494``` 1495 1496```nginx 1497# /etc/nginx/sites-available/api.example.com 1498 1499server { 1500 listen 443 ssl;