Forem: NHero

Password Auth in Express with Typescript & JWT

NHero — Sat, 23 May 2026 20:51:54 +0000

⚡ Quick Architecture Cheat Sheet (For Fast Revision)

If you are using this post to refresh your memory, here is the core token blueprint:

Token Type	Stored In	Lifetime (Recommended)	Primary Purpose
Access Token	HTTP-Only Cookie / Auth Header	15 Minutes	Authenticating short-lived protected route requests
Refresh Token	Database & HTTP-Only Cookie	7 to 10 Days	Requesting a brand new Access Token when it expires

The Token Lifecycle Flow

[Client] -------------- 1. Send Login Credentials ---------------> [Backend]
[Client] <-------- 2. Set Access & Refresh Cookies --------------- [Backend] (Saves Refresh Token to DB)

[Client] -------- 3. Access Protected Route (With Cookie) --------> [verifyJWT Middleware] -> [Granted]

Project Setup & Prerequisites

📂 Project Structure

└── src/
    ├── @types/
    ├── controllers/
    ├── middlewares/
    ├── models/
    ├── routes/
    ├── utils/
    ├── app.ts
    └── index.ts

📥 Install Required Packages

Run the following commands to install the necessary production and development dependencies:

npm install jsonwebtoken bcrypt mongoose cookie-parser
npm install -D @types/jsonwebtoken @types/bcrypt

🌐 Environment Variables

Create a .env file in your root directory:

ACCESS_TOKEN_SECRET=your_super_secret_access_key
ACCESS_TOKEN_EXPIRY=15m

REFRESH_TOKEN_SECRET=your_super_secret_refresh_key
REFRESH_TOKEN_EXPIRY=7d

Step 1: Standardizing Global API Responses

Before touching authentication, we build reusable helper classes. This keeps frontend handling much cleaner since every response follows the same structure.

export class ApiError extends Error {
  statusCode: number;
  message: string;
  errors: any[];
  stack?: string;
  data: any;
  success: boolean;

  constructor(
    statusCode: number,
    message = "Something went wrong",
    errors = [],
    stack = ""
  ) {
    super(message)
    this.statusCode = statusCode
    this.data = null
    this.message = message
    this.success = false
    this.errors = errors

    if (stack) {
      this.stack = stack
    } else {
      Error.captureStackTrace(this, this.constructor)
    }
  }
}

export class ApiResponse {
  statusCode: number;
  data: any;
  message: string;
  success: boolean;

  constructor(
    statusCode: number,
    data: any,
    message: string = "Success"
  ) {
    this.statusCode = statusCode
    this.data = data
    this.message = message
    this.success = statusCode < 400
  }
}

💡 Why use this pattern?
Instead of manually typing return res.status(200).json({ success: true, data }) in dozens of locations, these utility classes enforce structural consistency across your entire backend footprint.

Step 2: Designing the Data Layer (The User Model)

Instead of hashing passwords manually inside controllers every time, we move the logic into the schema itself using pre-save hooks and custom schema methods.

import { model, Schema, type HydratedDocument } from "mongoose";
import jwt, { type Secret, type SignOptions } from "jsonwebtoken";
import bcrypt from "bcrypt";

export interface IUser {
  username: string;
  fullName: string;
  email: string;
  password: string;
  avatarUrl?: string;
  refreshToken?: string;

  generateAccessToken: () => string;
  generateRefreshToken: () => string;
  isPasswordCorrect: (password: string) => Promise<boolean>;
}

export type IUserDocument = HydratedDocument<IUser>;

const userSchema = new Schema<IUser>({
  username: { type: String, required: true, unique: true, lowercase: true },
  fullName: { type: String, required: true },
  email: { type: String, required: true, unique: true },
  password: { type: String, required: true },
  avatarUrl: { type: String },
  refreshToken: { type: String }
});

// Automatic Password Hashing Hook
userSchema.pre("save", async function (next): Promise<void> {
  if (!this.isModified("password")) return next();

  this.password = await bcrypt.hash(this.password, 10);
  next();
});

