node-scrypt-wrapper/index.js

/**
 * Helpers to make using node's built-in scrypt implementation more
 * straightforward to use and testable
 *
 * See https://nodejs.org/api/crypto.html#cryptoscryptpassword-salt-keylen-options-callback
 * https://stackoverflow.com/questions/62908969/password-hashing-in-nodejs-using-built-in-crypto
 *
 */
const {
  scrypt,
  scryptSync,
  timingSafeEqual,
  randomBytes,
} = require('node:crypto')

/// Node recommends at least 16 at time of writing. 24 is more than that and
// also will result in a base64 string which doesn't contain padding, which is
// always nice.
const DEFAULT_SALT_LENGTH = 24

// Node defaults to 16384 (1 << 14)
const DEFAULT_COST = 14

// Not really sure why this is the value everyone is using.
const DEFAULT_KEY_LENGTH = 64

/**
 * @class
 * @extends {Error}
 * @classdesc An error thrown when there was a problem encountered while parsing a serialized hash
 * @property {?Exception} cause An exception which was thrown while parsing this string.
 * @property {any} malformedString
 */
class ParseError extends Error {
  /**
   * @param {any} malformedString - The string which could not be parsed
   * @param {?Exception} cause - An error which was raised while trying to parse the string
   */
  constructor(malformedString, cause) {
    super(
      `error parsing ${malformedString}, expected hash encoded by @techworkers/scrypt-wrapper`,
    )
    this.cause = cause
    this.malformedString = malformedString
  }
}

/**
 * @class
 * @extends {Error}
 * @classdesc An Error thrown when the given options value passed to hash() or hashSync() is invalid
 * @property {HashOptions} options The options passed to hash() or hashSync()
 */
class InvalidOptions extends Error {
  /**
   *
   * @param {HashOptions} options The options which were received that are invalid
   */
  constructor(options) {
    super(
      `invalid options were received:\n\tcost: ${options.cost}\n\tkeyLength: ${options.keyLength}\n\tsaltLength: ${options.saltLength}`,
    )
    this.options = options
  }

  /**
   * Check that the given options are actually what they're expected to be
   * @param {HashOptions} options
   * @param {?function} reject A function called with the error rather than it being thrown
   */
  static validateOptions(options, reject) {
    const { cost, keyLength, saltLength } = options
    // Cost validation
    if (
      !(typeof cost === 'number' || cost instanceof Number) ||
      cost < 13 ||
      !Number.isInteger(cost)
    ) {
      const err = new InvalidOptions(options)
      if (reject) reject(err)
      else throw err
    }
    // keyLength validation
    if (
      !(typeof keyLength === 'number' || keyLength instanceof Number) ||
      !Number.isInteger(keyLength)
    ) {
      const err = new InvalidOptions(options)
      if (reject) reject(err)
      else throw err
    }
    // saltLength validation
    if (
      !(typeof saltLength === 'number' || saltLength instanceof Number) ||
      saltLength < 16 /* (recommended minimum) */ ||
      !Number.isInteger(saltLength)
    ) {
      const err = new InvalidOptions(options)
      if (reject) reject(err)
      else throw err
    }
  }
}

/**
 * @typedef HashOptions the optional values which may be passed to hash() and hashSync()
 * @property {number} cost the number of bits to shift 1 to to get the cost value. Defaults to 14
 * @property {number} keyLength how long the generated hash should be. Defaults to 64.
 * @property {number} saltLength the number of random bytes to use as a salt. Defaults to 24.
 */

/**
 * Generate an scrypt hash for the given password. The resulting string is as
 * follows:
 *  - The base-16 cost value
 *  - a dot ('.')
 *  - the URL-safe base64-encoded salt
 *  - a dot ('.')
 *  - the URL-safe base64-encoded derived hash
 *
 * @param {string} password the plain-text password
 * @param {?HashOptions} options optional settings
 * @throws {InvalidOptions} if the options aren't within the expected constraints
 * @returns {Promise<string>}
 */
