koala73
diff --git a/‎.github/workflows/deploy-worker.yml‎
Lines changed: 80 additions & 0 deletions b/‎.github/workflows/deploy-worker.yml‎
Lines changed: 80 additions & 0 deletions
diff --git a/‎docs/architecture/pro-monetization.md‎
Lines changed: 1 addition & 1 deletion b/‎docs/architecture/pro-monetization.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎tests/cors-preflight-live.test.mjs‎
Lines changed: 139 additions & 0 deletions b/‎tests/cors-preflight-live.test.mjs‎
Lines changed: 139 additions & 0 deletions
diff --git a/‎workers/api-cors-preflight/README.md‎
Lines changed: 77 additions & 0 deletions b/‎workers/api-cors-preflight/README.md‎
Lines changed: 77 additions & 0 deletions
@@ -0,0 +1,80 @@
+name: Deploy api-cors-preflight Worker
+
+# Deploys the Cloudflare Worker that owns CORS for api.worldmonitor.app.
+# Triggers on push to main when workers/api-cors-preflight/** changes, OR on
+# manual dispatch. The path filter is the only thing keeping unrelated PRs
+# from re-deploying the Worker on every merge.
+#
+# Required repo secrets:
+#   CLOUDFLARE_API_TOKEN  — token scoped to Workers Scripts:Edit + Workers
+#                           Routes:Edit on the worldmonitor.app zone.
+#   CLOUDFLARE_ACCOUNT_ID — CF account that owns the Worker.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'workers/api-cors-preflight/**'
+      - '.github/workflows/deploy-worker.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  unit-test:
+    name: Unit tests
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: workers/api-cors-preflight
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - name: Install
+        run: npm install --no-audit --no-fund
+      - name: Run unit tests
+        run: node --test index.test.mjs
+
+  deploy:
+    name: Wrangler deploy
+    needs: unit-test
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: workers/api-cors-preflight
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - name: Install
+        run: npm install --no-audit --no-fund
+      - name: Deploy
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        run: npx wrangler deploy
+
+  live-smoke:
+    name: Live preflight smoke test
+    needs: deploy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - name: Wait for Worker propagation
+        # Cloudflare documents Workers propagation to the global edge as up
+        # to ~30 s, occasionally longer. A 15 s wait races the in-flight
+        # propagation window and can either (a) false-green by smoke-testing
+        # the OLD Worker that's still serving at some PoPs, or (b) false-fail
+        # transiently. 30 s aligns with the documented propagation SLA.
+        run: sleep 30
+      - name: Smoke test live OPTIONS preflight
+        env:
+          LIVE_SMOKE: '1'
+        run: node --test tests/cors-preflight-live.test.mjs
@@ -91,7 +91,7 @@ Before creating a session, `getCheckoutBlockingSubscription` checks for active/o
 - **Edge endpoints** that accept Clerk JWTs must go through `validateBearerToken` (`server/auth-session.ts`). Applies to `/api/create-checkout`, `/api/customer-portal`, `/api/referral/me`.
 - **Middleware UA guard** (`middleware.ts`): short-UA guard 403s non-browser fetches by default. New API endpoints called from Railway cron must be added to `PUBLIC_API_PATHS`.
 - **Gateway premium check** (`server/gateway.ts`): accepts either Clerk `publicMetadata.plan === 'pro'` role OR Convex `entitlements.tier >= 1 && validUntil >= now`. Both signals must agree for a request to be treated as paid.
-- **CORS**: Cloudflare Worker `api-cors-preflight` is the source of truth for `api.worldmonitor.app`. Overrides `api/_cors.js` + `vercel.json`.
+- **CORS**: Cloudflare Worker `api-cors-preflight` is the source of truth for `api.worldmonitor.app`. Overrides `api/_cors.js` + `vercel.json`. Worker source lives at [`workers/api-cors-preflight/`](../../workers/api-cors-preflight/); it short-circuits OPTIONS preflight at the edge (skipping Vercel) and stamps CORS headers onto non-OPTIONS responses on the way back. Unit-tested in `workers/api-cors-preflight/index.test.mjs`, smoke-tested live in `tests/cors-preflight-live.test.mjs` (gated by `LIVE_SMOKE=1`), and deployed by `.github/workflows/deploy-worker.yml` on changes under `workers/api-cors-preflight/`. The Worker's allowlist + Allow-Headers list MUST stay a superset of `api/_cors.js#getCorsHeaders`; drift breaks credentialed CORS site-wide (2026-05-27 outage post-mortem).
 - **HMAC identity bridge**: Dodo metadata `wm_user_id` is signed with a server-side key (`convex/lib/identitySigning.ts`) so webhooks can trust the user association without an additional lookup.
 
 ## Known gaps & active work
 
