A CORS preflight is answered wherever a CORS header is written

[TobiiNT]

OPTIONS matched no route on this server. It fell through to whatever the host had, and a host
with a deny-everything fallback policy answered 401 - on the discovery documents, on the JWKS,
and on the RFC 9728 metadata the resource server serves.

Measured against a running deployment, 2026-09-08:

OPTIONS /.well-known/openid-configuration        -> 401    (GET -> 200, ACAO: *)
OPTIONS /.well-known/oauth-authorization-server  -> 401    (GET -> 200, ACAO: *)
OPTIONS /.well-known/jwks.json                   -> 401    (GET -> 200, ACAO: *)
OPTIONS /token                                   -> 401    (POST -> 400, ACAO: *)

Why this is worth a release, given nothing was broken that day

A browser preflights only once a request stops being simple, and the OIDC client libraries fetch
these with CORS-safelisted headers alone. So the defect waits for the first client that adds a
request header of its own.

What that client is shown is not a 401. It is the browser's generic "no
Access-Control-Allow-Origin header is present", pointing at CORS configuration that is in fact
correct. The cost is the hour spent looking there. That is how this was found: chasing exactly that
message on a deployment whose CORS was right.

Authenticating a preflight cannot be right in any case. The browser sends it with no credentials by
specification, so there is nothing in it to authenticate.

The rule

Every route that writes Access-Control-Allow-Origin answers OPTIONS, and no other route
does. That is the two discovery documents, the JWKS, the three /.well-known catch-alls,
/token, and both forms of the protected-resource metadata.

The boundary is held from both sides, because the permissive half is the half somebody would
later read as a licence: /authorize MUST have no CORS at all (OAuth 2.1 §3.2, RFC 9700 §2.6), and
a change that made every OPTIONS succeed would have taken that with it. There is a test for the
route that must not be touched, not only for the ones that must.

Three decisions

The requested headers are echoed, not published as a fixed list. These endpoints are read
without credentials and already answer * with no Access-Control-Allow-Credentials, so the
browser sends no ambient authority and naming back what was asked grants nothing they do not
already grant to anyone. A fixed list would make the next header a client adds the next incident,
which is precisely how this one arrived.

The /.well-known catch-alls answer the preflight too, and still 404 after it. That reads
backwards until you see the alternative: a refused preflight tells a browser client only "CORS",
while an answered one lets the real request reach the bare 404 the route exists to give - the
answer that lets a client try its next probe, which is the whole reason that route is there.

204 and not 200: there is nothing to send, and a preflight body is a body every client
discards.

A comment that had become false

DiscoveryEndpoints' remarks ended "these are simple cross-origin GETs, so no preflight is
involved". That was true of the clients we had rather than of the endpoint. Corrected in place,
with what it cost.

Red-first

The three document routes and /token fail without the change; the control - a host route that
never asked for CORS - passes before and after.

Failed!  - Failed: 4, Passed: 1, Total: 5      (before)
Passed!  - Failed: 0, Passed: 5, Total: 5      (after)

Checks

dotnet build Boltway.slnx      0 warnings
python3 scripts/check-dashes.py   0 in prose or comments
dotnet test Boltway.slnx       14 of 15 suites green, 2618 tests

The one red suite is Boltway.Storage.PostgreSql.Tests, which fails rather than skips without a
real server and has none in this container. That is the documented behaviour, not a regression: a
storage suite that skips itself is green in exactly the situation where it measured nothing.

Version

<Version> 0.5.1 -> 0.5.2 and PackageValidationBaselineVersion 0.5.0 -> 0.5.1, which
The_api_compatibility_baseline_is_the_previous_released_version holds to CHANGELOG's second
heading. Nothing a consumer compiles against moved; the version turns because the behaviour did.

Deploying it

No Boltway tag is needed. AUTH_TAG=main in the deploy workflow, because this repository has no
release process, so the next connector deploy carries this once ci has pushed the image.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HwL9CdWHruodcVHeQAKtGR

---

Generated by Claude Code