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

.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"