The Root CORS Analysis.

Recently, to let a hosted web app talk to servers we control on other hosts, the project I work on introduced an allowed-origins list. The discussion around it was enlightening in the way that only production incidents are. It still surprises me how misunderstood CORS protections are among engineers who do not work directly with core web or browser technologies. But it is also understandable. Most of the time it is set-and-forget. The browser handles it for you, and the whole mechanism hides behind a safe-feeling checkbox.

1. What CORS actually is

Cross-Origin Resource Sharing is an HTTP-header mechanism that lets a server tell the browser which origins are allowed to read a response. The canonical definition is from MDN:

CORS is an HTTP-header based mechanism that allows a server to indicate any origins (domain, scheme, or port) other than its own from which a browser should permit loading resources.

That definition quietly contradicts a few assumptions people bring to CORS. The ones that bite hardest:

1. CORS is not server-side access control. The request still reaches your server. An attacker's page can POST to your endpoint all day; the browser only refuses to expose the response to the calling script. PortSwigger puts it bluntly in their CORS research: "CORS is not a protection against cross-origin attacks such as cross-site request forgery (CSRF)". The Express cors package README says the same thing in plainer English: any HTTP client (curl, Postman, another server) can call your API regardless of CORS settings. Authentication and authorization remain your job, server-side, unconditionally.

2. CORS is not applied to non-browser clients. curl, CLIs, SDKs, server-to-server calls: none of them send an Origin header, and none of them enforce CORS. If your security story depends on the browser "blocking" bad actors, you have no story at all for scripts.

3. CORS is not implemented by your server. The browser is the enforcer. Your server emits headers; the browser decides what to expose. That single fact explains most "works in curl, broken in the browser" mysteries.

2. When preflight fires, and why

The browser sends Origin on cross-origin requests and preflights the ones that can cause side effects. Per MDN, a request triggers an OPTIONS preflight when it is not "simple": methods other than GET, HEAD, or POST; content types other than application/x-www-form-urlencoded, multipart/form-data, and text/plain; or any non-safelisted custom header (an Authorization header is the one that bites most API engineers). application/json POST is not simple, which is why every JSON API bumps into preflight on day one.

Rules worth memorizing, all from MDN and the Fetch spec:

• Access-Control-Allow-Origin: * cannot be combined with credentials. MDN: "The server must specify an origin in the value of the Access-Control-Allow-Origin header, instead of specifying the * wildcard" when responding to credentialed requests. The browser will block the response outright.
• If you reflect a single origin dynamically (allowlist matching), you must send Vary: Origin. Otherwise shared caches (CDNs, proxies) can serve a cached response stamped for one origin to a different one: cache poisoning. MDN: "the server should also include Origin in the Vary response header."
• Origin can serialize as null. Sandboxed iframes, data: URLs, about:blank, and some redirects send Origin: null. Whitelisting null is one of PortSwigger's canonical CORS misconfigurations: an attacker can trigger it from a sandboxed page. Treat null as untrusted unless you have a concrete reason.
• Preflight caching (Access-Control-Max-Age) defaults to 5 seconds per MDN; browsers cap it internally. Raising it reduces round trips for chatty clients but lengthens the window in which a config change does not take effect for clients with cached preflights.
• Middleware ordering matters. If your auth middleware runs before the CORS handler, it can reject the OPTIONS preflight before any CORS headers exist, and the browser masks real 4xx/5xx errors as generic CORS failures when the error response lacks CORS headers. Answer OPTIONS before auth, and emit CORS headers on error paths too.

3. WebSockets do not play by these rules

This is the section most server-side engineers never get taught. RFC 6455 (The WebSocket Protocol, 2011) section 1.6 explains that Origin exists to protect against unauthorized cross-origin use of a WebSocket server by scripts: the server is informed of the origin generating the connection request and may reject it with an HTTP error. For browser clients that is not optional. Section 4.1 step 8 requires the handshake to "include a header field with the name Origin" when the request comes from a browser client, and section 4.2.1 item 7 says a connection attempt lacking the header should not be interpreted as coming from a browser client. Non-browser clients may omit it.

