Authentication & Sessions

npm init -y && npm pkg set type=module
npm i express express-session connect-redis redis passport passport-local passport-jwt \
  jsonwebtoken csrf-csrf cookie-parser express-rate-limit \
  fastify @fastify/cookie @fastify/jwt @fastify/rate-limit

# Each value is generated once and kept out of version control (.env is in .gitignore).
{
  echo "SESSION_SECRET=$(node -p "crypto.randomBytes(32).toString('hex')")"
  echo "JWT_SECRET=$(node -p "crypto.randomBytes(32).toString('base64url')")"
  echo "CSRF_SECRET=$(node -p "crypto.randomBytes(32).toString('hex')")"
  echo "REDIS_URL=redis://127.0.0.1:6379"
} > .env

import { scrypt, randomBytes, timingSafeEqual } from 'node:crypto';
import { promisify } from 'node:util';

const scryptAsync = promisify(scrypt);

export async function hashPassword(password) {
  const salt = randomBytes(16);
  const key = await scryptAsync(password.normalize('NFKC'), salt, 64);
  return `scrypt$${salt.toString('base64url')}$${key.toString('base64url')}`;
}

export async function verifyPassword(password, stored) {
  const [, salt, hash] = stored.split('$');
  const expected = Buffer.from(hash, 'base64url');
  const actual = await scryptAsync(password.normalize('NFKC'), Buffer.from(salt, 'base64url'), expected.length);
  return timingSafeEqual(actual, expected);
}

// A tiny in-memory user table for the examples; Bookshelf uses SQLite or PostgreSQL.
export const users = new Map();

// Returns the new user, or null when the address is already registered: an existing account is never overwritten.
// The password is hashed first in both cases, so a duplicate signup costs the same time as a new one.
export async function addUser(email, password) {
  const passwordHash = await hashPassword(password);
  if (users.has(email)) return null;
  const user = { id: randomBytes(8).toString('hex'), email, role: 'reader', passwordHash, verified: false };
  users.set(email, user);
  return user;
}

// Used to keep timing similar when the account does not exist.
export const dummyHash = await hashPassword('not-a-real-password');

import express from 'express';
import session from 'express-session';
import { RedisStore } from 'connect-redis';
import { createClient } from 'redis';
import { addUser, users, verifyPassword, dummyHash } from './users.js';

const { SESSION_SECRET, REDIS_URL } = process.env;
if (!SESSION_SECRET) throw new Error('SESSION_SECRET is required'); // fail fast, no fallback string

const redis = createClient({ url: REDIS_URL });
await redis.connect();

const app = express();
app.set('trust proxy', 1); // one reverse proxy in front: required for secure cookies behind TLS termination
app.use(express.json());
app.use(session({
  store: new RedisStore({ client: redis, prefix: 'bookshelf:sess:', ttl: 60 * 60 }),
  name: 'bookshelf.sid',
  secret: SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  rolling: false,
  cookie: { httpOnly: true, secure: true, sameSite: 'lax', maxAge: 60 * 60 * 1000, path: '/' },
}));

const regenerate = (req) => new Promise((ok, fail) => req.session.regenerate((e) => (e ? fail(e) : ok())));
const save = (req) => new Promise((ok, fail) => req.session.save((e) => (e ? fail(e) : ok())));

app.post('/login', async (req, res) => {
  const { email, password } = req.body;
  const user = users.get(email);
  const ok = await verifyPassword(password, user ? user.passwordHash : dummyHash);
  if (!user || !ok) return res.status(401).json({ error: 'invalid credentials' });
  await regenerate(req); // new session id at the privilege change: defeats session fixation
  req.session.userId = user.id;
  req.session.createdAt = Date.now();
  await save(req);
  res.json({ ok: true });
});

app.get('/me', (req, res) => {
  if (!req.session.userId) return res.status(401).json({ error: 'not signed in' });
  res.json({ userId: req.session.userId });
});

app.post('/logout', (req, res, next) => {
  req.session.destroy((err) => {
    if (err) return next(err);
    res.clearCookie('bookshelf.sid', { path: '/' });
    res.status(204).end();
  });
});

await addUser('ada@example.com', 'correct horse battery staple');
const server = app.listen(0, '127.0.0.1');
await new Promise((r) => server.once('listening', r));
const base = `http://127.0.0.1:${server.address().port}`;
const https = { 'x-forwarded-proto': 'https', 'content-type': 'application/json' };

let res = await fetch(`${base}/me`, { headers: https });
console.log('anonymous /me:', res.status, '| Set-Cookie:', res.headers.get('set-cookie'));

res = await fetch(`${base}/login`, { method: 'POST', headers: https, body: JSON.stringify({ email: 'ada@example.com', password: 'wrong' }) });
console.log('bad login:', res.status);

