zapo-js 0.2.0 → 0.3.0

package/dist/esm/infra/perf/StoreLock.js

@@ -25,12 +25,14 @@ export class StoreLock {
                 current = Promise.reject(error);
             }
         }
-        const tracker = current.then(() => undefined, () => undefined);
+        const tracker = current.then(StoreLock._noop, StoreLock._noop);
         this.chains.set(key, tracker);
-        void tracker.finally(() => {
-            if (this.chains.get(key) === tracker) {
+        tracker.then(() => {
+            if (this.chains.get(key) === tracker)
+                this.chains.delete(key);
+        }, () => {
+            if (this.chains.get(key) === tracker)
                 this.chains.delete(key);
-            }
         });
         return current;
     }
@@ -75,3 +77,4 @@ export class StoreLock {
         }
     }
 }
+StoreLock._noop = () => undefined;

package/dist/esm/media/WaMediaCrypto.js

@@ -1,4 +1,4 @@
-import { createCipheriv, createDecipheriv, createHash, createHmac } from 'node:crypto';
+import { createHash, createHmac } from 'node:crypto';
 import { once } from 'node:events';
 import { createWriteStream } from 'node:fs';
 import { stat, unlink } from 'node:fs/promises';
@@ -8,10 +8,91 @@ import { PassThrough } from 'node:stream';
 import { hkdf } from '../crypto/core/hkdf.js';
 import { aesCbcDecrypt, aesCbcEncrypt, hmacSign, importAesCbcKey, importHmacKey, sha256 } from '../crypto/core/primitives.js';
 import { randomBytesAsync } from '../crypto/core/random.js';
-import { ENC_KEY_END, ENC_KEY_START, HMAC_TRUNCATED_SIZE, IV_SIZE, MAC_KEY_END, MAC_KEY_START, MEDIA_HKDF_SIZE } from './constants.js';
-import { WA_APP_STATE_KEY_TYPES, getWaMediaHkdfInfo } from '../protocol/constants.js';
-import { assertByteLength, concatBytes, EMPTY_BYTES, toChunkBytes, toBytesView, uint8Equal, uint8TimingSafeEqual } from '../util/bytes.js';
+import { ENC_KEY_END, ENC_KEY_START, HMAC_TRUNCATED_SIZE, IV_SIZE, MAC_KEY_END, MAC_KEY_START, MEDIA_HKDF_SIZE, SIDECAR_CHUNK_SIZE, SIDECAR_HMAC_SIZE } from './constants.js';
+import { getWaMediaHkdfInfo, WA_APP_STATE_KEY_TYPES } from '../protocol/constants.js';
+import { assertByteLength, concatBytes, EMPTY_BYTES, toBytesView, toChunkBytes, uint8Equal, uint8TimingSafeEqual } from '../util/bytes.js';
 import { toError } from '../util/primitives.js';
