X-Git-Url: http://git.squeep.com/?a=blobdiff_plain;f=lib%2Fmystery-box.js;h=a3e3192047a30d80a89a597e0158e46eb23b3f9e;hb=HEAD;hp=5dcf1b1fe4dbc8486c62de6e0cf3cbd3be96f2a6;hpb=2ef5f9c74d92c8eb8cc0bd03fecc9d1a1d306489;p=squeep-mystery-box diff --git a/lib/mystery-box.js b/lib/mystery-box.js index 5dcf1b1..a3e3192 100644 --- a/lib/mystery-box.js +++ b/lib/mystery-box.js @@ -4,7 +4,7 @@ const { EventEmitter } = require('events'); const crypto = require('crypto'); const zlib = require('zlib'); const { promisify } = require('util'); -const common = require('./common'); +const { MysteryBoxError } = require('./errors'); const allVersions = require('./version-parameters'); const { performance } = require('perf_hooks'); const { name: packageName, version: packageVersion } = require('../package.json'); @@ -19,6 +19,7 @@ const brotliDecompressAsync = promisify(zlib.brotliDecompress); const deflateRawAsync = promisify(zlib.deflateRaw); const inflateRawAsync = promisify(zlib.inflateRaw); const scryptAsync = promisify(crypto.scrypt); +const randomBytesAsync = promisify(crypto.randomBytes); /** * Only you will know what's inside your... @@ -62,18 +63,18 @@ const compressionFlagsShift = 0; const payloadFlagsMask = (availableFlags.BufferPayload); const payloadFlagsShift = 7; - class MysteryBox extends EventEmitter { /** - * @param {Object} options - * @param {String|String[]} options.encryptionSecret - if an array, will always encrypt with first secret, will attempt to decrypt with all; useful for rolling secrets - * @param {Number=} options.defaultFlags + * @param {object} options options + * @param {string|string[]} options.encryptionSecret if an array, will always encrypt with first secret, will attempt to decrypt with all; useful for rolling secrets + * @param {number=} options.defaultFlags default flags to use when packing boxes + * @param {any[]} args passed on to EventEmitter constructor */ constructor(options = {}, ...args) { super(...args); - this.secrets = common.ensureArray(options.encryptionSecret); + this.secrets = MysteryBox._ensureArray(options.encryptionSecret); if (!this.secrets.length) { - throw new Error('missing encryption secret'); + throw new MysteryBoxError('missing encryption secret'); } // Filter any unavailable algorithms @@ -93,19 +94,37 @@ class MysteryBox extends EventEmitter { // Default to highest this.bestVersion = Number(Object.keys(this.versionParameters).sort().pop()); if (Number.isNaN(this.bestVersion)) { - throw new Error('no supported versions available'); + throw new MysteryBoxError('no supported versions available'); } this.Flags = availableFlags; this.defaultFlags = 'defaultFlags' in options ? options.defaultFlags : availableFlags.Flate; if (this.defaultFlags < 0 || this.defaultFlags > 255) { - throw new RangeError('Invalid default flag value'); + throw new MysteryBoxError('Invalid default flag value'); + } + } + + + /** + * Return an array containing x if x is something and not an array + * @param {*} x thing to ensure is an array + * @returns {any[]} thing array or thing in an array + */ + static _ensureArray(x) { + if (x === undefined) { + return []; + } + if (!Array.isArray(x)) { + return Array(x); } + return x; } /** * Parse the bits out of the flags. + * @param {number} flags flags + * @returns {object} decoded flags */ static _decodeFlags(flags) { return { @@ -117,6 +136,11 @@ class MysteryBox extends EventEmitter { /** * Generate key data. + * @param {string} deriver key deriver enum + * @param {Buffer} secret secret + * @param {Buffer} salt salt + * @param {number} keyBytes bytes in key + * @returns {Promise} key */ static async _keyFromSecret(deriver, secret, salt, keyBytes) { switch (deriver) { @@ -142,15 +166,15 @@ class MysteryBox extends EventEmitter { return scryptAsync(secret, salt, keyBytes); default: - throw new RangeError('unsupported key deriver'); + throw new MysteryBoxError('unsupported key deriver'); } } /** * Return bits and bit mask for given number of encoded bytes. - * @param {Number} numBytes - * @returns {Object} + * @param {number} numBytes number of bytes + * @returns {object} bits value and mask */ static _versionHeaderBits(numBytes) { // Round up to 8 bits in result, just to be proper. @@ -169,8 +193,8 @@ class MysteryBox extends EventEmitter { * Number of packed bytes is indicated by location of first leading 0 bit. * Support for numbers larger than 127 is of dubious practicality, but here * it is anyhow. - * @param {Number} firstByte - * @returns {Object} + * @param {number} firstByte first byte contains encoded byte length + * @returns {object} number of bytes and masked first byte */ static _versionHeaderDecode(firstByte) { for (let numBytes = 1; numBytes <= 8; numBytes++) { @@ -187,7 +211,7 @@ class MysteryBox extends EventEmitter { } } // Nine bytes would be an extravagence. - throw new RangeError(`unsupported version header (0x${firstByte.toString(16)})`); + throw new MysteryBoxError(`unsupported version header (0x${firstByte.toString(16)})`); } @@ -197,8 +221,8 @@ class MysteryBox extends EventEmitter { * many total bytes comprise the version, in big-endian encoding. * Returns decoded version and number of bytes used to decode. * Only supports up to 6-byte numbers, and of those, only up to 4398046511103. - * @param {Buffer} buf - N.B. will be mogrified - * @returns {Object} + * @param {Buffer} buf N.B. will be mogrified + * @returns {object} decoded version and version byte length */ static _versionDecode(buf) { const headerByte = buf.readUInt8(0); @@ -211,7 +235,7 @@ class MysteryBox extends EventEmitter { } if (versionBytes > 6) { - throw new RangeError(`unsupported version (${versionBytes} bytes)`); + throw new MysteryBoxError(`unsupported version (${versionBytes} bytes)`); } // Otherwise, update the masked first byte and parse the rest of the buffer. @@ -225,8 +249,8 @@ class MysteryBox extends EventEmitter { /** * Encode a version identifier into a buffer of a variable number of bytes. - * @param {Number} version - * @returns {Object} + * @param {number} version version number to encode + * @returns {object} encoded version buffer and number of bytes */ static _versionEncode(version) { let versionBytes = 0; @@ -244,7 +268,7 @@ class MysteryBox extends EventEmitter { } else if (version <= 0x03ffffffffff) { // 34359738368-4398046511103 versionBytes = 6; } else { - throw new RangeError('version too large to encode'); + throw new MysteryBoxError(`version too large to encode (${version})`); } const buffer = Buffer.alloc(versionBytes); @@ -261,7 +285,8 @@ class MysteryBox extends EventEmitter { /** * Stats tracked when packing/unpacking boxes. - * @returns {Object} + * @param {string} method method name generating stats + * @returns {object} stats and timings */ static _newStats(method) { return { @@ -287,16 +312,16 @@ class MysteryBox extends EventEmitter { /** * Put contents into a mysterious box. - * @param {Object|Buffer} contents - * @param {Number=} version - * @param {Number=} flags - * @returns {String} + * @param {object|Buffer} contents object or buffer + * @param {number=} version version + * @param {number=} flags flags + * @returns {Promise} encoded contents */ async pack(contents, version = this.bestVersion, flags = this.defaultFlags) { const { stats, timingsMs } = MysteryBox._newStats('pack'); if (!(version in this.versionParameters)) { - throw new RangeError(`MysteryBox format version ${version} not supported`); + throw new MysteryBoxError(`MysteryBox format version ${version} not supported`); } // eslint-disable-next-line security/detect-object-injection const v = this.versionParameters[version]; @@ -320,13 +345,13 @@ class MysteryBox extends EventEmitter { const { buffer: versionBuffer, versionBytes } = MysteryBox._versionEncode(v.version); if (versionBytes !== v.versionBytes) { - throw new Error('internal inconsistency, mismatched version byte length'); + throw new MysteryBoxError('internal inconsistency, mismatched version byte length'); } const [iv, salt] = await Promise.all([ v.ivBytes, v.saltBytes, - ].map((b) => common.randomBytesAsync(b))); + ].map((b) => randomBytesAsync(b))); timingsMs.preCompress = performance.now(); let compressedContents; @@ -342,7 +367,6 @@ class MysteryBox extends EventEmitter { break; } stats.compressedBytes = Buffer.byteLength(compressedContents); - // const compressionRatio = stats.compressedBytes / stats.serializedBytes; timingsMs.postCompress = timingsMs.preCrypt = performance.now(); let payload; @@ -383,14 +407,14 @@ class MysteryBox extends EventEmitter { /** * Take contents out of a mysterious box. - * @param {String} box - Base64URL encoded payload - * @returns {Object} + * @param {string} box - Base64URL encoded payload + * @returns {Promise} decoded contents */ async unpack(box) { const { stats, timingsMs } = MysteryBox._newStats('unpack'); if (!box) { - throw new RangeError('nothing to unpack'); + throw new MysteryBoxError('nothing to unpack'); } const raw = Buffer.from(box, 'base64url'); @@ -398,20 +422,20 @@ class MysteryBox extends EventEmitter { const { version, versionBytes } = MysteryBox._versionDecode(raw); if (!(version in this.versionParameters)) { - throw new RangeError('unsupported version'); + throw new MysteryBoxError(`unsupported version (${version})`); } // eslint-disable-next-line security/detect-object-injection const v = this.versionParameters[version]; if (v.versionBytes !== versionBytes) { - throw new Error('internal inconsistency, mismatched version byte length'); + throw new MysteryBoxError('internal inconsistency, mismatched version byte length'); } offset += v.versionBytes; stats.version = version; const minBytes = v.versionBytes + v.flagsBytes + v.ivBytes + v.saltBytes + v.tagBytes; if (raw.length < minBytes) { - throw new RangeError('not enough to unpack'); + throw new MysteryBoxError('not enough to unpack'); } const flags = raw.subarray(offset, offset + v.flagsBytes).readUInt8(0); @@ -489,8 +513,8 @@ class MysteryBox extends EventEmitter { /** * Pretty-print flag values - * @param {Number} flags - * @returns {String} + * @param {number} flags flags + * @returns {string} pretty flags */ _prettyFlags(flags) { const flagNames = Object.entries(this.Flags).reduce((acc, cur) => { @@ -506,8 +530,14 @@ class MysteryBox extends EventEmitter { /** * Everyone loves numbers. - * @param {Object} timingsMs - * @returns + * @param {object} timingsMs raw timings + * @param {number} timingsMs.start start + * @param {number} timingsMs.preCompress checkpoint + * @param {number} timingsMs.postCompress checkpoint + * @param {number} timingsMs.preCrypt checkpoint + * @param {number} timingsMs.postCrypt checkpoint + * @param {number} timingsMs.end checkpoint + * @returns {object} computed timings */ static _timingsLog({ start, preCompress, postCompress, preCrypt, postCrypt, end }) { return { @@ -519,4 +549,4 @@ class MysteryBox extends EventEmitter { } -module.exports = MysteryBox; \ No newline at end of file +module.exports = MysteryBox;