DEV Community: bismark66

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.