Why does this matter? Because WebSockets are not subject to the Same-Origin Policy. A malicious page can open a WebSocket to any host, cookies go along for the ride, and CORS never intervenes. The only server-side defense is to validate Origin at the handshake. RFC 6455 section 10.2:

Servers that are not intended to process input from any web page but only for certain sites SHOULD verify the Origin field is an origin they expect. If the origin indicated is unacceptable to the server, then it SHOULD respond to the WebSocket handshake with a reply containing HTTP 403 Forbidden status code.

The attack this defends against has a name: Cross-Site WebSocket Hijacking (CSWSH). The OWASP WebSocket Security Cheat Sheet walks the scenario: user logs into your app, session cookie established; user later visits a malicious site; the malicious site opens a WebSocket to your app; the browser sends the cookies automatically; the server accepts and the attacker gets live, authenticated access. Real-world case cited by OWASP: the 2023 Gitpod CSWSH vulnerability, where insufficient origin validation allowed full account takeover.

OWASP's prescribed defense, verbatim:

Validate the Origin header on every handshake. Always use an explicit allowlist of trusted origins. Browsers include this header and malicious JavaScript cannot override it.

Use an allowlist, not a denylist. No wildcards, no substring matching. Compare scheme, host, and port.

The OWASP cheat sheet adds the adjacent defenses: prefer wss:// over ws:// in production, use SameSite cookies to blunt cross-site cookie transmission, use CSRF tokens in the handshake for apps that already use CSRF protection, and validate sessions on long-lived connections (re-validate every ~30 minutes; close on expiry).

One nuance worth keeping straight: TLS kills DNS rebinding but not CSWSH. Over wss://, a rebinding attacker's certificate validation fails, so the rebinding vector dies at the handshake. CSWSH does not involve rebinding at all: the attacker connects to your real host, and TLS authenticates the server to the browser, not the requesting origin to the server. That is why origin validation stays mandatory even on wss://.

4. The attacks you are actually defending against

CORS configuration is only sensible once you know the threat model. For a server-side engineer, four attacker stories matter:

The messy one for local/self-hosted services is DNS rebinding, because the naive fix ("allow requests whose Origin matches Host") is exactly what the attack exploits. After a rebind, Origin: http://evil.com and Host: evil.com match. The robust rule is to validate the Host against identities the server derives from its own OS (interface table, hostname, mDNS), never by resolving the Host header. If you implement "allow any Host that resolves to one of my IPs", you have reimplemented the attack, because the attacker's host does resolve to your IP during the attack.

There is a second layer worth knowing about, because it changes the calculus for local-first apps. The browser platform now ships its own gate for public-to-private traffic. The feature formerly known as Private Network Access (PNA, originally CORS-RFC1918) is shipping as Local Network Access (LNA): as of 2026, in Chromium (Chrome and Edge) it is the permission-prompt model gated behind fetch(url, { targetAddressSpace: "local" }) (Chrome blog, June 2025), and in Firefox it rolled out through 2026 (restrictions on by default for all users from Firefox 153). Safari has not shipped it. Chrome split the permission into local-network and loopback-network in 145, and WebSocket traffic gained LNA coverage in Chromium 147, so exact coverage depends on the version. Spec-wise it remains a WICG proposal (private-network-access) rather than a Fetch-spec section. Treat browser support as uneven, and date-stamp your assumptions.

5. The levers you can pull

Here's every lever on the board and what it costs you:

The one default I would fight to keep out of the box is the wildcard. * is an escape hatch, not a default. Some local-first servers ship it for "make it work" support; if you support it, warn loudly, document it as discouraged, and keep an exact-origin path documented. In the incident, the * workaround users found on a forum was the answer that kept them stuck on an insecure default.

6. Which levers are worth your time

The question this post is trying to answer: given my app, my audience, my deployment, which levers should I actually pull? Work through these in order. Most of the answers will be "no", and each one keeps you out of a category of support tickets.

