Refresh tokens, rotation and reuse detection

Why two tokens: the revocation problem

A JWT access token is self-contained: the server verifies its signature and trusts the claims inside without a database lookup. That statelessness is the whole point — it scales, and any service with the public key can validate it. But it has a hard consequence: you cannot revoke a JWT before its exp. There is no server-side record to delete; the token is valid until it expires, period. So if one leaks, your only lever is how short you made exp.

That forces the design. Keep the access token short-lived — ~15 minutes — so a stolen one is a 15-minute problem, not a forever problem. But you can’t make users log in every 15 minutes, so you pair it with a refresh token — long-lived (~7–30 days) — whose only job is to be exchanged at /auth/refresh for a new access token.

import { Injectable } from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';

@Injectable()
export class TokenService {
  constructor(private readonly jwt: JwtService) {}

  // two tokens, two secrets, two very different TTLs
  async issuePair(userId: string, familyId: string) {
    const accessToken = await this.jwt.signAsync(
      { sub: userId },
      { secret: process.env.ACCESS_SECRET, expiresIn: '15m' },   // short: caps theft blast radius
    );
    const refreshToken = await this.jwt.signAsync(
      { sub: userId, familyId },
      { secret: process.env.REFRESH_SECRET, expiresIn: '30d' },  // long: avoids constant re-login
    );
    return { accessToken, refreshToken };
  }
}

The refresh token is now the sensitive credential — it lives for weeks and mints access tokens on demand. So it must be server-side trackable (unlike the stateless access token), and it must never touch JS-readable storage. It travels as an httpOnly, Secure, SameSite cookie: httpOnly keeps it out of document.cookie so XSS can’t read it, Secure pins it to HTTPS, SameSite blunts CSRF. The access token can sit in memory; the refresh token sits in a hardened cookie.

Rotation: make every refresh single-use

The naive design hands back the same refresh token for its whole 30-day life. That is exactly the skeleton key from the incident: one leak buys 30 days of silent access. Rotation fixes the lifetime problem: on every call to /auth/refresh, you issue a brand-new refresh token and invalidate the old one. Each refresh token is single-use.

async refresh(presentedToken: string) {
  const record = await this.findFamilyRecord(presentedToken); // looks up by hash (below)
  if (!record || record.revoked) throw new UnauthorizedException();

  // ROTATION: the old token is now spent; mint a fresh pair on the same family
  await this.markConsumed(record.id);
  return this.issuePair(record.userId, record.familyId);
}

Rotation does two things. It shrinks the validity window — a leaked refresh token is only good until the legitimate client next refreshes, often minutes, not weeks. And, crucially, it gives you a detection signal: once a token is rotated, presenting it again is anomalous, and anomalies are something you can act on.

Reuse detection: the consumed token is a tripwire

Here is the core mechanism. A rotated refresh token is single-use, so it should never be seen again. If a consumed refresh token is presented a second time, there is only one explanation: two parties hold that token — the legitimate client and a thief. The leak already happened; the duplicate presentation is the system telling you.

The hard part is that you cannot tell which party is which. The request from the attacker and the request from the victim look identical — both carry a once-valid token. So you make the only safe assumption: compromise. You revoke the entire token family — every refresh token descended from the original login — which forces a full re-authentication.

Model it as a family. Each login starts a family (a familyId); every rotation chains the next token onto that same family. The family record tracks which token is currently live and whether the family is revoked.

// On refresh: if the presented token was ALREADY consumed, that's reuse → kill the family
async refresh(presentedToken: string) {
  const record = await this.findByHash(this.hash(presentedToken));
  if (!record) throw new UnauthorizedException();

  if (record.consumed) {
    // REUSE DETECTED: a single-use token came back. Two holders exist.
    await this.revokeFamily(record.familyId);  // nuke every descendant of this login
    throw new UnauthorizedException('token reuse detected');
  }

  await this.markConsumed(record.id);
  const familyId = record.familyId;
  return this.issuePairAndStore(record.userId, familyId);
}

Now replay the incident with rotation in place. The attacker steals a refresh token and uses it to mint an access token — fine, they rotated it, they now hold token v2. Later, the real user’s client refreshes with the token it still holds (the one the attacker already consumed, v1). The server sees a consumed token presented again → reuse detected → it revokes the whole family. Both the attacker’s v2 and any future refresh die. The user is bounced to the login screen, re-authenticates, and starts a fresh family; the attacker is locked out. The 26-day window collapses to “until the user’s next refresh.”

Storage: hash the refresh token, never store it raw

The family record lives in your database — but you must not store the raw refresh token in it. If you did, a database leak (a dump, a backup left in a bucket, a read-only SQLi) would hand an attacker every live refresh token in plaintext: instant account takeover at scale, no signature forgery needed. Instead, store only a hash of the refresh token — argon2/bcrypt, or a plain SHA-256 since the token is already high-entropy — exactly as you’d store a password. On refresh, hash the presented token and compare against the stored value.

import { createHash } from 'node:crypto';

// the token is high-entropy random already, so a fast SHA-256 is fine here
private hash(token: string): string {
  return createHash('sha256').update(token).digest('hex');
}

private async issuePairAndStore(userId: string, familyId: string) {
  const { accessToken, refreshToken } = await this.tokens.issuePair(userId, familyId);
  await this.familyRepo.save({
    familyId,
    userId,
    tokenHash: this.hash(refreshToken), // store the HASH, never the raw token
    consumed: false,
    revoked: false,
  });
  return { accessToken, refreshToken };
}

The wiring in Nest mirrors the access path but stays separate: a JwtRefreshStrategy (distinct from the access JwtStrategy) reads the refresh token from the cookie and validates its signature with the refresh secret; the /auth/refresh endpoint is guarded by it; and the service does the stateful part — look up the family by hash, check consumed/revoked, rotate, store the new hash, return the new pair. @nestjs/jwt signs both tokens, but with different secrets and different TTLs, so an access token can never be replayed as a refresh token or vice versa.