git.squeep.com Git - squeep-mystery-box/blob - lib/mystery-box.js

   1 'use strict';
   2
   3 const crypto = require('crypto');
   4 const zlib = require('zlib');
   5 const { promisify } = require('util');
   6 const { base64ToBase64URL, base64URLToBase64 } = require('@squeep/base64url');
   7 const common = require('./common');
   8 const allVersions = require('./version-parameters');
   9 const { performance } = require('perf_hooks');
  10
  11 const _fileScope = common.fileScope(__filename);
  12
  13 const brotliCompressAsync = promisify(zlib.brotliCompress);
  14 const brotliDecompressAsync = promisify(zlib.brotliDecompress);
  15 const deflateRawAsync = promisify(zlib.deflateRaw);
  16 const inflateRawAsync = promisify(zlib.inflateRaw);
  17 const scryptAsync = promisify(crypto.scrypt);
  18
  19 /**
  20  * Only you will know what's inside your...
  21  *    \  |            |               | __ )
  22  *   |\/ | |   |  __| __|  _ \  __|   | __ \   _ \ \  /
  23  *   |   | |   |\__ \ |    __/ |  |   | |   | (   |`  <
  24  *  _|  _|\__, |____/\__|\___|_| \__, |____/ \___/ _/\_\
  25  *        ____/                  ____/
  26  *
  27  * Our very own way of converting a buffer or serializable object
  28  * to and from an opaque and web-safe representation, which we can
  29  * let anyone see without disclosing the contents, nor allowing it
  30  * to be modified without detection.
  31  *
  32  * The result is a Base64URL-encoded byte-array consisting of:
  33  * - version, indicating format and encryption algorithm
  34  * - flags, indicating state of the contents
  35  * - iv/nonce, randomness for the algorithm
  36  * - salt, applied to a secret to derive a key
  37  * - tag, additional room for encryption to validate the previous fields
  38  * - payload, encrypted version of possibly compressed and serialized object
  39  *
  40  */
  41
  42
  43 const availableFlags = {
  44   Brotli: (1<<0), // Slightly better compression, but slow
  45   Flate: (1<<1), // Slightly worse compression, but much faster especially with larger payloads.  Prefer this.
  46   FutureCompression: (1<<0)|(1<<1), // Something else, like zstd maybe.
  47
  48   Unused2: (1<<2),
  49   Unused3: (1<<3),
  50   Unused4: (1<<4),
  51   Unused5: (1<<5),
  52   Unused6: (1<<6),
  53
  54   BufferPayload: (1<<7), // Payload is a buffer, not an object
  55 };
  56 const compressionFlagsMask = (availableFlags.Flate | availableFlags.Brotli);
  57 const compressionFlagsShift = 0;
  58 const payloadFlagsMask = (availableFlags.BufferPayload);
  59 const payloadFlagsShift = 7;
  60
  61
  62 class MysteryBox {
  63   /**
  64    * @param {Console} logger
  65    * @param {Object} options
  66    * @param {String} options.encryptionSecret
  67    * @param {Number=} options.defaultFlags
  68    */
  69   constructor(logger, options = {}) {
  70     this.logger = logger;
  71     this.options = options;
  72
  73     this.secret = options.encryptionSecret;
  74     if (!this.secret) {
  75       throw new Error('missing encryption secret');
  76     }
  77     // TODO: support secret rolling
  78
  79     // Filter any unavailable algorithms
  80     const availableCiphers = crypto.getCiphers();
  81     this.versionParameters = Object.entries(allVersions).reduce((acc, [v, p]) => {
  82       if (availableCiphers.includes(p.algorithm)) {
  83         acc[v] = p; // eslint-disable-line security/detect-object-injection
  84       }
  85       return acc;
  86     }, {});
  87
  88     // Default to highest
  89     this.bestVersion = Number(Object.keys(this.versionParameters).sort().pop());
  90     if (Number.isNaN(this.bestVersion)) {
  91       throw new Error('no supported versions available');
  92     }
  93
  94     this.Flags = availableFlags;
  95     this.defaultFlags = 'defaultFlags' in options ? options.defaultFlags : availableFlags.Flate;
  96     if (this.defaultFlags < 0 || this.defaultFlags > 255) {
  97       throw new RangeError('Invalid default flag value');
  98     }
  99   }
 100
 101
 102   /**
 103    * Parse the bits out of the flags.
 104    */
 105   static _decodeFlags(flags) {
 106     return {
 107       compression: (flags & compressionFlagsMask) >> compressionFlagsShift,
 108       payloadIsBuffer: Boolean((flags & payloadFlagsMask) >> payloadFlagsShift),
 109     };
 110   }
 111
 112
 113   /**
 114    * Put contents into a mysterious box.
 115    * @param {Object|Buffer} contents
 116    * @returns {String}
 117    */
 118   async pack(contents, version = this.bestVersion, flags = this.defaultFlags) {
 119     const _scope = _fileScope('pack');
 120     const timingsMs = {
 121       start: performance.now(),
 122       preCompress: 0,
 123       postCompress: 0,
 124       preEncrypt: 0,
 125       postEncrypt: 0,
 126       end: 0,
 127     };
 128
 129     if (!(version in this.versionParameters)) {
 130       throw new RangeError(`MysteryBox format version ${version} not supported`);
 131     }
 132     // eslint-disable-next-line security/detect-object-injection
 133     const v = this.versionParameters[version];
 134
 135     const { compression } = MysteryBox._decodeFlags(flags);
 136
 137     if (Buffer.isBuffer(contents)) {
 138       flags |= this.Flags.BufferPayload;
 139     } else {
 140       contents = JSON.stringify(contents);
 141     }
 142
 143     const versionBuffer = Buffer.alloc(v.versionBytes);
 144     versionBuffer.writeUInt8(v.version, 0);
 145
 146     const [iv, salt] = await Promise.all([
 147       v.ivBytes,
 148       v.saltBytes,
 149     ].map((b) => common.randomBytesAsync(b)));
 150
 151     timingsMs.preCompress = performance.now();
 152     let compressedContents;
 153     switch (compression) {
 154       case 0: // No compression requested
 155         compressedContents = contents;
 156         break;
 157       case this.Flags.Brotli:
 158         compressedContents = await brotliCompressAsync(contents);
 159         break;
 160       case this.Flags.Flate:
 161         compressedContents = await deflateRawAsync(contents);
 162         break;
 163     }
 164     timingsMs.postCompress = timingsMs.preCrypt = performance.now();
 165
 166     let payload;
 167     if (compressedContents.length >= contents.length) {
 168       flags = flags & ~compressionFlagsMask;
 169       payload = contents;
 170     } else {
 171       payload = compressedContents;
 172     }
 173     const flagsBuffer = Buffer.alloc(v.flagsBytes);
 174     flagsBuffer.writeUInt8(flags, 0);
 175
 176     // Authenticate all this data
 177     const aadBuffer = Buffer.concat([versionBuffer, flagsBuffer, iv, salt]);
 178
 179     const key = await scryptAsync(this.secret, salt, v.keyBytes);
 180     const cipher = crypto.createCipheriv(v.algorithm, key, iv, v.algOptions);
 181     cipher.setAAD(aadBuffer);
 182     const encrypted = cipher.update(payload);
 183     const final = cipher.final();
 184     const tag = cipher.getAuthTag();
 185
 186     const merged = Buffer.concat([versionBuffer, flagsBuffer, iv, salt, tag, encrypted, final]).toString('base64');
 187     const result = base64ToBase64URL(merged);
 188     timingsMs.end = timingsMs.postCrypt = performance.now();
 189
 190     this.logger.debug(_scope, 'statistics', { version, flags: this._prettyFlags(flags), serialized: contents.length, compressed: payload.length, encoded: result.length, ...MysteryBox._timingsLog(timingsMs) });
 191
 192     return result;
 193   }
 194
 195
 196   /**
 197    * Take contents out of a mysterious box.
 198    * @param {String} box - Base64URL encoded payload
 199    * @returns {Object}
 200    */
 201   async unpack(box) {
 202     const _scope = _fileScope('unpack');
 203     const timingsMs = {
 204       start: performance.now(),
 205       preCompress: 0,
 206       postCompress: 0,
 207       preCrypt: 0,
 208       postCrypt: 0,
 209       end: 0,
 210     };
 211
 212     if (!box) {
 213       throw new RangeError('nothing to unpack');
 214     }
 215
 216     const raw = Buffer.from(base64URLToBase64(box), 'base64');
 217     let offset = 0;
 218
 219     const version = raw.slice(offset, 1).readUInt8(0);
 220     if (!(version in this.versionParameters)) {
 221       throw new RangeError('unsupported version');
 222     }
 223     // eslint-disable-next-line security/detect-object-injection
 224     const v = this.versionParameters[version];
 225     offset += v.versionBytes;
 226
 227     const minBytes = v.versionBytes + v.flagsBytes + v.ivBytes + v.saltBytes + v.tagBytes;
 228     if (raw.length < minBytes) {
 229       throw new RangeError('not enough to unpack');
 230     }
 231
 232     const flags = raw.slice(offset, offset + v.flagsBytes).readUInt8(0);
 233     offset += v.flagsBytes;
 234
 235     const { compression, payloadIsBuffer } = MysteryBox._decodeFlags(flags);
 236
 237     const iv = raw.slice(offset, offset + v.ivBytes);
 238     offset += v.ivBytes;
 239
 240     const salt = raw.slice(offset, offset + v.saltBytes);
 241     offset += v.saltBytes;
 242
 243     const aad = raw.slice(0, offset); // Everything up to here
 244
 245     const tag = raw.slice(offset, offset + v.tagBytes);
 246     offset += v.tagBytes;
 247
 248     const encrypted = raw.slice(offset);
 249
 250     timingsMs.preCrypt = performance.now();
 251     const key = await scryptAsync(this.secret, salt, v.keyBytes);
 252     const decipher = crypto.createDecipheriv(v.algorithm, key, iv, v.algOptions);
 253     decipher.setAAD(aad);
 254     decipher.setAuthTag(tag);
 255
 256     const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]);
 257
 258     let payload;
 259     timingsMs.preCompress = timingsMs.postCrypt = performance.now();
 260     switch (compression) {
 261       case 0: // No compression
 262         payload = decrypted;
 263         break;
 264       case this.Flags.Brotli:
 265         payload = await brotliDecompressAsync(decrypted);
 266         break;
 267       case this.Flags.Flate:
 268         payload = await inflateRawAsync(decrypted);
 269         break;
 270     }
 271     timingsMs.end = timingsMs.postCompress = performance.now();
 272
 273     if (!payloadIsBuffer) {
 274       payload = JSON.parse(payload.toString('utf8'));
 275     }
 276
 277     this.logger.debug(_scope, 'statistics', { version, flags: this._prettyFlags(flags), ...MysteryBox._timingsLog(timingsMs) });
 278
 279     return payload;
 280   }
 281
 282
 283   /**
 284    * Pretty-print flag values
 285    * @param {Number} flags
 286    * @returns {String}
 287    */
 288   _prettyFlags(flags) {
 289     const flagNames = Object.entries(this.Flags).reduce((acc, cur) => {
 290       const [flagName, flagValue] = cur;
 291       if ((flags & flagValue) === flagValue) {
 292         acc.push(flagName);
 293       }
 294       return acc;
 295     }, []);
 296     return `0x${flags.toString(16).padStart(2, '0')} [${flagNames.join(',')}]`;
 297   }
 298
 299
 300   /**
 301    * Everyone loves numbers.
 302    * @param {Object} timingsMs
 303    * @returns
 304    */
 305   static _timingsLog({ start, preCompress, postCompress, preCrypt, postCrypt, end }) {
 306     return {
 307       totalMs: end - start,
 308       compressMs: postCompress - preCompress,
 309       cryptMs: postCrypt - preCrypt,
 310     };
 311   }
 312
 313 }
 314
 315 // Expose for stubbing in tests
 316 MysteryBox._test = { crypto };
 317
 318 module.exports = MysteryBox;