Q1. Do browsers talk to your server at all? If your consumers are CLIs, SDKs, server-to-server integrations, or mobile apps: no CORS work is warranted. CORS is a browser response-sharing protocol. Adding headers anyway does not make your API "more open", it makes it less safe by widening browser-side exposure for no benefit.

Q2. Cookies or tokens? Cookie-based auth is where CORS gets expensive: credentialed requests need exact-origin ACAO (never *), Access-Control-Allow-Credentials: true, Vary: Origin, plus CSRF story (see the OWASP CSRF Prevention Cheat Sheet). Token-based auth (Authorization header) still triggers preflight for the custom header, but the credentials rules vanish and CSRF mostly does too. If you can move to tokens, you spend less time in CORS land.

One LAN-specific trap: cross-site credentialed cookie flows require SameSite=None; Secure, and Secure cookies cannot be set over plain http:// (localhost excepted). So on http://192.168.x.x, cookie-authed cross-origin calls effectively cannot work at all. If your LAN-facing deployment is plain HTTP, budget for token auth or TLS; do not plan on cookies.

Q3. Who can reach the port?

• Loopback only: the browser gate (loopback exemptions, LNA) already protects you; keep origin handling minimal (allow loopback, allow desktop webview schemes).
• LAN (your own hosts, mDNS, VPN): build the zero-config same-origin rule with Host validation (section 7). No config burden on users, rebinding still rejected.
• Public / remote names (DynDNS, Tailscale, tunnels, hosted frontends): explicit allowlist, authoritative when set, plus TLS.

Q4. Do you serve WebSockets? Then handshake Origin validation is mandatory, full stop. This is non-negotiable per RFC 6455 and OWASP; it is the cheapest CSWSH defense that exists.

Q5. What does a misconfiguration cost you? This is the ignored question in most CORS tutorials. For a public SaaS, a permissive * on an authenticated endpoint is a data-exfiltration vulnerability: that is an incident. For a home-lab dashboard behind a LAN, the worst realistic outcome of an over-permissive origin is usually an annoying support thread, but the worst outcome of a misjudged hardening is a broken dashboard for every user, which is exactly what happened in our case. Decide which failure you can't live with before you pick a default.

7. The zero-config LAN pattern

The pattern that ended the incident is worth stealing for any local-first server: allow same-origin requests when the request's Host is one of the server's own identities, derived from the OS, never from DNS. Browsers make this free: when a user opens http://192.168.1.17:8080, the browser sends Origin: http://192.168.1.17:8080 and Host: 192.168.1.17:8080. Origin is Host by construction. The server only needs to recognize itself, safely. The only wrinkle: Origin always carries its scheme, while Host does not, so the comparison must normalize both sides before it can ever match.

def is_origin_allowed(origin, host, scheme, allowlist):
    if not origin:                            # curl, CLIs, SDKs
        return True                           # gate by auth, not by Origin
    if allowlist:
        return origin in allowlist            # explicit intent is authoritative;
                                              # note: a custom allowlist disables the
                                              # zero-config fallbacks below by design

    # Normalize both sides to scheme + host:port before comparing
    req_origin = parse_origin(origin)         # e.g. "http://192.168.1.17:8080"
    expected_origin = f"{scheme}://{host}"

    if is_loopback(host):
        return req_origin == expected_origin  # Also matches registered local webview schemes (app://, file://, etc.)
    if host in server_self_set():             # OS interfaces, hostname, mDNS
        return req_origin == expected_origin
    return False                              # reject; log origin + remediation hint

Where server_self_set() is:

• every local interface address (IPv4 and IPv6) from the OS interface table (getifaddrs / GetAdaptersAddresses), not just the bind address, so Wi-Fi, Ethernet, VPN and vLAN interfaces all work;
• the machine hostname and hostname.local (mDNS names are link-local by definition and cannot be forged through public DNS);
• the configured bind host when non-wildcard.

Anything not in that set falls through to the explicit allowlist: DynDNS names, Tailscale MagicDNS, custom reverse-proxy hostnames, and so on. The same check runs on the WebSocket Upgrade handshake.

