zapo-js 0.1.0

package/dist/esm/appstate/WaAppStateSyncClient.js

@@ -0,0 +1,803 @@
+import { APP_STATE_DEFAULT_COLLECTIONS, APP_STATE_EMPTY_LT_HASH } from './constants.js';
+import { keyIdToHex } from './utils.js';
+import { WaAppStateCrypto } from './WaAppStateCrypto.js';
+import { parseSyncResponse } from './WaAppStateSyncResponseParser.js';
+import { proto } from '../proto.js';
+import { WA_APP_STATE_COLLECTION_STATES, WA_DEFAULTS, WA_IQ_TYPES, WA_NODE_TAGS, WA_XMLNS } from '../protocol/constants.js';
+import { decodeProtoBytes } from '../util/base64.js';
+import { uint8Equal } from '../util/bytes.js';
+import { longToNumber } from '../util/primitives.js';
+export class WaAppStateMissingKeyError extends Error {
+    constructor(message, keyId, collection) {
+        super(message);
+        this.keyId = keyId;
+        this.collection = collection;
+        this.name = 'WaAppStateMissingKeyError';
+    }
+}
+export class WaAppStateSyncClient {
+    constructor(options) {
+        this.logger = options.logger;
+        this.query = options.query;
+        this.store = options.store;
+        this.hostDomain = options.hostDomain ?? WA_DEFAULTS.HOST_DOMAIN;
+        this.defaultTimeoutMs = options.defaultTimeoutMs ?? WA_DEFAULTS.APP_STATE_SYNC_TIMEOUT_MS;
+        this.onMissingKeys = options.onMissingKeys;
+        this.crypto = new WaAppStateCrypto();
+        this.syncContext = null;
+        this.syncPromise = null;
+    }
+    async exportState() {
+        this.logger.trace('app-state export requested');
+        return this.store.exportData();
+    }
+    async importSyncKeys(keys) {
+        this.logger.debug('app-state importing sync keys', { count: keys.length });
+        const inserted = await this.store.upsertSyncKeys(keys);
+        if (inserted > 0) {
+            this.crypto.clearCache();
+            this.logger.info('app-state sync keys persisted', { inserted });
+        }
+        return inserted;
+    }
+    async importSyncKeyShare(share) {
+        const keys = [];
+        for (const item of share.keys ?? []) {
+            const keyId = 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: keyIdToHex(keyId)
+                });
+                continue;
+            }
+            const keyData = decodeProtoBytes(item.keyData?.keyData, 'appStateSyncKeyShare.keys[].keyData.keyData');
+            keys.push({
+                keyId,
+                keyData,
+                timestamp: item.keyData?.timestamp === null || item.keyData?.timestamp === undefined
+                    ? Date.now()
+                    : this.normalizeProtoLong(item.keyData?.timestamp, 'appStateSyncKeyShare.keys[].keyData.timestamp'),
+                fingerprint: item.keyData?.fingerprint ?? undefined
+            });
+        }
+        return this.importSyncKeys(keys);
+    }
+    async sync(options = {}) {
+        if (this.syncPromise) {
+            this.logger.debug('app-state sync already in flight, joining existing run');
+            return this.syncPromise;
+        }
+        const inFlight = this.syncOnce(options);
+        this.syncPromise = inFlight;
+        try {
+            return await inFlight;
+        }
+        finally {
+            if (this.syncPromise === inFlight) {
+                this.syncPromise = null;
+            }
+        }
+    }
+    async syncOnce(options = {}) {
+        const context = {
+            keys: new Map(),
+            collections: new Map(),
+            dirtyCollections: new Set()
+        };
+        this.syncContext = context;
+        const collections = [
+            ...new Set(options.collections ?? APP_STATE_DEFAULT_COLLECTIONS)
+        ];
+        try {
+            this.logger.info('app-state sync start', {
+                collections: collections.length,
+                pendingMutations: options.pendingMutations?.length ?? 0
+            });
+            const pendingByCollection = this.groupPendingMutations(options.pendingMutations ?? []);
+            const resultMap = new Map();
+            let stateChanged = false;
+            let collectionsToSync = [...collections];
+            const missingKeysHandler = options.onMissingKeys ?? this.onMissingKeys;
+            const maxSyncIterations = 5;
+            let syncIteration = 0;
+            while (collectionsToSync.length > 0) {
+                syncIteration += 1;
+                if (syncIteration > maxSyncIterations) {
+                    this.logger.warn('app-state sync reached max iterations', {
+                        maxSyncIterations,
+                        remainingCollections: collectionsToSync
+                    });
+                    for (const collection of collectionsToSync) {
+                        resultMap.set(collection, {
+                            collection,
+                            state: WA_APP_STATE_COLLECTION_STATES.ERROR_RETRY
+                        });
+                    }
+                    break;
+                }
+                const round = await this.syncCollectionsRound(collectionsToSync, pendingByCollection, options);
+                stateChanged = stateChanged || round.stateChanged;
+                for (const result of round.results) {
+                    resultMap.set(result.collection, result);
+                }
+                if (missingKeysHandler &&
+                    round.missingKeyIds.length > 0 &&
+                    round.blockedCollections.length > 0) {
+                    await this.notifyMissingKeys({
+                        onMissingKeys: missingKeysHandler,
+                        keyIds: round.missingKeyIds,
+                        collections: round.blockedCollections
+                    });
+                }
+                collectionsToSync = [...round.collectionsToRefetch];
+                if (collectionsToSync.length > 0) {
+                    this.logger.debug('app-state scheduling refetch for collections', {
+                        iteration: syncIteration,
+                        collections: collectionsToSync
+                    });
+                }
+            }
+            if (stateChanged && context.dirtyCollections.size > 0) {
+                await this.persistCollectionUpdates();
+                this.logger.info('app-state sync persisted updated state');
+            }
+            const orderedResults = collections.map((collection) => resultMap.get(collection) ?? {
+                collection,
+                state: WA_APP_STATE_COLLECTION_STATES.ERROR_RETRY
+            });
+            this.logger.info('app-state sync finished', {
+                collections: orderedResults.length,
+                stateChanged
+            });
+            return { collections: orderedResults };
+        }
+        finally {
+            if (this.syncContext === context) {
+                this.syncContext = null;
+            }
+        }
+    }
+    async syncCollectionsRound(collections, pendingByCollection, options) {
+        const prepared = await this.prepareSyncRoundRequest(collections, pendingByCollection);
+        const iqNode = this.buildSyncIqNode(prepared.collectionNodes);
+        const payloadByCollection = await this.fetchSyncPayloadByCollection(iqNode, options.timeoutMs ?? this.defaultTimeoutMs);
+        const collectionOutcomes = await Promise.all(collections.map((collection) => this.processCollectionRound({
+            collection,
+            payloadByCollection,
+            pendingByCollection,
+            options,
+            outgoingContexts: prepared.outgoingContexts,
+            skippedUploadCollections: prepared.skippedUploadCollections
+        })));
+        return {
+            results: collectionOutcomes.map((entry) => entry.result),
+            collectionsToRefetch: collectionOutcomes
+                .filter((entry) => entry.shouldRefetch)
+                .map((entry) => entry.collection),
+            stateChanged: collectionOutcomes.some((entry) => entry.stateChanged),
+            missingKeyIds: this.collectDistinctMissingKeyIds(collectionOutcomes
+                .map((entry) => entry.missingKeyId)
+                .filter((value) => value !== null)),
+            blockedCollections: collectionOutcomes
+                .filter((entry) => entry.result.state === WA_APP_STATE_COLLECTION_STATES.BLOCKED)
+                .map((entry) => entry.collection)
+        };
+    }
+    async prepareSyncRoundRequest(collections, pendingByCollection) {
+        const requests = await Promise.all(collections.map((collection) => this.buildCollectionSyncRequest(collection, pendingByCollection)));
+        const outgoingContexts = new Map();
+        const skippedUploadCollections = new Set();
+        for (const request of requests) {
+            if (request.outgoingContext) {
+                outgoingContexts.set(request.collection, request.outgoingContext);
+            }
+            if (request.skippedUpload) {
+                skippedUploadCollections.add(request.collection);
+            }
+        }
+        return {
+            collectionNodes: requests.map((request) => request.node),
+            outgoingContexts,
+            skippedUploadCollections
+        };
+    }
+    async buildCollectionSyncRequest(collection, pendingByCollection) {
+        const collectionState = await this.getCollectionState(collection);
+        const hasPersistedState = collectionState.version > 0 ||
+            collectionState.indexValueMap.size > 0 ||
+            !uint8Equal(collectionState.hash, APP_STATE_EMPTY_LT_HASH);
+        const attrs = {
+            name: collection
+        };
+        if (hasPersistedState) {
+            attrs.version = String(collectionState.version);
+        }
+        else {
+            attrs.return_snapshot = 'true';
+        }
+        const children = [];
+        const pendingMutations = pendingByCollection.get(collection) ?? [];
+        let outgoingContext;
+        let skippedUpload = false;
+        if (pendingMutations.length > 0) {
+            if (!hasPersistedState) {
+                skippedUpload = true;
+                this.logger.debug('app-state skipped outgoing patch upload until snapshot bootstrap', {
+                    collection,
+                    pendingMutations: pendingMutations.length
+                });
+            }
+            else {
+                const outgoing = await this.buildOutgoingPatch(collection, collectionState, pendingMutations);
+                outgoingContext = outgoing.context;
+                children.push({
+                    tag: WA_NODE_TAGS.PATCH,
+                    attrs: {},
+                    content: outgoing.encodedPatch
+                });
+            }
+        }
+        return {
+            collection,
+            outgoingContext,
+            skippedUpload,
+            node: {
+                tag: WA_NODE_TAGS.COLLECTION,
+                attrs,
+                content: children.length > 0 ? children : undefined
+            }
+        };
+    }
+    buildSyncIqNode(collectionNodes) {
+        return {
+            tag: WA_NODE_TAGS.IQ,
+            attrs: {
+                to: this.hostDomain,
+                type: WA_IQ_TYPES.SET,
+                xmlns: WA_XMLNS.APP_STATE_SYNC
+            },
+            content: [
+                {
+                    tag: WA_NODE_TAGS.SYNC,
+                    attrs: {},
+                    content: collectionNodes
+                }
+            ]
+        };
+    }
+    async fetchSyncPayloadByCollection(iqNode, timeoutMs) {
+        const responseNode = await this.query(iqNode, timeoutMs);
+        this.logger.debug('app-state sync iq response received', {
+            tag: responseNode.tag,
+            type: responseNode.attrs.type
+        });
+        const payloads = parseSyncResponse(responseNode);
+        this.logger.debug('app-state sync payloads parsed', { count: payloads.length });
+        const payloadByCollection = new Map();
+        for (const payload of payloads) {
+            payloadByCollection.set(payload.collection, payload);
+        }
+        return payloadByCollection;
+    }
+    async processCollectionRound({ collection, payloadByCollection, pendingByCollection, options, outgoingContexts, skippedUploadCollections }) {
+        const payload = payloadByCollection.get(collection);
+        let shouldRefetch = false;
+        let collectionStateChanged = false;
+        if (!payload) {
+            this.logger.warn('app-state sync response missing collection payload', { collection });
+            return this.createCollectionOutcome(collection, WA_APP_STATE_COLLECTION_STATES.ERROR_RETRY);
+        }
+        if (payload.state === WA_APP_STATE_COLLECTION_STATES.ERROR_FATAL ||
+            payload.state === WA_APP_STATE_COLLECTION_STATES.ERROR_RETRY) {
+            return this.createCollectionOutcome(collection, payload.state, payload.version);
+        }
+        const pendingMutationsCount = pendingByCollection.get(collection)?.length ?? 0;
+        if (payload.state === WA_APP_STATE_COLLECTION_STATES.CONFLICT_HAS_MORE) {
+            shouldRefetch = true;
+        }
+        else if (payload.state === WA_APP_STATE_COLLECTION_STATES.CONFLICT &&
+            pendingMutationsCount > 0) {
+            shouldRefetch = true;
+        }
+        if (payload.state === WA_APP_STATE_COLLECTION_STATES.CONFLICT) {
+            return this.createCollectionOutcome(collection, pendingMutationsCount > 0
+                ? WA_APP_STATE_COLLECTION_STATES.CONFLICT
+                : WA_APP_STATE_COLLECTION_STATES.SUCCESS, payload.version, shouldRefetch);
+        }
+        if (payload.state === WA_APP_STATE_COLLECTION_STATES.CONFLICT_HAS_MORE) {
+            return this.createCollectionOutcome(collection, payload.state, payload.version, shouldRefetch);
+        }
+        try {
+            let appliedMutations = [];
+            if (payload.snapshotReference) {
+                const downloader = options.downloadExternalBlob;
+                if (!downloader) {
+                    throw new Error(`snapshot for ${payload.collection} requires external blob downloader`);
+                }
+                const snapshotBytes = await downloader(payload.collection, 'snapshot', payload.snapshotReference);
+                const snapshot = this.validateSnapshot(payload.collection, proto.SyncdSnapshot.decode(snapshotBytes));
+                const snapshotMutations = await this.applySnapshot(payload.collection, snapshot);
+                appliedMutations = appliedMutations.concat(snapshotMutations);
+                collectionStateChanged = true;
+            }
+            if (payload.patches.length > 0) {
+                const readyPatches = await this.resolveReadyPatches(payload, options);
+                for (const readyPatch of readyPatches) {
+                    const patchMutations = await this.applyPatch(payload.collection, readyPatch);
+                    appliedMutations = appliedMutations.concat(patchMutations);
+                    collectionStateChanged = true;
+                }
+            }
+            else {
+                const outgoingContext = outgoingContexts.get(payload.collection);
+                if (outgoingContext &&
+                    payload.state === WA_APP_STATE_COLLECTION_STATES.SUCCESS &&
+                    payload.version === outgoingContext.patchVersion) {
+                    this.setCollectionState(payload.collection, outgoingContext.patchVersion, outgoingContext.nextHash, outgoingContext.nextIndexValueMap);
+                    collectionStateChanged = true;
+                }
+            }
+            if (payload.state === WA_APP_STATE_COLLECTION_STATES.SUCCESS_HAS_MORE) {
+                shouldRefetch = true;
+            }
+            if (payload.state === WA_APP_STATE_COLLECTION_STATES.SUCCESS &&
+                skippedUploadCollections.has(collection)) {
+                shouldRefetch = true;
+            }
+            this.logger.debug('app-state collection processed', {
+                collection: payload.collection,
+                state: payload.state,
+                version: payload.version,
+                appliedMutations: appliedMutations.length
+            });
+            return this.createCollectionOutcome(collection, payload.state, payload.version, shouldRefetch, collectionStateChanged, appliedMutations);
+        }
+        catch (error) {
+            if (error instanceof WaAppStateMissingKeyError) {
+                this.logger.warn('app-state blocked by missing key', {
+                    collection: payload.collection,
+                    message: error.message
+                });
+                return this.createCollectionOutcome(collection, 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
+            });
+            return this.createCollectionOutcome(collection, WA_APP_STATE_COLLECTION_STATES.ERROR_RETRY, payload.version, true, collectionStateChanged);
+        }
+    }
+    createCollectionOutcome(collection, state, version, shouldRefetch = false, stateChanged = false, mutations, missingKeyId = null) {
+        return {
+            collection,
+            shouldRefetch,
+            stateChanged,
+            missingKeyId,
+            result: {
+                collection,
+                state,
+                version,
+                ...(mutations ? { mutations } : {})
+            }
+        };
+    }
+    collectDistinctMissingKeyIds(keyIds) {
+        const byHex = new Map();
+        for (const keyId of keyIds) {
+            const keyHex = keyIdToHex(keyId);
+            if (byHex.has(keyHex)) {
+                continue;
+            }
+            byHex.set(keyHex, keyId);
+        }
+        return [...byHex.values()];
+    }
+    async notifyMissingKeys(input) {
+        const keyIds = this.collectDistinctMissingKeyIds(input.keyIds);
+        const collections = [...new Set(input.collections)];
+        if (keyIds.length === 0 || collections.length === 0) {
+            return;
+        }
+        const keyIdsHex = keyIds.map((keyId) => keyIdToHex(keyId));
+        this.logger.info('app-state requesting missing sync keys', {
+            keys: keyIdsHex.length,
+            keyIds: keyIdsHex.join(','),
+            collections: collections.join(',')
+        });
+        try {
+            await input.onMissingKeys({
+                keyIds,
+                collections
+            });
+        }
+        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)
+            });
+        }
+    }
+    async resolveReadyPatches(payload, options) {
+        const sortedPatches = payload.patches
+            .map((patch) => ({
+            patch,
+            sortVersion: this.parseCollectionPatchVersion(payload.collection, patch)
+        }))
+            .sort((left, right) => left.sortVersion - right.sortVersion)
+            .map((entry) => entry.patch);
+        return Promise.all(sortedPatches.map(async (patch) => {
+            let readyPatch = patch;
+            if ((!readyPatch.mutations || readyPatch.mutations.length === 0) &&
+                readyPatch.externalMutations) {
+                const downloader = options.downloadExternalBlob;
+                if (!downloader) {
+                    throw new Error(`external patch for ${payload.collection} requires external blob downloader`);
+                }
+                const patchBytes = await downloader(payload.collection, 'patch', readyPatch.externalMutations);
+                const decodedMutations = proto.SyncdMutations.decode(patchBytes);
+                readyPatch = {
+                    ...readyPatch,
+                    mutations: decodedMutations.mutations ?? []
+                };
+            }
+            return this.validatePatch(payload.collection, readyPatch);
+        }));
+    }
+    validateSnapshot(collection, snapshot) {
+        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`);
+        }
+        return snapshot;
+    }
+    parseCollectionPatchVersion(collection, patch) {
+        const parsed = this.normalizeProtoLong(patch.version?.version, `patch.version.version (${collection})`);
+        if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+            throw new Error(`patch for ${collection} has invalid version ${parsed}`);
+        }
+        return parsed;
+    }
+    validatePatch(collection, patch) {
+        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 (patch.mutations && patch.mutations.length > 0 && patch.externalMutations) {
+            throw new Error(`patch for ${collection} has inline and external mutations together`);
+        }
+        if (patch.exitCode?.code !== null &&
+            patch.exitCode?.code !== undefined &&
+            patch.exitCode.code !== 0) {
+            throw new Error(`patch for ${collection} has terminal exitCode ${patch.exitCode.code}: ${patch.exitCode.text ?? ''}`);
+        }
+        return patch;
+    }
+    async applySnapshot(collection, snapshot) {
+        const version = this.normalizeProtoLong(snapshot.version?.version, `snapshot.version.version (${collection})`);
+        const keyId = decodeProtoBytes(snapshot.keyId?.id, `snapshot.keyId.id (${collection})`);
+        const keyData = await this.getKeyData(keyId);
+        if (!keyData) {
+            throw new WaAppStateMissingKeyError(`missing snapshot key ${keyIdToHex(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 = keyIdToHex(decrypted.indexMac);
+            indexValueMap.set(indexMacHex, decrypted.valueMac);
+            mutations.push({
+                collection,
+                operation: 'set',
+                source: 'snapshot',
+                index: decrypted.index,
+                value: decrypted.value,
+                version: decrypted.version,
+                indexMac: decrypted.indexMac,
+                valueMac: decrypted.valueMac,
+                keyId: recordKeyId,
+                timestamp: this.normalizeProtoLong(decrypted.value?.timestamp, `snapshot.record.value.timestamp (${collection})`)
+            });
+        }
+        const ltHash = await this.crypto.ltHashAdd(APP_STATE_EMPTY_LT_HASH, Array.from(indexValueMap.values()));
+        const expectedSnapshotMac = await this.crypto.generateSnapshotMac(keyData, ltHash, version, collection);
+        if (!uint8Equal(expectedSnapshotMac, snapshot.mac)) {
+            throw new Error(`snapshot MAC mismatch for ${collection}`);
+        }
+        this.setCollectionState(collection, version, ltHash, indexValueMap);
+        return mutations;
+    }
+    async applyPatch(collection, patch) {
+        const patchVersion = this.normalizeProtoLong(patch.version?.version, `patch.version.version (${collection})`);
+        const current = await this.getCollectionState(collection);
+        if (current.version !== patchVersion - 1) {
+            throw new Error(`patch version mismatch for ${collection}: local=${current.version}, incoming=${patchVersion}`);
+        }
+        const patchKeyId = decodeProtoBytes(patch.keyId?.id, `patch.keyId.id (${collection})`);
+        const patchKeyData = await this.getKeyData(patchKeyId);
+        if (!patchKeyData) {
+            throw new WaAppStateMissingKeyError(`missing patch key ${keyIdToHex(patchKeyId)} for ${collection}`, patchKeyId, collection);
+        }
+        const decryptedMutations = await this.decryptPatchMutations(collection, patch);
+        const nextState = await this.computeNextCollectionState(current.hash, current.indexValueMap, decryptedMutations.map((mutation) => ({
+            operation: mutation.operationCode,
+            indexMac: mutation.indexMac,
+            valueMac: mutation.valueMac
+        })), collection);
+        await this.assertPatchMacsMatch(patch, collection, patchKeyData, patchVersion, nextState.hash, decryptedMutations);
+        this.setCollectionState(collection, patchVersion, nextState.hash, nextState.indexValueMap);
+        return decryptedMutations.map(({ operationCode, ...mutation }) => {
+            void operationCode;
+            return mutation;
+        });
+    }
+    async decryptSnapshotRecords(collection, snapshot) {
+        return Promise.all((snapshot.records ?? []).map(async (record) => {
+            const indexMac = decodeProtoBytes(record.index?.blob, `snapshot.record.index.blob (${collection})`);
+            const valueBlob = decodeProtoBytes(record.value?.blob, `snapshot.record.value.blob (${collection})`);
+            const recordKeyId = decodeProtoBytes(record.keyId?.id, `snapshot.record.keyId.id (${collection})`);
+            const recordKeyData = await this.getKeyData(recordKeyId);
+            if (!recordKeyData) {
+                throw new WaAppStateMissingKeyError(`missing snapshot mutation key ${keyIdToHex(recordKeyId)} for ${collection}`, recordKeyId, collection);
+            }
+            const decrypted = await this.crypto.decryptMutation({
+                operation: proto.SyncdMutation.SyncdOperation.SET,
+                keyId: recordKeyId,
+                keyData: recordKeyData,
+                indexMac,
+                valueBlob
+            });
+            return {
+                decrypted,
+                recordKeyId
+            };
+        }));
+    }
+    async decryptPatchMutations(collection, patch) {
+        return Promise.all((patch.mutations ?? []).map(async (mutation) => {
+            const operationCode = mutation.operation;
+            if (operationCode === null || operationCode === undefined) {
+                throw new Error(`patch mutation is missing operation (${collection})`);
+            }
+            const record = mutation.record;
+            if (!record) {
+                throw new Error(`patch mutation is missing record (${collection})`);
+            }
+            const indexMac = decodeProtoBytes(record.index?.blob, `patch.record.index.blob (${collection})`);
+            const valueBlob = decodeProtoBytes(record.value?.blob, `patch.record.value.blob (${collection})`);
+            const recordKeyId = decodeProtoBytes(record.keyId?.id, `patch.record.keyId.id (${collection})`);
+            const recordKeyData = await this.getKeyData(recordKeyId);
+            if (!recordKeyData) {
+                throw new WaAppStateMissingKeyError(`missing mutation key ${keyIdToHex(recordKeyId)} for ${collection}`, recordKeyId, collection);
+            }
+            const decrypted = await this.crypto.decryptMutation({
+                operation: operationCode,
+                keyId: recordKeyId,
+                keyData: recordKeyData,
+                indexMac,
+                valueBlob
+            });
+            return {
+                collection,
+                operation: operationCode === proto.SyncdMutation.SyncdOperation.REMOVE
+                    ? 'remove'
+                    : 'set',
+                source: 'patch',
+                operationCode,
+                index: decrypted.index,
+                value: decrypted.value,
+                version: decrypted.version,
+                indexMac: decrypted.indexMac,
+                valueMac: decrypted.valueMac,
+                keyId: recordKeyId,
+                timestamp: this.normalizeProtoLong(decrypted.value?.timestamp, `patch.record.value.timestamp (${collection})`)
+            };
+        }));
+    }
+    async assertPatchMacsMatch(patch, collection, patchKeyData, patchVersion, nextHash, decryptedMutations) {
+        const snapshotMac = decodeProtoBytes(patch.snapshotMac, `patch.snapshotMac (${collection})`);
+        const expectedSnapshotMac = await this.crypto.generateSnapshotMac(patchKeyData, nextHash, patchVersion, collection);
+        if (!uint8Equal(expectedSnapshotMac, snapshotMac)) {
+            throw new Error(`patch snapshot MAC mismatch for ${collection}`);
+        }
+        const patchMac = decodeProtoBytes(patch.patchMac, `patch.patchMac (${collection})`);
+        const expectedPatchMac = await this.crypto.generatePatchMac(patchKeyData, snapshotMac, decryptedMutations.map((mutation) => mutation.valueMac), patchVersion, collection);
+        if (!uint8Equal(expectedPatchMac, patchMac)) {
+            throw new Error(`patch MAC mismatch for ${collection}`);
+        }
+    }
+    async buildOutgoingPatch(collection, snapshot, pendingMutations) {
+        const activeKey = await this.store.getActiveSyncKey();
+        if (!activeKey) {
+            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 operationCode = mutation.operation === 'remove'
+                ? proto.SyncdMutation.SyncdOperation.REMOVE
+                : proto.SyncdMutation.SyncdOperation.SET;
+            const encrypted = await this.crypto.encryptMutation({
+                operation: operationCode,
+                keyId: activeKey.keyId,
+                keyData: activeKey.keyData,
+                index: mutation.index,
+                value,
+                version: mutation.version
+            });
+            return { operationCode, encrypted };
+        }));
+        const encryptedMutations = encryptedResults.map(({ operationCode, encrypted }) => ({
+            operation: operationCode,
+            record: {
+                keyId: { id: activeKey.keyId },
+                index: { blob: encrypted.indexMac },
+                value: { blob: encrypted.valueBlob }
+            }
+        }));
+        const macMutations = encryptedResults.map(({ operationCode, encrypted }) => ({
+            operation: operationCode,
+            indexMac: encrypted.indexMac,
+            valueMac: encrypted.valueMac
+        }));
+        const nextState = await this.computeNextCollectionState(snapshot.hash, snapshot.indexValueMap, macMutations, collection);
+        const patchVersion = snapshot.version + 1;
+        const snapshotMac = await this.crypto.generateSnapshotMac(activeKey.keyData, nextState.hash, patchVersion, collection);
+        const patchMac = await this.crypto.generatePatchMac(activeKey.keyData, snapshotMac, macMutations.map((item) => item.valueMac), patchVersion, collection);
+        const encodedPatch = proto.SyncdPatch.encode({
+            version: { version: patchVersion },
+            mutations: encryptedMutations,
+            snapshotMac,
+            patchMac,
+            keyId: { id: activeKey.keyId }
+        }).finish();
+        return {
+            encodedPatch,
+            context: {
+                collection,
+                patchVersion,
+                nextHash: nextState.hash,
+                nextIndexValueMap: nextState.indexValueMap
+            }
+        };
+    }
+    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 = keyIdToHex(mutation.indexMac);
+            const existing = indexValueMap.get(indexMacHex);
+            if (mutation.operation === proto.SyncdMutation.SyncdOperation.REMOVE) {
+                if (!existing) {
+                    missingRemoveCount += 1;
+                    continue;
+                }
+                indexValueMap.delete(indexMacHex);
+                removeValues.push(existing);
+                continue;
+            }
+            if (existing) {
+                removeValues.push(existing);
+            }
+            indexValueMap.set(indexMacHex, mutation.valueMac);
+            addValues.push(mutation.valueMac);
+        }
+        if (missingRemoveCount > 0) {
+            this.logger.warn('app-state mutation remove index mac not found', {
+                collection,
+                missingRemoveCount
+            });
+        }
+        const nextHash = await this.crypto.ltHashSubtractThenAdd(baseHash, addValues, removeValues);
+        return {
+            hash: nextHash.hash,
+            indexValueMap
+        };
+    }
+    normalizeProtoLong(value, field) {
+        try {
+            return longToNumber(value);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new Error(`invalid ${field}: ${reason}`);
+        }
+    }
+    groupPendingMutations(pendingMutations) {
+        const grouped = new Map();
+        for (const mutation of pendingMutations) {
+            const list = grouped.get(mutation.collection);
+            if (list) {
+                list.push(mutation);
+            }
+            else {
+                grouped.set(mutation.collection, [mutation]);
+            }
+        }
+        const compacted = new Map();
+        for (const [collection, list] of grouped.entries()) {
+            const seenIndexes = new Set();
+            const reversed = [];
+            for (let index = list.length - 1; index >= 0; index -= 1) {
+                const mutation = list[index];
+                if (seenIndexes.has(mutation.index)) {
+                    continue;
+                }
+                seenIndexes.add(mutation.index);
+                reversed.push(mutation);
+            }
+            compacted.set(collection, reversed.reverse());
+        }
+        return compacted;
+    }
+    async getKeyData(keyId) {
+        const context = this.requireSyncContext();
+        const keyHex = keyIdToHex(keyId);
+        if (context.keys.has(keyHex)) {
+            return context.keys.get(keyHex) ?? null;
+        }
+        const value = await this.store.getSyncKeyData(keyId);
+        context.keys.set(keyHex, value);
+        return value;
+    }
+    async getCollectionState(collection) {
+        const context = this.requireSyncContext();
+        const cached = context.collections.get(collection);
+        if (cached) {
+            return cached;
+        }
+        const state = await this.store.getCollectionState(collection);
+        context.collections.set(collection, state);
+        return state;
+    }
+    setCollectionState(collection, version, hash, indexValueMap) {
+        const context = this.requireSyncContext();
+        context.collections.set(collection, {
+            version,
+            hash,
+            indexValueMap
+        });
+        context.dirtyCollections.add(collection);
+    }
+    async persistCollectionUpdates() {
+        const context = this.requireSyncContext();
+        const updates = [];
+        for (const collection of context.dirtyCollections.values()) {
+            const state = context.collections.get(collection);
+            if (!state) {
+                continue;
+            }
+            updates.push({
+                collection,
+                version: state.version,
+                hash: state.hash,
+                indexValueMap: state.indexValueMap
+            });
+        }
+        if (updates.length === 0) {
+            return;
+        }
+        await this.store.setCollectionStates(updates);
+    }
+    requireSyncContext() {
+        if (!this.syncContext) {
+            throw new Error('app-state sync context is not initialized');
+        }
+        return this.syncContext;
+    }
+}