zapo-js 0.2.0 → 1.0.0

package/dist/appstate/{WaAppStateSyncClient.js → sync/WaAppStateSyncClient.js}

@@ -1,16 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WaAppStateSyncClient = exports.WaAppStateMissingKeyError = void 0;
-const constants_1 = require("./constants");
-const WaAppStateCrypto_1 = require("./WaAppStateCrypto");
-const WaAppStateSyncResponseParser_1 = require("./WaAppStateSyncResponseParser");
-const _proto_1 = require("../proto.js");
-const constants_2 = require("../protocol/constants");
-const jid_1 = require("../protocol/jid");
-const query_1 = require("../transport/node/query");
-const bytes_1 = require("../util/bytes");
-const bytes_2 = require("../util/bytes");
-const primitives_1 = require("../util/primitives");
+exports.WaAppStateSyncClient = void 0;
+const constants_1 = require("../constants");
+const WaAppStateCrypto_1 = require("../crypto/WaAppStateCrypto");
+const response_parser_1 = require("../parsers/response-parser");
+const _crypto_1 = require("../../crypto/index.js");
+const _proto_1 = require("../../proto.js");
+const constants_2 = require("../../protocol/constants");
+const jid_1 = require("../../protocol/jid");
+const query_1 = require("../../transport/node/query");
+const bytes_1 = require("../../util/bytes");
+const primitives_1 = require("../../util/primitives");
 class WaAppStateMissingKeyError extends Error {
     constructor(message, keyId, collection) {
         super(message);
@@ -19,24 +19,56 @@ class WaAppStateMissingKeyError extends Error {
         this.name = 'WaAppStateMissingKeyError';
     }
 }
-exports.WaAppStateMissingKeyError = WaAppStateMissingKeyError;
+/**
+ * App-state synchronization client. Owns the sync key inventory, processes
+ * snapshots/patches, encrypts pending mutations, and persists the resulting
+ * collection state in the {@link WaAppStateStore}.
+ */
 class WaAppStateSyncClient {
     constructor(options) {
         this.logger = options.logger;
         this.query = options.query;
         this.store = options.store;
+        this.serverClock = options.serverClock;
         this.getCurrentMeJid = options.getCurrentMeJid;
         this.hostDomain = options.hostDomain ?? constants_2.WA_DEFAULTS.HOST_DOMAIN;
         this.defaultTimeoutMs = options.defaultTimeoutMs ?? constants_2.WA_DEFAULTS.APP_STATE_SYNC_TIMEOUT_MS;
         this.onMissingKeys = options.onMissingKeys;
-        this.crypto = new WaAppStateCrypto_1.WaAppStateCrypto();
+        this.isOwnAccountDevice = options.isOwnAccountDevice;
+        this.sendKeyShare = options.sendKeyShare;
+        this.triggerSync = options.triggerSync;
+        this.crypto = new WaAppStateCrypto_1.WaAppStateCrypto(undefined, options.skipMacVerification === true);
+        this.mobilePrimary = options.mobilePrimary ?? false;
         this.syncContext = null;
         this.syncPromise = null;
     }
-    async exportState() {
-        this.logger.trace('app-state export requested');
-        return this.store.exportData();
+    /**
+     * Returns the active app-state sync key, generating and persisting a new
+     * one when the store is empty (used during initial setup).
+     */
+    async ensureInitialSyncKey() {
+        const existing = await this.store.getActiveSyncKey();
+        if (existing) {
+            return existing;
+        }
+        const keyIdBytes = await (0, _crypto_1.randomBytesAsync)(2);
+        const keyData = await (0, _crypto_1.randomBytesAsync)(32);
+        const rawId = await (0, _crypto_1.randomIntAsync)(0, 4294967295);
+        const key = {
+            keyId: keyIdBytes,
+            keyData,
+            timestamp: this.serverClock.nowMs(),
+            fingerprint: { rawId, currentIndex: 0, deviceIndexes: [0] }
+        };
+        await this.store.upsertSyncKeys([key]);
+        this.crypto.clearCache();
+        this.logger.info('app-state initial sync key generated (mobile primary)', {
+            keyId: (0, bytes_1.bytesToHex)(keyIdBytes),
+            rawId
+        });
+        return key;
     }
+    /** Imports peer-shared sync keys into the store; returns the count actually added. */
     async importSyncKeys(keys) {
         this.logger.debug('app-state importing sync keys', { count: keys.length });
         const inserted = await this.store.upsertSyncKeys(keys);
@@ -46,13 +78,126 @@ class WaAppStateSyncClient {
         }
         return inserted;
     }
+    /** Handler for `AppStateSyncKeyShare` protocol messages – stores received keys and triggers a sync. */
+    async handleIncomingKeyShare(context, protocolMessage) {
+        const log = this.logger.child({ id: context.id, from: context.remoteJid });
+        const share = protocolMessage.appStateSyncKeyShare;
+        if (!share) {
+            log.warn('incoming app-state key share protocol message without payload');
+            return;
+        }
+        try {
+            const imported = await this.importSyncKeyShare(share);
+            log.info('imported app-state sync key share from protocol message', { imported });
+            if (imported > 0 && this.triggerSync) {
+                void this.triggerSync().catch((error) => {
+                    log.warn('failed to sync app-state after key share import', {
+                        message: (0, primitives_1.toError)(error).message
+                    });
+                });
+            }
+        }
+        catch (error) {
+            log.warn('failed to import app-state sync key share from protocol message', {
+                message: (0, primitives_1.toError)(error).message
+            });
+        }
+    }
+    /** Handler for `AppStateSyncKeyRequest` protocol messages – replies with the requested keys via `sendKeyShare`. */
+    async handleIncomingKeyRequest(context, protocolMessage) {
+        const log = this.logger.child({ id: context.id, from: context.remoteJid });
+        const request = protocolMessage.appStateSyncKeyRequest;
+        if (!request) {
+            log.warn('incoming app-state key request protocol message without payload');
+            return;
+        }
+        const senderJid = context.participant ?? context.remoteJid;
+        if (!senderJid) {
+            log.warn('incoming app-state key request missing sender jid');
+            return;
+        }
+        let requesterDeviceJid;
+        try {
+            const requesterRaw = (0, jid_1.applyDeviceToJid)(senderJid, context.senderDevice);
+            requesterDeviceJid = (0, jid_1.normalizeDeviceJid)(requesterRaw);
+        }
+        catch (error) {
+            log.warn('incoming app-state key request has malformed sender jid', {
+                senderJid,
+                message: (0, primitives_1.toError)(error).message
+            });
+            return;
+        }
+        const deviceLog = log.child({ to: requesterDeviceJid });
+        if (this.isOwnAccountDevice && !this.isOwnAccountDevice(requesterDeviceJid)) {
+            deviceLog.warn('incoming app-state key request ignored: sender is not own account');
+            return;
+        }
+        const requestedKeyIds = this.extractKeyRequestIds(request);
+        if (requestedKeyIds.length === 0) {
+            deviceLog.warn('incoming app-state key request has no valid key ids');
+            return;
+        }
+        if (!this.sendKeyShare) {
+            deviceLog.warn('incoming app-state key request received but no sendKeyShare wired');
+            return;
+        }
+        const requestedKeys = await this.store.getSyncKeysBatch(requestedKeyIds);
+        const availableKeys = [];
+        const missingKeyIds = [];
+        for (let i = 0; i < requestedKeys.length; i += 1) {
+            const key = requestedKeys[i];
+            if (key !== null) {
+                availableKeys.push(key);
+            }
+            else {
+                missingKeyIds.push(requestedKeyIds[i]);
+            }
+        }
+        try {
+            await this.sendKeyShare(requesterDeviceJid, availableKeys, missingKeyIds);
+            deviceLog.info('responded to app-state key request', {
+                requested: requestedKeyIds.length,
+                shared: availableKeys.length,
+                missing: missingKeyIds.length
+            });
+        }
+        catch (error) {
+            deviceLog.warn('failed to respond to app-state key request', {
+                requested: requestedKeyIds.length,
+                shared: availableKeys.length,
+                missing: missingKeyIds.length,
+                message: (0, primitives_1.toError)(error).message
+            });
+        }
+    }
+    extractKeyRequestIds(request) {
+        const deduped = new Map();
+        for (const key of request.keyIds ?? []) {
+            try {
+                const keyId = (0, bytes_1.decodeProtoBytes)(key.keyId, 'appStateSyncKeyRequest.keyIds[].keyId');
+                const keyHex = (0, bytes_1.bytesToHex)(keyId);
+                if (deduped.has(keyHex)) {
+                    continue;
+                }
+                deduped.set(keyHex, keyId);
+            }
+            catch (error) {
+                this.logger.trace('ignoring malformed app-state key id request entry', {
+                    message: (0, primitives_1.toError)(error).message
+                });
+            }
+        }
+        return [...deduped.values()];
+    }
+    /** Imports the keys from a decoded `AppStateSyncKeyShare` proto message. */
     async importSyncKeyShare(share) {
         const keys = [];
         for (const item of share.keys ?? []) {
             const keyId = (0, bytes_1.decodeProtoBytes)(item.keyId?.keyId, 'appStateSyncKeyShare.keys[].keyId.keyId');
             if (!item.keyData?.keyData) {
                 this.logger.debug('app-state sync key share entry missing key data', {
-                    keyId: (0, bytes_2.bytesToHex)(keyId)
+                    keyId: (0, bytes_1.bytesToHex)(keyId)
                 });
                 continue;
             }
@@ -61,13 +206,19 @@ class WaAppStateSyncClient {
                 keyId,
                 keyData,
                 timestamp: item.keyData?.timestamp === null || item.keyData?.timestamp === undefined
-                    ? Date.now()
+                    ? this.serverClock.nowMs()
                     : this.normalizeProtoLong(item.keyData?.timestamp, 'appStateSyncKeyShare.keys[].keyData.timestamp'),
                 fingerprint: item.keyData?.fingerprint ?? undefined
             });
         }
         return this.importSyncKeys(keys);
     }
+    /**
+     * Runs one app-state sync round across the requested collections,
+     * applying any `pendingMutations` and downloading external snapshots
+     * via `options.downloadExternalBlob` when present. Concurrent calls
+     * share the in-flight promise.
+     */
     async sync(options = {}) {
         if (this.syncPromise) {
             this.logger.debug('app-state sync already in flight, joining existing run');
@@ -99,7 +250,7 @@ class WaAppStateSyncClient {
             for (let index = 0; index < collections.length; index += 1) {
                 context.collections.set(collections[index], initialCollectionStates[index]);
             }
-            this.logger.info('app-state sync start', {
+            this.logger.debug('app-state sync start', {
                 collections: collections.length,
                 pendingMutations: options.pendingMutations?.length ?? 0
             });
@@ -149,13 +300,13 @@ class WaAppStateSyncClient {
             }
             if (stateChanged && context.dirtyCollections.size > 0) {
                 await this.persistCollectionUpdates();
-                this.logger.info('app-state sync persisted updated state');
+                this.logger.debug('app-state sync persisted updated state');
             }
             const orderedResults = collections.map((collection) => resultMap.get(collection) ?? {
                 collection,
                 state: constants_2.WA_APP_STATE_COLLECTION_STATES.ERROR_RETRY
             });
-            this.logger.info('app-state sync finished', {
+            this.logger.debug('app-state sync finished', {
                 collections: orderedResults.length,
                 stateChanged
             });
@@ -220,7 +371,7 @@ class WaAppStateSyncClient {
                 blockedCollections.push(entry.collection);
             }
             if (entry.missingKeyId) {
-                const keyHex = (0, bytes_2.bytesToHex)(entry.missingKeyId);
+                const keyHex = (0, bytes_1.bytesToHex)(entry.missingKeyId);
                 if (!missingKeyIdHexes.has(keyHex)) {
                     missingKeyIdHexes.add(keyHex);
                     missingKeyIds.push(entry.missingKeyId);
@@ -287,7 +438,7 @@ class WaAppStateSyncClient {
             content: [
                 {
                     tag: constants_2.WA_NODE_TAGS.SYNC,
-                    attrs: {},
+                    attrs: this.mobilePrimary ? { data_namespace: '3' } : {},
                     content: collectionNodes
                 }
             ]
@@ -300,7 +451,7 @@ class WaAppStateSyncClient {
             type: responseNode.attrs.type
         });
         (0, query_1.assertIqResult)(responseNode, 'app-state sync');
-        const payloads = (0, WaAppStateSyncResponseParser_1.parseSyncResponse)(responseNode);
+        const payloads = (0, response_parser_1.parseSyncResponse)(responseNode);
         this.logger.debug('app-state sync payloads parsed', { count: payloads.length });
         const payloadByCollection = new Map();
         for (const payload of payloads) {
@@ -309,11 +460,12 @@ class WaAppStateSyncClient {
         return payloadByCollection;
     }
     async processCollectionRound({ collection, payloadByCollection, pendingByCollection, options, outgoingContexts, skippedUploadCollections }) {
+        const collectionLogger = this.logger.child({ collection });
         const payload = payloadByCollection.get(collection);
         let shouldRefetch = false;
         let collectionStateChanged = false;
         if (!payload) {
-            this.logger.warn('app-state sync response missing collection payload', { collection });
+            collectionLogger.warn('app-state sync response missing collection payload');
             return this.createCollectionOutcome(collection, constants_2.WA_APP_STATE_COLLECTION_STATES.ERROR_RETRY);
         }
         if (payload.state === constants_2.WA_APP_STATE_COLLECTION_STATES.ERROR_FATAL ||
@@ -373,8 +525,7 @@ class WaAppStateSyncClient {
                     payload.state === constants_2.WA_APP_STATE_COLLECTION_STATES.SUCCESS_HAS_MORE ||
                     (payload.state === constants_2.WA_APP_STATE_COLLECTION_STATES.SUCCESS &&
                         skippedUploadCollections.has(collection));
-            this.logger.debug('app-state collection processed', {
-                collection: payload.collection,
+            collectionLogger.debug('app-state collection processed', {
                 state: payload.state,
                 version: payload.version,
                 appliedMutations: appliedMutations.length
@@ -383,16 +534,13 @@ class WaAppStateSyncClient {
         }
         catch (error) {
             if (error instanceof WaAppStateMissingKeyError) {
-                this.logger.warn('app-state blocked by missing key', {
-                    collection: payload.collection,
+                collectionLogger.debug('app-state blocked by missing key', {
                     message: error.message
                 });
                 return this.createCollectionOutcome(collection, constants_2.WA_APP_STATE_COLLECTION_STATES.BLOCKED, payload.version, shouldRefetch, collectionStateChanged, undefined, error.keyId);
             }
-            const message = error instanceof Error ? error.message : String(error);
-            this.logger.warn('app-state collection processing failed', {
-                collection: payload.collection,
-                message
+            collectionLogger.debug('app-state collection processing failed', {
+                message: (0, primitives_1.toError)(error).message
             });
             return this.createCollectionOutcome(collection, constants_2.WA_APP_STATE_COLLECTION_STATES.ERROR_RETRY, payload.version, true, collectionStateChanged);
         }
@@ -417,12 +565,14 @@ class WaAppStateSyncClient {
         if (keyIds.length === 0 || collections.length === 0) {
             return;
         }
-        const keyIdsHex = keyIds.map((keyId) => (0, bytes_2.bytesToHex)(keyId));
-        this.logger.info('app-state requesting missing sync keys', {
+        const keyIdsHex = keyIds.map((keyId) => (0, bytes_1.bytesToHex)(keyId));
+        const requestLogger = this.logger.child({
             keys: keyIdsHex.length,
-            keyIds: keyIdsHex.join(','),
             collections: collections.join(',')
         });
+        requestLogger.debug('app-state requesting missing sync keys', {
+            keyIds: keyIdsHex.join(',')
+        });
         try {
             await input.onMissingKeys({
                 keyIds,
@@ -430,10 +580,8 @@ class WaAppStateSyncClient {
             });
         }
         catch (error) {
-            this.logger.warn('app-state missing key callback failed', {
-                keys: keyIdsHex.length,
-                collections: collections.join(','),
-                message: error instanceof Error ? error.message : String(error)
+            requestLogger.warn('app-state missing key callback failed', {
+                message: (0, primitives_1.toError)(error).message
             });
         }
     }
@@ -456,7 +604,8 @@ class WaAppStateSyncClient {
                 const decodedMutations = _proto_1.proto.SyncdMutations.decode(patchBytes);
                 readyPatch = {
                     ...readyPatch,
-                    mutations: decodedMutations.mutations ?? []
+                    mutations: decodedMutations.mutations ?? [],
+                    externalMutations: undefined
                 };
             }
             return this.validatePatch(payload.collection, readyPatch);
@@ -466,11 +615,13 @@ class WaAppStateSyncClient {
         if (!snapshot.version?.version) {
             throw new Error(`snapshot for ${collection} is missing version`);
         }
-        if (!snapshot.mac) {
-            throw new Error(`snapshot for ${collection} is missing mac`);
-        }
-        if (!snapshot.keyId?.id) {
-            throw new Error(`snapshot for ${collection} is missing keyId`);
+        if (!this.crypto.isMacVerificationSkipped) {
+            if (!snapshot.mac) {
+                throw new Error(`snapshot for ${collection} is missing mac`);
+            }
+            if (!snapshot.keyId?.id) {
+                throw new Error(`snapshot for ${collection} is missing keyId`);
+            }
         }
         return snapshot;
     }
@@ -485,14 +636,16 @@ class WaAppStateSyncClient {
         if (!patch.version?.version) {
             throw new Error(`patch for ${collection} is missing version`);
         }
-        if (!patch.snapshotMac) {
-            throw new Error(`patch for ${collection} is missing snapshotMac`);
-        }
-        if (!patch.patchMac) {
-            throw new Error(`patch for ${collection} is missing patchMac`);
-        }
-        if (!patch.keyId?.id) {
-            throw new Error(`patch for ${collection} is missing keyId`);
+        if (!this.crypto.isMacVerificationSkipped) {
+            if (!patch.snapshotMac) {
+                throw new Error(`patch for ${collection} is missing snapshotMac`);
+            }
+            if (!patch.patchMac) {
+                throw new Error(`patch for ${collection} is missing patchMac`);
+            }
+            if (!patch.keyId?.id) {
+                throw new Error(`patch for ${collection} is missing keyId`);
+            }
         }
         if (patch.mutations && patch.mutations.length > 0 && patch.externalMutations) {
             throw new Error(`patch for ${collection} has inline and external mutations together`);
@@ -506,16 +659,19 @@ class WaAppStateSyncClient {
     }
     async applySnapshot(collection, snapshot) {
         const version = this.normalizeProtoLong(snapshot.version?.version, `snapshot.version.version (${collection})`);
-        const keyId = (0, bytes_1.decodeProtoBytes)(snapshot.keyId?.id, `snapshot.keyId.id (${collection})`);
-        const keyData = await this.getKeyData(keyId);
-        if (!keyData) {
-            throw new WaAppStateMissingKeyError(`missing snapshot key ${(0, bytes_2.bytesToHex)(keyId)} for ${collection}`, keyId, collection);
+        let keyData = null;
+        if (!this.crypto.isMacVerificationSkipped) {
+            const keyId = (0, bytes_1.decodeProtoBytes)(snapshot.keyId?.id, `snapshot.keyId.id (${collection})`);
+            keyData = await this.getKeyData(keyId);
+            if (!keyData) {
+                throw new WaAppStateMissingKeyError(`missing snapshot key ${(0, bytes_1.bytesToHex)(keyId)} for ${collection}`, keyId, collection);
+            }
         }
         const indexValueMap = new Map();
         const mutations = [];
         const decryptedRecords = await this.decryptSnapshotRecords(collection, snapshot);
         for (const { decrypted, recordKeyId } of decryptedRecords) {
-            const indexMacHex = (0, bytes_2.bytesToHex)(decrypted.indexMac);
+            const indexMacHex = (0, bytes_1.bytesToHex)(decrypted.indexMac);
             indexValueMap.set(indexMacHex, decrypted.valueMac);
             mutations.push({
                 collection,
@@ -537,9 +693,11 @@ class WaAppStateSyncClient {
             ltHashInputIndex += 1;
         }
         const ltHash = await this.crypto.ltHashAdd(constants_1.APP_STATE_EMPTY_LT_HASH, ltHashInput);
-        const expectedSnapshotMac = await this.crypto.generateSnapshotMac(keyData, ltHash, version, collection);
-        if (!(0, bytes_2.uint8Equal)(expectedSnapshotMac, snapshot.mac)) {
-            throw new Error(`snapshot MAC mismatch for ${collection}`);
+        if (keyData !== null) {
+            const expectedSnapshotMac = await this.crypto.generateSnapshotMac(keyData, ltHash, version, collection);
+            if (!(0, bytes_1.uint8TimingSafeEqual)(expectedSnapshotMac, snapshot.mac)) {
+                throw new Error(`snapshot MAC mismatch for ${collection}`);
+            }
         }
         this.setCollectionState(collection, version, ltHash, indexValueMap);
         return mutations;
@@ -550,10 +708,13 @@ class WaAppStateSyncClient {
         if (current.version !== patchVersion - 1) {
             throw new Error(`patch version mismatch for ${collection}: local=${current.version}, incoming=${patchVersion}`);
         }
-        const patchKeyId = (0, bytes_1.decodeProtoBytes)(patch.keyId?.id, `patch.keyId.id (${collection})`);
-        const patchKeyData = await this.getKeyData(patchKeyId);
-        if (!patchKeyData) {
-            throw new WaAppStateMissingKeyError(`missing patch key ${(0, bytes_2.bytesToHex)(patchKeyId)} for ${collection}`, patchKeyId, collection);
+        let patchKeyData = null;
+        if (!this.crypto.isMacVerificationSkipped) {
+            const patchKeyId = (0, bytes_1.decodeProtoBytes)(patch.keyId?.id, `patch.keyId.id (${collection})`);
+            patchKeyData = await this.getKeyData(patchKeyId);
+            if (!patchKeyData) {
+                throw new WaAppStateMissingKeyError(`missing patch key ${(0, bytes_1.bytesToHex)(patchKeyId)} for ${collection}`, patchKeyId, collection);
+            }
         }
         const decryptedMutations = await this.decryptPatchMutations(collection, patch);
         const macMutations = new Array(decryptedMutations.length);
@@ -568,7 +729,9 @@ class WaAppStateSyncClient {
             };
         }
         const nextState = await this.computeNextCollectionState(current.hash, current.indexValueMap, macMutations, collection);
-        await this.assertPatchMacsMatch(patch, collection, patchKeyData, patchVersion, nextState.hash, valueMacs);
+        if (patchKeyData !== null) {
+            await this.assertPatchMacsMatch(patch, collection, patchKeyData, patchVersion, nextState.hash, valueMacs);
+        }
         this.setCollectionState(collection, patchVersion, nextState.hash, nextState.indexValueMap);
         return decryptedMutations;
     }
@@ -593,7 +756,7 @@ class WaAppStateSyncClient {
             decryptTasks[i] = (async () => {
                 const recordKeyData = await this.getKeyData(recordKeyId);
                 if (!recordKeyData) {
-                    throw new WaAppStateMissingKeyError(`missing snapshot mutation key ${(0, bytes_2.bytesToHex)(recordKeyId)} for ${collection}`, recordKeyId, collection);
+                    throw new WaAppStateMissingKeyError(`missing snapshot mutation key ${(0, bytes_1.bytesToHex)(recordKeyId)} for ${collection}`, recordKeyId, collection);
                 }
                 const decrypted = await this.crypto.decryptMutation({
                     operation: _proto_1.proto.SyncdMutation.SyncdOperation.SET,
@@ -640,7 +803,7 @@ class WaAppStateSyncClient {
             decryptTasks[i] = (async () => {
                 const recordKeyData = await this.getKeyData(recordKeyId);
                 if (!recordKeyData) {
-                    throw new WaAppStateMissingKeyError(`missing mutation key ${(0, bytes_2.bytesToHex)(recordKeyId)} for ${collection}`, recordKeyId, collection);
+                    throw new WaAppStateMissingKeyError(`missing mutation key ${(0, bytes_1.bytesToHex)(recordKeyId)} for ${collection}`, recordKeyId, collection);
                 }
                 const decrypted = await this.crypto.decryptMutation({
                     operation: operationCode,
@@ -671,12 +834,16 @@ class WaAppStateSyncClient {
     async assertPatchMacsMatch(patch, collection, patchKeyData, patchVersion, nextHash, valueMacs) {
         const snapshotMac = (0, bytes_1.decodeProtoBytes)(patch.snapshotMac, `patch.snapshotMac (${collection})`);
         const expectedSnapshotMac = await this.crypto.generateSnapshotMac(patchKeyData, nextHash, patchVersion, collection);
-        if (!(0, bytes_2.uint8Equal)(expectedSnapshotMac, snapshotMac)) {
-            throw new Error(`patch snapshot MAC mismatch for ${collection}`);
+        // non-fatal: wa-mob/wa-web tolerate this – patchMac below covers payload integrity.
+        if (!(0, bytes_1.uint8TimingSafeEqual)(expectedSnapshotMac, snapshotMac)) {
+            this.logger.debug('patch snapshot MAC mismatch (tolerated)', {
+                collection,
+                patchVersion
+            });
         }
         const patchMac = (0, bytes_1.decodeProtoBytes)(patch.patchMac, `patch.patchMac (${collection})`);
         const expectedPatchMac = await this.crypto.generatePatchMac(patchKeyData, snapshotMac, valueMacs, patchVersion, collection);
-        if (!(0, bytes_2.uint8Equal)(expectedPatchMac, patchMac)) {
+        if (!(0, bytes_1.uint8TimingSafeEqual)(expectedPatchMac, patchMac)) {
             throw new Error(`patch MAC mismatch for ${collection}`);
         }
     }
@@ -685,7 +852,7 @@ class WaAppStateSyncClient {
             throw new WaAppStateMissingKeyError(`no sync key available to upload ${collection}`, null, collection);
         }
         const encryptedResults = await Promise.all(pendingMutations.map(async (mutation) => {
-            const value = mutation.operation === 'set' ? mutation.value : mutation.previousValue;
+            const value = mutation.operation === 'set' ? mutation.value : null;
             const operationCode = mutation.operation === 'remove'
                 ? _proto_1.proto.SyncdMutation.SyncdOperation.REMOVE
                 : _proto_1.proto.SyncdMutation.SyncdOperation.SET;
@@ -724,14 +891,12 @@ class WaAppStateSyncClient {
         const snapshotMac = await this.crypto.generateSnapshotMac(activeKey.keyData, nextState.hash, patchVersion, collection);
         const patchMac = await this.crypto.generatePatchMac(activeKey.keyData, snapshotMac, valueMacs, patchVersion, collection);
         const deviceIndex = this.resolveDeviceIndex();
-        const clientDebugData = this.buildPatchClientDebugData();
         const encodedPatch = _proto_1.proto.SyncdPatch.encode({
             mutations: encryptedMutations,
             snapshotMac,
             patchMac,
             keyId: { id: activeKey.keyId },
-            ...(deviceIndex === undefined ? {} : { deviceIndex }),
-            clientDebugData
+            ...(deviceIndex === undefined ? {} : { deviceIndex })
         }).finish();
         return {
             encodedPatch,
@@ -759,19 +924,13 @@ class WaAppStateSyncClient {
             return undefined;
         }
     }
-    buildPatchClientDebugData() {
-        return _proto_1.proto.PatchDebugData.encode({
-            isSenderPrimary: false,
-            senderPlatform: _proto_1.proto.PatchDebugData.Platform.WEB
-        }).finish();
-    }
     async computeNextCollectionState(baseHash, baseMap, mutations, collection) {
         const indexValueMap = new Map(baseMap);
         const addValues = [];
         const removeValues = [];
         let missingRemoveCount = 0;
         for (const mutation of mutations) {
-            const indexMacHex = (0, bytes_2.bytesToHex)(mutation.indexMac);
+            const indexMacHex = (0, bytes_1.bytesToHex)(mutation.indexMac);
             const existing = indexValueMap.get(indexMacHex);
             if (mutation.operation === _proto_1.proto.SyncdMutation.SyncdOperation.REMOVE) {
                 if (!existing) {
@@ -805,8 +964,7 @@ class WaAppStateSyncClient {
             return (0, primitives_1.longToNumber)(value);
         }
         catch (error) {
-            const reason = error instanceof Error ? error.message : String(error);
-            throw new Error(`invalid ${field}: ${reason}`);
+            throw new Error(`invalid ${field}: ${(0, primitives_1.toError)(error).message}`);
         }
     }
     groupPendingMutations(pendingMutations) {
@@ -845,7 +1003,7 @@ class WaAppStateSyncClient {
         const missingKeyHexes = new Set();
         for (let index = 0; index < keyIds.length; index += 1) {
             const keyId = keyIds[index];
-            const keyHex = (0, bytes_2.bytesToHex)(keyId);
+            const keyHex = (0, bytes_1.bytesToHex)(keyId);
             if (context.keys.has(keyHex) || missingKeyHexes.has(keyHex)) {
                 continue;
             }
@@ -857,12 +1015,12 @@ class WaAppStateSyncClient {
         }
         const loadedKeyData = await this.store.getSyncKeyDataBatch(missingKeyIds);
         for (let index = 0; index < missingKeyIds.length; index += 1) {
-            context.keys.set((0, bytes_2.bytesToHex)(missingKeyIds[index]), loadedKeyData[index] ?? null);
+            context.keys.set((0, bytes_1.bytesToHex)(missingKeyIds[index]), loadedKeyData[index] ?? null);
         }
     }
     async getKeyData(keyId) {
         const context = this.requireSyncContext();
-        const keyHex = (0, bytes_2.bytesToHex)(keyId);
+        const keyHex = (0, bytes_1.bytesToHex)(keyId);
         if (context.keys.has(keyHex)) {
             return context.keys.get(keyHex) ?? null;
         }

package/dist/appstate/utils.js

@@ -7,17 +7,29 @@ exports.downloadExternalBlobReference = downloadExternalBlobReference;
 const constants_1 = require("../protocol/constants");
 const bytes_1 = require("../util/bytes");
 const APP_STATE_COLLECTION_NAMES = new Set(Object.values(constants_1.WA_APP_STATE_COLLECTIONS));
+/**
+ * Returns `value` typed as a known {@link AppStateCollectionName}, or `null`
+ * when the string is unrecognized.
+ */
 function parseCollectionName(value) {
     return value && APP_STATE_COLLECTION_NAMES.has(value) ? value : null;
 }
 function keyDeviceId(keyId) {
     return keyId.byteLength < 6 ? null : (keyId[0] << 8) | keyId[1];
 }
+/**
+ * Reads the 32-bit big-endian epoch encoded in bytes 2..5 of an app-state key id.
+ * Returns `-1` when the key id is too short.
+ */
 function keyEpoch(keyId) {
     return keyId.byteLength < 6
         ? -1
         : keyId[2] * 16777216 + keyId[3] * 65536 + keyId[4] * 256 + keyId[5];
 }
+/**
+ * Picks the highest-epoch app-state sync key from `keys`. Ties are broken by
+ * the lower device id. Returns `null` when the iterable is empty.
+ */
 function pickActiveSyncKey(keys) {
     let active = null;
     for (const key of keys) {
@@ -42,6 +54,10 @@ function pickActiveSyncKey(keys) {
     }
     return active;
 }
+/**
+ * Downloads and decrypts an external app-state blob via the media transfer
+ * client. Throws when the reference is missing required fields.
+ */
 async function downloadExternalBlobReference(mediaTransfer, reference) {
     if (!reference.directPath) {
         throw new Error('external blob reference is missing directPath');