Rotación de Refresh Tokens JWT en Node.js

1. El Problema: Los Tokens de Larga Vida Son una Bomba

Un JWT es autocontenido y stateless, y por eso mismo es peligroso cuando vive demasiado. Quien tenga un access token válido ES el usuario hasta que expire — no hay sesión en el servidor para matar. OWASP es directo: vidas cortas, validación estricta de exp, iss y aud, y jamás aceptar alg none.

La solución tiene tres partes que funcionan juntas: access tokens que expiran en minutos, refresh tokens de vida más larga pero que rotan en cada uso, y almacenamiento que deja las credenciales duraderas fuera del alcance de JavaScript. Construyamos exactamente eso.

2. Los Conceptos Mínimos: Access, Refresh, Rotación

Antes de tocar código necesitás cuatro ideas claras. Son simples, pero si fallás en cualquiera todo el diseño se cae.

3. Tutorial Paso a Paso: Rotación en Node.js

Usaremos jsonwebtoken (v9, la librería mantenida por Auth0 con jwt.sign y jwt.verify) sobre Express. El mismo patrón se porta a jose — el equivalente está al final.

npm install express jsonwebtoken cookie-parser

import express from "express";
import jwt from "jsonwebtoken";
import cookieParser from "cookie-parser";
import crypto from "crypto";

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

const accessToken = jwt.sign(
  { sub: user.id, role: user.role },
  process.env.ACCESS_TOKEN_SECRET,
  { expiresIn: "15m", audience: "fintech-api", issuer: "my-fintech" }
);

const tokenId = crypto.randomUUID();
sessions.set(tokenId, { userId: user.id });

const refreshToken = jwt.sign(
  { sub: user.id },
  process.env.REFRESH_TOKEN_SECRET,
  { expiresIn: "7d", audience: "fintech-api", issuer: "my-fintech", jwtid: tokenId }
);

res.cookie("refreshToken", refreshToken, {
  httpOnly: true,
  secure: true,
  sameSite: "strict",
  path: "/auth/refresh",
  maxAge: 7 * 24 * 60 * 60 * 1000
});
res.json({ accessToken });

function requireAuth(req, res, next) {
  const header = req.headers.authorization || "";
  const token = header.replace("Bearer ", "");
  try {
    req.user = jwt.verify(token, process.env.ACCESS_TOKEN_SECRET, {
      algorithms: ["HS256"],
      audience: "fintech-api",
      issuer: "my-fintech"
    });
    return next();
  } catch (err) {
    return res.status(401).json({ message: "Invalid or expired token" });
  }
}

app.get("/api/balance", requireAuth, (req, res) => {
  res.json({ balance: getBalance(req.user.sub) });
});

app.post("/auth/refresh", (req, res) => {
  const oldToken = req.cookies.refreshToken;
  if (!oldToken) return res.status(401).json({ message: "Missing token" });
  let payload;
  try {
    payload = jwt.verify(oldToken, process.env.REFRESH_TOKEN_SECRET, {
      algorithms: ["HS256"],
      audience: "fintech-api",
      issuer: "my-fintech"
    });
  } catch (err) {
    return res.status(401).json({ message: "Invalid token" });
  }
  if (!sessions.has(payload.jti)) {
    revokeFamily(payload.sub); // reuso detectado: quemar todo
    return res.status(401).json({ message: "Reuse detected" });
  }
  sessions.delete(payload.jti);
  const tokenId = crypto.randomUUID();
  sessions.set(tokenId, { userId: payload.sub });
  const accessToken = jwt.sign({ sub: payload.sub },
    process.env.ACCESS_TOKEN_SECRET, { expiresIn: "15m" });
  const refreshToken = jwt.sign({ sub: payload.sub },
    process.env.REFRESH_TOKEN_SECRET, { expiresIn: "7d", jwtid: tokenId });
  res.cookie("refreshToken", refreshToken, {
    httpOnly: true, secure: true, sameSite: "strict", path: "/auth/refresh"
  });
  res.json({ accessToken });
});

app.post("/auth/logout", (req, res) => {
  const token = req.cookies.refreshToken;
  if (token) {
    const decoded = jwt.decode(token);
    if (decoded && decoded.jti) sessions.delete(decoded.jti);
  }
  res.clearCookie("refreshToken", { path: "/auth/refresh" });
  res.json({ message: "Logged out" });
});

4. jsonwebtoken vs jose: ¿Cuál Librería en 2026?

Ambas librerías emiten tokens válidos, pero vienen de épocas distintas. Así elijo entre ellas para trabajo en producción.

5. Dónde Vive Cada Token: Cookies Bien Hechas

El almacenamiento es donde fallan la mayoría de las implementaciones. La regla es simple: las credenciales duraderas jamás deben ser legibles por JavaScript, y las cookies deben tener el scope más angosto posible.

6. Rotación en Producción: Los Tres Ritmos

La rotación no es un solo endpoint — es un ciclo de vida. Estos son los tres ritmos que corro en cada API fintech que entrego.

7. Errores Comunes que Hackean Fintechs

Tras revisar varias implementaciones de auth fintech, las mismas fallas aparecen una y otra vez. Contrastá tu codebase con ambas listas antes de deployar.

Conclusión

Access tokens de vida corta limitan el radio de explosión, la rotación con detección de reuso convierte el robo en alarma, y las cookies httpOnly mantienen las credenciales duraderas lejos de scripts inyectados. Ninguna de las tres funciona sola — juntas son el piso que OWASP espera de cualquier API que mueve dinero.

Partí del código de la sección 3, respaldalo con un store jti en Redis en producción y conectá los eventos de detección de reuso a tu alertamiento. Tu yo de incident-response te lo va a agradecer — y si querés esto implementado en tu API fintech, ya sabés dónde encontrarme.

Fuentes

• OWASP JSON Web Token Cheat Sheet
• auth0/node-jsonwebtoken — README y docs de API
• panva/jose — README y docs de API
• JWT Authentication: Refresh Token Rotation Best Practices in 2026
• JWT Access Token vs Refresh Token — Complete Guide (2026)