Authentication & Authorization

// passwords.mjs
import argon2 from 'argon2';
import bcrypt from 'bcrypt';

// argon2id with explicit parameters (memory in KiB). Start from the current OWASP minimums and measure on the
// production hardware: a hash should take roughly 100 to 500 ms.
const ARGON2_OPTIONS = {
  type: argon2.argon2id,
  memoryCost: 19 * 1024,
  timeCost: 2,
  parallelism: 1,
};

export async function hashPassword(plain) {
  return argon2.hash(plain, ARGON2_OPTIONS);
}

export async function verifyPassword(hash, plain) {
  try {
    return await argon2.verify(hash, plain);
  } catch {
    return false; // malformed hash or unsupported format: treat as a failed login
  }
}

// True when the stored hash uses weaker parameters than the current ones, so the caller can rehash after a
// successful login and upgrade the database gradually.
export function needsRehash(hash) {
  return argon2.needsRehash(hash, ARGON2_OPTIONS);
}

// bcrypt alternative: the cost is the second argument, and the salt is generated and embedded automatically.
const BCRYPT_COST = 12;

export async function hashPasswordBcrypt(plain) {
  return bcrypt.hash(plain, BCRYPT_COST);
}

export async function verifyPasswordBcrypt(hash, plain) {
  return bcrypt.compare(plain, hash);
}

// users.mjs
import { randomUUID } from 'node:crypto';
import { hashPassword, verifyPassword } from './passwords.mjs';

const users = new Map(); // id -> { id, email, passwordHash, role, createdAt }

// A hash of a random password, computed once at startup. It lets the login code spend the same time on an unknown
// email as on a known one (see "User enumeration" below).
const DUMMY_HASH = await hashPassword(randomUUID());

export const ROLES = Object.freeze(['reader', 'editor', 'admin']);

export async function createUser({ email, password }) {
  const normalized = email.trim().toLowerCase();
  for (const user of users.values()) {
    if (user.email === normalized) {
      return null; // the caller decides how to report a duplicate without revealing it
    }
  }
  const user = {
    id: randomUUID(),
    email: normalized,
    passwordHash: await hashPassword(password),
    role: 'reader', // fixed by the server, never taken from the request body
    createdAt: new Date().toISOString(),
  };
  users.set(user.id, user);
  return user;
}

export async function findById(id) {
  return users.get(id) ?? null;
}

export async function findByEmail(email) {
  const normalized = email.trim().toLowerCase();
  for (const user of users.values()) {
    if (user.email === normalized) {
      return user;
    }
  }
  return null;
}

// Verifies credentials in constant structure: the same work happens whether or not the account exists.
export async function authenticate(email, password) {
  const user = await findByEmail(email);
  const valid = await verifyPassword(user?.passwordHash ?? DUMMY_HASH, password);
  return user && valid ? user : null;
}

// The only shape that leaves the server. Allow-list the fields; never spread the stored record.
export function toPublicUser(user) {
  return { id: user.id, email: user.email, role: user.role };
}

// session-login.mjs
import express from 'express';
import session from 'express-session';
import passport from 'passport';
import { Strategy as LocalStrategy } from 'passport-local';
import { authenticate, createUser, findById, toPublicUser } from './users.mjs';

const app = express();
app.use(express.urlencoded({ extended: false }));
app.use(express.json());

// In production run behind a proxy that terminates TLS and set the trust proxy setting first, otherwise the
// secure cookie is never sent. See "Behind Proxies".
const isProduction = process.env.NODE_ENV === 'production';
if (isProduction) {
  app.set('trust proxy', 1);
}

app.use(
  session({
    name: 'bookshelf.sid',
    secret: process.env.SESSION_SECRET, // a long random value from the environment
    resave: false,
    saveUninitialized: false,
    cookie: {
      httpOnly: true,
      secure: isProduction,
      sameSite: 'lax',
      maxAge: 1000 * 60 * 60 * 8,
    },
    // store: a Redis or database store in production. The default MemoryStore leaks memory and is single process.
  }),
);

app.use(passport.initialize());
app.use(passport.session());

// The strategy verifies credentials. Report every failure with the same message.
passport.use(
  new LocalStrategy({ usernameField: 'email' }, async (email, password, done) => {
    try {
      const user = await authenticate(email, password);
      if (!user) {
        return done(null, false, { message: 'Invalid email or password' });
      }
      return done(null, user);
    } catch (error) {
      return done(error);
    }
  }),
);

// Store the smallest thing that identifies the user: its id, not the whole record.
passport.serializeUser((user, done) => {
  done(null, user.id);
});