res = await fetch(`${base}/login`, { method: 'POST', headers: https, body: JSON.stringify({ email: 'ada@example.com', password: 'correct horse battery staple' }) });
const raw = res.headers.get('set-cookie');
console.log('login:', res.status);
console.log('Set-Cookie:', raw.replace(/(bookshelf\.sid=)[^;]{8}[^;]*/, '$1<id…>'));
const cookie = raw.split(';')[0];

res = await fetch(`${base}/me`, { headers: { ...https, cookie } });
console.log('with cookie /me:', res.status, await res.json().then((j) => Object.keys(j)));
console.log('keys in Redis:', (await redis.keys('bookshelf:sess:*')).length);

res = await fetch(`${base}/logout`, { method: 'POST', headers: { ...https, cookie } });
console.log('logout:', res.status);
res = await fetch(`${base}/me`, { headers: { ...https, cookie } });
console.log('after logout /me:', res.status, '| keys in Redis:', (await redis.keys('bookshelf:sess:*')).length);

// Without X-Forwarded-Proto the Secure cookie is not issued over plain HTTP:
res = await fetch(`${base}/login`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ email: 'ada@example.com', password: 'correct horse battery staple' }) });
console.log('login over plain HTTP, Set-Cookie:', res.headers.get('set-cookie'));

server.close();
await redis.quit();

anonymous /me: 401 | Set-Cookie: null
bad login: 401
login: 200
Set-Cookie: bookshelf.sid=<id…>; Path=/; Expires=Sun, 04 Oct 2026 00:31:45 GMT; HttpOnly; Secure; SameSite=Lax
with cookie /me: 200 [ 'userId' ]
keys in Redis: 2
logout: 204
after logout /me: 401 | keys in Redis: 1
login over plain HTTP, Set-Cookie: null

import express from 'express';
import session from 'express-session';
import passport from 'passport';
import { Strategy as LocalStrategy } from 'passport-local';
import { addUser, users, verifyPassword, dummyHash } from './users.js';

const { SESSION_SECRET } = process.env;
if (!SESSION_SECRET) throw new Error('SESSION_SECRET is required');

const byId = new Map();

passport.use(new LocalStrategy({ usernameField: 'email' }, async (email, password, done) => {
  try {
    const user = users.get(email);
    const ok = await verifyPassword(password, user ? user.passwordHash : dummyHash);
    // One message for "unknown user" and "wrong password": no account enumeration.
    return ok && user ? done(null, user) : done(null, false, { message: 'invalid credentials' });
  } catch (err) {
    return done(err);
  }
}));

// Keep the session small: store only the id, load the rest per request.
passport.serializeUser((user, done) => done(null, user.id));
passport.deserializeUser((id, done) => done(null, byId.get(id) ?? false));

const app = express();
app.set('trust proxy', 1);
app.use(express.json());
app.use(session({
  name: 'bookshelf.sid',
  secret: SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  cookie: { httpOnly: true, secure: true, sameSite: 'lax', maxAge: 30 * 60 * 1000 },
})); // default MemoryStore: fine for a demo, never for production
app.use(passport.initialize());
app.use(passport.session());

app.post('/login', passport.authenticate('local', { failWithError: true }), (req, res) => {
  res.json({ ok: true, role: req.user.role });
}, (err, req, res, next) => res.status(err.status ?? 500).json({ error: 'invalid credentials' }));

const ensureAuth = (req, res, next) => (req.isAuthenticated() ? next() : res.status(401).json({ error: 'not signed in' }));
app.get('/me', ensureAuth, (req, res) => res.json({ role: req.user.role }));
app.post('/logout', ensureAuth, (req, res, next) => {
  req.logout((err) => (err ? next(err) : res.status(204).end())); // logout() is asynchronous since Passport 0.6
});

const ada = await addUser('ada@example.com', 'correct horse battery staple');
byId.set(ada.id, ada);

const server = app.listen(0, '127.0.0.1');
await new Promise((r) => server.once('listening', r));
const base = `http://127.0.0.1:${server.address().port}`;
const h = { 'x-forwarded-proto': 'https', 'content-type': 'application/json' };
const sid = (setCookie) => decodeURIComponent(setCookie.split(';')[0].split('=')[1]).slice(2, 10) + '…';

// An attacker plants a session id before login (session fixation attempt).
let res = await fetch(`${base}/me`, { headers: h });
console.log('anonymous:', res.status);

res = await fetch(`${base}/login`, { method: 'POST', headers: h, body: JSON.stringify({ email: 'ada@example.com', password: 'nope' }) });
console.log('bad password:', res.status, await res.json());

