github 0auth fixes

docs/auth-proxy.md

@@ -1,17 +1,15 @@
 # Auth Proxy — Production Ingress Requirement
 
-The application uses **same-origin authentication**: the browser and React Router SSR both hit
-`/api/auth/*` on the public application domain. This keeps cookies first-party, avoids
-cross-origin credentials, and gives development and production the same API surface.
+The application uses **same-origin authentication**: the browser and React Router SSR both hit `/api/auth/*` on the public application domain. This keeps cookies first-party, avoids cross-origin credentials, and gives development and production the same API surface.
 
 ## Required production route
 
 At the public application domain, route:
 
-| Prefix | Target |
-|---|---|
-| `/api/auth/*` | Convex HTTP site |
-| `/*` | React Router frontend |
+| Prefix        | Target                |
+| ------------- | --------------------- |
+| `/api/auth/*` | Convex HTTP site      |
+| `/*`          | React Router frontend |
 
 ### Caddy
 
@@ -31,8 +29,7 @@ zopu.example.com {
 
 ### Dokploy / Traefik
 
-Create a higher-priority path router for `/api/auth` that forwards to the external Convex
-site URL. Ensure it:
+Create a higher-priority path router for `/api/auth` that forwards to the external Convex site URL. Ensure it:
 
 - Preserves the original browser `Cookie` header
 - Passes `Set-Cookie` responses back (rewrite domain if Convex emits an explicit one)
@@ -44,8 +41,7 @@ site URL. Ensure it:
 
 ## Convex environment
 
-The Convex deployment `SITE_URL` must match the public origin users visit, not the Convex
-site URL:
+The Convex deployment `SITE_URL` must match the public origin users visit, not the Convex site URL:
 
 ```bash
 # Production
@@ -58,15 +54,20 @@ npx convex env set SITE_URL 'http://100.101.157.28:5173'
 npx convex env set SITE_URL 'https://zopu.cheaptricks.puter.wtf'
 ```
 
-This value populates Better Auth's `trustedOrigins`. The Convex deployment also uses
-`CONVEX_SITE_URL` as the internal `baseURL` for route registration; that value is the HTTP
-site URL (e.g. `https://befitting-dalmatian-161.convex.site`).
+This value is Better Auth's public `baseURL` and `trustedOrigins`. It must be the browser origin because Better Auth writes OAuth state cookies and receives provider callbacks through the same-origin proxy. `CONVEX_SITE_URL` remains the internal Convex HTTP site URL.
+
+## One origin per shared OAuth deployment
+
+GitHub OAuth Apps expose one authorization callback URL. The value must exactly equal `<SITE_URL>/api/auth/callback/github`, including scheme, host, port, and path. A GitHub authorization request whose `redirect_uri` differs returns `Invalid Redirect URI` before the user can grant access.
+
+`SITE_URL` is also single-valued in a Convex deployment. Therefore, two browser origins that share one deployment—such as Tailscale development and Puter staging—cannot use GitHub OAuth at the same time. Either switch both the Convex `SITE_URL` and the GitHub OAuth App callback together before testing the other origin, or give each public environment its own Convex deployment and OAuth App.
+
+Never set Better Auth's `baseURL` to `CONVEX_SITE_URL` for the browser flow. The browser creates the OAuth state cookie on `SITE_URL`; a provider callback sent directly to `CONVEX_SITE_URL` cannot read that cookie and fails with `state_mismatch`.
 
 ## Why same-origin
 
 1. **First-party cookies.** No `SameSite=None`, no third-party cookie restrictions.
-2. **SSR consistency.** The React Router server uses the same auth surface the browser
-   sees; no cross-host credential translation.
+2. **SSR consistency.** The React Router server uses the same auth surface the browser sees; no cross-host credential translation.
 3. **No CORS complexity.** The browser talks only to its own origin.
 4. **The reverse proxy handles the cross-host hop server-side.**