Authentication: Passwords, Sessions and Roles

'use strict';

const crypto = require('node:crypto');
const { promisify } = require('node:util');

const scrypt = promisify(crypto.scrypt);

// One of the five equal-strength scrypt settings in the
// OWASP Password Storage Cheat Sheet: N = 2^14, r = 8,
// p = 5. It needs 16 MiB, within Node's default limit.
const COST = { N: 16384, r: 8, p: 5 };
const KEY_BYTES = 32;
const SALT_BYTES = 16;

// Returns "scrypt$N$r$p$salt$key", salt and key in base64.
// The settings travel with the hash, so they can be raised
// later without breaking the passwords already stored.
async function hashPassword(password) {
  const salt = crypto.randomBytes(SALT_BYTES);
  const key = await scrypt(password, salt, KEY_BYTES, COST);
  return [
    'scrypt', COST.N, COST.r, COST.p,
    salt.toString('base64'), key.toString('base64'),
  ].join('$');
}

async function verifyPassword(password, stored) {
  const parts = String(stored).split('$');
  if (parts.length !== 6 || parts[0] !== 'scrypt') {
    return false;
  }
  const [, N, r, p, saltText, keyText] = parts;
  const salt = Buffer.from(saltText, 'base64');
  const expected = Buffer.from(keyText, 'base64');
  const cost = { N: Number(N), r: Number(r), p: Number(p) };
  const key = await scrypt(password, salt, expected.length, cost);
  // Compares every byte whatever happens, so the time taken
  // does not tell an attacker how much of a guess was right.
  return crypto.timingSafeEqual(key, expected);
}

module.exports = { hashPassword, verifyPassword };

$ cd ~/canteen-preorder
$ node -e "
> const { hashPassword, verifyPassword } = require('./src/passwords');
> (async () => {
>   const a = await hashPassword('the same password');
>   const b = await hashPassword('the same password');
>   const part = (h) => h.split('\$');
>   console.log('settings:', part(a).slice(0, 4).join('\$'));
>   console.log('salt and key, in bytes:',
>     Buffer.from(part(a)[4], 'base64').length,
>     Buffer.from(part(a)[5], 'base64').length);
>   console.log('two hashes of one password are equal?', a === b);
>   console.log('right password verifies?',
>     await verifyPassword('the same password', a));
>   console.log('wrong password verifies?',
>     await verifyPassword('the same password ', a));
>   const t = Date.now();
>   await hashPassword('timing');
>   console.log('one hash takes about', Date.now() - t, 'ms');
> })();
> "
settings: scrypt$16384$8$5
salt and key, in bytes: 16 32
two hashes of one password are equal? false
right password verifies? true
wrong password verifies? false
one hash takes about 163 ms

// The 10,000 most common passwords of 8 to 128 characters,
// read once at start-up (data/README.md says where they come
// from). A password on this list is among the first an
// attacker tries, so it is refused whatever its length.
const COMMON = new Set(fs.readFileSync(
  path.join(__dirname, '..', 'data', 'common-passwords.txt'),
  'utf8').split('\n').filter(Boolean));

function checkPassword(p, password) {
  if (typeof password !== 'string'
      || password.length < 8 || password.length > 128) {
    p.add('password', 'Use a password of 8 to 128 characters.');
  } else if (COMMON.has(password)
      || COMMON.has(password.toLowerCase())) {
    p.add('password', 'This password is too common. '
      + 'Choose one that is hard to guess.');
  }
}

# data/common-passwords.txt

The 10,000 most commonly used passwords that are 8 to 128 characters long,
the lengths the application would otherwise accept, one to a line, the most
common first. Registration and new staff accounts refuse every one of them
(SRS FR-1, security control S5). OWASP's Application Security Verification
Standard 5.0, requirement 6.2.4, asks for at least the 3,000 most common.

## Where it comes from

SecLists, the collection of security testing lists by Daniel Miessler and its
contributors, file
`Passwords/Common-Credentials/xato-net-10-million-passwords-100000.txt`:
100,000 different passwords from Mark Burnett's ten million passwords
dataset of 2015, sorted from most to least common. Downloaded on
30 September 2026, SHA-256
`1472aafa2561df5e3293aee252aee3ca660c12b399a283cf808bb01b39be388b`.

Made with:

    curl -fsSLo xato.txt https://raw.githubusercontent.com/danielmiessler/SecLists/master/Passwords/Common-Credentials/xato-net-10-million-passwords-100000.txt
    tr -d '\r' < xato.txt | awk 'length >= 8 && length <= 128' | head -n 10000 > data/common-passwords.txt

## Licence

SecLists is released under the MIT License:

    MIT License

    Copyright (c) 2018 Daniel Miessler

    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in all
    copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    SOFTWARE.

      <label for="register-password">Password: 8 or more
        characters, and not one you use anywhere else</label>

$ cd ~/canteen-preorder
$ npm start > server.log 2>&1 &
$ curl -s -o /dev/null --retry 10 --retry-connrefused localhost:3000/api/health
$ curl -s -H 'Content-Type: application/json' \
>   -d '{"name":"Meera Joshi","email":"meera@college.example","password":"sunshine1"}' \
>   localhost:3000/api/auth/register | jq -c .error.details
{"password":"This password is too common. Choose one that is hard to guess."}
$ curl -s -H 'Content-Type: application/json' \
>   -d '{"name":"Meera Joshi","email":"meera@college.example","password":"peas-under-the-bench"}' \
>   localhost:3000/api/auth/register | jq -c .user
{"id":7,"name":"Meera Joshi","email":"meera@college.example","role":"student"}
$ wc -l < data/common-passwords.txt
10000

