JWT access + refresh token rotation (conceptual)

import { randomUUID } from "crypto";
import { hashToken, issueRefreshToken } from "./tokens";

export class TokenReuseError extends Error {}

interface RefreshRecord {
  tokenHash: string;
  userId: string;
  familyId: string;
  used: boolean;
  rotatedTo: string | null;
  expiresAt: number;
}

export class RefreshTokenStore {
  private byHash = new Map<string, RefreshRecord>();

  async save(record: RefreshRecord): Promise<void> {
    this.byHash.set(record.tokenHash, record);
  }

  async revokeFamily(familyId: string): Promise<void> {
    for (const rec of this.byHash.values()) {
      if (rec.familyId === familyId) rec.used = true;
    }
  }

  async rotate(rawToken: string): Promise<{ userId: string; next: string }> {
    const record = this.byHash.get(hashToken(rawToken));
    if (!record || record.expiresAt < Date.now()) {
      throw new TokenReuseError("unknown or expired token");
    }
    if (record.used) {
      // an old token was replayed: treat the whole lineage as compromised
      await this.revokeFamily(record.familyId);
      throw new TokenReuseError("refresh token reuse detected");
    }

    const next = await issueRefreshToken(this, record.userId, record.familyId);
    record.used = true;
    record.rotatedTo = hashToken(next);
    return { userId: record.userId, next };
  }

  async startSession(userId: string): Promise<{ familyId: string; token: string }> {
    const familyId = randomUUID();
    const token = await issueRefreshToken(this, userId, familyId);
    return { familyId, token };
  }
}

import { Router } from "express";
import { RefreshTokenStore, TokenReuseError } from "./store";
import { signAccessToken } from "./tokens";

export function authRoutes(store: RefreshTokenStore) {
  const router = Router();

  const cookieOpts = {
    httpOnly: true,
    secure: true,
    sameSite: "strict" as const,
    path: "/auth/refresh",
  };

  router.post("/login", async (req, res) => {
    const user = await authenticate(req.body.email, req.body.password);
    if (!user) return res.status(401).json({ error: "invalid credentials" });

    const { familyId, token } = await store.startSession(user.id);
    res.cookie("rt", token, cookieOpts);
    res.json({ accessToken: signAccessToken(user.id, familyId) });
  });

  router.post("/refresh", async (req, res) => {
    const presented = req.cookies?.rt;
    if (!presented) return res.status(401).json({ error: "no refresh token" });

    try {
      const { userId, next } = await store.rotate(presented);
      res.cookie("rt", next, cookieOpts);
      res.json({ accessToken: signAccessToken(userId, "") });
    } catch (err) {
      if (err instanceof TokenReuseError) {
        res.clearCookie("rt", cookieOpts);
        return res.status(401).json({ error: "session revoked" });
      }
      throw err;
    }
  });

  return router;
}

declare function authenticate(email: string, password: string): Promise<{ id: string } | null>;