update dependencies and devDependencies
[squeep-mystery-box] / 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;