function hash(password, options) {
  const cost = options?.cost ?? DEFAULT_COST
  const keyLength = options?.keyLength ?? DEFAULT_KEY_LENGTH
  const saltLength = options?.saltLength ?? DEFAULT_SALT_LENGTH
  const salt = randomBytes(saltLength)
  const $cost = 1 << cost
  return new Promise((resolve, reject) => {
    InvalidOptions.validateOptions({ cost, keyLength, saltLength }, reject)
    let $hash = cost.toString(16) + '.'
    $hash += salt.toString('base64url') + '.'
    scrypt(
      password.normalize(),
      salt,
      keyLength,
      { cost: $cost },
      (err, key) => {
        if (err) reject(err)
        else resolve($hash + key.toString('base64url'))
      },
    )
  })
}

/**
 * Like the above hash() function but synchronous.
 *
 * @param {string} password the plain-text password
 * @param {?HashOptions} options optional settings
 * @throws {InvalidOptions} if the options aren't within the expected constraints
 * @returns {Promise<string>}
 */
function hashSync(password, options) {
  const cost = options?.cost ?? DEFAULT_COST
  const keyLength = options?.keyLength ?? DEFAULT_KEY_LENGTH
  const saltLength = options?.saltLength ?? DEFAULT_SALT_LENGTH
  InvalidOptions.validateOptions({ cost, keyLength, saltLength })
  const salt = randomBytes(saltLength)
  const $cost = 1 << cost
  let $hash = cost.toString(16) + '.'
  $hash += salt.toString('base64url') + '.'
  return (
    $hash +
    scryptSync(password.normalize(), salt, keyLength, { cost: $cost }).toString(
      'base64url',
    )
  )
}

/**
 * Verify that the given plaintext password derives the given hash. The hash is
 * expected to be in the format as encoded by the above hash() function, which
 * also encodes the cost and salt used to create it.
 *
 * @param {string} derivedHash The hash as derived and encoded by the above
 *                             hash() function
 * @param {string} password The plaintext password to compare
 * @async
 * @returns {Promise<bool>} whether the password matches
 */
function verify(derivedHash, password) {
  return new Promise((resolve, reject) => {
    var $cost, $salt, $key
    try {
      ;[$cost, $salt, $key] = derivedHash.split('.')
    } catch (e) {
      return reject(new ParseError(derivedHash, e))
    }
    if (!$cost || !$salt || !$key) {
      return reject(new ParseError(derivedHash))
    }
    var cost, salt, key
    try {
      cost = 1 << Number.parseInt($cost, 16)
      salt = Buffer.from($salt, 'base64url')
      key = Buffer.from($key, 'base64url')
    } catch (e) {
      return reject(new ParseError(derivedHash, e))
    }
    scrypt(password.normalize(), salt, key.length, { cost }, (err, newKey) => {
      if (err) reject(err)
      else resolve(timingSafeEqual(key, newKey))
    })
  })
}

/**
 * Like `verify()`, but synchronous.
 *
 * @param {string} derivedHash The hash as derived and encoded by the above
 *                             hash() function
 * @param {string} password The plaintext password to compare
 * @throws {ParseError} when there's a problem parsing the given hash
 * @returns {Promise<bool>} whether the password matches
 */
function verifySync(derivedHash, password) {
  var $cost, $salt, $key
  try {
    ;[$cost, $salt, $key] = derivedHash.split('.')
  } catch (e) {
    throw new ParseError(derivedHash, e)
  }
  if (!$cost || !$salt || !$key) {
    throw new ParseError(derivedHash)
  }
  var cost, salt, key
  try {
    cost = 1 << Number.parseInt($cost, 16)
    salt = Buffer.from($salt, 'base64url')
    key = Buffer.from($key, 'base64url')
  } catch (e) {
    throw new ParseError(derivedHash, e)
  }
  const newKey = scryptSync(password.normalize(), salt, key.length, { cost })
  return timingSafeEqual(key, newKey)
}

module.exports = {
  hash,
  hashSync,
  verify,
  verifySync,
  ParseError,
  InvalidOptions,
}