Amr Samir | JWT Authentication & Refresh Token Rotation Architecture

1. The Myth of "Completely Stateless" JWTs

JSON Web Tokens (JWT) are widely adopted for distributed authentication. However, naive implementations suffer from critical security flaws:

No Instant Revocation: If a user's account is compromised, a valid stateless JWT cannot be revoked until its expiration time.

XSS Vulnerabilities: Storing JWTs in browser localStorage allows any malicious third-party script to steal user credentials.

code

+----------------------------------------------------------------------+
|                     JWT Security Token Architecture                  |
|                                                                      |
|  [ Access Token ]  --> Short TTL (5-15 mins) --> Memory / HTTP-Only  |
|  [ Refresh Token ] --> Long TTL (7-30 days)  --> Secure Cookie + DB  |
+----------------------------------------------------------------------+

2. Refresh Token Rotation with Reuse Detection

code

1. Client sends Refresh Token #1 -> Server validates.
2. Server invalidates Refresh Token #1 and issues [ Access Token #2, Refresh Token #2 ].
3. If an attacker attempts to replay Refresh Token #1:
   💥 Server detects token reuse, immediately REVOKES the entire token family,
      and forces all sessions to re-authenticate!

4. Production NestJS Implementation

typescript

@Injectable()
export class AuthService {
  async rotateRefreshToken(userId: string, oldToken: string) {
    const tokenRecord = await this.prisma.refreshToken.findUnique({ where: { token: oldToken } });

    if (!tokenRecord) {
      // Possible compromise! Revoke all tokens for this user family
      await this.prisma.refreshToken.deleteMany({ where: { userId } });
      throw new UnauthorizedException('Security alert: Token reuse detected. Please log in again.');
    }

    if (tokenRecord.expiresAt < new Date()) {
      await this.prisma.refreshToken.delete({ where: { id: tokenRecord.id } });
      throw new UnauthorizedException('Session expired');
    }

    // Invalidate old token and issue new pair
    await this.prisma.refreshToken.delete({ where: { id: tokenRecord.id } });

    const newAccessToken = this.jwtService.sign({ sub: userId }, { expiresIn: '15m' });
    const newRefreshToken = crypto.randomBytes(40).toString('hex');

    await this.prisma.refreshToken.create({
      data: {
        token: newRefreshToken,
        userId,
        expiresAt: new Date(Date.now() + 7 * 24 * 3600 * 1000),
      },
    });

    return { accessToken: newAccessToken, refreshToken: newRefreshToken };
  }
}

JWT Authentication in Production: Access Tokens, Refresh Token Rotation & Revocation

Recommended Posts

Designing Secure Password Reset & OTP Verification: Timing Attacks, Rate Limits & State

CORS Deep Dive: Why the Browser Sends Preflight OPTIONS and How to Fix It

Reliable User Registration: Solving the Dual-Write Problem with Transactional Outbox

Related Projects

Related Certificates

JWT Authentication in Production: Access Tokens, Refresh Token Rotation & Revocation

1. The Myth of "Completely Stateless" JWTs

2. Refresh Token Rotation with Reuse Detection

3. Secure Storage: HTTP-Only Cookies vs LocalStorage

4. Production NestJS Implementation

5. Summary Checklist