docs(openapi): add /auth/exchange — closes contract gap that hid 2026-05-30 outage

The 2026-05-30 prod-login outage chained 3 failures along /auth/exchange
(client missing, preflight rejected, ACAC missing). Even with the new
contract-CI gate (api #202), the bug class wasn't catchable because
/auth/exchange was literally NOT in the OpenAPI spec — agents and the
typed-client codegen pipeline had no contract to enforce.

Adds the path with the full CORS contract documented in the description
so any future regression to the headers / preflight rules is visible in
the diff that breaks the snapshot-drift gate.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mastermanas805

internal/handlers/openapi.go

@@ -1623,6 +1623,19 @@ const openAPISpec = `{
         }
       }
     },
+    "/auth/exchange": {
+      "post": {
+        "summary": "Exchange the AUTH-004 bridge cookie for a session JWT",
+        "description": "Final leg of the AUTH-004 cross-origin sign-in handshake. The /auth/email/callback and /auth/github/callback handlers set a short-lived HttpOnly auth_exchange_cookie and 302 to https://instanode.dev/login/callback?signed_in=1. The dashboard then makes a credentials:include POST to this endpoint. CORS contract: response MUST include Access-Control-Allow-Origin: https://instanode.dev AND Access-Control-Allow-Credentials: true — the browser blocks the read otherwise. Request MUST be a CORS-simple POST (no custom headers like Accept: application/json), since adding one forces a preflight that PreflightAllowlist may reject. Returns 200 + the bearer JWT (24h, HS256, aud=https://api.instanode.dev) on success. The 2026-05-29 to 2026-05-30 prod-login outage chained three failures along this exact endpoint — documenting it here so any future regression is catchable by the cross-stack contract gate (api PR #202).",
+        "requestBody": { "required": false, "description": "No body. The bridge cookie travels in the Cookie header via credentials:include." },
+        "responses": {
+          "200": { "description": "Cookie verified; JWT minted", "content": { "application/json": { "schema": { "type": "object", "required": ["ok", "token"], "properties": { "ok": { "type": "boolean" }, "token": { "type": "string", "description": "Session JWT — store in localStorage and send as Authorization: Bearer for /api/v1/* calls" } } } } } },
+          "400": { "description": "Bridge cookie missing / expired (canonical envelope with error code cookie_missing_or_expired)" },
+          "401": { "description": "Cookie present but signature invalid or aud mismatch" },
+          "503": { "description": "JWT signing failed (downstream)" }
+        }
+      }
+    },
     "/auth/email/callback": {
       "get": {
         "summary": "Consume a magic link, mint a session JWT, 302 to <return_to>",

openapi.snapshot.json

@@ -8084,6 +8084,50 @@
         "summary": "Send a passwordless magic-link sign-in email"
       }
     },
+    "/auth/exchange": {
+      "post": {
+        "description": "Final leg of the AUTH-004 cross-origin sign-in handshake. The /auth/email/callback and /auth/github/callback handlers set a short-lived HttpOnly auth_exchange_cookie and 302 to https://instanode.dev/login/callback?signed_in=1. The dashboard then makes a credentials:include POST to this endpoint. CORS contract: response MUST include Access-Control-Allow-Origin: https://instanode.dev AND Access-Control-Allow-Credentials: true — the browser blocks the read otherwise. Request MUST be a CORS-simple POST (no custom headers like Accept: application/json), since adding one forces a preflight that PreflightAllowlist may reject. Returns 200 + the bearer JWT (24h, HS256, aud=https://api.instanode.dev) on success. The 2026-05-29 to 2026-05-30 prod-login outage chained three failures along this exact endpoint — documenting it here so any future regression is catchable by the cross-stack contract gate (api PR #202).",
+        "requestBody": {
+          "description": "No body. The bridge cookie travels in the Cookie header via credentials:include.",
+          "required": false
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "ok": {
+                      "type": "boolean"
+                    },
+                    "token": {
+                      "description": "Session JWT — store in localStorage and send as Authorization: Bearer for /api/v1/* calls",
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "ok",
+                    "token"
+                  ],
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Cookie verified; JWT minted"
+          },
+          "400": {
+            "description": "Bridge cookie missing / expired (canonical envelope with error code cookie_missing_or_expired)"
+          },
+          "401": {
+            "description": "Cookie present but signature invalid or aud mismatch"
+          },
+          "503": {
+            "description": "JWT signing failed (downstream)"
+          }
+        },
+        "summary": "Exchange the AUTH-004 bridge cookie for a session JWT"
+      }
+    },
     "/auth/github": {
       "post": {
         "description": "Programmatic / SPA flow. Body: {\"code\":\"<github-oauth-code>\"}. Returns 200 with a 24h session JWT plus user/team ids. Returns 503 oauth_not_configured when GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET are not set in the environment.",