A few implementation details are easy to get wrong:

• Empty Origin must stay allowed. The code path that extracts Origin must not turn absence into rejection, or you have re-broken every CLI and SDK user. Test it explicitly.
• Refresh the self set. Compute it at startup and re-enumerate on config change and on a short TTL (60 seconds is a sane default), or on interface-up events where the platform exposes them. A user who connects a VPN after the server started should see the new interface appear without a restart. Serve an immutable snapshot to worker threads instead of a shared mutable set.
• Normalization deserves unit tests. Default ports (:80/:443 omitted), hostname case, trailing dots (mybox.local.), IPv6 zone IDs, IPv4-mapped IPv6, and the wss/ws vs https/http scheme mapping all need explicit tests. This is where "it worked on my machine" bugs are born. The pseudocode above collapses the whole comparison to req_origin == expected_origin precisely so that every one of these cases has exactly one place to be tested and one place to be wrong.
• Proxy boundary. If a reverse proxy or tailscale serve terminates TLS, the upstream server sees plain HTTP and must recover the original scheme from X-Forwarded-Proto. Honor that header only from known, configured proxies, or do not read it at all. A client spoofing X-Forwarded-Proto: https over plain HTTP changes the scheme inside your origin comparison, which is a trust boundary you do not want to hand to arbitrary clients.

8. Rollout discipline

The post-mortem of the incident was not "we had the wrong origin check." It was "we shipped a breaking change without flagging it, without a migration path, and without a discoverable way out." The security change was intentional, correct, and released as an unannounced breaking change anyway. That is a process failure, not a CORS failure, and it is the most transferable lesson in this post.

When you change origin behavior, ship in stages. In practice the first two often land in the same PR; the order is what matters, not the ceremony:

1. Diagnosis release: add actionable logging. When a request is rejected, log the rejected origin plus a remediation hint. That single change turns support threads into self-service and tells you how many real users are affected before you break anything.
2. Config release: land the allowlist surface (config file, CLI, admin API), apply it live without a restart, and make explicit configuration authoritative. Give the conscientious users a knob before you take away the permissive default.
3. Restore-UX release: add the zero-config same-origin rule (the self set) so legitimate LAN users get their pre-hardening experience back, with the security backstop already in place.
4. Only then, harden the default. With docs, migration guides, GUI knobs, and loud warnings on non-loopback binds already shipped. Hardening should be a visible, reversible settings change, not a surprise.

Ground rules that apply across all four:

• Never ship a relaxation without its backstop.
• Keep knob semantics stable across releases. Do not rename allowed_origins, do not flip precedence mid-cycle, do not change what "same-origin" means between versions. Change defaults and validation only, each with a loud notice.
• Test the browser path and the CLI path. Test the "user who only set host=0.0.0.0" case. Test "VPN connected after start." Test the rebinding regression (origin == host == evil.com). If those four tests are in CI, the worst incidents in this space stop being possible.

9. TL;DR

• CORS is a browser opt-in for reading responses. It is not access control, it does not apply to scripts, and it is enforced by the browser, not your server.
• * + credentials never works. Reflect origins only from an allowlist, and send Vary: Origin when you do.
• WebSockets bypass SOP: validate Origin at the handshake, per RFC 6455 and OWASP, or you have CSWSH.
• DNS rebinding defeats naive Origin == Host checks; validate Host against OS-derived identities, never by resolving it.
• The zero-config LAN pattern (same-origin + self set) is the sweet spot for local-first servers. Explicit allowlist wins whenever it is set — and by winning, it disables the zero-config fallbacks, so a custom allowlist must list every origin you still want to reach.
• Browsers are slowly becoming a gate themselves (LNA in Chrome/Edge/Firefox; Safari lags). Date-stamp your assumptions and keep server-side validation as the backstop.
• For a public SaaS, a loose * is a breach; for a LAN tool, a misjudged hardening is an outage. Decide per context, and roll out origin changes like the breaking changes they are.