res = await fetch(`${base}/login`, { method: 'POST', headers: h, body: JSON.stringify({ email: 'ada@example.com', password: 'correct horse battery staple' }) });
console.log('login:', res.status, await res.json());
const cookie = res.headers.get('set-cookie').split(';')[0];
console.log('session id after login starts with:', sid(res.headers.get('set-cookie')));

res = await fetch(`${base}/me`, { headers: { ...h, cookie } });
console.log('/me:', res.status, await res.json());

res = await fetch(`${base}/logout`, { method: 'POST', headers: { ...h, cookie } });
console.log('logout:', res.status);
res = await fetch(`${base}/me`, { headers: { ...h, cookie } });
console.log('/me after logout (old cookie):', res.status);
server.close();

anonymous: 401
bad password: 401 { error: 'invalid credentials' }
login: 200 { ok: true, role: 'reader' }
session id after login starts with: phQ9LRYm…
/me: 200 { role: 'reader' }
logout: 204
/me after logout (old cookie): 401

// Is the session id rotated at login by Passport 0.7? Compare ids before and after.
import express from 'express';
import session from 'express-session';
import passport from 'passport';
import { Strategy as LocalStrategy } from 'passport-local';
passport.use(new LocalStrategy((u, p, done) => done(null, { id: 'u1' })));
passport.serializeUser((u, done) => done(null, u.id));
passport.deserializeUser((id, done) => done(null, { id }));
const app = express();
app.use(express.json());
app.use(session({ secret: process.env.SESSION_SECRET, resave: false, saveUninitialized: true }));
app.use(passport.initialize(), passport.session());
app.get('/anon', (req, res) => res.json({ sid: req.sessionID.slice(0, 6) }));
app.post('/login', passport.authenticate('local'), (req, res) => res.json({ sid: req.sessionID.slice(0, 6) }));
const s = app.listen(0); await new Promise((r) => s.once('listening', r));
const b = `http://127.0.0.1:${s.address().port}`;
let r = await fetch(`${b}/anon`); const c = r.headers.get('set-cookie').split(';')[0];
console.log('before login:', (await r.json()).sid);
r = await fetch(`${b}/login`, { method: 'POST', headers: { cookie: c, 'content-type': 'application/json' }, body: JSON.stringify({ username: 'a', password: 'b' }) });
console.log('after login :', (await r.json()).sid);
s.close();

before login: GhpkxP
after login : H4vxra

import jwt from 'jsonwebtoken';
import { generateKeyPairSync } from 'node:crypto';

const { JWT_SECRET } = process.env;
if (!JWT_SECRET) throw new Error('JWT_SECRET is required'); // no `|| 'dev-secret'` fallback

const short = (t) => `<JWT: ${t.split('.').length} parts, ${t.length} characters>`;
const b64 = (o) => Buffer.from(JSON.stringify(o)).toString('base64url');

// Issue: short expiry, issuer, audience, subject, unique id.
const token = jwt.sign({ role: 'reader' }, JWT_SECRET, {
  algorithm: 'HS256',
  expiresIn: '15m',
  issuer: 'bookshelf',
  audience: 'bookshelf-api',
  subject: 'user-123',
  jwtid: crypto.randomUUID(),
});
console.log('token:', short(token));

// Verify: pin algorithms, issuer and audience.
const verifyOptions = { algorithms: ['HS256'], issuer: 'bookshelf', audience: 'bookshelf-api' };
const claims = jwt.verify(token, JWT_SECRET, verifyOptions);
console.log('claims:', { sub: claims.sub, role: claims.role, ttl: claims.exp - claims.iat });

const attempt = (label, fn) => {
  try { fn(); console.log(label, '-> ACCEPTED'); } catch (e) { console.log(label, '->', e.name + ':', e.message); }
};

// 1. A forged token with "alg": "none".
const forged = `${b64({ alg: 'none', typ: 'JWT' })}.${b64({ sub: 'user-123', role: 'admin', iss: 'bookshelf', aud: 'bookshelf-api' })}.`;
attempt('alg none', () => jwt.verify(forged, JWT_SECRET, verifyOptions));

// 2. Expired token.
const old = jwt.sign({ role: 'reader' }, JWT_SECRET, { algorithm: 'HS256', expiresIn: -10, issuer: 'bookshelf', audience: 'bookshelf-api' });
attempt('expired', () => jwt.verify(old, JWT_SECRET, verifyOptions));

// 3. Wrong audience.
attempt('wrong audience', () => jwt.verify(token, JWT_SECRET, { ...verifyOptions, audience: 'other-api' }));

// 4. Tampered payload.
const [h, , s] = token.split('.');
attempt('tampered', () => jwt.verify(`${h}.${b64({ sub: 'user-123', role: 'admin' })}.${s}`, JWT_SECRET, verifyOptions));

// 5. Algorithm confusion: an HS256 token "signed" with an RSA public key must not verify against an RS256-only config.
const { publicKey, privateKey } = generateKeyPairSync('rsa', { modulusLength: 2048 });
const pub = publicKey.export({ type: 'spki', format: 'pem' });
const confused = jwt.sign({ sub: 'user-123', role: 'admin' }, pub, { algorithm: 'HS256' });
attempt('HS256 with RSA public key', () => jwt.verify(confused, pub, { algorithms: ['RS256'] }));

// Asymmetric: the API only holds the public key.
const rs = jwt.sign({ role: 'reader' }, privateKey, { algorithm: 'RS256', expiresIn: '15m' });
console.log('RS256 verify:', jwt.verify(rs, pub, { algorithms: ['RS256'] }).role);

// decode() does NOT verify anything.
console.log('decode() of the forged token:', jwt.decode(forged).role);

token: <JWT: 3 parts, 285 characters>
claims: { sub: 'user-123', role: 'reader', ttl: 900 }
alg none -> JsonWebTokenError: jwt signature is required
expired -> TokenExpiredError: jwt expired
wrong audience -> JsonWebTokenError: jwt audience invalid. expected: other-api
tampered -> JsonWebTokenError: invalid signature
HS256 with RSA public key -> JsonWebTokenError: invalid algorithm
RS256 verify: reader
decode() of the forged token: admin

import express from 'express';
import passport from 'passport';
import { Strategy as JwtStrategy, ExtractJwt } from 'passport-jwt';
import jwt from 'jsonwebtoken';
import { createHash, randomBytes, randomUUID } from 'node:crypto';
import { addUser, users, verifyPassword, dummyHash } from './users.js';

const { JWT_SECRET } = process.env;
if (!JWT_SECRET) throw new Error('JWT_SECRET is required');

const ISSUER = 'bookshelf';
const AUDIENCE = 'bookshelf-api';
const ACCESS_TTL = '5m';
const REFRESH_TTL_MS = 7 * 24 * 60 * 60 * 1000;

const byId = new Map();
// Refresh tokens are opaque random strings; only their SHA-256 digest is stored.
const refreshTokens = new Map(); // digest -> { userId, familyId, used, expiresAt }
const digest = (t) => createHash('sha256').update(t).digest('hex');

passport.use(new JwtStrategy({
  jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
  secretOrKey: JWT_SECRET,
  algorithms: ['HS256'], // pinned: passport-jwt hands this to jsonwebtoken
  issuer: ISSUER,
  audience: AUDIENCE,
}, (payload, done) => done(null, byId.get(payload.sub) ?? false)));

const accessToken = (user) => jwt.sign({ role: user.role }, JWT_SECRET, {
  algorithm: 'HS256', expiresIn: ACCESS_TTL, issuer: ISSUER, audience: AUDIENCE, subject: user.id, jwtid: randomUUID(),
});

function issueRefresh(res, userId, familyId = randomUUID()) {
  const token = randomBytes(32).toString('base64url');
  refreshTokens.set(digest(token), { userId, familyId, used: false, expiresAt: Date.now() + REFRESH_TTL_MS });
  res.cookie('refresh', token, { httpOnly: true, secure: true, sameSite: 'strict', path: '/auth/refresh', maxAge: REFRESH_TTL_MS });
}

const app = express();
app.set('trust proxy', 1);
app.use(express.json());
app.use(passport.initialize());

app.post('/auth/login', async (req, res) => {
  const user = users.get(req.body.email);
  const ok = await verifyPassword(req.body.password ?? '', user ? user.passwordHash : dummyHash);
  if (!user || !ok) return res.status(401).json({ error: 'invalid credentials' });
  issueRefresh(res, user.id);
  res.json({ accessToken: accessToken(user), expiresIn: 300 });
});

app.post('/auth/refresh', (req, res) => {
  const presented = /(?:^|; )refresh=([^;]+)/.exec(req.headers.cookie ?? '')?.[1];
  const record = presented && refreshTokens.get(digest(presented));
  if (!record || record.expiresAt < Date.now()) return res.status(401).json({ error: 'invalid refresh token' });
  if (record.used) { // reuse of a rotated token: assume theft, revoke the whole family
    for (const [k, v] of refreshTokens) if (v.familyId === record.familyId) refreshTokens.delete(k);
    return res.status(401).json({ error: 'refresh token reuse detected' });
  }
  record.used = true;
  issueRefresh(res, record.userId, record.familyId); // rotation: every use returns a new token
  res.json({ accessToken: accessToken(byId.get(record.userId)), expiresIn: 300 });
});

app.get('/books', passport.authenticate('jwt', { session: false }), (req, res) => res.json({ user: req.user.id, books: [] }));

const ada = await addUser('ada@example.com', 'correct horse battery staple');
byId.set(ada.id, ada);

const server = app.listen(0, '127.0.0.1');
await new Promise((r) => server.once('listening', r));
const base = `http://127.0.0.1:${server.address().port}`;
const h = { 'x-forwarded-proto': 'https', 'content-type': 'application/json' };
const cookieOf = (r) => r.headers.get('set-cookie').split(';')[0];

let res = await fetch(`${base}/books`);
console.log('no token:', res.status);

res = await fetch(`${base}/auth/login`, { method: 'POST', headers: h, body: JSON.stringify({ email: 'ada@example.com', password: 'correct horse battery staple' }) });
console.log('refresh cookie attributes:', res.headers.get('set-cookie').replace(/refresh=[^;]+/, 'refresh=<token…>').replace(/Expires=[^;]+; /, ''));
const { accessToken: at } = await res.json();
const rt1 = cookieOf(res);

res = await fetch(`${base}/books`, { headers: { authorization: `Bearer ${at}` } });
console.log('with access token:', res.status);

res = await fetch(`${base}/auth/refresh`, { method: 'POST', headers: { ...h, cookie: rt1 } });
console.log('refresh #1:', res.status);
const rt2 = cookieOf(res);

res = await fetch(`${base}/auth/refresh`, { method: 'POST', headers: { ...h, cookie: rt1 } });
console.log('replaying the old refresh token:', res.status, await res.json());

res = await fetch(`${base}/auth/refresh`, { method: 'POST', headers: { ...h, cookie: rt2 } });
console.log('the newer token after reuse detection:', res.status);
server.close();

no token: 401
refresh cookie attributes: refresh=<token…>; Max-Age=604800; Path=/auth/refresh; HttpOnly; Secure; SameSite=Strict
with access token: 200
refresh #1: 200
replaying the old refresh token: 401 { error: 'refresh token reuse detected' }
the newer token after reuse detection: 401

import express from 'express';
import session from 'express-session';
import { randomBytes, timingSafeEqual } from 'node:crypto';

const { SESSION_SECRET } = process.env;
if (!SESSION_SECRET) throw new Error('SESSION_SECRET is required');

const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);

// Layer 1: Fetch Metadata. Browsers send Sec-Fetch-Site; refuse state changes that start on another site.
function fetchMetadata(req, res, next) {
  const site = req.get('sec-fetch-site');
  if (SAFE_METHODS.has(req.method) || site === undefined || site === 'same-origin' || site === 'none') return next();
  return res.status(403).json({ error: 'cross-site request refused' });
}

// Layer 2: synchronizer token bound to the session, sent in a header (never in the URL).
function csrfToken(req) {
  req.session.csrf ??= randomBytes(32).toString('base64url');
  return req.session.csrf;
}
function verifyCsrf(req, res, next) {
  if (SAFE_METHODS.has(req.method)) return next();
  const sent = Buffer.from(req.get('x-csrf-token') ?? '');
  const expected = Buffer.from(req.session.csrf ?? '');
  if (sent.length === 0 || sent.length !== expected.length || !timingSafeEqual(sent, expected)) {
    return res.status(403).json({ error: 'invalid csrf token' });
  }
  return next();
}

const app = express();
app.set('trust proxy', 1);
app.use(express.json());
app.use(session({
  name: '__Host-bookshelf.sid', // __Host- prefix: Secure, Path=/, no Domain attribute
  secret: SESSION_SECRET, resave: false, saveUninitialized: false,
  cookie: { httpOnly: true, secure: true, sameSite: 'lax', path: '/' },
}));
app.use(fetchMetadata);

app.get('/csrf-token', (req, res) => res.json({ token: csrfToken(req) }));
app.post('/books', verifyCsrf, (req, res) => res.status(201).json({ created: req.body.title }));

const server = app.listen(0, '127.0.0.1');
await new Promise((r) => server.once('listening', r));
const base = `http://127.0.0.1:${server.address().port}`;
const h = { 'x-forwarded-proto': 'https', 'content-type': 'application/json' };
const body = JSON.stringify({ title: 'Dune' });

let res = await fetch(`${base}/csrf-token`, { headers: h });
const cookie = res.headers.get('set-cookie').split(';')[0];
const { token } = await res.json();
console.log('cookie name:', cookie.split('=')[0]);

res = await fetch(`${base}/books`, { method: 'POST', headers: { ...h, cookie }, body });
console.log('no token:', res.status);
res = await fetch(`${base}/books`, { method: 'POST', headers: { ...h, cookie, 'x-csrf-token': 'wrong' }, body });
console.log('wrong token:', res.status);
res = await fetch(`${base}/books`, { method: 'POST', headers: { ...h, cookie, 'x-csrf-token': token }, body });
console.log('right token:', res.status);
res = await fetch(`${base}/books`, { method: 'POST', headers: { ...h, cookie, 'x-csrf-token': token, 'sec-fetch-site': 'cross-site' }, body });
console.log('right token, cross-site (Fetch Metadata):', res.status);
server.close();

cookie name: __Host-bookshelf.sid
no token: 403
wrong token: 403
right token: 201
right token, cross-site (Fetch Metadata): 403

import express from 'express';
import session from 'express-session';
import cookieParser from 'cookie-parser';
import { doubleCsrf } from 'csrf-csrf';

const { SESSION_SECRET, CSRF_SECRET } = process.env;
if (!SESSION_SECRET || !CSRF_SECRET) throw new Error('SESSION_SECRET and CSRF_SECRET are required');

const { generateCsrfToken, doubleCsrfProtection, invalidCsrfTokenError } = doubleCsrf({
  getSecret: () => CSRF_SECRET,
  getSessionIdentifier: (req) => req.session.id, // ties the token to the session
  cookieName: '__Host-psifi.x-csrf-token',
  cookieOptions: { sameSite: 'lax', secure: true, httpOnly: true, path: '/' },
  getCsrfTokenFromRequest: (req) => req.headers['x-csrf-token'],
});

const app = express();
app.set('trust proxy', 1);
app.use(express.json());
app.use(session({ secret: SESSION_SECRET, resave: false, saveUninitialized: true, cookie: { secure: true, httpOnly: true, sameSite: 'lax' } }));
app.use(cookieParser(SESSION_SECRET)); // after express-session, before the CSRF middleware
app.get('/csrf-token', (req, res) => res.json({ token: generateCsrfToken(req, res) }));
app.use(doubleCsrfProtection);
app.post('/books', (req, res) => res.status(201).json({ ok: true }));
app.use((err, req, res, next) => (err === invalidCsrfTokenError ? res.status(403).json({ error: 'invalid csrf token' }) : next(err)));

const server = app.listen(0, '127.0.0.1');
await new Promise((r) => server.once('listening', r));
const base = `http://127.0.0.1:${server.address().port}`;
const h = { 'x-forwarded-proto': 'https', 'content-type': 'application/json' };

let res = await fetch(`${base}/csrf-token`, { headers: h });
const cookies = res.headers.getSetCookie().map((c) => c.split(';')[0]).join('; ');
const { token } = await res.json();
console.log('cookies set:', res.headers.getSetCookie().map((c) => c.split('=')[0]));

res = await fetch(`${base}/books`, { method: 'POST', headers: { ...h, cookie: cookies }, body: '{}' });
console.log('cookie only:', res.status);
res = await fetch(`${base}/books`, { method: 'POST', headers: { ...h, cookie: cookies, 'x-csrf-token': token }, body: '{}' });
console.log('cookie + header:', res.status);
server.close();

cookies set: [ '__Host-psifi.x-csrf-token', 'connect.sid' ]
cookie only: 403
cookie + header: 201

import express from 'express';
import rateLimit, { ipKeyGenerator } from 'express-rate-limit';
import { addUser, users, verifyPassword, dummyHash } from './users.js';

const app = express();
app.set('trust proxy', 1); // required to see the real client address behind one proxy; never `true`
app.use(express.json());

// Layer 1: per-IP limiter on the login route (in-memory store here; use a shared store with several instances).
const loginLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  limit: 20,
  standardHeaders: 'draft-8',
  legacyHeaders: false,
  keyGenerator: (req) => ipKeyGenerator(req.ip),
  message: { error: 'too many attempts, try again later' },
});

// Layer 2: per-account lockout with exponential back-off, independent of the source address.
const failures = new Map(); // email -> { count, lockedUntil }
const MAX_FAILURES = 5;
const lockSeconds = (count) => Math.min(2 ** (count - MAX_FAILURES) * 30, 15 * 60);

app.post('/login', loginLimiter, async (req, res) => {
  const email = String(req.body.email ?? '').toLowerCase();
  const state = failures.get(email) ?? { count: 0, lockedUntil: 0 };
  if (state.lockedUntil > Date.now()) {
    res.set('Retry-After', String(Math.ceil((state.lockedUntil - Date.now()) / 1000)));
    return res.status(429).json({ error: 'account temporarily locked' });
  }
  const user = users.get(email);
  const ok = await verifyPassword(String(req.body.password ?? ''), user ? user.passwordHash : dummyHash);
  if (!user || !ok) {
    state.count += 1;
    if (state.count >= MAX_FAILURES) state.lockedUntil = Date.now() + lockSeconds(state.count) * 1000;
    failures.set(email, state); // also tracked for unknown emails, so lockouts do not reveal which accounts exist
    return res.status(401).json({ error: 'invalid credentials' });
  }
  failures.delete(email);
  res.json({ ok: true });
});

await addUser('ada@example.com', 'correct horse battery staple');
const server = app.listen(0, '127.0.0.1');
await new Promise((r) => server.once('listening', r));
const base = `http://127.0.0.1:${server.address().port}`;
const post = (password, email = 'ada@example.com') => fetch(`${base}/login`, {
  method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ email, password }),
});

for (let i = 1; i <= 6; i += 1) {
  const r = await post('wrong');
  console.log(`attempt ${i}:`, r.status, r.headers.get('retry-after') ? `Retry-After: ${r.headers.get('retry-after')}` : '', r.headers.get('ratelimit') ? `RateLimit: ${r.headers.get('ratelimit')}` : '');
}
const r = await post('correct horse battery staple');
console.log('correct password while locked:', r.status);

// The per-IP limiter on its own: a different victim account each time.
for (let i = 1; i <= 25; i += 1) {
  const r2 = await post('x', `user${i}@example.com`);
  if (r2.status === 429) { console.log(`per-IP limit reached on request ${i + 7} from this address:`, r2.status); break; }
}
server.close();

attempt 1: 401  RateLimit: "20-in-15min"; r=19; t=900
attempt 2: 401  RateLimit: "20-in-15min"; r=18; t=900
attempt 3: 401  RateLimit: "20-in-15min"; r=17; t=900
attempt 4: 401  RateLimit: "20-in-15min"; r=16; t=900
attempt 5: 401  RateLimit: "20-in-15min"; r=15; t=900
attempt 6: 429 Retry-After: 30 RateLimit: "20-in-15min"; r=14; t=900
correct password while locked: 429
per-IP limit reached on request 21 from this address: 429

import express from 'express';
import { createHash, randomBytes } from 'node:crypto';
import { addUser, users } from './users.js';

const TOKEN_TTL_MS = 24 * 60 * 60 * 1000;
const sha256 = (value) => createHash('sha256').update(value).digest('hex');
const pending = new Map(); // sha256(token) as hex -> { email, expiresAt }; a table with a unique index in a real database

// Issue: 256 random bits, only the digest is stored, the link never contains the e-mail address.
export function createVerificationToken(email) {
  const token = randomBytes(32).toString('base64url');
  pending.set(sha256(token), { email, expiresAt: Date.now() + TOKEN_TTL_MS });
  return token;
}

const sent = []; // stand-in for Nodemailer's sendMail()
const sendVerificationMail = (email, token) => sent.push({ to: email, link: `https://bookshelf.example/verify?token=${token}` });
// The owner of an existing account learns that someone tried to register it; the attacker learns nothing.
const sendAlreadyRegisteredMail = (email) => sent.push({ to: email, text: 'You already have an account. Use "forgot password" if needed.' });

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

app.post('/signup', async (req, res) => {
  const { email, password } = req.body;
  const user = await addUser(email, password); // hashes in both cases; null for an address that already has an account
  if (user) sendVerificationMail(user.email, createVerificationToken(user.email));
  else sendAlreadyRegisteredMail(email); // no new user, no token, the existing password hash is untouched
  res.status(202).json({ message: 'check your inbox' }); // same status, body and (roughly) time either way
});

// GET only shows a confirmation page: mail scanners and link previews fetch URLs, they must not change state.
app.get('/verify', (req, res) => res.type('html').send('<form method="post"><button>Confirm my e-mail address</button></form>'));

app.post('/verify', (req, res) => {
  const token = String(req.query.token ?? '');
  const key = sha256(token); // lookup by digest of a high-entropy token: a fast hash is fine here
  const record = pending.get(key);
  if (!record || record.expiresAt < Date.now()) return res.status(400).json({ error: 'invalid or expired link' });
  pending.delete(key); // single use
  users.get(record.email).verified = true;
  res.json({ verified: true });
});

const server = app.listen(0, '127.0.0.1');
await new Promise((r) => server.once('listening', r));
const base = `http://127.0.0.1:${server.address().port}`;

let r = await fetch(`${base}/signup`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ email: 'grace@example.com', password: 'a long passphrase here' }) });
console.log('signup:', r.status);
const link = new URL(sent[0].link);
const token = link.searchParams.get('token');
console.log('link:', `${link.origin}${link.pathname}?token=${token.slice(0, 6)}…`, '| token chars:', token.length, '| contains e-mail:', sent[0].link.includes('grace'));
console.log('stored digests:', [...pending.keys()].map((k) => `${k.slice(0, 6)}…`));

const post = (t) => fetch(`${base}/verify?token=${encodeURIComponent(t)}`, { method: 'POST' });
console.log('GET /verify changes state:', (await fetch(`${base}/verify?token=${token}`)).status, users.get('grace@example.com').verified);
console.log('POST with a guessed value:', (await post('grace@example.com')).status);
console.log('POST with the real token:', (await post(token)).status, users.get('grace@example.com').verified);
console.log('POST again (single use):', (await post(token)).status);

const before = users.get('grace@example.com').passwordHash;
r = await fetch(`${base}/signup`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ email: 'grace@example.com', password: 'attacker chosen password' }) });
console.log('signup again for the same address:', r.status, '| account overwritten:', users.get('grace@example.com').passwordHash !== before, '| new token issued:', pending.size > 0);
console.log('second mail:', sent[1]);
server.close();

signup: 202
link: https://bookshelf.example/verify?token=uo-sJu… | token chars: 43 | contains e-mail: false
stored digests: [ '736edd…' ]
GET /verify changes state: 200 false
POST with a guessed value: 400
POST with the real token: 200 true
POST again (single use): 400
signup again for the same address: 202 | account overwritten: false | new token issued: false
second mail: {
  to: 'grace@example.com',
  text: 'You already have an account. Use "forgot password" if needed.'
}

import Fastify from 'fastify';
import fastifyCookie from '@fastify/cookie';
import fastifyJwt from '@fastify/jwt';
import fastifyRateLimit from '@fastify/rate-limit';
import { addUser, users, verifyPassword, dummyHash } from './users.js';

const { JWT_SECRET, SESSION_SECRET } = process.env;
if (!JWT_SECRET || !SESSION_SECRET) throw new Error('JWT_SECRET and SESSION_SECRET are required');

const app = Fastify({ trustProxy: 1, logger: false });

await app.register(fastifyCookie, { secret: SESSION_SECRET }); // enables signed cookies
await app.register(fastifyJwt, {
  secret: JWT_SECRET,
  sign: { algorithm: 'HS256', expiresIn: '10m', iss: 'bookshelf' },
  verify: { algorithms: ['HS256'], allowedIss: 'bookshelf' }, // the default accepts every algorithm: pin it
});
await app.register(fastifyRateLimit, { global: false }); // opt in per route

app.decorate('authenticate', async (request, reply) => {
  try {
    await request.jwtVerify();
  } catch {
    return reply.code(401).send({ error: 'unauthorized' });
  }
});

app.post('/login', {
  config: { rateLimit: { max: 5, timeWindow: '1 minute' } },
  schema: { body: { type: 'object', required: ['email', 'password'], properties: { email: { type: 'string' }, password: { type: 'string' } } } },
}, async (request, reply) => {
  const user = users.get(request.body.email);
  const ok = await verifyPassword(request.body.password, user ? user.passwordHash : dummyHash);
  if (!user || !ok) return reply.code(401).send({ error: 'invalid credentials' });
  reply.setCookie('bookshelf.seen', '1', { signed: true, httpOnly: true, secure: true, sameSite: 'lax', path: '/' });
  return { accessToken: await reply.jwtSign({ role: user.role }, { sub: user.id }) };
});

app.get('/books', { preHandler: app.authenticate }, async (request) => ({ user: request.user.sub, role: request.user.role }));

await addUser('ada@example.com', 'correct horse battery staple');
const login = (password) => app.inject({ method: 'POST', url: '/login', payload: { email: 'ada@example.com', password } });

let res = await login('correct horse battery staple');
console.log('login:', res.statusCode, '| cookie:', res.cookies[0].name, res.cookies[0].httpOnly, res.cookies[0].secure, res.cookies[0].sameSite);
const { accessToken } = res.json();
res = await app.inject({ method: 'GET', url: '/books', headers: { authorization: `Bearer ${accessToken}` } });
console.log('with token:', res.statusCode, res.json().role);
res = await app.inject({ method: 'GET', url: '/books' });
console.log('without token:', res.statusCode);

for (let i = 1; i <= 6; i += 1) {
  res = await login('wrong');
  if (res.statusCode === 429) { console.log(`login failure ${i}: ${res.statusCode}`, res.headers['retry-after'] ? `retry-after ${res.headers['retry-after']}` : ''); break; }
}
await app.close();

login: 200 | cookie: bookshelf.seen true true Lax
with token: 200 reader
without token: 401
login failure 5: 429 retry-after 60