corswhy

Find which response header rejects a browser's CORS preflight before you change server code.

⚡ Quickstart • 🔍 How it works • 📖 Examples • 💬 FAQ

[!TIP] With the included demo server running, inspect its 401 route without a global install. Requires Node.js 20 or newer:

npx --yes github:Arthur031221/corswhy http://127.0.0.1:18765/auth --origin http://localhost:5173 --method POST --header authorization,content-type --credentials include

Why corswhy

Browsers send an OPTIONS preflight before some cross-origin requests. If authentication blocks OPTIONS, or a response does not allow the requested origin or headers, the browser reports a generic CORS error before the actual request reaches your handler.

A raw OPTIONS response shows headers but leaves you to compare them with the browser's origin, method, and requested headers. corswhy runs those checks and reports which one failed, with a repair hint, before you change server code.

Features

• 🔎 Checks the preflight response: Reports the status, allowed origin, credentials when requested, method, and requested headers.
• 📨 Sends browser preflight fields: Includes Origin, Access-Control-Request-Method, and the header names supplied with --header.
• 🛑 Sends only OPTIONS: It never sends the actual request or a request body.
• ⚡ Skips unnecessary probes: A GET, HEAD, or POST without named unsafe headers needs no preflight, so corswhy sends nothing.
• 🧾 Explains failed checks: Shows each check and a repair hint for the first failure.
• 🗂 Supports scripts: Use --json for a structured report.

Quickstart

Requires Node.js 20 or newer. From a checkout, install with npm install -g .. To run from GitHub without a global install, use npx github:Arthur031221/corswhy before the URL and options shown below.

With a local API at http://localhost:8000/api that returns 401 to OPTIONS, run:

corswhy http://localhost:8000/api \
  --origin http://localhost:5173 \
  --method POST \
  --header authorization,content-type \
  --credentials include

OPTIONS 401  http://localhost:8000/api
Origin http://localhost:5173  Method POST

FAIL  OPTIONS status     401
FAIL  Allow origin       (missing)
FAIL  Allow credentials  (missing)
PASS  Allow method       (safelisted method)
FAIL  Allow headers      (missing)

Fix: Let OPTIONS reach the CORS handler without authentication.
Browser behavior for private networks, cookies, and extensions was not tested.

Examples

Start the included fixture server in another terminal:

node demo/server.js

Its /ok route returns the required CORS response headers. A GET without named unsafe headers does not need a preflight, so corswhy sends no request.

corswhy http://127.0.0.1:18765/ok \
  --origin http://localhost:5173 \
  --method POST \
  --header authorization,content-type
OPTIONS 204  http://127.0.0.1:18765/ok
Origin http://localhost:5173  Method POST
PASS  OPTIONS status     204
PASS  Allow origin       http://localhost:5173
PASS  Allow method       POST
PASS  Allow headers      authorization, content-type
Preflight checks passed. The actual response was not tested.
Browser behavior for private networks, cookies, and extensions was not tested.

corswhy http://127.0.0.1:18765/ok --origin http://localhost:5173

No preflight expected for these inputs. Supply header names from the browser preflight if it sent one.
Actual response CORS checks were not tested.

How it works

corswhy sends OPTIONS with Origin, Access-Control-Request-Method, and, when supplied, the names in Access-Control-Request-Headers. It checks the response status, allowed origin, credentials when requested, method, and headers. It does not send POST, PUT, DELETE, or a request body.

The checks follow the Fetch standard's CORS protocol. The MDN preflight guide explains why browsers send OPTIONS before certain cross-origin requests.

FAQ

Contributing

See CONTRIBUTING.md for local development. To report an issue, open an issue.

License

MIT licensed. See LICENSE.