passport.deserializeUser(async (id, done) => {
  try {
    const user = await findById(id);
    done(null, user ?? false); // false clears a stale session instead of failing every request
  } catch (error) {
    done(error);
  }
});

app.post('/register', async (req, res) => {
  const { email, password } = req.body ?? {};
  if (typeof email !== 'string' || typeof password !== 'string' || password.length < 12 || password.length > 256) {
    return res.status(400).json({ message: 'A valid email and a password of 12 to 256 characters are required' });
  }
  await createUser({ email, password });
  // Same answer whether or not the address already existed; confirm by email in a real system.
  res.status(202).json({ message: 'If the address can be registered, a confirmation was sent' });
});

app.post('/login', (req, res, next) => {
  passport.authenticate('local', (error, user, info) => {
    if (error) {
      return next(error);
    }
    if (!user) {
      return res.status(401).json({ message: info?.message ?? 'Invalid email or password' });
    }
    // req.login regenerates the session id (Passport 0.6 and later) and then serializes the user.
    req.login(user, (loginError) => {
      if (loginError) {
        return next(loginError);
      }
      res.json(toPublicUser(user));
    });
  })(req, res, next);
});

app.get('/me', (req, res) => {
  if (!req.isAuthenticated()) {
    return res.status(401).json({ message: 'Authentication required' });
  }
  res.json(toPublicUser(req.user));
});

// POST, not GET, and with a callback: Passport 0.6 and later made logout asynchronous.
app.post('/logout', (req, res, next) => {
  req.logout((error) => {
    if (error) {
      return next(error);
    }
    res.status(204).end();
  });
});

app.listen(3000, (error) => {
  if (error) {
    throw error;
  }
});

// guards.mjs
import { ROLES } from './users.mjs';

// Authentication: is there an identity at all? Works with Passport (req.user) and with the JWT middleware below.
export function requireAuthentication(req, res, next) {
  const identity = req.user ?? req.auth;
  if (!identity) {
    res.set('WWW-Authenticate', 'Bearer realm="bookshelf"');
    return res.status(401).json({ status: 401, message: 'Authentication required' });
  }
  next();
}

// Role-based access control: a role has a fixed set of permissions, and routes ask for a permission, not a role name.
const PERMISSIONS = Object.freeze({
  reader: ['book:read', 'review:create'],
  editor: ['book:read', 'book:create', 'book:update', 'review:create'],
  admin: ['book:read', 'book:create', 'book:update', 'book:delete', 'review:create', 'review:delete', 'user:manage'],
});

export function roleOf(req) {
  return req.user?.role ?? req.auth?.role;
}

export function can(role, permission) {
  return ROLES.includes(role) && PERMISSIONS[role].includes(permission);
}

export function requirePermission(permission) {
  return (req, res, next) => {
    if (!can(roleOf(req), permission)) {
      return res.status(403).json({ status: 403, message: 'You do not have permission to do this' });
    }
    next();
  };
}

// Ownership: the identity may act on this resource only when it owns it, or is an administrator.
export function requireOwnerOrAdmin(loadOwnerId) {
  return async (req, res, next) => {
    const ownerId = await loadOwnerId(req); // may throw; Express 5 forwards the rejection
    if (ownerId === undefined) {
      return res.status(404).json({ status: 404, message: 'Not found' });
    }
    const subject = req.user?.id ?? req.auth?.sub;
    if (ownerId !== subject && roleOf(req) !== 'admin') {
      // 404 instead of 403 when the existence of the resource is itself private.
      return res.status(404).json({ status: 404, message: 'Not found' });
    }
    next();
  };
}

// reviews-router.mjs
import { Router } from 'express';
import { requireAuthentication, requireOwnerOrAdmin, requirePermission } from './guards.mjs';

const reviews = new Map([['r1', { id: 'r1', bookId: 'b1', authorId: 'u1', text: 'Great' }]]);

export const reviewsRouter = Router();

// Everything below this line requires a login. Public routes are registered on another router.
reviewsRouter.use(requireAuthentication);

reviewsRouter.post('/', requirePermission('review:create'), (req, res) => {
  const { bookId, text } = req.body ?? {};
  const review = { id: `r${reviews.size + 1}`, bookId, authorId: req.user?.id ?? req.auth.sub, text };
  reviews.set(review.id, review);
  res.status(201).json(review);
});

// The author may edit their own review; an administrator may edit any review.
reviewsRouter.patch(
  '/:id',
  requireOwnerOrAdmin((req) => reviews.get(req.params.id)?.authorId),
  (req, res) => {
    const review = reviews.get(req.params.id);
    // Allow-list the editable fields so that authorId and bookId cannot be reassigned by the request body.
    if (typeof req.body?.text === 'string') {
      review.text = req.body.text;
    }
    res.json(review);
  },
);

