docs: updated social auth docs that was ambiguios before

Author: yash-pouranik

docs/authentication.md

@@ -128,129 +128,259 @@ await fetch('https://api.ub.bitbros.in/api/userAuth/public/dev_pulse', {
 > [!NOTE]
 > This endpoint never returns sensitive fields like `password` or `email`.
 
-## 7. Social Auth
+## 7. Social Auth (GitHub / Google)
 
-Supported providers:
-- GitHub
-- Google
+Social auth lets your users sign in using their GitHub or Google accounts instead of email/password.
 
-Social auth is configured from the dashboard:
-1. Set your project `Site URL` in Project Settings.
-2. Open `Auth -> Social Auth`.
-3. Copy the read-only callback URL shown for the provider.
-4. Register that callback URL in the provider console.
-5. Save the provider `Client ID` and `Client Secret` in urBackend and enable the provider.
+### Overview: How It Works
 
-### Start the provider login
-
-**Endpoint**: `GET /api/userAuth/social/:provider/start`
-
-Required headers:
-- `x-api-key: pk_live_*` or `x-api-key: sk_live_*`
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  Your App   │────▶│  urBackend  │────▶│  Provider   │────▶│  urBackend  │
+│  (Frontend) │     │  /start     │     │  (GitHub/   │     │  /callback  │
+│             │     │             │     │   Google)   │     │             │
+└─────────────┘     └─────────────┘     └─────────────┘     └──────┬──────┘
+                                                                   │
+                    ┌─────────────┐     ┌─────────────┐            │
+                    │  Your App   │◀────│  urBackend  │◀───────────┘
+                    │  /auth/     │     │  redirects  │
+                    │  callback   │     │  with tokens│
+                    └─────────────┘     └─────────────┘
+```
 
-Example:
+---
+
+### Step 0: Dashboard Setup (One-time)
+
+Before your frontend can use social auth:
+
+1. **Set Site URL** → Go to `Project Settings` → Add your frontend URL (e.g., `https://myapp.com`)
+2. **Configure Provider** → Go to `Auth` → `Social Auth` → Select GitHub or Google
+3. **Copy Callback URL** → urBackend shows a read-only callback URL like:
+   ```
+   https://api.ub.bitbros.in/api/userAuth/social/github/callback
+   ```
+4. **Register in Provider Console**:
+   - GitHub: `Settings → Developer settings → OAuth Apps → New OAuth App`
+   - Google: `Google Cloud Console → APIs & Services → Credentials → Create OAuth Client`
+   - Paste the callback URL from Step 3
+5. **Save Credentials** → Copy `Client ID` and `Client Secret` from provider → Paste in urBackend dashboard → Enable
+
+---
+
+### Step 1: Create a Callback Page in Your Frontend
+
+> ⚠️ **You MUST create this page!** urBackend will redirect users here after OAuth.
+
+Create a page at `/auth/callback` in your frontend app. This page will:
+1. Extract tokens from the URL
+2. Exchange `rtCode` for refresh token
+3. Store tokens and redirect user to dashboard
+
+**React Example (`/auth/callback`):**
+
+```jsx
+// pages/AuthCallback.jsx
+import { useEffect } from 'react';
+import { useNavigate } from 'react-router-dom';
+
+function AuthCallback() {
+  const navigate = useNavigate();
+
+  useEffect(() => {
+    async function handleCallback() {
+      // Step 2a: Check for errors
+      const queryParams = new URLSearchParams(window.location.search);
+      const error = queryParams.get('error');
+      
+      if (error) {
+        alert('Login failed: ' + error);
+        navigate('/login');
+        return;
+      }
+
+      // Step 2b: Extract tokens from URL
+      const hashParams = new URLSearchParams(window.location.hash.slice(1));
+      const accessToken = hashParams.get('token');
+      const rtCode = queryParams.get('rtCode');
+
+      if (!accessToken || !rtCode) {
+        alert('Missing tokens');
+        navigate('/login');
+        return;
+      }
+
+      // Step 3: Exchange rtCode for refresh token
+      const response = await fetch('https://api.ub.bitbros.in/api/userAuth/social/exchange', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-api-key': 'pk_live_YOUR_KEY'
+        },
+        body: JSON.stringify({ token: accessToken, rtCode })
+      });
+
+      const data = await response.json();
+
+      if (!data.success) {
+        alert('Token exchange failed');
+        navigate('/login');
+        return;
+      }
+
+      // Step 4: Store tokens and redirect
+      localStorage.setItem('accessToken', accessToken);
+      localStorage.setItem('refreshToken', data.data.refreshToken);
+
+      // Optional: store extra info
+      localStorage.setItem('provider', queryParams.get('provider'));
+      localStorage.setItem('userId', queryParams.get('userId'));
+
+      navigate('/dashboard');
+    }
+
+    handleCallback();
+  }, [navigate]);
+
+  return <div>Completing login...</div>;
+}
 
-```javascript
-window.location.href = 'https://api.ub.bitbros.in/api/userAuth/social/github/start';
+export default AuthCallback;
 ```
 
-This endpoint redirects the browser to the provider and uses the project `Site URL` to send users back to:
+---
 
-```text
-<Site URL>/auth/callback
-```
+### Step 2: Add Login Button in Your Frontend
+
+When user clicks "Login with GitHub" or "Login with Google", redirect them to urBackend's start endpoint:
 
-### What the callback URL contains
+```jsx
+// components/LoginButtons.jsx
+const API_KEY = 'pk_live_YOUR_KEY';
+const API_URL = 'https://api.ub.bitbros.in';
 
-After successful provider login, urBackend redirects to your frontend callback route with:
-- `token` in the URL fragment
-- `rtCode` in the query string
-- `provider`, `projectId`, `userId`, `isNewUser`, and `linkedByEmail` in the query string
+function LoginButtons() {
+  const handleGitHubLogin = () => {
+    // Redirect browser to urBackend, which redirects to GitHub
+    window.location.href = `${API_URL}/api/userAuth/social/github/start?x-api-key=${API_KEY}`;
+  };
 
-Example redirect:
+  const handleGoogleLogin = () => {
+    window.location.href = `${API_URL}/api/userAuth/social/google/start?x-api-key=${API_KEY}`;
+  };
 
-```text
-https://your-app.example/auth/callback?rtCode=abc123&provider=github&projectId=proj_1&userId=user_1&isNewUser=false&linkedByEmail=true#token=eyJ...
+  return (
+    <div>
+      <button onClick={handleGitHubLogin}>Login with GitHub</button>
+      <button onClick={handleGoogleLogin}>Login with Google</button>
+    </div>
+  );
+}
 ```
 
-`token` is intentionally placed in the fragment so it is not exposed through normal query-string logging or referrer leakage.
+> **Note:** You can also pass `x-api-key` as a header, but since this is a redirect (not fetch), query param is easier.
 
-### Exchange the one-time `rtCode`
+---
 
-**Endpoint**: `POST /api/userAuth/social/exchange`
+### Complete Flow Summary
 
-Required headers:
+| Step | What Happens | Who Does It |
+|------|--------------|-------------|
+| 1 | User clicks "Login with GitHub" | Your frontend |
+| 2 | Browser redirects to `/api/userAuth/social/github/start` | Your frontend |
+| 3 | urBackend redirects to GitHub login page | urBackend |
+| 4 | User logs in on GitHub | User |
+| 5 | GitHub redirects to urBackend callback | GitHub |
+| 6 | urBackend creates/links user, generates tokens | urBackend |
+| 7 | urBackend redirects to `<your-site>/auth/callback?rtCode=...#token=...` | urBackend |
+| 8 | Your callback page extracts `token` and `rtCode` | Your frontend |
+| 9 | Your callback page calls `/social/exchange` with both | Your frontend |
+| 10 | urBackend returns `refreshToken` | urBackend |
+| 11 | Your app stores tokens, redirects to dashboard | Your frontend |
 
-```javascript
-{
-  'Content-Type': 'application/json',
-  'x-api-key': 'YOUR_KEY'
-}
-```
+---
 
-Required JSON body:
+### API Reference
 
-```javascript
-{
-  token: 'ACCESS_TOKEN_FROM_HASH',
-  rtCode: 'ONE_TIME_CODE_FROM_QUERY'
-}
-```
+#### Start OAuth Flow
 
-Example frontend callback handler:
+**Endpoint:** `GET /api/userAuth/social/:provider/start`
 
-```javascript
-const hashParams = new URLSearchParams(window.location.hash.slice(1));
-const queryParams = new URLSearchParams(window.location.search);
+| Param | Value |
+|-------|-------|
+| `:provider` | `github` or `google` |
+| `x-api-key` | Your publishable key (query param or header) |
 
-const token = hashParams.get('token');
-const rtCode = queryParams.get('rtCode');
+**Response:** Browser redirect to provider login page
 
-if (!token || !rtCode) {
-  throw new Error('Missing auth callback tokens');
-}
+---
 
-const response = await fetch('https://api.ub.bitbros.in/api/userAuth/social/exchange', {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json'
-  },
-  body: JSON.stringify({ token, rtCode })
-});
+#### Exchange rtCode for Refresh Token
+
+**Endpoint:** `POST /api/userAuth/social/exchange`
 
-const payload = await response.json();
+**Headers:**
+```
+Content-Type: application/json
+x-api-key: pk_live_YOUR_KEY
 ```
 
-Successful response:
+**Body:**
+```json
+{
+  "token": "eyJ... (access token from URL fragment)",
+  "rtCode": "abc123 (one-time code from query string)"
+}
+```
 
-```javascript
+**Success Response:**
+```json
 {
-  success: true,
-  data: {
-    refreshToken: 'REFRESH_TOKEN_VALUE'
+  "success": true,
+  "data": {
+    "refreshToken": "REFRESH_TOKEN_VALUE"
   },
-  message: 'Refresh token exchanged successfully'
+  "message": "Refresh token exchanged successfully"
 }
 ```
 
-Expected client behavior after success:
-1. Keep using the original `token` as the access token.
-2. Store `data.refreshToken` for session continuation.
-3. Optionally store `provider`, `projectId`, and `userId` from the callback query string.
-4. Redirect the user into the authenticated part of your app.
+**Error Responses:**
+```json
+{ "success": false, "message": "rtCode and token are required" }
+{ "success": false, "message": "Invalid or expired refresh token exchange code" }
+```
 
-Common error responses:
+---
 
-```javascript
-{ success: false, message: 'rtCode and token are required' }
-{ success: false, message: 'Invalid or expired refresh token exchange code' }
-{ success: false, message: 'Invalid refresh token exchange payload' }
+### What Gets Passed to Your Callback URL
+
+After successful login, urBackend redirects to:
+
+```
+https://your-site.com/auth/callback?rtCode=abc&provider=github&projectId=p1&userId=u1&isNewUser=false&linkedByEmail=true#token=eyJ...
 ```
 
-Notes:
-- `rtCode` is short-lived and one-time use.
-- Existing users are linked by verified email when possible.
-- New social-auth users still receive a generated hashed password internally to satisfy the required `users` schema contract.
+| Param | Location | Description |
+|-------|----------|-------------|
+| `token` | URL fragment (`#`) | Access token (JWT) - use for API calls |
+| `rtCode` | Query string | One-time code to exchange for refresh token |
+| `provider` | Query string | `github` or `google` |
+| `projectId` | Query string | Your urBackend project ID |
+| `userId` | Query string | The user's ID in your database |
+| `isNewUser` | Query string | `true` if account was just created |
+| `linkedByEmail` | Query string | `true` if existing account was linked |
+| `error` | Query string | Error message (only on failure) |
+
+> **Why is `token` in the fragment?** Fragments (`#...`) are never sent to servers in HTTP requests, preventing token leakage through referrer headers or server logs.
+
+---
+
+### Important Notes
+
+1. **rtCode expires in 60 seconds** - Exchange it immediately
+2. **rtCode is one-time use** - Cannot be reused
+3. **Account linking** - If a user with the same verified email exists, accounts are automatically linked
+4. **New users** - A hashed password is auto-generated internally (users can still set a real password later)
 
 ## Security Note