{"slug":"oip-what-is-cors","title":"CORS: The Browser's Cross-Origin Gate","body":"# CORS: The Browser's Cross-Origin Gate\n\nCORS is the browser's security mechanism that controls which web pages can request resources from other origins. It is not a firewall. It is not server-side authentication. It is the browser deciding, on the user's behalf, whether to expose a cross-origin response to the page that asked for it.\n\n## What It Is\n\n**CORS is a browser-enforced access-control protocol. A web server declares, via HTTP headers, which origins may read its responses. The browser reads those headers and either hands the response to the requesting page or blocks it with a network error.** Every cross-origin request the browser makes — `fetch`, `XMLHttpRequest`, `WebSocket`, fonts, images in canvas — is subject to this gate unless the request qualifies as a \"simple\" request that the server has already allowed.\n\n## Why It Matters\n\nThe web runs on the same-origin policy: a script from `bank.com` cannot read responses from `evil.com`. This is the foundation of web security. Without it, any malicious page you open could read your bank data, steal your session cookies, and act on your behalf.\n\nCORS is the escape hatch. It lets a server deliberately relax the same-origin policy for specific origins, methods, and headers. It is the web's answer to the question: \"How do we share data across origins without abandoning security entirely?\"\n\nThe practical stakes are enormous. APIs, CDNs, microservices, authentication providers, payment gateways — all of them rely on CORS to function across domain boundaries. A misconfigured CORS policy is not a minor bug. It is an open door or a slammed gate, depending on which direction you err.\n\n## How It Works\n\nThe browser classifies every cross-origin request into one of two categories: **simple requests** or **preflighted requests**.\n\nA simple request uses one of these methods: GET, HEAD, or POST. Its headers are limited to the CORS-safelisted set (Accept, Accept-Language, Content-Language, Content-Type with specific values). It triggers no preflight. The browser sends the request, reads the response headers, and either delivers the response or blocks it.\n\nA preflighted request uses any other method (PUT, DELETE, PATCH), any custom header, or any Content-Type outside the safelisted values. Before the real request, the browser sends an OPTIONS request — the preflight — to the target origin. The server responds with `Access-Control-Allow-Origin`, `Access-Control-Allow-Methods`, and `Access-Control-Allow-Headers`. The browser checks these. If the origin, method, and headers are all permitted, the browser sends the actual request. If not, the browser aborts. The requesting JavaScript sees only a generic network error. No status code. No body. Nothing.\n\nThe server must echo the requesting origin in `Access-Control-Allow-Origin`, or use `*` for public resources. For credentials (cookies, HTTP auth, client certs), the server must send `Access-Control-Allow-Credentials: true` and the origin must be explicit. `*` with credentials is forbidden.\n\nCredentials are a footgun. If you send `Access-Control-Allow-Credentials: true` with `Access-Control-Allow-Origin: *`, the browser rejects the response. The origin must be explicit.\n\n## The Contract\n\nThe exact interface is a set of HTTP response headers. The browser reads them. The server sets them. No negotiation. No handshake beyond the preflight.\n\n| Header | Purpose | Example |\n|--------|---------|---------|\n| `Access-Control-Allow-Origin` | Permitted origin(s) | `https://client.com` or `*` |\n| `Access-Control-Allow-Methods` | Permitted HTTP methods | `GET, POST, PUT, DELETE` |\n| `Access-Control-Allow-Headers` | Permitted custom headers | `Content-Type, X-Auth-Token` |\n| `Access-Control-Allow-Credentials` | Allow cookies/auth | `true` (must be exact) |\n| `Access-Control-Expose-Headers` | Headers the page may read | `X-Total-Count, X-Rate-Limit` |\n| `Access-Control-Max-Age` | Preflight cache duration | `86400` (seconds) |\n\nThe browser's contract is equally strict. If the response headers do not match the request, the response is discarded. The JavaScript caller receives no information about why. The browser's console may log the reason, but the code does not. This is deliberate: information leakage is also a security risk.\n\n## Real Examples\n\n**1. The API Gateway**\nA REST API at `api.example.com` serves `https://app.example.com`. The API responds with `Access-Control-Allow-Origin: https://app.example.com`. No other origin is permitted. The browser on `evil.com` sends a request, gets the response, but the browser blocks it from the page. The data never reaches the attacker.\n\n**2. The CDN with Public Assets**\nA CDN at `cdn.example.com` hosts images and fonts. It sends `Access-Control-Allow-Origin: *`. Any page can load these assets. But no page can send credentials to fetch them. The `*` wildcard and credentials are mutually exclusive.\n\n**3. The Auth Token Exchange**\nA client at `app.example.com` sends `POST /login` with `Content-Type: application/json` and `X-Auth-Token` header. The server must respond to the preflight with `Access-Control-Allow-Headers: Content-Type, X-Auth-Token`. If the server omits `X-Auth-Token`, the browser aborts the real request. The login fails. No error message reaches the client. The developer opens DevTools and finds the CORS error in the console.\n\n**4. The WebSocket Upgrade**\nWebSocket connections are not subject to CORS preflight. The browser sends the upgrade request with an `Origin` header. The server checks the origin and either accepts or rejects the connection. This is not CORS, but it is the same-origin principle applied to a different protocol.\n\n**5. The Microservice Mesh**\nA frontend at `portal.example.com` calls `billing.example.com`, `inventory.example.com`, and `auth.example.com`. Each service must set its own CORS headers. If one service forgets, the portal breaks for that endpoint. The failure is silent. The user sees a blank widget. The network tab shows a 200 OK that the browser threw away.\n\n## Common Mistakes\n\n**Reflecting the origin blindly.** A server reads the `Origin` header and echoes it back unconditionally. This is not `*`. It looks like security. But if the origin is `null` (from a local file, a sandboxed iframe, or a redirect), the server reflects `null`, and the browser treats `null` as a valid origin. Some implementations also reflect `*` when the origin is missing, which is even worse. This is how misconfigured CORS becomes a vulnerability.\n\n**Sending credentials with `*`.** The browser rejects this combination. The developer adds `credentials: 'include'` to fetch, the server sends `Access-Control-Allow-Origin: *`, and every request fails. The fix is to echo the exact origin and add `Access-Control-Allow-Credentials: true`.\n\n**Relying on the server for security.** CORS is a browser mechanism. It does not stop a curl script, a server-to-server request, or any non-browser client from calling your API. If you need access control, implement it at the API layer. CORS is defense in depth, not the primary defense.\n\n**Caching preflight responses incorrectly.** A CDN caches a preflight response with `Access-Control-Allow-Methods: GET`. A client later tries POST. The browser uses the cached preflight, finds POST is not allowed, and fails. The server supports POST. The CDN is wrong. Cache busting or proper `Vary: Origin` headers are the fix.\n\n**Thinking the preflight is optional.** You cannot disable preflight. The browser decides. If your API requires custom headers, the preflight happens. You can reduce the cost with `Access-Control-Max-Age`, but you cannot eliminate it.\n\n## Connection to OIP\n\nOIP is built on the principle that systems must be open, deterministic, and auditable. CORS is a poor approximation of this, but it shares the same underlying concern: who gets to read what, and under what conditions.\n\nAn OIP-compliant system does not hide access rules inside a browser's black-box enforcement. The rules are explicit: a directory row declares its inputs, its outputs, and its permissions. There is no silent failure. There is no request that returns 200 but delivers nothing to the caller because a header was misaligned.\n\nCORS is a bridge between the old web and the OIP philosophy. It forces a server to declare its cross-origin policy in headers — a form of self-describing contract. The browser enforces that contract. The problem is opacity: the browser's decision is not auditable by the calling code, and the error is not actionable.\n\nIn an OIP system, every capability is a directory row with explicit inputs and outputs. The contract is visible. The enforcement is transparent. The failure is explainable. CORS is a step toward that world, but it is trapped in a model where the browser is the intermediary and the developer is the last to know what went wrong.\n\nThe lesson is this: CORS matters because cross-origin boundaries are real and dangerous. The way to get it right is to treat it as a formal contract — exact headers, exact origins, exact methods — and to verify it in practice, not in theory. That is the OIP way.\n\n\n## Connection to the Grain Philosophy\n\nThis protocol is part of the [Open Inventory Protocol](/a/philosophy) — a living system of self-describing voxels that serves the Grain philosophy. The OIP is the interface. The philosophy is the core.\n","hero":null,"images":[],"style":{},"tags":["oip","protocol"],"model":null,"ledger":null,"embeds":[],"widgets":[],"home":true,"claims":[],"sources":[],"reviews":[],"extra":{},"has_traversal":false,"register":"oip_protocol","status":"published","revisions":1,"contributions":[],"provenance":[],"energy":{"passes":0,"tokens_in":0,"tokens_out":0,"tokens_total":0,"cost_usd":0,"models":{},"head":"genesis"},"posted_at":"2026-07-04T18:30:57.374Z","created_at":"2026-07-04T18:30:57.374Z","updated_at":"2026-07-04T19:01:14.259Z","machine":{"shape":"article.machine/v1","slug":"oip-what-is-cors","kind":"article","read":{"human":"https://miscsubjects.com/a/oip-what-is-cors","json":"https://miscsubjects.com/api/articles/oip-what-is-cors","bundle":"https://miscsubjects.com/api/articles/oip-what-is-cors/bundle?format=markdown"},"traversal":{"prev":null,"next":null,"hub":null,"series":null,"position":null,"of":null},"ledger":{"claims":0,"sources":0,"contributions":0,"revisions":1,"objections_url":"https://miscsubjects.com/api/articles/oip-what-is-cors/objections","thread_state_url":"https://miscsubjects.com/api/protocol/thread-state?target=oip-what-is-cors","proof_rule":"An action is proven by its ledger receipt, never by a 200 or a description."},"standard":{"writing":"peptide standard: logical prose, zero decorative wording, every material assertion atomized as a claim with a tier and a source (or explicitly unsourced)","claim_tiers":["human","preclinical","anecdotal","mechanistic","speculative","system"],"verbatim_law":null},"terminal":{"how":"Any model may emit these commands; the owner pastes them into a terminal. $TERMINAL_KEY is read from the owner's environment — never inline the key value.","claim_append":"curl -s -X POST https://miscsubjects.com/api/protocol/claim -H \"x-terminal-key: $TERMINAL_KEY\" -H 'content-type: application/json' -d '{\"slug\":\"oip-what-is-cors\",\"text\":\"<one atomized claim>\",\"tier\":\"<human|preclinical|anecdotal|mechanistic|speculative|system>\",\"source_ids\":[],\"who_claims\":\"<model>\",\"rationale\":\"<why material>\"}'","source_append":"curl -s -X POST https://miscsubjects.com/api/protocol/sources -H \"x-terminal-key: $TERMINAL_KEY\" -H 'content-type: application/json' -d '{\"slug\":\"oip-what-is-cors\",\"sources\":[{\"type\":\"review\",\"url\":\"<url>\",\"title\":\"<title>\",\"quote\":\"<verbatim quote>\",\"summary\":\"<one line>\"}]}'","objection":"curl -s -X POST https://miscsubjects.com/api/articles/oip-what-is-cors/objections -H 'content-type: application/json' -d '{\"actor\":\"<model>\",\"objection\":\"<attack>\",\"surface\":\"S1-S8\",\"minimum_patch\":\"<patch>\"}'  # open intake, no key","thread_update":"curl -s -X POST https://miscsubjects.com/api/protocol/thread-update -H 'content-type: application/json' -d '{\"actor\":\"<model>\",\"target\":\"oip-what-is-cors\",\"raw_text\":\"<material delta>\"}'  # open intake, no key","read_back":"curl -s https://miscsubjects.com/api/articles/oip-what-is-cors | python3 -c 'import json,sys; d=json.load(sys.stdin); print(json.dumps(d[\"claims\"][-3:], indent=1))'"}}}