reviewsRouter.delete('/:id', requirePermission('review:delete'), (req, res) => {
  reviews.delete(req.params.id);
  res.status(204).end();
});

// auth-router.mjs
import { createHash, randomBytes, randomUUID } from 'node:crypto';
import cookieParser from 'cookie-parser';
import express from 'express';
import { authenticate, findById, toPublicUser } from './users.mjs';
import { signAccessToken } from './tokens.mjs';

const REFRESH_TTL_MS = 1000 * 60 * 60 * 24 * 14;
const REFRESH_COOKIE = 'bookshelf_refresh';

// hash -> { userId, familyId, expiresAt, used }. A database table with an index on the hash in a real application.
const refreshTokens = new Map();

const sha256 = (value) => createHash('sha256').update(value).digest('hex');

function issueRefreshToken(userId, familyId = randomUUID()) {
  const token = randomBytes(32).toString('base64url');
  refreshTokens.set(sha256(token), { userId, familyId, expiresAt: Date.now() + REFRESH_TTL_MS, used: false });
  return token;
}

function revokeFamily(familyId) {
  for (const [hash, record] of refreshTokens) {
    if (record.familyId === familyId) {
      refreshTokens.delete(hash);
    }
  }
}

function setRefreshCookie(res, token) {
  res.cookie(REFRESH_COOKIE, token, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'strict',
    path: '/auth', // sent only to the authentication endpoints
    maxAge: REFRESH_TTL_MS,
  });
}

export const authRouter = express.Router();
authRouter.use(cookieParser());

authRouter.post('/login', express.json(), async (req, res) => {
  const { email, password } = req.body ?? {};
  if (typeof email !== 'string' || typeof password !== 'string') {
    return res.status(400).json({ message: 'email and password are required' });
  }
  const user = await authenticate(email, password);
  if (!user) {
    return res.status(401).json({ message: 'Invalid email or password' });
  }
  setRefreshCookie(res, issueRefreshToken(user.id));
  res.json({ accessToken: await signAccessToken(user), user: toPublicUser(user) });
});

authRouter.post('/refresh', async (req, res) => {
  const presented = req.cookies?.[REFRESH_COOKIE];
  const record = presented ? refreshTokens.get(sha256(presented)) : undefined;
  if (!record || record.expiresAt < Date.now()) {
    res.clearCookie(REFRESH_COOKIE, { path: '/auth' });
    return res.status(401).json({ message: 'Invalid refresh token' });
  }
  if (record.used) {
    // Reuse of a rotated token: assume theft and end the whole session family.
    revokeFamily(record.familyId);
    res.clearCookie(REFRESH_COOKIE, { path: '/auth' });
    return res.status(401).json({ message: 'Refresh token reuse detected' });
  }
  const user = await findById(record.userId);
  if (!user) {
    revokeFamily(record.familyId);
    return res.status(401).json({ message: 'Invalid refresh token' });
  }
  record.used = true;
  setRefreshCookie(res, issueRefreshToken(user.id, record.familyId));
  res.json({ accessToken: await signAccessToken(user) });
});

authRouter.post('/logout', (req, res) => {
  const presented = req.cookies?.[REFRESH_COOKIE];
  const record = presented ? refreshTokens.get(sha256(presented)) : undefined;
  if (record) {
    revokeFamily(record.familyId);
  }
  res.clearCookie(REFRESH_COOKIE, { path: '/auth' });
  res.status(204).end();
});

// rate-limit.mjs
import { ipKeyGenerator, rateLimit } from 'express-rate-limit';

const common = {
  standardHeaders: 'draft-8',
  legacyHeaders: false,
  skipSuccessfulRequests: true, // only failed logins consume the budget
  handler: (req, res) => {
    res.status(429).json({ status: 429, message: 'Too many attempts, try again later' });
  },
};

// One client trying many accounts.
export const loginLimiterByIp = rateLimit({
  ...common,
  windowMs: 15 * 60 * 1000,
  limit: 10, // failed attempts per window and address
  keyGenerator: (req) => ipKeyGenerator(req.ip),
});

// Many addresses trying one account. Looser, because anyone can spend it to lock the real user out.
export const loginLimiterByAccount = rateLimit({
  ...common,
  windowMs: 60 * 60 * 1000,
  limit: 20, // failed attempts per window and account
  keyGenerator: (req) => `account:${String(req.body?.email ?? '').trim().toLowerCase()}`,
});

// app.post('/login', loginLimiterByIp, loginLimiterByAccount, ...)