Sessions & Token Management#

AuthHero implements a secure session system with short-lived JWT access tokens, long-lived refresh tokens, automatic rotation, and reuse detection.

Token Types#

Access Token (JWT)#

The access token is a compact JWT containing:

{
  "userId": "cm...",
  "sessionId": "cm...",
  "iat": 1700000000,
  "exp": 1700000900
}

It is signed with ACCESS_TOKEN_SECRET using HS256. The token is never stored in cookies — it stays in memory (Zustand store) to prevent CSRF attacks.

Refresh Token#

The refresh token is a cryptographically random 80-hex-character string (40 bytes). Only its SHA-256 hash is stored in the database — the server never persists the plaintext token.

The refresh token is set as a cookie with these properties:

Session Creation#

Sessions are created through a centralized createSession()function used by all login paths (email/password, OAuth, MFA challenge):

export async function createSession(
  userId: string,
  userAgent?: string,
  ipAddress?: string,
) {
  // 1. Generate random refresh token
  const refreshToken = crypto.randomBytes(TOKEN_LENGTH.REFRESH).toString("hex");
  const refreshTokenHash = hashToken(refreshToken);

  // 2. Sign JWT access token
  const session = await prisma.session.create({
    data: {
      userId,
      refreshTokenHash,
      expiresAt: new Date(Date.now() + TOKEN_EXPIRY.REFRESH_TOKEN_DAYS * 86400000),
      userAgent,
      ipAddress,
    },
  });

  const accessToken = signAccessToken({ userId, sessionId: session.id });

  return { accessToken, refreshToken };
}

Refresh Token Rotation#

Every time the access token expires and the client refreshes it, the refresh token is rotated: the old one is consumed and a new one is issued.

Reuse Detection#

How it works:

• When a refresh request comes in, the server hashes the token and looks for a matching session
• If no session has that hash, but the token was previously valid (meaning it was rotated), this is reuse
• The server calls logoutAllSessions(userId) which sets revokedAt on every session for that user
• The response includes error code SESSION_REVOKED

Logout#

Single Session Logout#

POST /auth/logout (requires auth) — Revokes the current session by setting revokedAt. Clears the refresh token cookie.

Logout All Sessions#

POST /auth/logout-all (requires auth) — Revokes all sessions for the user across all devices. Triggered automatically on password change for security.

Session Lifecycle Summary#

CREATED ──────→ ACTIVE ──────→ EXPIRED
   │                │                │
   │                ├── rotate ──→ ACTIVE (new token hash)
   │                │
   │                ├── logout ──→ REVOKED
   │                │
   │                └── reuse detected ──→ ALL SESSIONS REVOKED

Events that revoke all sessions:
  • Refresh token reuse detected
  • Password changed
  • POST /auth/logout-all

Authentication Middleware#

The authenticate middleware runs on protected routes and performs two checks:

• JWT verification — Validates the signature and extracts userId + sessionId
• Session check — Queries the database to confirm the session hasn't been revoked (this catches cases where a user logged out but the JWT hasn't expired yet)

// 1. Extract token from Authorization header
const token = req.headers.authorization?.split(" ")[1];

// 2. Verify JWT and extract payload
const { userId, sessionId } = verifyAccessToken(token);

// 3. Check session is still valid in DB
const session = await prisma.session.findUnique({ where: { id: sessionId } });
if (!session || session.revokedAt) throw new AppError(401, "Session revoked");

// 4. Attach user context to request
req.user = { userId, sessionId };