// Secure Password Comparison Method
userSchema.methods.isPasswordCorrect = async function (password: string): Promise<boolean> {
  return await bcrypt.compare(password, this.password);
};

// Access Token Generator
userSchema.methods.generateAccessToken = function (): string {
  return jwt.sign(
    {
      _id: this._id,
      email: this.email,
      username: this.username,
      fullName: this.fullName,
    },
    process.env.ACCESS_TOKEN_SECRET as Secret,
    {
      expiresIn: process.env.ACCESS_TOKEN_EXPIRY,
    } as SignOptions
  );
};

// Refresh Token Generator
userSchema.methods.generateRefreshToken = function (): string {
  return jwt.sign(
    {
      _id: this._id,
    },
    process.env.REFRESH_TOKEN_SECRET as Secret,
    {
      expiresIn: process.env.REFRESH_TOKEN_EXPIRY,
    } as SignOptions
  );
};

export const User = model<IUser>("User", userSchema);

🧠 Revision Insight: Why handle Hashing & Token generation in the Model?

Automatic Hashing: The pre("save") hook ensures you can never accidentally save a plaintext password to your database.

Encapsulation: Controllers don't need to know how JWTs are signed or how passwords are encrypted. They simply call user.generateAccessToken().

Step 3: Centralizing Token Orchestration

Instead of issuing and saving tokens inside our login controller, we create an independent utility helper. This utility issues the pairs and commits the refresh token to the database.

src/utils/generateTokens.ts

import { Types } from "mongoose";
import { User } from "../models/User.model.js";
import { ApiError } from "./ApiError.js";

export const generateTokens = async (userId: Types.ObjectId | string): Promise<{ accessToken: string; refreshToken: string }> => {
  try {
    const user = await User.findById(userId);
    if (!user) {
      throw new ApiError(404, "User not found");
    }

    const accessToken = user.generateAccessToken();
    const refreshToken = user.generateRefreshToken();

    // Store the refresh token in the database to manage active sessions
    user.refreshToken = refreshToken;
    await user.save({ validateBeforeSave: false });

    return { accessToken, refreshToken };
  } catch (err) {
    throw new ApiError(500, "Error while generating authentication tokens");
  }
};

🔒 Security Checkpoint: Why save the Refresh Token to the database?
Storing refresh tokens statefully allows the backend to force a hard logout, instantly invalidate stolen sessions, and roll out security practices like refresh token rotation.

Step 4: Coding the Authentication Controllers

Now we implement our core application logic: User Registration, Login, and Session Management.

Shared Cookie Parameters

To guard against client-side script token theft, we enforce strict browser settings via cookie options:

const cookieOptions = {
  httpOnly: true, // Prevents XSS script execution from reading the token
  secure: process.env.NODE_ENV === "production", // Forces HTTPS connections in production
  sameSite: "strict" as const, // Suppresses CSRF attacks across origins
};

import { type Request, type Response } from "express";
import { User } from "../models/User.model.js";
import { ApiError } from "../utils/ApiError.js";
import { ApiResponse } from "../utils/ApiResponse.js";
import { generateTokens } from "../utils/generateTokens.js";

// 1. REGISTER USER
export const registerUser = async (req: Request, res: Response) => {
  const { username, email, fullName, password } = req.body;

  if ([fullName, email, username, password].some((field) => field?.trim() === "")) {
    throw new ApiError(400, "All registration fields are required");
  }

  const userExists = await User.findOne({ $or: [{ username }, { email }] });
  if (userExists) {
    throw new ApiError(409, "A user with this username or email already exists");
  }

  const user = await User.create({
    fullName,
    email,
    password,
    username: username.toLowerCase(),
  });

  const createdUser = await User.findById(user._id).select("-password -refreshToken");
  if (!createdUser) {
    throw new ApiError(500, "Something went wrong while creating the user account");
  }

  return res.status(201).json(
    new ApiResponse(201, createdUser, "User registered successfully")
  );
};