+const AES_BLOCK_SIZE = 16;
+const PKCS7_FULL_BLOCK = new Uint8Array(AES_BLOCK_SIZE).fill(AES_BLOCK_SIZE);
+async function aesCbcEncryptChunk(key, iv, chunk, isFinal) {
+    const encrypted = await aesCbcEncrypt(key, iv, chunk);
+    if (isFinal) {
+        return {
+            ciphertext: encrypted,
+            nextIv: encrypted.subarray(encrypted.byteLength - AES_BLOCK_SIZE)
+        };
+    }
+    const ciphertext = encrypted.subarray(0, encrypted.byteLength - AES_BLOCK_SIZE);
+    return {
+        ciphertext,
+        nextIv: ciphertext.subarray(ciphertext.byteLength - AES_BLOCK_SIZE)
+    };
+}
+async function aesCbcDecryptChunk(key, iv, ciphertext, isFinal) {
+    const nextIv = toBytesView(ciphertext.subarray(ciphertext.byteLength - AES_BLOCK_SIZE));
+    if (isFinal) {
+        return { plaintext: await aesCbcDecrypt(key, iv, ciphertext), nextIv };
+    }
+    const padBlock = (await aesCbcEncrypt(key, nextIv, PKCS7_FULL_BLOCK)).subarray(0, AES_BLOCK_SIZE);
+    const withPad = concatBytes([ciphertext, padBlock]);
+    return { plaintext: await aesCbcDecrypt(key, iv, withPad), nextIv };
+}
+async function computeFirstFrameSidecar(macKey, ivCiphertext, firstFrameLength) {
+    const aligned = Math.ceil(firstFrameLength / AES_BLOCK_SIZE) * AES_BLOCK_SIZE;
+    const slice = ivCiphertext.subarray(0, IV_SIZE + aligned);
+    const key = await importHmacKey(macKey);
+    const digest = await hmacSign(key, slice);
+    return digest.subarray(0, SIDECAR_HMAC_SIZE);
+}
+class SidecarAccumulator {
+    constructor(macKey, estimatedSize = 0) {
+        this.resultOffset = 0;
+        this.totalPushed = 0;
+        this.windowOffset = 0;
+        this.nextChunkStart = 0;
+        this.macKey = macKey;
+        this.window = new Uint8Array(IV_SIZE + SIDECAR_CHUNK_SIZE);
+        const estimated = Math.max(Math.ceil(estimatedSize / SIDECAR_CHUNK_SIZE) + 1, 16);
+        this.result = new Uint8Array(estimated * SIDECAR_HMAC_SIZE);
+    }
+    push(data) {
+        let srcOffset = 0;
+        while (srcOffset < data.byteLength) {
+            const windowEnd = this.nextChunkStart + IV_SIZE + SIDECAR_CHUNK_SIZE;
+            const remaining = windowEnd - this.totalPushed;
+            const toCopy = Math.min(remaining, data.byteLength - srcOffset);
+            this.window.set(data.subarray(srcOffset, srcOffset + toCopy), this.windowOffset);
+            this.windowOffset += toCopy;
+            this.totalPushed += toCopy;
+            srcOffset += toCopy;
+            if (this.totalPushed === windowEnd) {
+                this.flushChunk();
+            }
+        }
+    }
+    finish() {
+        if (this.windowOffset > 0) {
+            this.flushChunk();
+        }
+        return this.result.subarray(0, this.resultOffset);
+    }
+    flushChunk() {
+        const digest = createHmac('sha256', this.macKey)
+            .update(this.window.subarray(0, this.windowOffset))
+            .digest();
+        if (this.resultOffset + SIDECAR_HMAC_SIZE > this.result.byteLength) {
+            const grown = new Uint8Array(this.result.byteLength * 2);
+            grown.set(this.result);
+            this.result = grown;
+        }
+        this.result.set(digest.subarray(0, SIDECAR_HMAC_SIZE), this.resultOffset);
+        this.resultOffset += SIDECAR_HMAC_SIZE;
+        this.nextChunkStart += SIDECAR_CHUNK_SIZE;
+        const overlapSrc = this.window.subarray(this.windowOffset - IV_SIZE, this.windowOffset);
+        this.window.set(overlapSrc, 0);
+        this.windowOffset = IV_SIZE;
+    }
+}
 export class WaMediaCrypto {
     static async generateMediaKey() {
         return randomBytesAsync(32);
@@ -27,24 +108,41 @@ export class WaMediaCrypto {
             refKey: expanded.subarray(MAC_KEY_END, MEDIA_HKDF_SIZE)
         };
     }
-    static async encryptBytes(mediaType, mediaKey, plaintext) {
+    static async encryptBytes(mediaType, mediaKey, plaintext, options) {
         const keys = await WaMediaCrypto.deriveKeys(mediaType, mediaKey);
-        const [aesKey, macKey] = await Promise.all([
+        const [aesKey, hmacKey] = await Promise.all([
             importAesCbcKey(keys.encKey),
             importHmacKey(keys.macKey)
         ]);
         const ciphertext = await aesCbcEncrypt(aesKey, keys.iv, plaintext);
         const ivCiphertext = concatBytes([keys.iv, ciphertext]);
-        const mac = await hmacSign(macKey, ivCiphertext);
+        const mac = await hmacSign(hmacKey, ivCiphertext);
         const signature = mac.subarray(0, HMAC_TRUNCATED_SIZE);
         const ciphertextHmac = concatBytes([ciphertext, signature]);
+        let streamingSidecar;
+        if (options?.sidecar !== false) {
+            const acc = new SidecarAccumulator(keys.macKey);
+            acc.push(keys.iv);
+            acc.push(ciphertext);
+            acc.push(signature);
+            streamingSidecar = acc.finish();
+        }
+        const firstFrameSidecar = options?.firstFrameLength !== undefined
+            ? await computeFirstFrameSidecar(keys.macKey, ivCiphertext, options.firstFrameLength)
+            : undefined;
         const [fileSha256, fileEncSha256] = await Promise.all([
             sha256(plaintext),
             sha256(ciphertextHmac)
         ]);
-        return { ciphertextHmac, fileSha256, fileEncSha256 };
+        return {
+            ciphertextHmac,
+            fileSha256,
+            fileEncSha256,
+            streamingSidecar,
+            firstFrameSidecar
+        };
     }
-    static async decryptBytes(mediaType, mediaKey, ciphertextHmac, expectedFileSha256, expectedFileEncSha256) {
+    static async decryptBytes(mediaType, mediaKey, ciphertextHmac, expectedFileSha256, expectedFileEncSha256, skipMacVerification = false) {
         if (ciphertextHmac.byteLength < HMAC_TRUNCATED_SIZE) {
             throw new Error(`ciphertext too short: ${ciphertextHmac.byteLength}`);
         }
@@ -55,17 +153,19 @@ export class WaMediaCrypto {
             }
         }
         const keys = await WaMediaCrypto.deriveKeys(mediaType, mediaKey);
+        const [aesKey, hmacKey] = await Promise.all([
+            importAesCbcKey(keys.encKey),
+            importHmacKey(keys.macKey)
+        ]);
         const ciphertext = ciphertextHmac.subarray(0, ciphertextHmac.byteLength - HMAC_TRUNCATED_SIZE);
         const expectedMac = ciphertextHmac.subarray(ciphertextHmac.byteLength - HMAC_TRUNCATED_SIZE);
         const ivCiphertext = concatBytes([keys.iv, ciphertext]);
-        const [macKey, aesKey] = await Promise.all([
-            importHmacKey(keys.macKey),
-            importAesCbcKey(keys.encKey)
-        ]);
-        const mac = await hmacSign(macKey, ivCiphertext);
-        const signature = mac.subarray(0, HMAC_TRUNCATED_SIZE);
-        if (!uint8TimingSafeEqual(signature, expectedMac)) {
-            throw new Error('media MAC mismatch');
+        if (!skipMacVerification) {
+            const mac = await hmacSign(hmacKey, ivCiphertext);
+            const signature = mac.subarray(0, HMAC_TRUNCATED_SIZE);
+            if (!uint8TimingSafeEqual(signature, expectedMac)) {
+                throw new Error('media MAC mismatch');
+            }
         }
         const plaintext = await aesCbcDecrypt(aesKey, keys.iv, ciphertext);
         const fileSha256 = await sha256(plaintext);
@@ -75,18 +175,18 @@ export class WaMediaCrypto {
         const fileEncSha256 = expectedFileEncSha256 ?? (await sha256(ciphertextHmac));
         return { plaintext, fileSha256, fileEncSha256 };
     }
-    static async encryptReadable(mediaType, mediaKey, plaintext) {
+    static async encryptReadable(mediaType, mediaKey, plaintext, options) {
         const keys = await WaMediaCrypto.deriveKeys(mediaType, mediaKey);
         const encrypted = new PassThrough();
-        const metadata = pumpEncryption(plaintext, encrypted, keys);
+        const metadata = pumpEncryption(plaintext, encrypted, keys, options?.sidecar !== false, options?.firstFrameLength);
         return { encrypted, metadata };
     }
-    static async encryptToFile(mediaType, mediaKey, plaintext) {
+    static async encryptToFile(mediaType, mediaKey, plaintext, options) {
         const keys = await WaMediaCrypto.deriveKeys(mediaType, mediaKey);
         const filePath = join(tmpdir(), `zapo-enc-${Date.now()}-${Math.random().toString(36).slice(2)}`);
         const output = createWriteStream(filePath);
         try {
-            const metadata = await pumpEncryptionToWritable(plaintext, output, keys);
+            const metadata = await pumpEncryptionToWritable(plaintext, output, keys, options?.sidecar !== false, options?.firstFrameLength);
             const fileSize = (await stat(filePath)).size;
             return { filePath, fileSize, ...metadata };
         }
@@ -112,42 +212,80 @@ export class WaMediaCrypto {
         return paddedLength + HMAC_TRUNCATED_SIZE;
     }
 }
-async function pumpEncryption(plaintext, encrypted, keys) {
+async function pumpEncryption(plaintext, encrypted, keys, computeSidecar, firstFrameLength) {
+    const aesKey = await importAesCbcKey(keys.encKey);
     const plainHash = createHash('sha256');
     const encHash = createHash('sha256');
     const hmac = createHmac('sha256', keys.macKey);
-    const cipher = createCipheriv('aes-256-cbc', keys.encKey, keys.iv);
+    const sidecar = computeSidecar ? new SidecarAccumulator(keys.macKey) : null;
+    const ffTarget = firstFrameLength !== undefined
+        ? IV_SIZE + Math.ceil(firstFrameLength / AES_BLOCK_SIZE) * AES_BLOCK_SIZE
+        : 0;
+    let ffCollected = 0;
+    const ffChunks = ffTarget > 0 ? [keys.iv] : [];
+    if (ffTarget > 0)
+        ffCollected = IV_SIZE;
     let plaintextLength = 0;
+    let currentIv = keys.iv;
+    let pending = EMPTY_BYTES;
     hmac.update(keys.iv);
+    sidecar?.push(keys.iv);
     try {
         for await (const chunk of plaintext) {
             const plainChunk = toChunkBytes(chunk);
-            if (plainChunk.byteLength === 0) {
+            if (plainChunk.byteLength === 0)
                 continue;
-            }
             plaintextLength += plainChunk.byteLength;
             plainHash.update(plainChunk);
-            const encryptedChunk = cipher.update(plainChunk);
-            if (encryptedChunk.byteLength > 0) {
-                hmac.update(encryptedChunk);
-                encHash.update(encryptedChunk);
-                await writeChunk(encrypted, encryptedChunk);
+            const combined = pending.byteLength > 0
+                ? concatBytes([pending, plainChunk])
+                : toBytesView(plainChunk);
+            const aligned = combined.byteLength - (combined.byteLength % AES_BLOCK_SIZE);
+            if (aligned === 0) {
+                pending = combined;
+                continue;
             }
+            const toEncrypt = toBytesView(combined.subarray(0, aligned));
+            pending = toBytesView(combined.subarray(aligned));
+            const { ciphertext, nextIv } = await aesCbcEncryptChunk(aesKey, currentIv, toEncrypt, false);
+            currentIv = nextIv;
+            hmac.update(ciphertext);
+            encHash.update(ciphertext);
+            sidecar?.push(ciphertext);
+            if (ffCollected < ffTarget) {
+                const need = ffTarget - ffCollected;
+                ffChunks.push(ciphertext.subarray(0, Math.min(need, ciphertext.byteLength)));
+                ffCollected += ciphertext.byteLength;
+            }
+            await writeChunk(encrypted, ciphertext);
         }
-        const encryptedFinal = cipher.final();
-        if (encryptedFinal.byteLength > 0) {
-            hmac.update(encryptedFinal);
-            encHash.update(encryptedFinal);
-            await writeChunk(encrypted, encryptedFinal);
+        const { ciphertext: finalCiphertext } = await aesCbcEncryptChunk(aesKey, currentIv, pending, true);
+        hmac.update(finalCiphertext);
+        encHash.update(finalCiphertext);
+        sidecar?.push(finalCiphertext);
+        if (ffCollected < ffTarget) {
+            const need = ffTarget - ffCollected;
+            ffChunks.push(finalCiphertext.subarray(0, Math.min(need, finalCiphertext.byteLength)));
         }
-        const signature = hmac.digest().subarray(0, HMAC_TRUNCATED_SIZE);
+        await writeChunk(encrypted, finalCiphertext);
+        const signature = toBytesView(hmac.digest().subarray(0, HMAC_TRUNCATED_SIZE));
         encHash.update(signature);
+        sidecar?.push(signature);
         await writeChunk(encrypted, signature);
         encrypted.end();
+        let firstFrameSidecar;
+        if (ffTarget > 0) {
+            const ivCiphertextSlice = concatBytes(ffChunks);
+            const ffKey = await importHmacKey(keys.macKey);
+            const ffDigest = await hmacSign(ffKey, ivCiphertextSlice);
+            firstFrameSidecar = ffDigest.subarray(0, SIDECAR_HMAC_SIZE);
+        }
         return {
             fileSha256: toBytesView(plainHash.digest()),
             fileEncSha256: toBytesView(encHash.digest()),
-            plaintextLength
+            plaintextLength,
+            streamingSidecar: sidecar?.finish(),
+            firstFrameSidecar
         };
     }
     catch (error) {
@@ -182,42 +320,80 @@ async function endWritable(stream) {
         stream.end(() => resolve());
     });
 }
-async function pumpEncryptionToWritable(plaintext, output, keys) {
+async function pumpEncryptionToWritable(plaintext, output, keys, computeSidecar, firstFrameLength) {
+    const aesKey = await importAesCbcKey(keys.encKey);
     const plainHash = createHash('sha256');
     const encHash = createHash('sha256');
     const hmac = createHmac('sha256', keys.macKey);
-    const cipher = createCipheriv('aes-256-cbc', keys.encKey, keys.iv);
+    const sidecar = computeSidecar ? new SidecarAccumulator(keys.macKey) : null;
+    const ffTarget = firstFrameLength !== undefined
+        ? IV_SIZE + Math.ceil(firstFrameLength / AES_BLOCK_SIZE) * AES_BLOCK_SIZE
+        : 0;
+    let ffCollected = 0;
+    const ffChunks = ffTarget > 0 ? [keys.iv] : [];
+    if (ffTarget > 0)
+        ffCollected = IV_SIZE;
     let plaintextLength = 0;
+    let currentIv = keys.iv;
+    let pending = EMPTY_BYTES;
     hmac.update(keys.iv);
+    sidecar?.push(keys.iv);
     try {
         for await (const chunk of plaintext) {
             const plainChunk = toChunkBytes(chunk);
-            if (plainChunk.byteLength === 0) {
+            if (plainChunk.byteLength === 0)
                 continue;
-            }
             plaintextLength += plainChunk.byteLength;
             plainHash.update(plainChunk);
-            const encryptedChunk = cipher.update(plainChunk);
-            if (encryptedChunk.byteLength > 0) {
-                hmac.update(encryptedChunk);
-                encHash.update(encryptedChunk);
-                await writeChunkToWritable(output, encryptedChunk);
+            const combined = pending.byteLength > 0
+                ? concatBytes([pending, plainChunk])
+                : toBytesView(plainChunk);
+            const aligned = combined.byteLength - (combined.byteLength % AES_BLOCK_SIZE);
+            if (aligned === 0) {
+                pending = combined;
+                continue;
+            }
+            const toEncrypt = toBytesView(combined.subarray(0, aligned));
+            pending = toBytesView(combined.subarray(aligned));
+            const { ciphertext, nextIv } = await aesCbcEncryptChunk(aesKey, currentIv, toEncrypt, false);
+            currentIv = nextIv;
+            hmac.update(ciphertext);
+            encHash.update(ciphertext);
+            sidecar?.push(ciphertext);
+            if (ffCollected < ffTarget) {
+                const need = ffTarget - ffCollected;
+                ffChunks.push(ciphertext.subarray(0, Math.min(need, ciphertext.byteLength)));
+                ffCollected += ciphertext.byteLength;
             }
+            await writeChunkToWritable(output, ciphertext);
         }
-        const encryptedFinal = cipher.final();
-        if (encryptedFinal.byteLength > 0) {
-            hmac.update(encryptedFinal);
-            encHash.update(encryptedFinal);
-            await writeChunkToWritable(output, encryptedFinal);
+        const { ciphertext: finalCiphertext } = await aesCbcEncryptChunk(aesKey, currentIv, pending, true);
+        hmac.update(finalCiphertext);
+        encHash.update(finalCiphertext);
+        sidecar?.push(finalCiphertext);
+        if (ffCollected < ffTarget) {
+            const need = ffTarget - ffCollected;
+            ffChunks.push(finalCiphertext.subarray(0, Math.min(need, finalCiphertext.byteLength)));
         }
-        const signature = hmac.digest().subarray(0, HMAC_TRUNCATED_SIZE);
+        await writeChunkToWritable(output, finalCiphertext);
+        const signature = toBytesView(hmac.digest().subarray(0, HMAC_TRUNCATED_SIZE));
         encHash.update(signature);
+        sidecar?.push(signature);
         await writeChunkToWritable(output, signature);
         await endWritable(output);
+        let firstFrameSidecar;
+        if (ffTarget > 0) {
+            const ivCiphertextSlice = concatBytes(ffChunks);
+            const ffKey = await importHmacKey(keys.macKey);
+            const ffDigest = await hmacSign(ffKey, ivCiphertextSlice);
+            firstFrameSidecar = ffDigest.subarray(0, SIDECAR_HMAC_SIZE);
+        }
         return {
             fileSha256: toBytesView(plainHash.digest()),
             fileEncSha256: toBytesView(encHash.digest()),
-            plaintextLength
+            plaintextLength,
+            streamingSidecar: sidecar?.finish(),
+            firstFrameSidecar
         };
     }
     catch (error) {
@@ -227,10 +403,12 @@ async function pumpEncryptionToWritable(plaintext, output, keys) {
     }
 }
 async function pumpDecryption(encrypted, plaintext, keys, options) {
+    const aesKey = await importAesCbcKey(keys.encKey);
     const plainHash = createHash('sha256');
     const encHash = createHash('sha256');
     const hmac = createHmac('sha256', keys.macKey);
-    const decipher = createDecipheriv('aes-256-cbc', keys.encKey, keys.iv);
+    let currentIv = keys.iv;
+    let pending = EMPTY_BYTES;
     hmac.update(keys.iv);
     try {
         let trailing = EMPTY_BYTES;
@@ -248,20 +426,37 @@ async function pumpDecryption(encrypted, plaintext, keys, options) {
             const ciphertextChunk = merged.subarray(0, merged.byteLength - HMAC_TRUNCATED_SIZE);
             trailing = merged.subarray(merged.byteLength - HMAC_TRUNCATED_SIZE);
             hmac.update(ciphertextChunk);
-            const plainChunk = decipher.update(ciphertextChunk);
-            if (plainChunk.byteLength > 0) {
-                plainHash.update(plainChunk);
-                await writeChunk(plaintext, plainChunk);
+            const combined = pending.byteLength > 0
+                ? concatBytes([pending, ciphertextChunk])
+                : toBytesView(ciphertextChunk);
+            const aligned = combined.byteLength - (combined.byteLength % AES_BLOCK_SIZE);
+            if (aligned > AES_BLOCK_SIZE) {
+                const toDecrypt = combined.subarray(0, aligned - AES_BLOCK_SIZE);
+                const { plaintext: plainChunk, nextIv } = await aesCbcDecryptChunk(aesKey, currentIv, toDecrypt, false);
+                currentIv = nextIv;
+                if (plainChunk.byteLength > 0) {
+                    plainHash.update(plainChunk);
+                    await writeChunk(plaintext, plainChunk);
+                }
+                pending = toBytesView(combined.subarray(aligned - AES_BLOCK_SIZE));
+            }
+            else {
+                pending = combined;
             }
         }
         if (trailing.byteLength !== HMAC_TRUNCATED_SIZE) {
             throw new Error(`ciphertext too short: ${trailing.byteLength}`);
         }
-        const signature = hmac.digest().subarray(0, HMAC_TRUNCATED_SIZE);
-        if (!uint8TimingSafeEqual(signature, trailing)) {
-            throw new Error('media MAC mismatch');
+        if (!options.skipMacVerification) {
+            const signature = hmac.digest().subarray(0, HMAC_TRUNCATED_SIZE);
+            if (!uint8TimingSafeEqual(signature, trailing)) {
+                throw new Error('media MAC mismatch');
+            }
+        }
+        if (pending.byteLength < AES_BLOCK_SIZE || pending.byteLength % AES_BLOCK_SIZE !== 0) {
+            throw new Error(`invalid ciphertext length: ${pending.byteLength}`);
         }
-        const plainFinal = decipher.final();
+        const { plaintext: plainFinal } = await aesCbcDecryptChunk(aesKey, currentIv, pending, true);
         if (plainFinal.byteLength > 0) {
             plainHash.update(plainFinal);
             await writeChunk(plaintext, plainFinal);