'use strict';

// Counts failed sign-ins per key (the address the request
// came from, plus the email tried) and refuses a key that has
// failed `max` times inside `windowMs`. The clock is passed
// in so that a test can move time forward without waiting.
//
// It is kept in memory, so it forgets everything when the
// server restarts and it would not be shared between two
// servers. For one canteen server that is enough; the SRS
// records the limit.
function attemptLimiter({ max, windowMs, clock = Date.now }) {
  const failures = new Map();

  function recent(key) {
    const since = clock() - windowMs;
    const times = (failures.get(key) || []).filter((t) => t > since);
    if (times.length > 0) failures.set(key, times);
    else failures.delete(key);
    return times;
  }

  return {
    // Seconds until this key may try again; 0 if it may now.
    blockedFor(key) {
      const times = recent(key);
      if (times.length < max) return 0;
      return Math.ceil((times[0] + windowMs - clock()) / 1000);
    },
    fail(key) {
      failures.set(key, [...recent(key), clock()]);
    },
    reset(key) {
      failures.delete(key);
    },
  };
}

module.exports = { attemptLimiter };

  async function login({ email, password }, ip) {
    const key = `${ip}|${email}`;
    const wait = attempts.blockedFor(key);
    if (wait > 0) throw tooManyAttempts(wait);
    const user = await store.users.findByEmail(email);
    const hash = user ? user.passwordHash : await noSuchUser;
    const ok = await verifyPassword(password, hash);
    if (!user || !ok || !user.isActive) {
      attempts.fail(key);
      throw new AppError(401, 'wrong_credentials',
        'The email or the password is wrong.');
    }
    attempts.reset(key);
    const token = crypto.randomBytes(32).toString('base64url');

$ cd ~/canteen-preorder
$ node -e "
> const run = async (email) => {
>   const t = Date.now();
>   await fetch('http://localhost:3000/api/auth/login', {
>     method: 'POST', headers: { 'Content-Type': 'application/json' },
>     body: JSON.stringify({ email, password: 'not the password' }),
>   });
>   return Date.now() - t;
> };
> (async () => {
>   await run('warm@college.example');
>   console.log('a real student, wrong password:',
>     await run('kabir@college.example'), 'ms');
>   console.log('nobody with that address:   ',
>     await run('nobody@college.example'), 'ms');
> })();
> "
a real student, wrong password: 158 ms
nobody with that address:    145 ms

function cookieOptions(config) {
  return {
    httpOnly: true, // page scripts cannot read the cookie
    sameSite: 'lax', // not sent on another site's form posts
    secure: config.cookieSecure, // HTTPS only, once it is on
    maxAge: config.sessionHours * 60 * 60 * 1000,
    path: '/',
  };
}

'use strict';

// Reads the Cookie header into { name: value }.
function parseCookies(header) {
  const cookies = {};
  for (const part of (header || '').split(';')) {
    const at = part.indexOf('=');
    if (at < 1) continue;
    const name = part.slice(0, at).trim();
    const value = part.slice(at + 1).trim();
    try {
      cookies[name] = decodeURIComponent(value);
    } catch {
      cookies[name] = value;
    }
  }
  return cookies;
}

// Looks up who is signed in, from the "sid" cookie, and puts
// that person on req.user (or null) for the routes to read.
function loadSession(auth) {
  return async (req, res, next) => {
    const token = parseCookies(req.get('Cookie')).sid;
    req.sessionToken = token;
    req.user = token ? await auth.userFromToken(token) : null;
    next();
  };
}

module.exports = { parseCookies, loadSession };

'use strict';

const { notSignedIn, forbidden } = require('../errors');

// Placed in front of a route: only signed-in users get past.
function requireUser(req, res, next) {
  next(req.user ? undefined : notSignedIn());
}

// Only signed-in users with one of these roles get past.
function requireRole(...roles) {
  return (req, res, next) => {
    if (!req.user) return next(notSignedIn());
    if (!roles.includes(req.user.role)) return next(forbidden());
    next();
  };
}

module.exports = { requireUser, requireRole };

$ cd ~/canteen-preorder
$ curl -s -o /dev/null -w "nobody signed in:      %{http_code}\n" \
>   localhost:3000/api/reports/daily
nobody signed in:      401
$ curl -s -c priya -H 'Content-Type: application/json' -o /dev/null \
>   -d '{"email":"priya@college.example","password":"canteen-demo"}' \
>   localhost:3000/api/auth/login
$ curl -s -b priya -o /dev/null -w "a student:             %{http_code}\n" \
>   localhost:3000/api/reports/daily
a student:             403
$ curl -s -c lata -H 'Content-Type: application/json' -o /dev/null \
>   -d '{"email":"owner@college.example","password":"canteen-demo"}' \
>   localhost:3000/api/auth/login
$ curl -s -b lata -o /dev/null -w "the owner:             %{http_code}\n" \
>   localhost:3000/api/reports/daily
the owner:             200
$ curl -s -b priya localhost:3000/api/auth/me | jq -c .user
{"id":3,"name":"Priya Menon","email":"priya@college.example","role":"student"}