github 0auth fixes

docs/deployment.md

@@ -1,11 +1,10 @@
 # Deployment Notes
 
-Two active environments share one Convex deployment (`dev:befitting-dalmatian-161`).
-Each runs its own web server, Flue agents process, and `.env` file.
+Two active environments share one Convex deployment (`dev:befitting-dalmatian-161`). Each runs its own web server, Flue agents process, and `.env` file.
 
 ## Environments
 
-| | Local Mac Dev | Cheaptricks Staging |
+|  | Local Mac Dev | Cheaptricks Staging |
 | --- | --- | --- |
 | SSH alias | (local) | `cheaptricks` |
 | Repo path | `/Users/puter/Workspace/zopu/code` | `/workspace/code` |
@@ -19,12 +18,9 @@ Each runs its own web server, Flue agents process, and `.env` file.
 
 ## Shared Convex deployment
 
-Deployment name: `dev:befitting-dalmatian-161`
-Convex URL: `https://befitting-dalmatian-161.convex.cloud`
-Convex Site URL: `https://befitting-dalmatian-161.convex.site`
+Deployment name: `dev:befitting-dalmatian-161` Convex URL: `https://befitting-dalmatian-161.convex.cloud` Convex Site URL: `https://befitting-dalmatian-161.convex.site`
 
-Convex env vars are deployment-scoped, not per-machine. Authenticate from any
-machine with `npx convex dev` inside `packages/backend`.
+Convex env vars are deployment-scoped, not per-machine. Authenticate from any machine with `npx convex dev` inside `packages/backend`.
 
 Key Convex env var:
 
@@ -32,9 +28,7 @@ Key Convex env var:
 SITE_URL = <the origin Better Auth should trust>
 ```
 
-This controls `trustedOrigins` in the Better Auth config
-(`packages/backend/convex/auth.ts`). It must match the URL the browser
-actually visits, or sign-in fails silently with a CORS rejection.
+This controls `trustedOrigins` in the Better Auth config (`packages/backend/convex/auth.ts`). It must match the URL the browser actually visits, or sign-in fails silently with a CORS rejection.
 
 When switching between environments:
 
@@ -48,6 +42,10 @@ npx convex env set SITE_URL 'http://100.101.157.28:5173'
 npx convex env set SITE_URL 'https://zopu.cheaptricks.puter.wtf'
 ```
 
+### OAuth consequence
+
+`SITE_URL` drives both Better Auth's public callback origin and the single GitHub OAuth App callback. When switching the shared deployment between the local and staging origins, also update the GitHub OAuth App's **Authorization callback URL** to `<SITE_URL>/api/auth/callback/github` before attempting a GitHub connection. GitHub OAuth Apps allow one callback URL; use distinct Convex deployments and OAuth Apps if both environments must operate concurrently.
+
 ## Local Mac Dev `.env`
 
 ```env
@@ -143,16 +141,24 @@ zopu.cheaptricks.puter.wtf {
     bind 135.181.82.179 2a01:4f9:c013:4a64::1
     encode zstd gzip
 
+    # Must precede the generic /api route: preserves /api/auth/* and cookies.
+    handle /api/auth/* {
+        reverse_proxy https://befitting-dalmatian-161.convex.site {
+            header_up Host befitting-dalmatian-161.convex.site
+        }
+    }
+
     handle_path /api/* {
         reverse_proxy 127.0.0.1:3585
     }
 
-    reverse_proxy 127.0.0.1:5173
+    handle {
+        reverse_proxy 127.0.0.1:5173
+    }
 }
 ```
 
-`/api/*` routes to the Flue agents process (port 3585).
-Everything else routes to the web dev server (port 5173).
+`/api/auth/*` is the same-origin Better Auth proxy to Convex. The generic `/api/*` route serves Flue at port `3585`; it must be evaluated only after the authentication route.
 
 Reload after changes:
 
@@ -162,8 +168,7 @@ sudo systemctl reload caddy
 
 ### Vite allowedHosts
 
-`apps/web/vite.config.ts` must include `server: { allowedHosts: true }` or
-Vite rejects requests arriving through the Caddy domain.
+`apps/web/vite.config.ts` must include `server: { allowedHosts: true }` or Vite rejects requests arriving through the Caddy domain.
 
 ### Start staging dev
 
@@ -211,23 +216,18 @@ Both environments use the same model via the Cheaptricks AI gateway:
 - Multimodal: text + image input
 
 The `AGENT_MODEL_BASE_URL` differs:
+
 - Local Mac: uses the external gateway URL
 - Cheaptricks: uses `https://ai.cheaptricks.puter.wtf/v1` (local to the box)
 
 ## Known gotchas
 
-1. **Convex SITE_URL is single-valued.** Only one origin can be trusted at a
-   time. Switch it when moving between local and staging, or sign-in breaks
-   silently with a CORS error in the browser console.
+1. **Convex `SITE_URL` is single-valued and is the OAuth callback origin.** Switch it together with the GitHub OAuth App's single callback URL when moving between local and staging. Running both origins concurrently requires separate Convex deployments and OAuth Apps.
 
-2. **Vite blocks unknown hosts by default.** Caddy domain must be allowed
-   via `server.allowedHosts` in `apps/web/vite.config.ts`.
+2. **Vite blocks unknown hosts by default.** Caddy domain must be allowed via `server.allowedHosts` in `apps/web/vite.config.ts`.
 
-3. **Flue port changed from 3583 to 3585.** The old Caddy config pointed at
-   3583/13100. Current ports are 3585 (Flue) and 5173 (web).
+3. **Flue port changed from 3583 to 3585.** The old Caddy config pointed at 3583/13100. Current ports are 3585 (Flue) and 5173 (web).
 
-4. **`.env` is gitignored.** Each machine maintains its own copy. The repo
-   ships `.env.example` as the template.
+4. **`.env` is gitignored.** Each machine maintains its own copy. The repo ships `.env.example` as the template.
 
-5. **Convex CLI auth is per-machine.** Run `npx convex dev` once inside
-   `packages/backend` on each new machine to authenticate the CLI.
+5. **Convex CLI auth is per-machine.** Run `npx convex dev` once inside `packages/backend` on each new machine to authenticate the CLI.