--- name: cors-tighten classification: convoy success_metric: | No `pages/api/**/*.js` handler ships an `Access-Control-Allow-Origin: *` header (or any other wildcard CORS header), AND no handler ships a same-origin redundant OPTIONS preflight handler. Browser-issued cross-origin POSTs to the auth surface return a CORS error instead of succeeding. `npm run test:smoke` continues to pass (the smoke spec is same-origin via the Vercel preview URL, so it is unaffected). skip: - role-design-system-auditor - role-a11y-auditor - role-ux-reviewer - role-ia-architect status: queued created: 2026-05-24 parent: ship-readiness addresses: P0 #5 (PARTIAL → RESOLVED) depends_on: - fix-auth-bypass (Brief 4, shipped — login + register CORS removal is the precedent) --- # Convoy: cors-tighten Drop wildcard `Access-Control-Allow-Origin: *` from the remaining `pages/api/**` handlers. The `fix-auth-bypass` Brief 4 already cleaned login + register; the documented follow-up was just `pages/api/auth/verify.js`, but a fresh audit (parent grep at convoy creation, 2026-05-24) found **24 files** repo-wide carrying the identical scaffolded pattern: ```js // Set CORS headers res.setHeader('Access-Control-Allow-Origin', '*'); res.setHeader('Access-Control-Allow-Methods', '...'); res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization'); // Handle preflight requests if (req.method === 'OPTIONS') { res.status(200).end(); return; } ``` The 24 files (spot-checked against `pages/api/cards/search.js`, `pages/api/collections.js`, `pages/api/user/avatar.js` — all identical except for the `Allow-Methods` verb list): ``` pages/api/admin/index.js pages/api/auth/verify.js pages/api/cards/[id]/ownership.js pages/api/cards/owned.js pages/api/cards/search.js pages/api/collections.js pages/api/collections/[identifier].js pages/api/collections/[identifier]/activity.js pages/api/collections/[identifier]/cards.js pages/api/collections/[identifier]/permissions.js pages/api/collections/[identifier]/thumbnails.js pages/api/community/collections.js pages/api/favorites.js pages/api/invite/accept.js pages/api/invite/decline.js pages/api/public/collections.js pages/api/user/avatar.js pages/api/user/avatar/generate.js pages/api/user/delete.js pages/api/user/password.js pages/api/user/profile.js pages/api/user/settings.js pages/api/user/stats.js pages/api/users/search.js ``` ## Why now P0 #5 in `.convoys/ship-readiness.md` was marked PARTIAL on 2026-05-23 because Brief 4 only fixed the auth surface (login, register) under that convoy's narrow auth-bypass mandate. The "Queued convoys" entry assumed `cors-tighten` would be a one-file follow-up on `verify.js`. The 23-file gap is a fresh discovery. The wildcard `Access-Control-Allow-Origin: *` allows any origin to read API responses from authenticated browser sessions. Combined with the JWT-in-`Authorization`-header pattern this is less exploitable than cookie-based sessions would be (browsers won't attach the token automatically across origins), but the wildcard still: 1. **Enables credential stuffing from third-party origins** — attacker can serve a page that POSTs to `/api/auth/login` with guessed credentials and read the response (success/failure + token). The 5-attempt/15-min rate limit from `lib/rate-limit.js` mitigates volume but not the attack-class. 2. **Enables arbitrary cross-origin reads of any authenticated GET response** if a victim manually attaches a Bearer token in the wrong browser context (or if a downstream consumer ever pivots to cookies, which `single-auth-provider` may eventually do). 3. **Defeats Vercel's same-origin-by-default deployment shape** — `tcg-vault.com` (or whatever it ends up being post-`pick-a-name`) and the API are served from the same Vercel project. There is no legitimate cross-origin caller. The header is purely scaffolding cruft from whatever generator created the original route templates. This convoy is launch sequence step 4 in `.convoys/ship-readiness.md`'s "Proposed launch sequence" (originally `add-rate-limiting`'s slot, but `cors-tighten` was queued separately and is logically prior — fixing CORS first means rate-limiting's protection isn't side-stepped by a cross-origin caller). ## Scope — TWO OPTIONS, architect picks at gate 1 ### Option A — Narrow (matches the documented queued convoy entry) - Drop wildcard CORS + OPTIONS handler from `pages/api/auth/verify.js` ONLY. ~10 LOC deletion. Closes P0 #5 from PARTIAL → RESOLVED-on-auth-surface. - Queue a separate `cors-sweep-all-routes` convoy for the remaining 23 files. Adds friction (two PRs, two doc-writer cleanups), but matches the convoy's original documented scope. ### Option B — Expanded (recommended by parent, pending architect ratification) - Drop wildcard CORS + OPTIONS handler from **all 24 files** in one PR. ~240 LOC deletion across 24 files, mechanically identical to what Brief 4 did to login + register. Closes P0 #5 fully — PARTIAL → RESOLVED. - Single mechanical sweep; no per-file design decisions; smoke + vitest defend against regression. - Same precedent shape applies (Brief 4's commit `297afca` is the reference diff). **Architect's responsibility at gate 1:** confirm Option B is mechanically safe (no file in the 24 has unique pre-OPTIONS body logic that depends on the wildcard, no file is doing a *narrow* CORS hint that should be preserved-but-tightened rather than deleted), or recommend Option A with explicit reasoning. Default recommendation is B — same-origin Vercel deployment means CORS headers serve no legitimate purpose anywhere on this API surface. ## Operator action required **None.** No env vars, no secrets, no infra changes. ## Decisions to ratify with operator 1. **Option A (narrow) vs Option B (expanded).** See Scope § above. Parent recommends Option B; architect investigates and ratifies. 2. **Should the OPTIONS preflight handler be replaced with a `405 Method Not Allowed`?** Once the wildcard CORS is gone, browsers will not send preflights to this API (same-origin doesn't preflight). Three sub-options: - **(a)** Delete the OPTIONS handler entirely. Method-check at top of handler (`if (req.method !== 'POST')`) returns 405. Same end-state as Brief 4 did to login + register. - **(b)** Keep the OPTIONS handler, return 405. Slightly friendlier to any future direct-CLI callers, but contradicts the "no special-case OPTIONS" simplification. - **(c)** Keep the OPTIONS handler, return 204. Strictly correct per RFC 7231 for an empty success response. Recommend (a). Matches Brief 4 precedent. Trivial to revisit if a real cross-origin caller ever lands. 3. **`pages/api/auth/verify.js` is a GET endpoint** — its `Allow-Methods` line is `'GET, POST, PUT, DELETE, OPTIONS'` (over-permissive). Should the method gate be tightened to GET-only at the same time? Recommend YES — the handler already has `if (req.method !== 'GET') return 405` at line 17, so tightening the `Allow-Methods` line is moot once it's deleted. No-op. 4. **Any tests need updating?** Vitest suite covers `pages/api/auth-utils.js` and `lib/permission-middleware.js` but NOT the per-route handlers directly. Smoke suite covers `home`, `sign-in`, `/api/health` — none of the 24 routes in scope are smoke-covered today, and smoke uses same-origin so CORS removal won't affect it. Recommend NO new tests in this convoy (deferred to a per-route handler test convoy that doesn't exist yet). ## Known constraints - **All 24 files use the IDENTICAL scaffolded pattern** (parent spot-checked 3 of 24; architect should spot-check 5+ more to rule out drift). Same 3-line CORS block, same OPTIONS-guard block. Differs only in the `Allow-Methods` verb list. - **Brief 4 of `fix-auth-bypass` (commit `297afca`)** is the exact precedent. The shape there was: delete the comment, delete the 3 setHeader calls, delete the if-OPTIONS block. That is the edit to apply 24 times. - **No lib-level change.** No need to add a "CORS helper module" or anything else — the right answer is "no CORS at all", same as Brief 4 settled on. - **CI workflow `forbidden-endpoints` job** does NOT currently forbid CORS headers. If we want a regression lock, the architect could optionally add a new CI grep-gate. Recommend YES if Option B is chosen (locks in the cleanup so it can't accumulate again). - **Same-origin assumption holds** — the API and frontend live on the same Vercel project (same domain). If that ever changes (separate API subdomain, mobile app calling the API directly), a real CORS layer needs to be designed at that point. This convoy explicitly does NOT design for that future — YAGNI. ## Acceptance criteria The convoy is shippable when ALL of the following hold: 1. The targeted files (`verify.js` for Option A; all 24 for Option B) have zero `Access-Control-Allow-Origin` references. 2. The targeted files have zero `if (req.method === 'OPTIONS')` blocks. 3. `npm run lint` exit code matches baseline (still 128 problems per `fix-lint-baseline`; do NOT regress). 4. `npm run test:run` (vitest) still passes 21/21 (no regression). 5. `npm run test:smoke` (via CI on the PR) still passes 3/3 against the Vercel preview — proves login + verify + /api/health flow end-to-end after the CORS removal. 6. `git grep -nE "Access-Control-Allow-Origin" -- 'pages/api/**'` returns zero matches (Option B) OR exactly N-1 matches where N=23 (Option A). 7. If Option B AND the architect picks "add CI regression lock": `.github/workflows/ci.yml`'s `forbidden-endpoints` job (or a new `forbidden-cors-headers` job) fails when any new `Access-Control-Allow-Origin` is reintroduced. ## Anything flagged but not acted on (in advance) - **A real CORS layer for a future mobile / 3rd-party API consumer.** Out of scope. If/when needed, design from scratch (probably as middleware) rather than re-scaffolding wildcards. - **`cors-sweep-all-routes` follow-up** — only relevant if Option A is chosen. Pre-queue the entry in ship-readiness's Queued convoys section if Option A wins. - **API-route handler unit tests** — none of the 24 files have vitest coverage today. Adding handler-level tests for each is a separate convoy (probably `fill-vitest-handler-coverage`). - **OPTIONS / CORS via Next.js middleware** — `middleware.js` doesn't exist. Adding a middleware layer to enforce same-origin is an over-engineered fix for "remove unnecessary headers"; YAGNI. Note for posterity in case a future agent considers it.