feat(auth): add OAuth2 login with Google and GitHub

Implement Passport OAuth strategies, extend the user model for provider
accounts, add auth routes and login UI, and document setup in the README.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Honey-pg

.env.example

@@ -0,0 +1 @@
+VITE_BACKEND_URL=http://localhost:5000

README.md

@@ -63,6 +63,102 @@ $ npm i
 $ npm start
 ```
 
+### OAuth2 sign-in (Google & GitHub)
+
+OAuth2 lets users sign in with Google or GitHub. Email/password login still works for local accounts.
+
+#### 1. Copy environment files
+
+```bash
+cp .env.example .env
+cp backend/.env.example backend/.env
+```
+
+Set these in **`backend/.env`** (required for OAuth redirects and sessions):
+
+| Variable | Description |
+|----------|-------------|
+| `SESSION_SECRET` | Long random string for express-session |
+| `MONGO_URI` | MongoDB connection string |
+| `BACKEND_URL` | Backend base URL (e.g. `http://localhost:5001`) |
+| `FRONTEND_URL` | Frontend URL (e.g. `http://localhost:5173`) |
+
+Set in **`.env`** (project root, for the React app):
+
+| Variable | Description |
+|----------|-------------|
+| `VITE_BACKEND_URL` | Same as `BACKEND_URL` (e.g. `http://localhost:5001`) |
+
+> **Note (macOS):** Port `5000` is often used by AirPlay. If the backend fails to start, set `PORT=5001` in `backend/.env` and use `5001` in `BACKEND_URL` and `VITE_BACKEND_URL`.
+
+#### 2. Set up Google OAuth2
+
+1. Open [Google Cloud Console](https://console.cloud.google.com/) and create or select a project.
+2. Go to **APIs & Services → OAuth consent screen**, choose **External**, and complete the required app name and support email fields.
+3. Go to **APIs & Services → Credentials → Create Credentials → OAuth client ID**.
+4. Application type: **Web application**.
+5. **Authorized redirect URIs** — add:
+   ```
+   http://localhost:5001/api/auth/google/callback
+   ```
+   (Use your `BACKEND_URL` host/port in production, e.g. `https://your-api.example.com/api/auth/google/callback`.)
+6. Copy the **Client ID** and **Client secret** into `backend/.env`:
+   ```env
+   GOOGLE_CLIENT_ID=your-google-client-id
+   GOOGLE_CLIENT_SECRET=your-google-client-secret
+   ```
+
+#### 3. Set up GitHub OAuth App
+
+1. Open [GitHub Developer Settings → OAuth Apps](https://github.com/settings/developers) and click **New OAuth App**.
+2. Fill in:
+   - **Application name:** e.g. `GitHub Tracker (local)`
+   - **Homepage URL:** `http://localhost:5173` (or your deployed frontend URL)
+   - **Authorization callback URL:**
+     ```
+     http://localhost:5001/api/auth/github/callback
+     ```
+     (Match your `BACKEND_URL` in production.)
+3. Click **Register application**, then **Generate a new client secret**.
+4. Add to `backend/.env`:
+   ```env
+   GITHUB_OAUTH_CLIENT_ID=your-github-client-id
+   GITHUB_OAUTH_CLIENT_SECRET=your-github-client-secret
+   ```
+
+> Use a **GitHub OAuth App**, not a Personal Access Token (PAT).
+
+#### 4. Install backend dependencies and restart
+
+From the `backend` folder:
+
+```bash
+cd backend
+npm install
+npm run dev
+```
+
+Restart the frontend after changing `.env`:
+
+```bash
+npm run dev
+```
+
+#### 5. Verify OAuth login
+
+1. Open `http://localhost:5173/login`.
+2. Click **Continue with Google** or **Continue with GitHub**.
+3. Complete the provider sign-in; you should be redirected back and logged in.
+
+If credentials are missing, the buttons still appear; clicking them shows a message to configure `backend/.env`. After adding secrets and restarting the backend, OAuth sign-in works end-to-end.
+
+**Callback URLs summary** (replace host/port with your `BACKEND_URL`):
+
+| Provider | Callback URL |
+|----------|----------------|
+| Google | `{BACKEND_URL}/api/auth/google/callback` |
+| GitHub | `{BACKEND_URL}/api/auth/github/callback` |
+
 ## 🧪 Backend Unit & Integration Testing with Jasmine
 
 This project uses the Jasmine framework for backend unit and integration tests. The tests cover:
@@ -94,6 +190,7 @@ npm install --save-dev jasmine @types/jasmine supertest express-session passport
 ### Test Files
 - `spec/user.model.spec.cjs` — Unit tests for the User model
 - `spec/auth.routes.spec.cjs` — Integration tests for authentication routes
+- `spec/oauthUser.spec.cjs` — Unit tests for OAuth user helpers
 
 ### Jasmine Configuration
 The Jasmine config (`spec/support/jasmine.mjs`) is set to recognize `.cjs`, `.js`, and `.mjs` test files:

backend/.env.example

@@ -0,0 +1,19 @@
+PORT=5000
+MONGO_URI=mongodb://127.0.0.1:27017/github_tracker
+SESSION_SECRET=replace-with-a-long-random-secret
+
+# URLs used for OAuth redirects and CORS
+BACKEND_URL=http://localhost:5000
+FRONTEND_URL=http://localhost:5173
+
+# Google OAuth2 (https://console.cloud.google.com/apis/credentials)
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+# Optional override; defaults to BACKEND_URL/api/auth/google/callback
+GOOGLE_CALLBACK_URL=
+
+# GitHub OAuth App (https://github.com/settings/developers)
+GITHUB_OAUTH_CLIENT_ID=
+GITHUB_OAUTH_CLIENT_SECRET=
+# Optional override; defaults to BACKEND_URL/api/auth/github/callback
+GITHUB_CALLBACK_URL=

backend/config/passportConfig.js

@@ -1,45 +1,128 @@
 const passport = require("passport");
-const LocalStrategy = require('passport-local').Strategy;
+const LocalStrategy = require("passport-local").Strategy;
+const GoogleStrategy = require("passport-google-oauth20").Strategy;
+const GitHubStrategy = require("passport-github2").Strategy;
 const User = require("../models/User");
+const {
+  findOrCreateOAuthUser,
+  toSessionUser,
+  isOAuthProviderConfigured,
+} = require("../utils/oauthUser");
+
+function getBackendUrl() {
+  return process.env.BACKEND_URL || `http://localhost:${process.env.PORT || 5000}`;
+}
+
+function getFrontendUrl() {
+  return process.env.FRONTEND_URL || "http://localhost:5173";
+}
 
 passport.use(
-    new LocalStrategy(
-        { usernameField: "email" },
-        async (email, password, done) => {
-            try {
-                const user = await User.findOne( {email} );
-                if (!user) {
-                    return done(null, false, { message: 'Email is invalid '});
-                }
-
-                const isMatch = await user.comparePassword(password);
-                if (!isMatch) {
-                    return done(null, false, { message: 'Invalid password' });
-                }
-
-                return done(null, {
-                    id : user._id.toString(),
-                    username: user.username,
-                    email: user.email
-                });
-            } catch (err) {
-                return done(err);
-            }
+  new LocalStrategy(
+    { usernameField: "email" },
+    async (email, password, done) => {
+      try {
+        const user = await User.findOne({ email });
+
+        if (!user) {
+          return done(null, false, { message: "Email is invalid " });
         }
-    )
+
+        if (user.provider !== "local" || !user.password) {
+          return done(null, false, {
+            message: `Please sign in with ${user.provider}`,
+          });
+        }
+
+        const isMatch = await user.comparePassword(password);
+        if (!isMatch) {
+          return done(null, false, { message: "Invalid password" });
+        }
+
+        return done(null, toSessionUser(user));
+      } catch (err) {
+        return done(err);
+      }
+    }
+  )
 );
 
-// Serialize user (store user info in session)
+if (isOAuthProviderConfigured("google")) {
+  passport.use(
+    new GoogleStrategy(
+      {
+        clientID: process.env.GOOGLE_CLIENT_ID,
+        clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+        callbackURL:
+          process.env.GOOGLE_CALLBACK_URL || `${getBackendUrl()}/api/auth/google/callback`,
+      },
+      async (_accessToken, _refreshToken, profile, done) => {
+        try {
+          const email = profile.emails?.[0]?.value;
+          const sessionUser = await findOrCreateOAuthUser({
+            provider: "google",
+            providerId: profile.id,
+            email,
+            displayName: profile.displayName,
+            username: profile.displayName,
+          });
+          return done(null, sessionUser);
+        } catch (err) {
+          return done(err, null);
+        }
+      }
+    )
+  );
+}
+
+if (isOAuthProviderConfigured("github")) {
+  passport.use(
+    new GitHubStrategy(
+      {
+        clientID: process.env.GITHUB_OAUTH_CLIENT_ID,
+        clientSecret: process.env.GITHUB_OAUTH_CLIENT_SECRET,
+        callbackURL:
+          process.env.GITHUB_CALLBACK_URL || `${getBackendUrl()}/api/auth/github/callback`,
+        scope: ["user:email"],
+      },
+      async (_accessToken, _refreshToken, profile, done) => {
+        try {
+          const email = profile.emails?.find((entry) => entry.primary)?.value
+            || profile.emails?.[0]?.value;
+
+          const sessionUser = await findOrCreateOAuthUser({
+            provider: "github",
+            providerId: profile.id,
+            email,
+            username: profile.username,
+            displayName: profile.displayName,
+          });
+          return done(null, sessionUser);
+        } catch (err) {
+          return done(err, null);
+        }
+      }
+    )
+  );
+}
+
 passport.serializeUser((user, done) => {
-    done(null, user.id);
+  done(null, user.id);
 });
 
-// Deserialize user (retrieve user from session)
 passport.deserializeUser(async (id, done) => {
-    try {
-        const user = await User.findById(id);
-        done(null, user);
-    } catch (err) {
-        done(err, null);
+  try {
+    const user = await User.findById(id);
+    if (!user) {
+      return done(null, false);
     }
+    done(null, toSessionUser(user));
+  } catch (err) {
+    done(err, null);
+  }
 });
+
+module.exports = {
+  getFrontendUrl,
+  isOAuthProviderConfigured,
+};

backend/models/User.js

@@ -1,6 +1,8 @@
 const mongoose = require("mongoose");
 const bcrypt = require("bcryptjs");
 
+const PROVIDERS = ["local", "google", "github"];
+
 const UserSchema = new mongoose.Schema({
   username: {
     type: String,
@@ -14,21 +16,33 @@ const UserSchema = new mongoose.Schema({
   },
   password: {
     type: String,
-    required: true,
+    required: function requiredPassword() {
+      return this.provider === "local";
+    },
+  },
+  provider: {
+    type: String,
+    enum: PROVIDERS,
+    default: "local",
+  },
+  providerId: {
+    type: String,
+    sparse: true,
   },
 });
 
-// ✅ FIXED: no next()
-UserSchema.pre('save', async function () {
-  if (!this.isModified('password')) return;
+UserSchema.index({ provider: 1, providerId: 1 }, { unique: true, sparse: true });
+
+UserSchema.pre("save", async function hashPasswordIfPresent() {
+  if (!this.isModified("password") || !this.password) return;
 
   const salt = await bcrypt.genSalt(10);
   this.password = await bcrypt.hash(this.password, salt);
 });
 
-// ✅ password comparison
-UserSchema.methods.comparePassword = async function (enteredPassword) {
+UserSchema.methods.comparePassword = async function comparePassword(enteredPassword) {
+  if (!this.password) return false;
   return bcrypt.compare(enteredPassword, this.password);
 };
 
-module.exports = mongoose.model("User", UserSchema);
+module.exports = mongoose.model("User", UserSchema);

backend/package.json

@@ -20,6 +20,8 @@
     "express-session": "^1.18.1",
     "mongoose": "^8.8.2",
     "passport": "^0.7.0",
+    "passport-github2": "^0.1.12",
+    "passport-google-oauth20": "^2.0.0",
     "passport-local": "^1.0.0",
     "winston": "^3.19.0",
     "zod": "^4.4.3"