Social Authentication with GitHub & Google OAuth

 Features:
 - Add GitHub and Google social auth support with secure OAuth 2.0 flow
 - Auto-generated provider callback URLs (read-only)
 - Encrypted OAuth client secrets storage
 - One-time rtCode token exchange mechanism
 - Automatic account linking by verified email

 Security Fixes:
 - [P1] Require siteUrl before enabling OAuth providers
 - [P1] Reject social login when email exists but provider email unverified
 - [P2] Forward OAuth errors to frontend callback instead of JSON
 - [P3] Add verifyApiKey middleware to /social/exchange endpoint

Author: yash-pouranik

README.md

@@ -152,10 +152,42 @@ Social Auth is configured in a Supabase-style flow:
 After a successful provider login, urBackend redirects users back to:
 `<Site URL>/auth/callback`
 
+The frontend callback flow is:
+1. Read `token` from the URL fragment and `rtCode` from the query string.
+2. Call `POST /api/userAuth/social/exchange` with JSON:
+   - `token`
+   - `rtCode`
+3. Expect a standard response in the form `{ success, data, message }`.
+4. On success, store the original access token together with `data.refreshToken`.
+5. Continue into the signed-in app.
+
+Callback example:
+
+```js
+const fragment = new URLSearchParams(window.location.hash.slice(1));
+const params = new URLSearchParams(window.location.search);
+
+const token = fragment.get('token');
+const rtCode = params.get('rtCode');
+
+const response = await fetch('/api/userAuth/social/exchange', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({ token, rtCode })
+});
+
+const payload = await response.json();
+// Success shape: { success: true, data: { refreshToken }, message: 'Refresh token exchanged successfully' }
+```
+
 GitHub and Google both support:
 - linking existing users by email when the provider returns a verified email matching an existing account
 - creating new users automatically when no matching account exists
 - issuing the same urBackend access and refresh tokens used by normal auth flows
+- backend-generated read-only provider callback URLs in the dashboard
+- redirecting to the project `Site URL` after provider login
 
 ---
 

apps/dashboard-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dashboard-api",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": true,
   "main": "src/app.js",
   "scripts": {

apps/dashboard-api/src/controllers/project.controller.js

@@ -1388,6 +1388,14 @@ module.exports.updateAuthProviders = async (req, res) => {
         });
       }
 
