JWT Access Token vs Refresh Token

// Decoded access token payload
{
  "sub": "user_123",          // Subject (user ID)
  "email": "alice@example.com",
  "role": "admin",
  "permissions": ["read", "write", "delete"],
  "iat": 1719216000,          // Issued at (Unix timestamp)
  "exp": 1719216900           // Expires in 15 minutes
}

const jwt = require("jsonwebtoken")
const crypto = require("crypto")

const ACCESS_SECRET = process.env.ACCESS_TOKEN_SECRET
const REFRESH_SECRET = process.env.REFRESH_TOKEN_SECRET

// Generate token pair on login
function generateTokens(user) {
  const accessToken = jwt.sign(
    { sub: user.id, email: user.email, role: user.role },
    ACCESS_SECRET,
    { expiresIn: "15m" }
  )
  
  const refreshToken = jwt.sign(
    { sub: user.id, tokenId: crypto.randomUUID() },
    REFRESH_SECRET,
    { expiresIn: "7d" }
  )
  
  return { accessToken, refreshToken }
}

// Login endpoint
app.post("/auth/login", async (req, res) => {
  const { email, password } = req.body
  const user = await db.findUser(email)
  if (!user || !await bcrypt.compare(password, user.passwordHash)) {
    return res.status(401).json({ error: "Invalid credentials" })
  }
  
  const { accessToken, refreshToken } = generateTokens(user)
  
  // Store refresh token in database (for revocation)
  await db.storeRefreshToken(refreshToken, user.id)
  
  // Set refresh token as httpOnly cookie
  res.cookie("refreshToken", refreshToken, {
    httpOnly: true, secure: true, sameSite: "strict",
    maxAge: 7 * 24 * 60 * 60 * 1000, path: "/auth"
  })
  
  // Return access token in body (stored in memory by client)
  res.json({ accessToken })
})

// Refresh endpoint
app.post("/auth/refresh", async (req, res) => {
  const { refreshToken } = req.cookies
  if (!refreshToken) return res.status(401).json({ error: "No refresh token" })
  
  try {
    const payload = jwt.verify(refreshToken, REFRESH_SECRET)
    
    // Check if token exists in database (not revoked)
    const stored = await db.findRefreshToken(refreshToken)
    if (!stored) return res.status(401).json({ error: "Token revoked" })
    
    // Rotation: invalidate old refresh token
    await db.deleteRefreshToken(refreshToken)
    
    // Issue new token pair
    const user = await db.findUserById(payload.sub)
    const newTokens = generateTokens(user)
    await db.storeRefreshToken(newTokens.refreshToken, user.id)
    
    res.cookie("refreshToken", newTokens.refreshToken, {
      httpOnly: true, secure: true, sameSite: "strict",
      maxAge: 7 * 24 * 60 * 60 * 1000, path: "/auth"
    })
    res.json({ accessToken: newTokens.accessToken })
  } catch {
    return res.status(401).json({ error: "Invalid refresh token" })
  }
})

// Logout — revoke refresh token
app.post("/auth/logout", (req, res) => {
  const { refreshToken } = req.cookies
  if (refreshToken) db.deleteRefreshToken(refreshToken)
  res.clearCookie("refreshToken", { path: "/auth" })
  res.json({ message: "Logged out" })
})

Scenario: Attacker steals refresh token R1

WITHOUT rotation:
  Attacker uses R1 → gets access token (works)
  Attacker uses R1 again → gets access token (still works!)
  Attacker has unlimited access until R1 expires (days)
  
WITH rotation:
  Attacker uses R1 → gets access token + new refresh token R2
  Real user tries to use R1 → FAILS (R1 was already used)
  Server detects reuse → REVOKES entire token family
  Both attacker (R2) and real user are forced to re-login
  Damage contained

// Database schema for refresh tokens
// tokens table: { id, token_hash, user_id, family_id, used, expires_at }

async function refreshWithRotation(oldToken) {
  const stored = await db.findToken(hash(oldToken))
  
  if (!stored) throw new Error("Token not found")
  
  if (stored.used) {
    // REUSE DETECTED — revoke entire family
    await db.deleteTokenFamily(stored.family_id)
    throw new Error("Token reuse detected — all sessions revoked")
  }
  
  // Mark old token as used (not deleted — kept for reuse detection)
  await db.markAsUsed(stored.id)
  
  // Issue new token in same family
  const newToken = generateRefreshToken()
  await db.storeToken({
    token_hash: hash(newToken),
    user_id: stored.user_id,
    family_id: stored.family_id, // Same family
    used: false,
    expires_at: addDays(7)
  })
  
  return newToken
}