// 2. LOGIN USER
export const loginUser = async (req: Request, res: Response) => {
  const { username, email, password } = req.body;

  if (!username && !email) {
    throw new ApiError(400, "Username or email is required");
  } 
  if (!password) {
    throw new ApiError(400, "Password field is required");
  }

  const user = await User.findOne({ $or: [{ username }, { email }] });
  if (!user) {
    throw new ApiError(404, "User account does not exist");
  }

  const isPassValid = await user.isPasswordCorrect(password);
  if (!isPassValid) {
    throw new ApiError(401, "Invalid user credentials");
  }

  const { accessToken, refreshToken } = await generateTokens(user._id);

  const userData = {
    _id: user._id,
    fullName: user.fullName,
    username: user.username,
    email: user.email,
    avatarUrl: user.avatarUrl,
  };

  return res
    .status(200)
    .cookie("accessToken", accessToken, cookieOptions)
    .cookie("refreshToken", refreshToken, cookieOptions)
    .json(
      new ApiResponse(200, { user: userData, accessToken, refreshToken }, "User logged in successfully")
    );
};

// 3. REFRESH ACCESS TOKEN
export const refreshAccessToken = async (req: Request, res: Response) => {
  const incomingRefreshToken = req.cookies.refreshToken || req.body.refreshToken;

  if (!incomingRefreshToken) {
    throw new ApiError(401, "Refresh token is missing");
  }

  try {
    const decodedToken = jwt.verify(incomingRefreshToken, process.env.REFRESH_TOKEN_SECRET!) as any;
    const user = await User.findById(decodedToken?._id);

    if (!user) {
      throw new ApiError(401, "Invalid refresh token: User context not found");
    }

    if (user.refreshToken !== incomingRefreshToken) { 
      throw new ApiError(401, "Refresh token has expired or been revoked");
    }

    const { accessToken, refreshToken: newRefreshToken } = await generateTokens(user._id);

    return res
      .status(200)
      .cookie("accessToken", accessToken, cookieOptions)
      .cookie("refreshToken", newRefreshToken, cookieOptions)
      .json(
        new ApiResponse(200, { accessToken, refreshToken: newRefreshToken }, "Access token refreshed successfully")
      );
  } catch (err: any) {
    throw new ApiError(401, err?.message || "Invalid refresh token signature");
  }
};

// 4. LOGOUT USER
export const logoutUser = async (req: Request, res: Response) => {
  const userId = req.user?._id;

  if (!userId) {
    throw new ApiError(400, "Authenticated user context required for logout");
  }

  // Clear the database reference token completely
  await User.findByIdAndUpdate(userId, { $unset: { refreshToken: 1 } });  

  return res
    .status(200)
    .clearCookie("accessToken", cookieOptions)  
    .clearCookie("refreshToken", cookieOptions)
    .json(new ApiResponse(200, {}, "User logged out successfully"));
};

Step 5: Building the Gatekeeper (Auth Middleware)

Any resource route requiring active authentication runs through this middleware. It validates the incoming token and attaches the complete user details to the Request lifecycle object.

src/middlewares/auth.middleware.ts

import { type NextFunction, type Request, type Response } from "express";
import { User } from "../models/User.model.js";
import { ApiError } from "../utils/ApiError.js";
import jwt, { type JwtPayload } from "jsonwebtoken";

export const verifyJWT = async (req: Request, _: Response, next: NextFunction) => {
  try {
    const accessToken = req.cookies?.accessToken || req.header("Authorization")?.replace("Bearer ", "");

    if (!accessToken) {
      throw new ApiError(401, "Authentication required: Access token missing");
    }

    const decodedToken = jwt.verify(accessToken, process.env.ACCESS_TOKEN_SECRET!) as JwtPayload;
    const user = await User.findById(decodedToken._id).select("-password -refreshToken");

    if (!user) {
      throw new ApiError(401, "Authentication failed: Revoked user authorization");
    }

    req.user = user;
    next();
  } catch (error: any) {
    next(new ApiError(401, error?.message || "Invalid or expired access token"));
  }
};

🔒 Security Checkpoint: Why verify against the Database?
A standalone JWT verification can successfully pass if it hasn't expired yet—even if the user was deleted, banned, or had their account deactivated 2 minutes ago. Checking the database explicitly stops these zombie sessions instantly.

Step 6: Setting Up Express Auth Routes

Now, let's assemble our system components within our routing configurations. By chaining our controllers, we inject our verifyJWT gatekeeper directly in front of endpoints that demand active session contexts (like /logout).

src/routes/auth.routes.ts

import { Router } from "express";
import { loginUser, logoutUser, registerUser, refreshAccessToken } from "../controllers/auth.controller.js";
import { verifyJWT } from "../middlewares/auth.middleware.js";

const router = Router();

// Public Routes
router.route("/register").post(registerUser);
router.route("/login").post(loginUser);
router.route("/refresh-token").post(refreshAccessToken);

// Protected Routes (Uses middleware prior to hitting the controller)
router.route("/logout").post(verifyJWT, logoutUser);

export default router;

💡 Intermediate Tip: Streamlining Bulk Protected Routes
If you have dedicated route files where every single endpoint requires authentication (such as user.routes.ts or dashboard.routes.ts), passing verifyJWT individually can lead to repetitive code. Instead, mount the middleware at the root layout of the router:
const router = Router();

// Mount globally onto this specific router group instance
router.use(verifyJWT);

// Every endpoint listed down below is automatically secured!
router.route("/profile").get(getUserProfile);
router.route("/settings").patch(updateSettings);


---

## Step 7: Extending Express Typing Configurations

By default, Express does not have a `user` property inside its global `Request` object. We use declaration merging to inject our custom Mongoose Document model type safely.

`src/@types/express/index.d.ts`

ts
import { type IUserDocument } from "../../models/User.model.js";

declare module "express-serve-static-core" {
interface Request {
user?: IUserDocument;
}
}

export {};


Make sure your `tsconfig.json` knows where to compile and read your local definitions files:

json
{
"compilerOptions": {
"moduleResolution": "NodeNext",
"typeRoots": [
"./node_modules/@types",
"./src/@types"
]
},
"include": [
"src//*",
"src/@types//*.d.ts"
]
}




---

## Final Checklist

When building or updating your authentication service, ensure you check off these steps:

* <input type="checkbox" /> Explicitly clear sensitive properties (`-password`, `-refreshToken`) when retrieving items.


* <input type="checkbox" /> Passwords are automatically hashed via Mongoose hooks before persisting.


* <input type="checkbox" /> Cookies use `httpOnly: true` and strict `sameSite` setups.


* <input type="checkbox" /> Database validation is run after clearing the basic cryptographic token checks.



Happy coding! 🚀

Struggled with Google OAuth in Express + TypeScript? I made a step-by-step guide using JWT auth, Passport.js, and MongoDB with a clean scalable setup 🚀

NHero — Sat, 23 May 2026 10:29:12 +0000

NHero

May 23

Google Login in Express with PassportJS & JWT

#webdev #backend #express #passportjs

Comments

3 min read

Google Login in Express with PassportJS & JWT

NHero — Sat, 23 May 2026 10:12:28 +0000

⚡ Quick OAuth + JWT Architecture (For Fast Revision)

When handling social logins while maintaining a stateless JWT ecosystem, follow this flow:

[User] --- 1. GET /auth/google ---> [Passport Engine] ---> (Redirects to Google Sign-In)
[User] <--- 2. Grants Permission -- [Google Server]
[Backend Callback] <-- 3. Code/Profile Handshake <-- [Google Server] (Verifies & Upserts User Profile)
[User] <--- 4. Sets Secure Access & Refresh Cookies --- [Backend Controller] (Generates Custom JWTs)

Core Strategy Rules

No Server-Side Sessions: We explicitly disable passport session serialization (session: false) because our app uses stateless JWT tokens.
User Accounts Linking: If a user registers normally with an email address and later hits the "Sign In with Google" button, we automatically link the identity by pinning the googleId onto the pre-existing document profile.

Prerequisites & Dependencies

📂 Project Structure

└── src/
    ├── config/
    ├── controllers/
    ├── middlewares/
    ├── models/
    ├── routes/
    ├── utils/
    ├── app.ts
    └── index.ts
├── .env

📥 Install Required Packages

Execute the following installation string to fetch Passport.js, the Google OAuth2.0 strategy token extensions, and their respective type-hint definitions:

npm install passport passport-google-oauth20 jsonwebtoken cookie-parser bcrypt mongoose
npm install -D @types/passport-google-oauth20

Step 1: Cloud Console Configurations

Before writing software, you need application credentials from the Google Cloud Dashboard.

Navigate to the Google Cloud Console.
Create a New Project using the project selection drop-down layout.
Configure your OAuth Consent Screen and designate the publishing status as External.
Head to the Clients page, choose Create Clients, and click OAuth Client ID.
Set the application type to Web Application and add your explicit callback mapping:

Authorized Redirect URIs: http://localhost:3000/api/v1/auth/google/callback

Save your changes and copy your Client ID and Client Secret tokens.

🌐 Environment Setup

Append these key-value configurations to your root .env file environment block:

GOOGLE_CLIENT_ID=your_google_client_id_here
GOOGLE_CLIENT_SECRET=your_google_client_secret_here
GOOGLE_CALLBACK_URL=http://localhost:3000/api/v1/auth/google/callback

Step 2: Adapting the Database Schema

To support alternative OAuth logins alongside traditional password profiles, update your Mongoose Model configuration.

🔒 Critical Security Rule
When integrating third-party OAuth provider chains, you must make your schema's password string optional (required: false). This allows users who signed up with Google to create accounts without passwords.

Make sure these key fields are mapped out in your user schema definitions:

const userSchema = new Schema({
  username: { type: String, required: true, unique: true },
  email: { type: String, required: true, unique: true },

  // Make password optional for OAuth registrations!
  password: { type: String, required: false }, 

  avatarUrl: { type: String },
  refreshToken: { type: String },
  googleId: { type: String } // Keeps track of mapped Google profiles
});

To maintain security, place an evaluation guard inside your traditional login controllers so social-only accounts cannot be hijacked through brute-force attempts:

if (!user.password) {
  throw new ApiError(400, "This account was registered via Google Sign-In. Please log in using Google.");
}

Step 3: Architecting the Passport Strategy

Now we configure Passport to handle Google authentication.

Here we:

receive the Google profile
check if the user already exists
create a new account if needed
link existing accounts using email

import passport from "passport";
import { Strategy as GoogleStrategy } from "passport-google-oauth20";
import { User } from "../models/User.model.js";
import { generateUsername } from "../utils/usernameGen.js";

passport.use(
  new GoogleStrategy(
    {
      clientID: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
      callbackURL: process.env.GOOGLE_CALLBACK_URL,
    },
    async (_accessToken, _refreshToken, profile, done) => {
      try {
        const email = profile.emails?.[0]?.value;

        if (!email) {
          return done(new Error("Google account profile must yield a primary email address"));
        }

        // Look for an existing account matching either the googleId OR the email address
        let user = await User.findOne({
          $or: [{ googleId: profile.id }, { email }],
        });

        // Case 1: Account exists but lacks a googleId link (First-time social login for an existing user)
        if (user && !user.googleId) {
          user.googleId = profile.id;
          await user.save();
        }

        // Case 2: No account exists under this email - Create a brand new user profile
        if (!user) {
          const uniqueUsername = await generateUsername(profile.displayName);

          user = await User.create({
            username: uniqueUsername,
            fullName: profile.displayName,
            email,
            googleId: profile.id,
            avatarUrl: profile.photos?.[0]?.value || "",
          });
        }

        // Remove sensitive fields before returning the user
        const sanitizedUser = await User.findById(user._id).select("-password -refreshToken -googleId");
        if (!sanitizedUser) {
          return done(new Error("User not found after creation"));
        }

        return done(null, sanitizedUser);
      } catch (error) {
        return done(error as Error);
      }
    }
  )
);

export default passport;

Dynamic Namespace Deduplication Utility

When creating users via OAuth, Google provides full display names, which aren't guaranteed to be unique, so we generate a fallback username if needed.:

src/utils/usernameGen.ts

import { User } from "../models/User.model.js";

export const generateUsername = async (
  displayName: string
): Promise<string> => {
  const cleaned = displayName
    .toLowerCase()
    .replace(/[^a-z0-9]/g, "");

  const baseUsername =
    cleaned.length > 0
      ? cleaned.slice(0, 15)
      : "user";

  let username = "";
  let exists = true;

  while (exists) {
    const suffix = Math.floor(
      1000 + Math.random() * 9000
    );

    username = `${baseUsername}${suffix}`;

    exists = !!(await User.exists({
      username,
    }));
  }

  return username;
};

Step 4: Building the Callback Controller & Routes

Once Passport successfully authenticates the user, control moves to our controller.. Here, we generate our custom app cookies and pass down the response payload.

The Controller Handlers

src/controllers/auth.controller.ts

import { type Request, type Response } from "express";
import { generateTokens } from "../utils/generateTokens.js";

export const googleAuthCallback = async (req: Request, res: Response) => {
  // Passport injects the sanitized profile info onto the req.user property
  const user = req.user!;

  // Generate our system's regular custom JWT tokens
  const { accessToken, refreshToken } = await generateTokens(user._id);

  const cookieOptions = {
    httpOnly: true,
    secure: process.env.NODE_ENV === "production",
    sameSite: "strict" as const,
  };

  return res
    .status(200)
    .cookie("accessToken", accessToken, cookieOptions)
    .cookie("refreshToken", refreshToken, cookieOptions)
    .json({
      success: true,
      message: "Google authentication handshake completed successfully",
      user,
    });
};

Defining Route Registrations

src/routes/auth.routes.ts

import { Router } from "express";
import passport from "passport";
import { googleAuthCallback } from "../controllers/auth.controller.js";

const router = Router();

// Route 1: Initial redirect request loop trigger
router.route("/google").get(
  passport.authenticate("google", {
    scope: ["profile", "email"], // Target scope values required from Google Cloud console
    session: false, // Ensures stateless JWT operations
  })
);

// Route 2: Target route intercept landing zone for redirect returns from Google
router.route("/google/callback").get(
  passport.authenticate("google", {
    failureRedirect: "/login",
    session: false,
    failureMessage: "Failed to login with Google credentials",
  }),
  googleAuthCallback
);

export default router;

Step 5: Mounting Initializations

Finally, register and load the Passport setup directly within your core runtime file (app.ts) before mounting your routes.

src/app.ts

import express from "express";
import cookieParser from "cookie-parser";
import passport from "./config/passport.js"; // Loads strategy definitions
import authRouter from "./routes/auth.routes.js";

const app = express();

app.use(express.json());
app.use(cookieParser());

// Initialize Passport Engine
app.use(passport.initialize());

// App Routes
app.use("/api/v1/auth", authRouter);

export { app };

🛠️ Diagnostics & Troubleshooting Checkpoints

⚠️ Common Bug: Redirection URI Mismatch Errors
If Google dumps a configuration block error message on your display screen during testing, double-check that your callback strings match exactly across all three of these locations:

The Allowed Callback parameter mapped inside your Cloud Dashboard Console.

The GOOGLE_CALLBACK_URL literal configuration inside your .env workspace variables.

The callbackURL property parameter initialized inside your Passport strategy constructor instantiation block.

Summary Checklist

Made backend password strings optional (required: false) on database models.
Set session: false across all routing hooks to stay completely stateless.
Bound fallback profile configurations matching profile.emails?.[0]?.value queries.
Handled unique namespace fallback conflicts using clean alphanumeric deduplication utility logic.

Happy coding! 🚀