node-scrypt-wrapper/index.js
2023-09-25 13:13:20 -04:00

224 lines
8 KiB
JavaScript

/**
* 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
}