zapo-js 0.2.0 → 1.0.0

package/dist/esm/appstate/{WaAppStateCrypto.js → crypto/WaAppStateCrypto.js}

@@ -1,46 +1,60 @@
-import { APP_STATE_DERIVED_INDEX_KEY_END, APP_STATE_DERIVED_KEY_LENGTH, APP_STATE_DERIVED_PATCH_MAC_KEY_END, APP_STATE_DERIVED_SNAPSHOT_MAC_KEY_END, APP_STATE_DERIVED_VALUE_ENCRYPTION_KEY_END, APP_STATE_DERIVED_VALUE_MAC_KEY_END, APP_STATE_EMPTY_LT_HASH, APP_STATE_IV_LENGTH, APP_STATE_MAC_OCTET_LENGTH, APP_STATE_POINT_SIZE, APP_STATE_VALUE_MAC_LENGTH } from './constants.js';
-import { hkdf } from '../crypto/core/hkdf.js';
-import { aesCbcDecrypt, aesCbcEncrypt, hmacSign, importAesCbcKey, importHmacKey, importHmacSha512Key } from '../crypto/core/primitives.js';
-import { randomBytesAsync } from '../crypto/core/random.js';
-import { proto } from '../proto.js';
-import { WA_APP_STATE_KDF_INFO } from '../protocol/constants.js';
-import { bytesToBase64 } from '../util/bytes.js';
-import { concatBytes, EMPTY_BYTES, intToBytes, TEXT_DECODER, TEXT_ENCODER, uint8Equal } from '../util/bytes.js';
-import { setBoundedMapEntry } from '../util/collections.js';
-import { normalizeNonNegativeInteger } from '../util/primitives.js';
+import { APP_STATE_DERIVED_INDEX_KEY_END, APP_STATE_DERIVED_KEY_LENGTH, APP_STATE_DERIVED_PATCH_MAC_KEY_END, APP_STATE_DERIVED_SNAPSHOT_MAC_KEY_END, APP_STATE_DERIVED_VALUE_ENCRYPTION_KEY_END, APP_STATE_DERIVED_VALUE_MAC_KEY_END, APP_STATE_EMPTY_LT_HASH, APP_STATE_IV_LENGTH, APP_STATE_MAC_OCTET_LENGTH, APP_STATE_POINT_SIZE, APP_STATE_VALUE_MAC_LENGTH } from '../constants.js';
+import { hkdf } from '../../crypto/core/hkdf.js';
+import { aesCbcDecrypt, aesCbcEncrypt, hmacSha256Sign, hmacSha512Sign } from '../../crypto/core/primitives.js';
+import { randomBytesAsync } from '../../crypto/core/random.js';
+import { proto } from '../../proto.js';
+import { WA_APP_STATE_KDF_INFO } from '../../protocol/constants.js';
+import { bytesToBase64, concatBytes, EMPTY_BYTES, intToBytes, TEXT_DECODER, TEXT_ENCODER, uint8TimingSafeEqual } from '../../util/bytes.js';
+import { setBoundedMapEntry } from '../../util/collections.js';
+import { normalizeNonNegativeInteger } from '../../util/primitives.js';
 const DEFAULT_DERIVED_KEYS_CACHE_MAX_SIZE = 256;
