github 0auth fixes

docs/git-provider-setup.md

@@ -6,20 +6,27 @@ This document covers manual setup for GitHub OAuth, Puter Git (Gitea), webhooks,
 
 ## GitHub OAuth Application
 
-1. Go to GitHub Settings > Developer settings > OAuth Apps > New OAuth App.
-2. Set the application name (e.g., "Zopu").
-3. Set the homepage URL to your `SITE_URL` (e.g., `https://zopu.cheaptricks.puter.wtf`).
-4. Set the callback URL to `<SITE_URL>/api/auth/callback/github`.
-5. Generate a client secret.
-6. Set Convex environment variables:
+1. Go to GitHub **Settings → Developer settings → OAuth Apps** and open the app whose client ID will be stored in Convex.
+2. Set the application name and homepage URL. The homepage URL should be the current `SITE_URL`.
+3. Set the single **Authorization callback URL** to exactly:
+   ```text
+   <SITE_URL>/api/auth/callback/github
    ```
+   GitHub OAuth Apps support one callback URL. Scheme, host, port, and path must match the `redirect_uri` sent by Better Auth exactly.
+4. Generate a client secret.
+5. Set the credentials on the Convex deployment—not only in the local `.env` file:
+   ```bash
+   cd packages/backend
    npx convex env set GITHUB_CLIENT_ID <your-client-id>
    npx convex env set GITHUB_CLIENT_SECRET <your-client-secret>
+   npx convex env list
    ```
 
+The configured `SITE_URL`, GitHub callback URL, and browser URL are one unit. For a shared Convex deployment, switch all three before testing a different public origin. See [Auth Proxy](./auth-proxy.md#one-origin-per-shared-oauth-deployment) for the deployment boundary.
+
 ### Requested scopes
 
-Zopu requests `repo` and `read:org`. The `repo` scope grants access to private repositories. `read:org` allows listing organization repositories.
+Zopu requests GitHub identity and private-repository access: `read:user`, `user:email`, `repo`, and `read:org`. `repo` grants access to private repositories; `read:org` permits organization repository discovery.
 
 ## GitHub Webhook (manual setup for OAuth-based version)
 
@@ -102,6 +109,18 @@ Better Auth requires the callback URL to be on the same origin as `SITE_URL`. If
 2. Complete the GitHub OAuth flow.
 3. Verify the connection state shows `active`.
 
+### OAuth diagnostics
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `Provider not found` from `/api/auth/link-social` | `GITHUB_CLIENT_ID` or `GITHUB_CLIENT_SECRET` is absent from the Convex deployment env store. A local `.env` does not configure cloud functions. | Set both variables with `npx convex env set` and verify with `npx convex env list`. |
+| GitHub `Invalid Redirect URI` | GitHub's saved callback does not exactly equal the app's `redirect_uri`. | Set the OAuth App's single callback to `<SITE_URL>/api/auth/callback/github`. |
+| `state_mismatch` at a `convex.site` page | Better Auth started on the public origin but GitHub returned to the direct Convex host, so the public-origin state cookie is unavailable. | Set Better Auth `baseURL` to `SITE_URL`; proxy `/api/auth/*` through the public origin. |
+| `email_doesn't_match` after selecting GitHub | A deployment predates the explicit-link policy or has not received the current auth configuration. | Deploy the current backend. Explicit `linkSocial` allows a different GitHub email without changing the Zopu account email. |
+| `externalEmail` is `null` during `connectGithub` | The GitHub account hides its public email; GitHub returns `null` from `/user`. | Deploy the current backend, which normalizes nullable provider emails before Convex persistence. |
+
+GitHub connections are explicit authenticated account links. The linked GitHub email may differ from the existing Zopu account email; Zopu retains the existing account email and only stores the GitHub identity and OAuth credential needed for repository access.
+
 ### Reconnection
 
 If a token is expired or revoked: