Forem: bismark66

The Hidden Cost of Login: How I Decoupled Session Cleanup from Authentication in NestJs

bismark66 — Mon, 13 Apr 2026 10:00:00 +0000

TL;DR

Login looks like two operations — password check + token issue — but there's often a third hiding at the end.
bcrypt is intentionally slow (~100ms). Everything else on the login path should be as lean as possible.
Running DELETE on expired sessions inside login() creates DB contention under load — users wait for cleanup that has nothing to do with their login succeeding.
The fix: move cleanup to a @Cron job using @nestjs/schedule. Login does only what the user is waiting for.
The principle: the critical path should contain only what the user is waiting for. Housekeeping belongs elsewhere.

When I built the auth flow for Truckly — a logistics platform I'm working on — I thought authentication was a solved problem. Validate credentials, issue tokens, send response. Standard stuff.

Then I looked more carefully at what was actually happening inside the login() method. There were operations in there that had no business blocking a user's login response. This is the story of finding them, understanding why they mattered, and fixing them.

Breaking Down the Login Path

Here's roughly what the original login flow looked like in NestJs, before the refactor. Each step is sequential — the user waits for all of them:

async login(email: string,password: string,  deviceInfo?: { ipAddress?: string; userAgent?: string; deviceType?: string }) {

// Step 1: Find user by email (fast — indexed column)  
const user = await this.usersService.findOneByEmail(email);

if (!user) throw new UnauthorizedException('User Not Found'); 

const payload = { email: user.email, sub: user.id, userType: user.userType }; 

// Step 2: bcrypt password comparison (~100ms — intentionally slow) const isMatch = await bcrypt.compare(password, user.password); 

if (!isMatch) throw new UnauthorizedException('Invalid credentials');  

// Step 3: Issue tokens, store session in user_sessions table (necessary)  
const accessToken = this.jwtService.sign(payload, { expiresIn: '60m' });  
const refreshToken = this.jwtService.sign(payload, {secret: this.configService.get('JWT_REFRESH_SECRET'), expiresIn: '7d',  });  
await this.createSession(user.id, refreshToken,refreshTokenExpiresAt, ...deviceInfo);  

// Step 4: Clean up expired sessions for this user — THIS WAS THE PROBLEM  
await this.userSessionRepository.createQueryBuilder().delete()    .where('refresh_token_expires_at < :now', { now: new Date() })    .andWhere('user_id = :userId', { userId: user.id }).execute(); 

return { access_token: accessToken, refresh_token: refreshToken };}

Four steps. Let's talk about each one's cost.

Step 1 — User Lookup (Fast)
A SELECT by email via findOneByEmail(). If there's an index on the email column — and there should be — this is a handful of milliseconds at most.

Step 2 — bcrypt.compare() (Slow — on purpose)
This is the one that surprises developers who haven't thought about it before. More on this in a moment.

Step 3 — Create Session (Predictable)
A JWT sign and an INSERT into the user_sessions table. Necessary. The user can't get their tokens without this.

Step 4 — Delete Expired Sessions (Variable, and not the user's problem)
A DELETE WHERE refresh_token_expires_at < NOW(). On a quiet database, this takes a few milliseconds. Under load, with concurrent logins happening, this step starts to hurt — and the user's response time takes the hit.

Why bcrypt Is Slow on Purpose

When you store a password, you store a hash — a one-way transformation. If your database leaks, an attacker can't read passwords directly; they have to crack each hash by brute-force guessing. Fast hashes like MD5 or SHA-256 let a modern GPU try billions of guesses per second. A password cracking session takes minutes.

bcrypt is designed like a lock that's slow to pick — not because it's broken, but because that resistance is the entire point. With a cost factor of 10–12, each guess takes ~50–100ms on a modern CPU. That means an attacker can only try ~10–20 passwords per second per core instead of billions. Brute force becomes impractical.

// bcrypt cost factor — each increment roughly doubles computation time

const hashedPassword = await bcrypt.hash(createUserDto.password, 10);

// At login — same work factor, same ~50–100ms cost 
const isMatch = await bcrypt.compare(pass, user.password);

That ~100ms is unavoidable and intentional. Anything else you add to the login critical path is felt on top of those 100ms. It raises the floor for every user, every login.

The Problem with Cleanup in the Critical Path
Here's the cleanup query that was in the original login flow:

// Ran synchronously inside login() — deleted expired sessions for the logging-in user

await this.userSessionRepository.createQueryBuilder().delete()  .where('refresh_token_expires_at < :now', { now: new Date() })  .andWhere('user_id = :userId', { userId: user.id })  .execute();

On a quiet system: fine. Under load:

Dozens or hundreds of users log in simultaneously
Each login fires a DELETE on user_sessions
The DB handles concurrent deletes alongside concurrent inserts (from Step 3)
Write contention grows — rows lock, queries queue, some start waiting
Login latency becomes unpredictable

Invisible in development, invisible in staging, visible in production when traffic peaks — exactly when you can least afford it.

But there's a more fundamental issue: the user doesn't care about cleanup. When someone logs in, they want their access token. They have zero interest in whether an expired session from three weeks ago gets cleaned up in the same request. That cleanup benefits the system, not the user. Making users wait for your housekeeping is a design smell.

The Fix: Async Cron Cleanup with @nestjs/schedule

Move cleanup out of login() entirely and into a background job.

npm install @nestjs/schedule

// app.module.ts — register the scheduler once 
import { ScheduleModule } from '@nestjs/schedule';

@Module({imports: [   
 ScheduleModule.forRoot(), 
// ...other imports
],})
export class AppModule {}

A dedicated service whose only job is housekeeping:

// session-cleanup.service.ts
import { Injectable, Logger } from '@nestjs/common';
import { Cron, CronExpression } from '@nestjs/schedule';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { UserSession } from '../auth/entities/user-session.entity';

@Injectable()
export class SessionCleanupService {  
private readonly logger = new Logger(SessionCleanupService.name);  constructor(
@InjectRepository(UserSession) 
private readonly userSessionRepository: Repository<UserSession>,
) {}  
/*  
* Runs every 30 minutes, fully independent of login traffic.  
* Deletes sessions where the refresh token has expired.   
* Users with active, unexpired sessions are completely unaffected.   */ 

@Cron(CronExpression.EVERY_30_MINUTES) 
async cleanupExpiredSessions(): Promise<void> { 
const result = await this.userSessionRepository      .createQueryBuilder()
.delete()
.where('refresh_token_expires_at < :now', {now: new Date()})     .execute();
this.logger.log(`Session cleanup complete. Removed ${result.affected ?? 0} expired sessions.`);}}

And the lean login method — three steps only:

// auth.service.ts — login critical path only
async login(  email: string,  password: string,  deviceInfo?: { ipAddress?: string; userAgent?: string; deviceType?: string },) 
{  
// Steps 1 + 2: user lookup + bcrypt comparison, via validateUser()  

const user = await this.validateUser(email, password);  
const payload = { email: user.email, sub: user.id, userType: user.userType };  

// Short-lived access token (stateless — no DB lookup on each request)  

const accessToken = this.jwtService.sign(payload, { expiresIn: '60m' }); 

// Long-lived refresh token (stored in DB for revocation support)  const refreshToken = this.jwtService.sign(payload, {secret: this.configService.get<string>('JWT_REFRESH_SECRET'),expiresIn: '7d',  });  

// Step 3: Persist session — only the refresh token, not the access token  
const refreshTokenExpiresAt = new Date();  refreshTokenExpiresAt.setDate(refreshTokenExpiresAt.getDate() + 7);  

await this.createSession(user.id,refreshToken,refreshTokenExpiresAt,    deviceInfo?.ipAddress,deviceInfo?.userAgent,deviceInfo?.deviceType);


// Step 4 is gone. SessionCleanupService runs every 30 min independently.  
return {access_token: accessToken,refresh_token: refreshToken,    expires_in: 3600, user: {id: user.id, email: user.email, firstName: user.firstName, ...},};}

One detail worth noting: only the refresh token is stored in the database. The access token is stateless — validated by JWT signature alone, no DB hit on every authenticated request. This keeps user_sessions lean and the auth hot path fast.

What Big Tech Does

Useful to see where these patterns evolve at greater scale.

Redis + TTL: Many companies move session storage out of the relational DB into Redis. Redis supports per-key TTL — set the expiry at write time, Redis deletes it automatically when it lapses. No cleanup job, no cron, no stale rows.

// Store session with 7-day TTL — Redis handles deletion automatically

await redis.set(  `session:${sessionId}`,  JSON.stringify({ userId, deviceType }),'EX',60 * 60 * 24 * 7,);

Lazy cleanup: Skip proactive cleanup entirely. When a session is read, check if it's expired and delete it then. No job needed; cost spreads across reads.

Async queues (BullMQ, Kafka): At larger scale, bookkeeping gets published to a queue and processed by isolated workers. A future evolution could emit a low-priority cleanup job after login rather than relying on a fixed cron window.

Argon2id: Modern systems are moving from bcrypt to Argon2id — winner of the Password Hashing Competition. Configurable across time and memory cost, more resistant to GPU-based attacks. Same intentional-slowness principle, more modern implementation.

The Principle: Never Make Users Wait for Bookkeeping

The critical path should contain only what the user is waiting for.

Anything that benefits the system — cleanup, analytics, audit logs, notification emails — should be decoupled from the operation the user is performing. This generalises:

Don't send a welcome email inside the registration handler — queue it
Don't update analytics counters inside the API response — emit an event
Don't run cleanup queries inside login — schedule them

Identify what the user is actually waiting for. Make that path lean. Push everything else out of the way.

Tradeoffs

Stale rows linger until the cron runs. A session that expires at 2:00 PM stays in the DB until the 2:30 PM sweep. For most apps this is fine — expired sessions won't pass refreshTokenExpiresAt < new Date() validation. But the rows exist temporarily.

Tune the cron frequency to your traffic. Every 30 minutes is a reasonable default. Millions of DAUs? Consider every 5 minutes. Hundreds of users? Once a day is enough.

Silent failures need alerting. Synchronous cleanup throws — you know when it fails. A cron job that fails silently just doesn't run. The Logger above is the minimum. Add metrics and alerting for production.

Conclusion

This change to an auth service is small but impactful — a new auth service, a cron decorator, a method moved. But the thinking behind it applies to almost any backend system.

Every time you're about to add an operation to a hot path, ask: does the user actually need to wait for this?

If the answer is "no, this benefits the system" — it belongs in background processing. The user should never be the vehicle for your database maintenance.

Follow for more backend engineering deep dives.

Building Secure Session Management in NestJS - Refresh Tokens, Device Tracking & Session Revocation(PART 2)

bismark66 — Tue, 31 Mar 2026 21:51:35 +0000

1. The Refresh Token Flow — Validating Against the DB

This is where the real security upgrade happens. Instead of just verifying the JWT signature, we now check the database to confirm the session still exists and hasn't been revoked.

// auth.service.ts — updated refreshToken method
async refreshToken(rawRefreshToken: string) {

// Step 1: Verify the JWT signature and check expiry.
// jwtService.verify() throws an error if the token is expired or the signature is invalid.


let payload: any;
try {

payload = this.jwtService.verify(rawRefreshToken, {
secret: this.configService.get<string>('JWT_REFRESH_SECRET'),
});
} catch {
// The token is either expired or was tampered with
throw new UnauthorizedException('Refresh token is invalid or expired');
}


// Step 2: Load all active sessions for this user from the database.
// We need to find the specific session that matches this refresh token.

// Note: we explicitly request 'refreshTokenHash' since it has select: false on the entity.

const sessions = await this.sessionRepository.find({
where: { userId: payload.sub, isActive: true },
select: ['id', 'refreshTokenHash', 'expiresAt', 'isActive'],
});

// Step 3: Compare the incoming token against each session's stored hash.
// bcrypt.compare() handles this — it hashes the raw token and checks if it matches.

let matchingSession: Session | null = null;

for (const session of sessions) {
const isMatch = await bcrypt.compare(
rawRefreshToken,
session.refreshTokenHash,
);

if (isMatch) {
matchingSession = session;
break; // Found it — no need to check further
}
}

// Step 4: If no matching session exists, it was revoked (user logged out)

if (!matchingSession) {
throw new UnauthorizedException('Session not found or has been revoked');
}

// Step 5: Double-check the session's own expiry timestamp

if (new Date() > matchingSession.expiresAt) {
await this.sessionRepository.update(matchingSession.id, {
isActive: false,
});

throw new UnauthorizedException('Session has expired. Please log in again.',);
}

// Step 6: Record that this session was just used (for "last active" display)

await this.sessionRepository.update(matchingSession.id, {
lastUsedAt: new Date(),
});

// Step 7: Issue a fresh access token

const user = await this.usersService.findOne(payload.sub);
if (!user) throw new UnauthorizedException('User not found');

const newPayload = { email: user.email, sub: user.id, role: user.role };
const accessToken = this.jwtService.sign(newPayload, { expiresIn: '15m' });
return {
access_token: accessToken,
expires_in: 900,
};
}

Why this matters: A stolen refresh token is now useless the moment the legitimate user logs out. The database is the source of truth — not just the JWT signature.

Performance note: If a user has many sessions (lots of devices), iterating through all of them to bcrypt-compare can be slow. A common optimization is to include the session ID in the refresh token's JWT payload, so you can look up the exact session directly and only do one bcrypt comparison.

2. Session Revocation — Logout (Single) and Logout-All

Single Device Logout
When a user logs out from one device, we mark that specific session as inactive. The refresh token is now dead — even if it hasn't reached its JWT expiry date.

// auth.service.ts
async logout(userId: string, sessionId: string) {
// Find the session — and confirm it actually belongs to this user.
// Never skip this check! Otherwise, user A could log out user B.

const session = await this.sessionRepository.findOne({
where: { id: sessionId, userId, isActive: true },
});

if (!session) {
throw new BadRequestException('Session not found');
}

// Mark as inactive (soft delete — we keep the row for audit purposes)

await this.sessionRepository.update(session.id, { isActive: false });
return { message: 'Logged out successfully' };
}

// auth.controller.ts
@Post('logout')
@UseGuards(JwtAuthGuard) // Must be authenticated to logout
@ApiBearerAuth()
async logout(@Req() req, @Body() body: { session_id: string }) {
// req.user.userId is populated by JwtStrategy.validate()
return this.authService.logout(req.user.userId, body.session_id);
}

Logout From All Devices
This is the "I think my account was compromised" button. One call, every session gone.

// auth.service.ts
async logoutAll(userId: string) {
// Deactivate every active session for this user in one query

await this.sessionRepository.update(
{ userId, isActive: true },
{ isActive: false },
);

return { message: 'Logged out from all devices successfully' };
}

// auth.controller.ts
@Post('logout-all')
@UseGuards(JwtAuthGuard)
@ApiBearerAuth()
@ApiOperation({ summary: 'Revoke all active sessions for the current user' })
async logoutAll(@Req() req) {
return this.authService.logoutAll(req.user.userId);
}

3. Password Change = Revoke All Sessions

This one is critical and often missed. When a user changes their password, you should immediately invalidate all their existing sessions.

Here's why this matters: imagine a user named Kofi suspects his account has been compromised. He changes his password. But without session revocation, any attacker who already has a valid refresh token can keep getting new access tokens for up to 7 more days -completely unaffected by the password change.

// auth.service.ts
async changePassword(
userId: string,
currentPassword: string,
newPassword: string
) {
// Get user including the password field (it has select: false on the entity)

const user = await this.usersService.findOneWithPassword(userId);

if (!user || !user.password) {
throw new BadRequestException('User not found');
}

// Verify the current password is correct before allowing the change

const isCurrentPasswordValid =  bcrypt.compare(currentPassword,user.password);

if (!isCurrentPasswordValid) {
throw new UnauthorizedException('Current password is incorrect');
}

// Hash and save the new password

const hashedNewPassword = await bcrypt.hash(newPassword, 10);
await this.usersService.updatePassword(userId, hashedNewPassword);

// ✅ CRITICAL STEP: Revoke ALL sessions.
// Any stolen refresh tokens are now completely useless.

await this.sessionRepository.update(
{ userId, isActive: true },
{ isActive: false },
);

return {
message:'Password changed successfully. You have been logged out from all devices. Please log in again.',
};
}

The user will need to log in again on all their devices — which is expected and correct. Security over convenience, always.

4. Listing Active Sessions - Letting Users See Where They're Logged In

This is the feature users love. You've seen it in Google Account settings: "Your account is currently active on these devices." Here's how to build it:

// auth.service.ts
async getActiveSessions(userId: string) {
const sessions = await this.sessionRepository.find({
where: { userId, isActive: true },
order: { createdAt: 'DESC' }, // most recent login first
});

// Map to a clean format for the client.
// We never expose the refreshTokenHash.

return sessions.map((session) => ({
id: session.id, // client uses this to revoke a specific session
device: ${session.browser} on ${session.os}, // "Chrome on macOS"
deviceType: session.deviceType,
ipAddress: session.ipAddress,
lastUsed: session.lastUsedAt || session.createdAt,
loggedInAt: session.createdAt,
expiresAt: session.expiresAt,
}));
}

// auth.controller.ts
@Get('sessions')
@UseGuards(JwtAuthGuard)
@ApiBearerAuth()
@ApiOperation({ summary: 'List all active sessions for the current user' })
async getSessions(@Req() req) {
return this.authService.getActiveSessions(req.user.userId);
}

A sample response:

[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"device": "Chrome on macOS",
"deviceType": "desktop",
"ipAddress": "41.66.12.34",
"lastUsed": "2026-03-02T09:45:00.000Z",
"loggedInAt": "2026-03-01T08:00:00.000Z",
"expiresAt": "2026-03-08T08:00:00.000Z"
},
{
"id": "660e8400-e29b-41d4-a716-446655440001",
"device": "Mobile Safari on iOS",
"deviceType": "mobile",
"ipAddress": "41.66.12.35",
"lastUsed": "2026-03-01T22:10:00.000Z",
"loggedInAt": "2026-02-28T14:22:00.000Z",
"expiresAt": "2026-03-07T14:22:00.000Z"
}
]

Users can pass the session id to POST /auth/logout to revoke any specific session they don't recognize.

5. Tradeoffs & Considerations

Nothing is free. Here's what you're taking on with this approach:

What you gain

Real logout — revocation actually works
Per-device visibility for users
Protection against token theft
Password change security (all sessions wiped)
Audit trail of login activity

What you're taking on
Database hit on every token refresh. Every time a client needs a new access token (up to every 15 minutes per active user), you query the database. For large-scale apps, this adds up.

Mitigation: cache session lookups in Redis with a short TTL, or embed the session ID in the JWT payload to enable a direct lookup instead of scanning all user sessions.
You need to clean up old sessions. Sessions pile up over time. Set up a scheduled cleanup job using @nestjs/schedule:

// sessions-cleanup.service.ts
import { Injectable } from '@nestjs/common';
import { Cron, CronExpression } from '@nestjs/schedule';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository, LessThan } from 'typeorm';
import { Session } from './session.entity';

@Injectable()
export class SessionsCleanupService {

constructor(
@InjectRepository(Session)
private sessionRepository: Repository<Session>,
) {}

// Runs every night at midnight

@Cron(CronExpression.EVERY_DAY_AT_MIDNIGHT)
async cleanupExpiredSessions() {
// Delete sessions that have passed their expiresAt date

const result = await this.sessionRepository.delete({
expiresAt: LessThan(new Date()),
});
console.log(Cleaned up ${result.affected} expired sessions);
}
}

Refresh token rotation (optional but recommended). For maximum security, issue a new refresh token on every /auth/refresh call and invalidate the old one. This means if a refresh token is stolen and used before the legitimate user uses it, the legitimate user's next refresh will fail — an early signal that something is wrong. This is more complex but closes a subtle replay attack window. User-Agent parsing is heuristic. The ua-parser-js library is good, but not perfect. Some browsers misreport themselves, and bots can spoof any user-agent string. Treat device info as helpful metadata for display purposes, not as a hard security boundary.

6. Conclusion + Key Takeaways

Here's a quick recap of what we built:

Feature	Implementation
Revocable sessions	Session entity in DB; logout marks isActive = false
Device tracking	DeviceInfoMiddleware parses User-Agent header on login
Secure token storage	bcrypt hash stored in DB; raw token never persisted
Single-device logout	POST /auth/logout with session_id
Logout all devices	POST /auth/logout-all bulk-deactivates all sessions
Password change security	changePassword revokes all sessions automatically
Active sessions screen	GET /auth/sessions returns clean session list

The core mental model to remember: JWTs are your fast lane; database sessions are your checkpoint. Short-lived access tokens (15 min) keep performance high because you only check the DB occasionally. Database-backed sessions give you the control to say "no" to a refresh token that was supposed to be dead.

If you're starting out: the most impactful things to implement first are the session entity, the DB lookup on refresh, and the revoke-all-on-password-change. Everything else — device tracking, cleanup jobs, session listing — is valuable but additive.
Your users are trusting you with their accounts.
Follow for more backend engineering deep dives.

Building Secure Session Management in NestJS - Refresh Tokens, Device Tracking & Session Revocation(PART 1)

bismark66 — Thu, 12 Mar 2026 10:56:48 +0000

1. The Hook — Why "Just Use JWT" Isn't Enough

If you've built auth before, you've probably done this:

User logs in → you generate a JWT → you send it back → done. And it works! For a weekend project. But let me ask you a few questions: What happens if a user's token gets stolen? Can you invalidate it? If a user changes their password, are their other logged-in devices kicked out? Can your users see where they're logged in — phone, laptop, browser — and revoke specific sessions? Do you even know how many active sessions exist right now? If you answered "no" to any of these, this article is for you.

In this post I'll walk through the entire thing — from the problem, to the architecture, to the actual code. By the end, you'll understand exactly how to implement production-grade session management in NestJS.

2. The Problem — What Breaks Without Proper Session Management

Let's start with a quick primer on how JWT auth normally works.

What is a JWT?
A JWT (JSON Web Token) is a string that encodes information — like a user's ID and role — and is cryptographically signed. It looks like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyLTEyMyIsImVtYWlsIjoiam9lQGV4YW1wbGUuY29tIn0.abc123

Three parts, separated by dots: header, payload, signature. You don't need to memorize this — just know that:

The payload contains data you encoded (user ID, role, expiry time)
The signature proves it wasn't tampered with
Anyone with a valid token can use it until it expires — you can't cancel it early

That last point is the key problem.

The "Hotel Key Card" Analogy
Think of a JWT like a hotel key card. When you check in, the front desk gives you a card that opens your room. It works for the duration of your stay.

Now imagine someone steals your key card. The hotel can't remotely deactivate that specific card — once it's issued, it opens the door until it expires.

Standard JWT auth has this exact problem:

No revocation. Once issued, a token is valid until expiry. If it's stolen, you can't stop it.
No visibility. You have no idea how many "copies" of a session exist or where they're being used from.
Password changes don't log out other devices. A user changes their password thinking they're secure — but any stolen tokens still work.
No real logout. Traditional JWT "logout" just deletes the token from localStorage. The token itself is still perfectly valid on the server.

What we had before
Here's a basic auth service:

// The "naive" version — functional but not production-safe
async login(email: string, password: string) {
const user = await this.validateUser(email, password);

if (!user) { throw new UnauthorizedException('Invalid credentials');}

const payload = { email: user.email, sub: user.id, role: user.role };

// Access token — valid for 15 minutes
const accessToken = this.jwtService.sign(payload, { expiresIn: '15m' });

// Refresh token — valid for 7 days (more on this below)
const refreshToken = this.jwtService.sign(payload,{
secret: this.configService.get<string>('JWT_REFRESH_SECRET'),
expiresIn: '7d',
});

return { access_token: accessToken, refresh_token: refreshToken };
}

This works, but there's no database record of this session. No way to revoke it. No device info. No IP. If someone grabs that refresh_token,they can silently keep refreshing access for 7 days.

Let's fix that.

3. The Architecture — JWT + Database-Backed Sessions

First: What's the difference between an access token and a refresh token?
This trips up a lot of beginners, so let's nail it before going further.

When a user logs in, we issue two tokens:

Access token — Short-lived (15 minutes). The client sends this with every API request. It's like your boarding pass: valid, fast to check, but expires quickly.
Refresh token — Long-lived (7 days). The client only uses this to request a new access token when the old one expires. It's like the ID you showed at check-in to get the boarding pass.

Why two tokens instead of one long-lived one? Because access tokens are sent constantly — if one leaks, the damage window is small (15 minutes max). The refresh token is only used occasionally and can be stored more securely.

The solution: hybrid JWT + DB sessions
We combine stateless JWTs with stateful database sessions. You get the performance benefits of JWTs for most requests, plus the control of server-side sessions when you need it.

Here's the high-level flow:

User logs in
│
▼
Validate credentials
│
▼
Create a Session record in the DB
(stores: refresh token hash, device info, IP, timestamps)
│
▼
Issue access token (JWT, 15 min) + refresh token (JWT, 7 days)
│
▼
User makes API requests using the short-lived access token
│
▼
Access token expires → client sends refresh token to /auth/refresh
│
▼
Look up session in DB → if found & valid → issue new access token
│
▼
On logout → delete session from DB (refresh token is now worthless)

The key insight: the refresh token is only as good as the session record in your database. Even if someone steals the refresh token, if you delete the session record, the token is dead.

4. The Session Entity — What Gets Stored Per Session

Let's start with the data model using typeOrm as our ORM(Object-Relational Mapper). A session represents one login event — one device, one browser, one app install.

// session.entity.ts
import {
Entity,
PrimaryGeneratedColumn,
Column,
CreateDateColumn,
ManyToOne,
JoinColumn,
} from 'typeorm';


import { User } from '../users/entities/user.entity';

@Entity('sessions')
export class Session {
@PrimaryGeneratedColumn('uuid')
id: string;

// Which user this session belongs to.
// onDelete: 'CASCADE' means if the user is deleted, their sessions are too.

@ManyToOne(() => User, { onDelete: 'CASCADE' })
@JoinColumn({ name: 'userId' })
user: User;

@Column()
userId: string;

// We store a HASH of the refresh token, never the raw token.
// Same reason you hash passwords — if the DB leaks, tokens are useless.
// select: false means this field is excluded from queries unless explicitly requested.

@Column({ select: false })
refreshTokenHash: string;

// Device & browser info (captured from the User-Agent header on login)
@Column({ nullable: true })
deviceType: string; // e.g. 'mobile', 'desktop', 'tablet'

@Column({ nullable: true })
browser: string; // e.g. 'Chrome', 'Safari', 'Firefox'

@Column({ nullable: true })
os: string; // e.g. 'Windows', 'macOS', 'Android'

// Where the login came from
@Column({ nullable: true })
ipAddress: string;

// The raw User-Agent string, kept for debugging
@Column({ nullable: true })
userAgent: string;

// When does this session expire? (should match the refresh token's expiry)
@Column({ type: 'timestamp' })
expiresAt: Date;

// Last time this session was used to get a new access token
@Column({ type: 'timestamp', nullable: true })
lastUsedAt: Date;

@CreateDateColumn()
createdAt: Date;

// Soft-delete flag: we mark sessions inactive rather than deleting them immediately.

// Useful for audit logs and security investigations.

@Column({ default: true })
isActive: boolean;

}

A few important design decisions here:

We hash the refresh token before storing it, just like passwords. If your database is ever compromised, the raw tokens are never exposed.
isActive flag lets you soft-delete sessions for auditing, rather than hard-deleting immediately.
expiresAt lets you write a cleanup cron job to purge old sessions periodically.

5. DeviceInfoMiddleware — Capturing Device Info on Every Login

When a user logs in from their iPhone, we want to record "iPhone, Safari, iOS 17". When they log in from their laptop, "Chrome, macOS". This is how apps like Google show you "Signed in on 3 devices."

What is a middleware?
In NestJS (and Express), a middleware is a function that runs before your route handler. Think of it as a checkpoint — every request passes through it, and you can attach extra information to the request object.

We get device info from the User-Agent HTTP header — a string the browser automatically sends with every request. You can parse it with the ua-parser-js library:

// device-info.middleware.ts
import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';
import * as UAParser from 'ua-parser-js';

// Extend Express's Request type so TypeScript knows about our custom property.
// This is TypeScript "declaration merging" — we're adding to an existing type.

declare global {
namespace Express {
interface Request {
deviceInfo?: {
deviceType: string;
browser: string;
os: string;
userAgent: string;
ipAddress: string;
};
}}}

@Injectable()
export class DeviceInfoMiddleware implements NestMiddleware {
use(req: Request, res: Response, next: NextFunction) {
const userAgentString = req.headers['user-agent'] || '';

// ua-parser-js parses the User-Agent string into structured data
const parser = new UAParser(userAgentString);
const result = parser.getResult();

// Determine if this is mobile, tablet, or desktop.
// Note: ua-parser-js returns undefined for desktops, so we default to 'desktop'.

const deviceType = result.device.type || 'desktop';

// Get the real IP address.
// When you're behind a proxy or load balancer (like nginx or Cloudflare),
// the real client IP is in the 'x-forwarded-for' header, not req.ip.

const ipAddress =
(req.headers['x-forwarded-for'] as string)?.split(',')[0]?.trim() ||
req.ip ||'unknown';

// Attach device info to the request object.
// Our auth service will read it from here during login.

req.deviceInfo = {
deviceType,
browser: result.browser.name || 'Unknown Browser',
os: result.os.name || 'Unknown OS',
userAgent: userAgentString,
ipAddress,
};

// Call next() to pass control to the next middleware or the route handler
next();
}
}

// auth.module.ts
import {
MiddlewareConsumer,
Module,
NestModule,
RequestMethod,
} from '@nestjs/common';

import { DeviceInfoMiddleware } from './device-info.middleware';
@Module({
// ... imports, providers, exports
})

export class AuthModule implements NestModule {
configure(consumer: MiddlewareConsumer) {
consumer
.apply(DeviceInfoMiddleware)

// Only apply to POST /auth/login
.forRoutes({ path: 'auth/login', method: RequestMethod.POST });
}}

6. The Login Flow — Creating a Session on Login

Now let's update the login method. After validating credentials, we create a session record in the database.

// auth.service.ts — updated login method
async login(
email: string,
password: string,
deviceInfo?: Request['deviceInfo'],
) {
// Step 1: Validate credentials (same as before)
const user = await this.validateUser(email, password);
if (!user) {
throw new UnauthorizedException('Invalid credentials');
}

// The JWT payload — this is what gets encoded inside the token
const payload = { email: user.email, sub: user.id, role: user.role };

// Step 2: Issue both tokens
const accessToken = this.jwtService.sign(payload, {
expiresIn: '15m', // Short-lived
});

const refreshToken = this.jwtService.sign(payload, {
secret: this.configService.get<string>('JWT_REFRESH_SECRET'),
expiresIn: '7d', // Long-lived
});

// Step 3: Hash the refresh token before storing it.
// We use bcrypt here (same library used for passwords).
const refreshTokenHash = await bcrypt.hash(refreshToken, 10);

// Step 4: Calculate when this session should expire (7 days from now)
const expiresAt = new Date();
expiresAt.setDate(expiresAt.getDate() + 7);

// Step 5: Create the session record in the database

const session = this.sessionRepository.create({
userId: user.id,
refreshTokenHash, // store the hash, never the raw token
expiresAt,

// Device info from the middleware (falls back gracefully if not present)

deviceType: deviceInfo?.deviceType || 'unknown',
browser: deviceInfo?.browser || 'unknown',
os: deviceInfo?.os || 'unknown',
userAgent: deviceInfo?.userAgent || '',
ipAddress: deviceInfo?.ipAddress || 'unknown',

isActive: true,
});
await this.sessionRepository.save(session);

return {
access_token: accessToken,
refresh_token: refreshToken, // raw token sent to client; hash stays in DB

expires_in: 900, // 15 minutes in seconds

session_id: session.id, // the client uses this to revoke this specific session later

user: {
id: user.id,
email: user.email,
firstName: user.firstName,
lastName: user.lastName,
role: user.role,
},
};
}

Update the controller to pass device info through:

// auth.controller.ts
@Post('login')
@ApiOperation({ summary: 'Login user' })
async login(
@Body() body: { email: string; password: string },
@Req() req: Request,
) {
// req.deviceInfo was attached by DeviceInfoMiddleware before this handler ran

return this.authService.login(body.email, body.password, req.deviceInfo);

}

We’ve now laid the foundation: why plain JWTs fall short, how database‑backed sessions solve those gaps, and how to capture device info cleanly in NestJS.
By now, you should see that production‑grade authentication isn’t just about issuing tokens — it’s about visibility, control, and security.
We’ve set up the building blocks in this first part.

In Part 2, we’ll go deeper — covering refresh flows, logout mechanics, session revocation,and give users the power to manage their own sessions. Stay tuned!

Follow @bismark66 for more backend engineering deep dives.