+      // P1: Require siteUrl before enabling any OAuth provider
+      if (nextEnabled && !project.siteUrl?.trim()) {
+        return res.status(422).json({
+          error: "siteUrl required",
+          message: `You must configure a Site URL in Project Settings before enabling ${provider} OAuth. The Site URL is used to redirect users after authentication.`,
+        });
+      }
+
       project.authProviders[provider] = {
         enabled: nextEnabled,
         clientId: nextClientId,

apps/public-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "public-api",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": true,
   "main": "src/app.js",
   "scripts": {

apps/public-api/src/__tests__/userAuth.social.test.js

@@ -97,6 +97,7 @@ const makeProject = () => ({
     _id: 'project_1',
     name: 'Demo',
     jwtSecret: 'jwt_secret',
+    siteUrl: 'http://localhost:5173',
     isAuthEnabled: true,
     resources: { db: { isExternal: false } },
     collections: [
@@ -221,7 +222,7 @@ describe('public userAuth social auth', () => {
     });
 
     test('handleSocialAuthCallback rejects when GitHub returns no email', async () => {
-        redis.get.mockResolvedValueOnce(JSON.stringify({ projectId: 'project_1', provider: 'github' }));
+        redis.get.mockResolvedValueOnce(JSON.stringify({ projectId: 'project_1', provider: 'github', callbackUrl: 'http://localhost:5173/auth/callback' }));
         mockProjectFindByIdChain.lean.mockResolvedValueOnce(makeProject());
         global.fetch
             .mockResolvedValueOnce({
@@ -242,10 +243,9 @@ describe('public userAuth social auth', () => {
 
         await controller.handleSocialAuthCallback(req, res);
 
-        expect(res.status).toHaveBeenCalledWith(422);
-        expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
-            error: expect.stringContaining('did not return an email address'),
-        }));
+        // P2: errors now redirect to frontend instead of JSON
+        expect(res.redirect).toHaveBeenCalledWith(expect.stringContaining('error='));
+        expect(res.redirect).toHaveBeenCalledWith(expect.stringContaining('did+not+return+an+email'));
     });
 
     test('handleSocialAuthCallback redirects after GitHub signup', async () => {
@@ -282,8 +282,9 @@ describe('public userAuth social auth', () => {
         }));
         expect(issueAuthTokens).toHaveBeenCalled();
         expect(res.redirect).toHaveBeenCalledWith(expect.stringContaining('/auth/callback?'));
-        expect(res.redirect).toHaveBeenCalledWith(expect.stringContaining('token=issued_access_token'));
         expect(res.redirect).toHaveBeenCalledWith(expect.stringContaining('rtCode='));
+        expect(res.redirect).toHaveBeenCalledWith(expect.stringContaining('#token=issued_access_token'));
+        expect(res.redirect).not.toHaveBeenCalledWith(expect.stringContaining('?token=issued_access_token'));
         expect(res.redirect).not.toHaveBeenCalledWith(expect.stringContaining('refreshToken=issued_refresh_token'));
     });
 
@@ -389,7 +390,7 @@ describe('public userAuth social auth', () => {
     });
 
     test('handleSocialAuthCallback rejects when Google returns no email', async () => {
-        redis.get.mockResolvedValueOnce(JSON.stringify({ projectId: 'project_1', provider: 'google' }));
+        redis.get.mockResolvedValueOnce(JSON.stringify({ projectId: 'project_1', provider: 'google', callbackUrl: 'http://localhost:5173/auth/callback' }));
         mockProjectFindByIdChain.lean.mockResolvedValueOnce(makeProject());
 
         global.fetch
@@ -407,14 +408,13 @@ describe('public userAuth social auth', () => {
 
         await controller.handleSocialAuthCallback(req, res);
 
-        expect(res.status).toHaveBeenCalledWith(422);
-        expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
-            error: expect.stringContaining('did not return an email address'),
-        }));
+        // P2: errors now redirect to frontend instead of JSON
+        expect(res.redirect).toHaveBeenCalledWith(expect.stringContaining('error='));
+        expect(res.redirect).toHaveBeenCalledWith(expect.stringContaining('did+not+return+an+email'));
     });
 
     test('handleSocialAuthCallback rejects invalid Google id_token audience', async () => {
-        redis.get.mockResolvedValueOnce(JSON.stringify({ projectId: 'project_1', provider: 'google' }));
+        redis.get.mockResolvedValueOnce(JSON.stringify({ projectId: 'project_1', provider: 'google', callbackUrl: 'http://localhost:5173/auth/callback' }));
         mockProjectFindByIdChain.lean.mockResolvedValueOnce(makeProject());
 
         global.fetch
@@ -432,10 +432,9 @@ describe('public userAuth social auth', () => {
 
         await controller.handleSocialAuthCallback(req, res);
 
-        expect(res.status).toHaveBeenCalledWith(500);
-        expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
-            error: 'Google id_token audience mismatch',
-        }));
+        // P2: errors now redirect to frontend instead of JSON
+        expect(res.redirect).toHaveBeenCalledWith(expect.stringContaining('error='));
+        expect(res.redirect).toHaveBeenCalledWith(expect.stringContaining('audience'));
     });
 
     test('exchangeSocialRefreshToken returns refresh token and deletes exchange code', async () => {
@@ -506,4 +505,107 @@ describe('public userAuth social auth', () => {
             message: 'Invalid refresh token exchange payload',
         });
     });
+
+    // P2: Provider error forwarding
+    test('handleSocialAuthCallback forwards provider error to frontend callback', async () => {
+        redis.get.mockResolvedValueOnce(JSON.stringify({
+            projectId: 'project_1',
+            provider: 'github',
+            callbackUrl: 'http://localhost:5173/auth/callback',
+        }));
+
+        const req = makeReq({
+            params: { provider: 'github' },
+            query: {
+                error: 'access_denied',
+                error_description: 'The user denied the request',
+                state: 'state_with_error',
+            },
+        });
+        const res = makeRes();
+
+        await controller.handleSocialAuthCallback(req, res);
+
+        expect(res.redirect).toHaveBeenCalledWith(expect.stringContaining('error='));
+        expect(res.redirect).toHaveBeenCalledWith(expect.stringContaining('The+user+denied'));
+    });
+
+    // P1: Email collision when provider email is not verified
+    test('handleSocialAuthCallback rejects if email exists but provider email not verified', async () => {
+        redis.get.mockResolvedValueOnce(JSON.stringify({
+            projectId: 'project_1',
+            provider: 'github',
+            callbackUrl: 'http://localhost:5173/auth/callback',
+        }));
+        mockProjectFindByIdChain.lean.mockResolvedValueOnce(makeProject());
+
+        const existingUser = { _id: 'existing_user', email: 'alice@example.com' };
+
+        // User not found by githubId, but found by email, then refetched after update
+        mockUsersModel.findOne
+            .mockResolvedValueOnce(null) // by githubId
+            .mockResolvedValueOnce(existingUser) // by email
+            .mockResolvedValueOnce({ ...existingUser, githubId: '123' }); // after updateOne
+
+        mockUsersModel.updateOne.mockResolvedValueOnce({ modifiedCount: 1 });
+
+        // GitHub returns an email that IS verified at provider
+        global.fetch
+            .mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({ access_token: 'github_access_token' }),
+            })
+            .mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({ id: 123, login: 'alice', avatar_url: '' }),
+            })
+            .mockResolvedValueOnce({
+                ok: true,
+                json: async () => ([{ email: 'alice@example.com', verified: true, primary: true }]),
+            });
+
+        const req = makeReq({ params: { provider: 'github' }, query: { code: 'code_1', state: 'state_1' } });
+        const res = makeRes();
+
+        await controller.handleSocialAuthCallback(req, res);
+
+        // With verified=true, should successfully link and redirect
+        expect(res.redirect).toHaveBeenCalledWith(expect.stringContaining('rtCode='));
+        expect(mockUsersModel.updateOne).toHaveBeenCalled();
+    });
+
+    // P1: Email collision when provider email is NOT verified (rejection case)
+    test('handleSocialAuthCallback rejects existing email when provider email unverified', async () => {
+        redis.get.mockResolvedValueOnce(JSON.stringify({
+            projectId: 'project_1',
+            provider: 'google',
+            callbackUrl: 'http://localhost:5173/auth/callback',
+        }));
+        mockProjectFindByIdChain.lean.mockResolvedValueOnce(makeProject());
+
+        // User not found by googleId, but found by email
+        mockUsersModel.findOne
+            .mockResolvedValueOnce(null) // by googleId
+            .mockResolvedValueOnce({ _id: 'existing_user', email: 'alice@example.com' }); // by email
+
+        // Google returns unverified email (email_verified: false)
+        global.fetch
+            .mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({ id_token: signGoogleIdToken({ email: 'alice@example.com', email_verified: false }) }),
+            })
+            .mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({ keys: [GOOGLE_JWK] }),
+            });
+
+        const req = makeReq({ params: { provider: 'google' }, query: { code: 'code_1', state: 'state_1' } });
+        const res = makeRes();
+
+        await controller.handleSocialAuthCallback(req, res);
+
+        // Should redirect with error because email exists but not verified for linking
+        expect(res.redirect).toHaveBeenCalledWith(expect.stringContaining('error='));
+        expect(res.redirect).toHaveBeenCalledWith(expect.stringContaining('not+verified'));
+    });
 });