@@ -0,0 +1,139 @@
+// Live CORS preflight smoke test against production.
+//
+// Gated behind LIVE_SMOKE=1 so it does NOT run in the default PR test gate —
+// fetching live api.worldmonitor.app from CI would false-positive during
+// deploys, network blips, or Cloudflare incidents.
+//
+// Run manually before/after a Worker deploy:
+//   LIVE_SMOKE=1 tsx --test tests/cors-preflight-live.test.mjs
+//
+// Or wire into a scheduled GitHub Action / Vercel cron if you want continuous
+// canary coverage.
+//
+// What this catches:
+//   - `Access-Control-Allow-Credentials: true` missing from OPTIONS preflight
+//     (the 2026-05-27 outage — see worldmonitor-architecture-gotchas/reference/
+//      cloudflare-worker-overrides-vercel-cors-for-preflight.md).
+//   - Origin echo broken (preflight echoes `https://worldmonitor.app` for an
+//     allowed origin → browsers reject as mismatched).
+//   - Worker bypassed entirely (Vercel fallback served instead — would still
+//     pass on healthy days but blow up if/when the Worker is re-enabled).
+//
+// This test deliberately mirrors what a real browser does for CORS preflight,
+// so a failure here is a strong signal of a real user-facing outage.
+
+import { strict as assert } from 'node:assert';
+import test from 'node:test';
+
+const BROWSER_UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
+const ORIGIN = 'https://www.worldmonitor.app';
+
+// Endpoints we hit. /api/health is canonical (always available, no auth).
+// Add a representative second one to catch route-specific Worker rules if
+// anyone ever adds them.
+const ENDPOINTS = [
+  'https://api.worldmonitor.app/api/health',
+  'https://api.worldmonitor.app/api/bootstrap?tier=fast',
+];
+
+const SHOULD_RUN = process.env.LIVE_SMOKE === '1';
+
+if (!SHOULD_RUN) {
+  test('LIVE smoke gated — set LIVE_SMOKE=1 to run', { skip: true }, () => {});
+}
+
+// Public-CORS paths that the Worker MUST pass through to Vercel unchanged.
+// External MCP clients (https://claude.ai, https://claude.com) hit these and
+// must receive the Vercel function's own CORS policy (typically ACAO: * for
+// OAuth/MCP), not the Worker's worldmonitor.app-only echo.
+const PUBLIC_CORS_PROBES = [
+  { url: 'https://api.worldmonitor.app/api/mcp', origin: 'https://claude.ai' },
+  { url: 'https://api.worldmonitor.app/api/oauth/register', origin: 'https://claude.com' },
+  { url: 'https://api.worldmonitor.app/api/oauth-protected-resource', origin: 'https://claude.ai' },
+];
+
+for (const { url, origin } of PUBLIC_CORS_PROBES) {
+  test(`OPTIONS ${url} from ${origin} bypasses Worker → Vercel ACAO survives`, { skip: !SHOULD_RUN }, async () => {
+    const resp = await fetch(url, {
+      method: 'OPTIONS',
+      headers: {
+        Origin: origin,
+        'User-Agent': BROWSER_UA,
+        'Access-Control-Request-Method': 'POST',
+        'Access-Control-Request-Headers': 'content-type',
+      },
+    });
+    await resp.arrayBuffer();
+    // Acceptance: the response must NOT echo the canonical worldmonitor.app
+    // fallback (which would mean the Worker short-circuited and the external
+    // client gets blocked). Either ACAO: * OR ACAO echoes the request origin
+    // is fine — both are valid public-CORS dispositions.
+    const acao = resp.headers.get('access-control-allow-origin');
+    assert.ok(
+      acao === '*' || acao === origin,
+      `Public-CORS path ${url} returned ACAO=${acao} for Origin=${origin}; expected '*' or echo. Worker is short-circuiting when it should bypass.`,
+    );
+  });
+}
+
+for (const url of ENDPOINTS) {
+  test(`OPTIONS ${url} returns ACAC: true for ${ORIGIN}`, { skip: !SHOULD_RUN }, async () => {
+    const resp = await fetch(url, {
+      method: 'OPTIONS',
+      headers: {
+        Origin: ORIGIN,
+        'User-Agent': BROWSER_UA,
+        'Access-Control-Request-Method': 'GET',
+        'Access-Control-Request-Headers': 'content-type',
+      },
+    });
+
+    // Drain body so the socket can be reused.
+    await resp.arrayBuffer();
+
+    assert.equal(
+      resp.status,
+      204,
+      `Preflight should be 204 No Content; got ${resp.status}`,
+    );
+    assert.equal(
+      resp.headers.get('access-control-allow-origin'),
+      ORIGIN,
+      'ACAO must echo the request origin (NOT https://worldmonitor.app fallback, NOT *)',
+    );
+    assert.equal(
+      resp.headers.get('access-control-allow-credentials'),
+      'true',
+      'ACAC must be present; missing it breaks every credentials:include request site-wide',
+    );
+    // Cloudflare may append `accept-encoding` to Vary for compression keying,
+    // so check that `Origin` is included (case-insensitive) rather than
+    // asserting exact equality.
+    const vary = (resp.headers.get('vary') || '').toLowerCase();
+    assert.ok(
+      vary.split(',').map((s) => s.trim()).includes('origin'),
+      `Vary header must include Origin so caches key on origin; got: ${resp.headers.get('vary')}`,
+    );
+    const acah = resp.headers.get('access-control-allow-headers') || '';
+    for (const required of ['Authorization', 'X-WorldMonitor-Key', 'X-Api-Key', 'X-Pro-Key', 'X-Widget-Key']) {
+      assert.ok(
+        acah.toLowerCase().includes(required.toLowerCase()),
+        `ACAH must include ${required}; got: ${acah}`,
+      );
+    }
+
+    // Worker's Allow-Methods MUST be a superset of every method any api/*
+    // route advertises. api/product-catalog.js advertises 'GET, DELETE,
+    // OPTIONS' on its preflight, so DELETE belongs in the global Worker list.
+    // Missing it silently breaks browser-origin product-catalog purges in
+    // prod — exactly the regression that PR review caught locally.
+    const acam = (resp.headers.get('access-control-allow-methods') || '')
+      .split(',').map((s) => s.trim().toUpperCase());
+    for (const required of ['GET', 'POST', 'DELETE', 'OPTIONS']) {
+      assert.ok(
+        acam.includes(required),
+        `ACAM must include ${required}; got: ${acam.join(', ')}`,
+      );
+    }
+  });
+}
@@ -0,0 +1,77 @@
+# api-cors-preflight
+
+Cloudflare Worker bound to `api.worldmonitor.app/*`. Owns CORS at the edge:
+short-circuits OPTIONS preflights (without forwarding to Vercel) and stamps
+matching CORS headers onto every non-OPTIONS response on the way back to the
+browser.
+
+## Why this exists separately from `api/_cors.js`
+
+Three CORS surfaces sit in front of every browser request to `api.worldmonitor.app`:
+
+1. **Cloudflare Worker (this directory)** — sees the request first; the
+   preflight response the browser actually checks comes from here.
+2. **Vercel edge function `api/_cors.js#getCorsHeaders`** — runs per-request
+   for non-OPTIONS, and supplies CORS headers that the Worker then overrides
+   with its own copy on the way out.
+3. **`vercel.json`** — no longer pins static `/api/*` CORS headers (removed in
+   PR #3923 because the wildcard `ACAO: *` was incompatible with credentialed
+   requests).
+
+When the app switched to `credentials: 'include'` (HttpOnly cookies, PR #3913),
+the Worker's preflight response was missing
+`Access-Control-Allow-Credentials: true`. Repo-side fixes (PR #3923) could not
+close the outage because the preflight never reaches Vercel. Moving the Worker
+source in-repo means future CORS changes:
+
+- Show up in `git log` / `git blame` / code review / greptile.
+- Get unit-tested in this directory (`index.test.mjs`).
+- Get smoke-tested against live prod (`tests/cors-preflight-live.test.mjs`).
+- Deploy from CI on merge (`.github/workflows/deploy-worker.yml`).
+
+## Deploy
+
+### From CI (preferred)
+
+Merge to `main` → `.github/workflows/deploy-worker.yml` runs `wrangler deploy`
+automatically when `workers/api-cors-preflight/**` changes. Requires repo
+secrets:
+
+- `CLOUDFLARE_API_TOKEN` — token with `Workers Scripts:Edit` + `Workers
+  Routes:Edit` for the `worldmonitor.app` zone.
+- `CLOUDFLARE_ACCOUNT_ID` — the CF account that owns the Worker.
+
+### From your laptop (fallback)
+
+```sh
+cd workers/api-cors-preflight
+npm install
+export CLOUDFLARE_API_TOKEN=...
+export CLOUDFLARE_ACCOUNT_ID=...
+npm run deploy
+```
+
+## Tests
+
+```sh
+# Unit tests against the Worker module directly (fast, deterministic).
+cd workers/api-cors-preflight && npm test
+
+# Live smoke test against prod. Gated by env var so it doesn't run in PR gates
+# (false positives during deploys).
+LIVE_SMOKE=1 tsx --test tests/cors-preflight-live.test.mjs
+```
+
+## Keep in sync
+
+The Worker's allowlist + Allow-Headers list **must be a superset of** what
+`api/_cors.js#getCorsHeaders` returns. If the Worker rejects an origin that the
+function would accept, the browser sees a mismatched origin echo and CORS
+rejects the request. Drift between the two is the load-bearing trap this
+package exists to make visible. Update both files together.
+
+## Related learning
+
+`~/.claude/skills/worldmonitor-architecture-gotchas/reference/cloudflare-worker-overrides-vercel-cors-for-preflight.md`
+captures the full post-mortem of the 2026-05-27 CORS outage that motivated
+pulling the Worker into the repo. Read it before touching this Worker.