+/**
+ * Implements the app-state mutation cryptography: HKDF key derivation (with
+ * a bounded LRU cache), per-mutation encrypt/decrypt, snapshot/patch MAC
+ * generation, and the LT-hash arithmetic used to track collection state.
+ */
 export class WaAppStateCrypto {
-    constructor(derivedKeysCacheMaxSize = DEFAULT_DERIVED_KEYS_CACHE_MAX_SIZE) {
+    constructor(derivedKeysCacheMaxSize = DEFAULT_DERIVED_KEYS_CACHE_MAX_SIZE, skipMacVerification = false) {
         this.derivedKeysCache = new Map();
         this.derivedKeysCacheMaxSize = normalizeNonNegativeInteger(derivedKeysCacheMaxSize, DEFAULT_DERIVED_KEYS_CACHE_MAX_SIZE);
+        this.skipMacVerification = skipMacVerification;
     }
+    get isMacVerificationSkipped() {
+        return this.skipMacVerification;
+    }
+    /** Empties the derived-keys LRU cache (e.g. after a session reset). */
     clearCache() {
         this.derivedKeysCache.clear();
     }
-    async deriveKeys(keyData) {
+    /**
+     * Derives the index/value/snapshot/patch keys from an app-state sync key.
+     * Cached by base64 of `keyData` (LRU-bounded).
+     */
+    deriveKeys(keyData) {
         const cacheKey = bytesToBase64(keyData);
         const cached = this.derivedKeysCache.get(cacheKey);
         if (cached) {
             this.touchDerivedKeysCacheEntry(cacheKey, cached);
             return cached;
         }
-        const derived = await hkdf(keyData, null, WA_APP_STATE_KDF_INFO.MUTATION_KEYS, APP_STATE_DERIVED_KEY_LENGTH);
+        const derived = hkdf(keyData, null, WA_APP_STATE_KDF_INFO.MUTATION_KEYS, APP_STATE_DERIVED_KEY_LENGTH);
         const keys = {
-            indexKey: derived.subarray(0, APP_STATE_DERIVED_INDEX_KEY_END),
-            valueEncryptionKey: derived.subarray(APP_STATE_DERIVED_INDEX_KEY_END, APP_STATE_DERIVED_VALUE_ENCRYPTION_KEY_END),
-            valueMacKey: derived.subarray(APP_STATE_DERIVED_VALUE_ENCRYPTION_KEY_END, APP_STATE_DERIVED_VALUE_MAC_KEY_END),
-            snapshotMacKey: derived.subarray(APP_STATE_DERIVED_VALUE_MAC_KEY_END, APP_STATE_DERIVED_SNAPSHOT_MAC_KEY_END),
-            patchMacKey: derived.subarray(APP_STATE_DERIVED_SNAPSHOT_MAC_KEY_END, APP_STATE_DERIVED_PATCH_MAC_KEY_END)
+            indexHmacKey: derived.subarray(0, APP_STATE_DERIVED_INDEX_KEY_END),
+            valueEncryptionAesKey: derived.subarray(APP_STATE_DERIVED_INDEX_KEY_END, APP_STATE_DERIVED_VALUE_ENCRYPTION_KEY_END),
+            valueMacHmacKey: derived.subarray(APP_STATE_DERIVED_VALUE_ENCRYPTION_KEY_END, APP_STATE_DERIVED_VALUE_MAC_KEY_END),
+            snapshotMacHmacKey: derived.subarray(APP_STATE_DERIVED_VALUE_MAC_KEY_END, APP_STATE_DERIVED_SNAPSHOT_MAC_KEY_END),
+            patchMacHmacKey: derived.subarray(APP_STATE_DERIVED_SNAPSHOT_MAC_KEY_END, APP_STATE_DERIVED_PATCH_MAC_KEY_END)
         };
         this.touchDerivedKeysCacheEntry(cacheKey, keys);
         return keys;
     }
-    async generateIndexMac(indexKey, indexBytes) {
-        const key = await importHmacKey(indexKey);
-        return hmacSign(key, indexBytes);
+    /** Computes the HMAC-SHA-256 index MAC over `indexBytes`. */
+    generateIndexMac(indexHmacKey, indexBytes) {
+        return hmacSha256Sign(indexHmacKey, indexBytes);
     }
+    /** Encrypts a single mutation value with AES-CBC + HMAC value-MAC. */
     async encryptMutation(args) {
-        const derivedKeys = await this.deriveKeys(args.keyData);
+        const derivedKeys = this.deriveKeys(args.keyData);
         const indexBytes = TEXT_ENCODER.encode(args.index);
         const encoded = proto.SyncActionData.encode({
             index: indexBytes,
@@ -52,37 +66,34 @@ export class WaAppStateCrypto {
         if (iv.byteLength !== APP_STATE_IV_LENGTH) {
             throw new Error(`invalid IV length ${iv.byteLength}`);
         }
-        const indexMacPromise = this.generateIndexMac(derivedKeys.indexKey, indexBytes);
-        const encryptionKey = await importAesCbcKey(derivedKeys.valueEncryptionKey);
-        const cipherText = await aesCbcEncrypt(encryptionKey, iv, encoded);
-        const cipherWithIv = concatBytes([iv, cipherText]);
+        const indexMac = this.generateIndexMac(derivedKeys.indexHmacKey, indexBytes);
+        const cipherText = aesCbcEncrypt(derivedKeys.valueEncryptionAesKey, iv, encoded);
         const associatedData = this.generateAssociatedData(args.operation, args.keyId);
-        const [valueMac, indexMac] = await Promise.all([
-            this.generateValueMac(derivedKeys.valueMacKey, associatedData, cipherWithIv),
-            indexMacPromise
-        ]);
+        const valueMac = this.generateValueMac(derivedKeys.valueMacHmacKey, associatedData, iv, cipherText);
         return {
             indexMac,
-            valueBlob: concatBytes([cipherWithIv, valueMac]),
+            valueBlob: concatBytes([iv, cipherText, valueMac]),
             valueMac
         };
     }
+    /** Verifies and decrypts a single app-state mutation. */
+    // eslint-disable-next-line @typescript-eslint/require-await
     async decryptMutation(args) {
         if (args.valueBlob.byteLength < APP_STATE_IV_LENGTH + APP_STATE_VALUE_MAC_LENGTH) {
             throw new Error('invalid mutation value blob');
         }
-        const derivedKeys = await this.deriveKeys(args.keyData);
+        const derivedKeys = this.deriveKeys(args.keyData);
         const iv = args.valueBlob.subarray(0, APP_STATE_IV_LENGTH);
         const mac = args.valueBlob.subarray(args.valueBlob.byteLength - APP_STATE_VALUE_MAC_LENGTH);
         const cipherText = args.valueBlob.subarray(APP_STATE_IV_LENGTH, args.valueBlob.byteLength - APP_STATE_VALUE_MAC_LENGTH);
-        const cipherWithIv = args.valueBlob.subarray(0, args.valueBlob.byteLength - APP_STATE_VALUE_MAC_LENGTH);
-        const associatedData = this.generateAssociatedData(args.operation, args.keyId);
-        const expectedMac = await this.generateValueMac(derivedKeys.valueMacKey, associatedData, cipherWithIv);
-        if (!uint8Equal(mac, expectedMac)) {
-            throw new Error('mutation value MAC mismatch');
+        if (!this.skipMacVerification) {
+            const associatedData = this.generateAssociatedData(args.operation, args.keyId);
+            const expectedMac = this.generateValueMac(derivedKeys.valueMacHmacKey, associatedData, iv, cipherText);
+            if (!uint8TimingSafeEqual(mac, expectedMac)) {
+                throw new Error('mutation value MAC mismatch');
+            }
         }
-        const decryptionKey = await importAesCbcKey(derivedKeys.valueEncryptionKey);
-        const plaintext = await aesCbcDecrypt(decryptionKey, iv, cipherText);
+        const plaintext = aesCbcDecrypt(derivedKeys.valueEncryptionAesKey, iv, cipherText);
         const syncActionData = proto.SyncActionData.decode(plaintext);
         if (!syncActionData.index) {
             throw new Error('missing sync action index');
@@ -90,9 +101,11 @@ export class WaAppStateCrypto {
         if (syncActionData.version === null || syncActionData.version === undefined) {
             throw new Error('missing sync action version');
         }
-        const generatedIndexMac = await this.generateIndexMac(derivedKeys.indexKey, syncActionData.index);
-        if (!uint8Equal(generatedIndexMac, args.indexMac)) {
-            throw new Error('mutation index MAC mismatch');
+        if (!this.skipMacVerification) {
+            const generatedIndexMac = this.generateIndexMac(derivedKeys.indexHmacKey, syncActionData.index);
+            if (!uint8TimingSafeEqual(generatedIndexMac, args.indexMac)) {
+                throw new Error('mutation index MAC mismatch');
+            }
         }
         return {
             index: TEXT_DECODER.decode(syncActionData.index),
@@ -102,43 +115,48 @@ export class WaAppStateCrypto {
             valueMac: mac
         };
     }
+    /** Generates the HMAC-SHA-512 snapshot MAC over the LT-hash + version + collection name. */
+    // eslint-disable-next-line @typescript-eslint/require-await
     async generateSnapshotMac(keyData, ltHash, version, collectionName) {
-        const derivedKeys = await this.deriveKeys(keyData);
-        const payload = concatBytes([
+        const derivedKeys = this.deriveKeys(keyData);
+        return hmacSha256Sign(derivedKeys.snapshotMacHmacKey, [
             ltHash,
             intToBytes(8, version),
             TEXT_ENCODER.encode(collectionName)
         ]);
-        const key = await importHmacKey(derivedKeys.snapshotMacKey);
-        return hmacSign(key, payload);
     }
+    /** Generates the HMAC-SHA-512 patch MAC binding mutations to a collection version. */
+    // eslint-disable-next-line @typescript-eslint/require-await
     async generatePatchMac(keyData, snapshotMac, valueMacs, version, collectionName) {
-        const derivedKeys = await this.deriveKeys(keyData);
-        const payload = concatBytes([
+        const derivedKeys = this.deriveKeys(keyData);
+        return hmacSha256Sign(derivedKeys.patchMacHmacKey, [
             snapshotMac,
             ...valueMacs,
             intToBytes(8, version),
             TEXT_ENCODER.encode(collectionName)
         ]);
-        const key = await importHmacKey(derivedKeys.patchMacKey);
-        return hmacSign(key, payload);
     }
+    /** Adds value MACs into the running LT-hash digest for a collection. */
+    // eslint-disable-next-line @typescript-eslint/require-await
     async ltHashAdd(base, addValues) {
         return this.ltHashApply(base, addValues, (left, right) => left + right);
     }
+    /** Removes value MACs from the running LT-hash digest (for `remove` operations). */
+    // eslint-disable-next-line @typescript-eslint/require-await
     async ltHashSubtract(base, removeValues) {
         return this.ltHashApply(base, removeValues, (left, right) => left - right);
     }
+    /** Combined subtract+add LT-hash update used when a key's value MAC changes in place. */
     async ltHashSubtractThenAdd(base, addValues, removeValues) {
         const subtractResult = await this.ltHashSubtract(base, removeValues);
         const hash = await this.ltHashAdd(subtractResult, addValues);
         return { hash, subtractResult };
     }
-    async ltHashApply(base, values, combine) {
+    ltHashApply(base, values, combine) {
         if (values.length === 0) {
             return base;
         }
-        const expandedValues = await Promise.all(values.map((value) => hkdf(value, null, WA_APP_STATE_KDF_INFO.PATCH_INTEGRITY, APP_STATE_EMPTY_LT_HASH.byteLength)));
+        const expandedValues = values.map((value) => hkdf(value, null, WA_APP_STATE_KDF_INFO.PATCH_INTEGRITY, APP_STATE_EMPTY_LT_HASH.byteLength));
         const out = new Uint8Array(base.byteLength);
         this.pointwiseWithOverflow(base, expandedValues[0], combine, out);
         for (let index = 1; index < expandedValues.length; index += 1) {
@@ -175,11 +193,10 @@ export class WaAppStateCrypto {
         out.set(keyId, 1);
         return out;
     }
-    async generateValueMac(valueMacKey, associatedData, cipherWithIv) {
+    generateValueMac(valueMacHmacKey, associatedData, iv, cipherText) {
         const octetLength = new Uint8Array(APP_STATE_MAC_OCTET_LENGTH);
         octetLength[octetLength.length - 1] = associatedData.byteLength & 0xff;
-        const key = await importHmacSha512Key(valueMacKey);
-        const full = await hmacSign(key, concatBytes([associatedData, cipherWithIv, octetLength]));
+        const full = hmacSha512Sign(valueMacHmacKey, concatBytes([associatedData, iv, cipherText, octetLength]));
         return full.subarray(0, APP_STATE_VALUE_MAC_LENGTH);
     }
     touchDerivedKeysCacheEntry(cacheKey, keys) {

package/dist/esm/appstate/index.js

@@ -1,6 +1,6 @@
-export * from './constants.js';
-export { encodeAppStateFingerprint, decodeAppStateFingerprint, decodeAppStateCollections, decodeAppStateSyncKeys } from './encoding.js';
+export { APP_STATE_EMPTY_LT_HASH } from './constants.js';
+export { encodeAppStateFingerprint, decodeAppStateFingerprint, decodeAppStateCollections, decodeAppStateSyncKeys } from './parsers/encoding.js';
 export * from './utils.js';
-export { WaAppStateCrypto } from './WaAppStateCrypto.js';
-export { parseSyncResponse } from './WaAppStateSyncResponseParser.js';
-export { WaAppStateSyncClient } from './WaAppStateSyncClient.js';
+export { WaAppStateCrypto } from './crypto/WaAppStateCrypto.js';
+export { parseSyncResponse } from './parsers/response-parser.js';
+export { WaAppStateSyncClient } from './sync/WaAppStateSyncClient.js';

package/dist/esm/appstate/{encoding.js → parsers/encoding.js}

@@ -1,11 +1,14 @@
-import { proto } from '../proto.js';
-import { asBytes, asNumber, asOptionalBytes, asString } from '../util/coercion.js';
+import { proto } from '../../proto.js';
+import { asBytes, asNumber, asOptionalBytes, asString } from '../../util/coercion.js';
+import { toError } from '../../util/primitives.js';
+/** Serializes an app-state sync key fingerprint to its protobuf bytes, or `null` when absent. */
 export function encodeAppStateFingerprint(fingerprint) {
     if (!fingerprint) {
         return null;
     }
     return proto.Message.AppStateSyncKeyFingerprint.encode(fingerprint).finish();
 }
+/** Inverse of {@link encodeAppStateFingerprint}; throws on malformed input. */
 export function decodeAppStateFingerprint(raw) {
     const bytes = asOptionalBytes(raw, 'appstate_sync_keys.fingerprint');
     if (!bytes) {
@@ -15,10 +18,10 @@ export function decodeAppStateFingerprint(raw) {
         return proto.Message.AppStateSyncKeyFingerprint.decode(bytes);
     }
     catch (error) {
-        const reason = error instanceof Error ? error.message : String(error);
-        throw new Error(`invalid appstate_sync_keys.fingerprint protobuf payload: ${reason}`);
+        throw new Error(`invalid appstate_sync_keys.fingerprint protobuf payload: ${toError(error).message}`);
     }
 }
+/** Decodes app-state sync-key SQL rows into {@link WaAppStateSyncKey} records. */
 export function decodeAppStateSyncKeys(rows) {
     const decoded = new Array(rows.length);
     for (let i = 0; i < rows.length; i += 1) {
@@ -32,6 +35,10 @@ export function decodeAppStateSyncKeys(rows) {
     }
     return decoded;
 }
+/**
+ * Joins app-state collection-version and index-value SQL rows into the
+ * `collections` shape used by the in-memory app-state store.
+ */
 export function decodeAppStateCollections(versionRows, valueRows) {
     const valueMapByCollection = new Map();
     for (const row of valueRows) {

package/dist/esm/appstate/{WaAppStateSyncResponseParser.js → parsers/response-parser.js}

@@ -1,7 +1,13 @@
-import { parseCollectionName } from './utils.js';
-import { proto } from '../proto.js';
-import { WA_APP_STATE_COLLECTION_STATES, WA_APP_STATE_ERROR_CODES, WA_IQ_TYPES, WA_NODE_TAGS } from '../protocol/constants.js';
-import { decodeNodeContentBase64OrBytes, findNodeChildrenByTags, findNodeChild, getNodeChildrenByTag } from '../transport/node/helpers.js';
+import { parseCollectionName } from '../utils.js';
+import { proto } from '../../proto.js';
+import { WA_APP_STATE_COLLECTION_STATES, WA_APP_STATE_ERROR_CODES, WA_IQ_TYPES, WA_NODE_TAGS } from '../../protocol/constants.js';
+import { decodeNodeContentBase64OrBytes, findNodeChild, findNodeChildrenByTags, getNodeChildrenByTag } from '../../transport/node/helpers.js';
+import { parseOptionalInt } from '../../util/primitives.js';
+/**
+ * Parses an app-state `sync` IQ response into one payload per collection,
+ * decoding embedded patches and snapshot references. Throws when the IQ is
+ * an error envelope or missing the `<sync>` child.
+ */
 export function parseSyncResponse(iqNode) {
     if (iqNode.tag !== WA_NODE_TAGS.IQ) {
         throw new Error(`invalid sync response tag ${iqNode.tag}`);
@@ -26,11 +32,10 @@ export function parseSyncResponse(iqNode) {
         const versionAttr = collectionNode.attrs.version;
         let version;
         if (versionAttr) {
-            const parsedVersion = Number.parseInt(versionAttr, 10);
-            if (!Number.isSafeInteger(parsedVersion) || parsedVersion < 0) {
+            version = parseOptionalInt(versionAttr);
+            if (version === undefined) {
                 throw new Error(`invalid app-state collection version "${versionAttr}"`);
             }
-            version = parsedVersion;
         }
         const [patchesNode, snapshotNode] = findNodeChildrenByTags(collectionNode, [
             WA_NODE_TAGS.PATCHES,
@@ -55,6 +60,11 @@ export function parseSyncResponse(iqNode) {
     }
     return payloads;
 }
+/**
+ * Reads a `<collection>` node and returns the right
+ * {@link AppStateCollectionState} (success / has-more / conflict / fatal /
+ * retryable) based on its `type` attribute and embedded error code.
+ */
 export function parseCollectionState(node) {
     const type = node.attrs.type;
     const hasMorePatches = node.attrs.has_more_patches === 'true';
@@ -71,7 +81,9 @@ export function parseCollectionState(node) {
             : WA_APP_STATE_COLLECTION_STATES.CONFLICT;
     }
     if (code === WA_APP_STATE_ERROR_CODES.BAD_REQUEST ||
-        code === WA_APP_STATE_ERROR_CODES.NOT_FOUND) {
+        code === WA_APP_STATE_ERROR_CODES.NOT_FOUND ||
+        code === WA_APP_STATE_ERROR_CODES.NOT_ALLOWED ||
+        code === WA_APP_STATE_ERROR_CODES.NOT_ACCEPTABLE) {
         return WA_APP_STATE_COLLECTION_STATES.ERROR_FATAL;
     }
     return WA_APP_STATE_COLLECTION_STATES.ERROR_RETRY;