zapo-js 0.3.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vinikjkkj <contact@vinicius.email>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -16,117 +16,55 @@
   <img alt="focus" src="https://img.shields.io/badge/focus-high--scale%20%2B%20multi--session-0A7EA4" />
 </p>
 
-## Table of Contents
-
-- [Stability Notice](#stability-notice)
-- [What Makes This Project Different](#what-makes-this-project-different)
-- [Core Principles](#core-principles)
-- [Architecture at a Glance](#architecture-at-a-glance)
-- [Requirements](#requirements)
-- [Quick Start](#quick-start)
-- [Minimal Usage](#minimal-usage)
-- [Useful Scripts](#useful-scripts)
-- [Versioning and Releases](#versioning-and-releases)
-- [GitHub Release Notes](#github-release-notes)
-- [Protobuf Generation](#protobuf-generation)
-- [Support the Project](#support-the-project)
-- [Contribution Notes](#contribution-notes)
-- [Disclaimer](#disclaimer)
-
-## Stability Notice
-
-> Frequent breaking changes are expected until the first major release.
-> If you run `zapo` in long-lived environments, pin exact versions and validate upgrades carefully.
-
-## What Makes This Project Different
-
-`zapo` is an independent runtime implementation (not a wrapper/fork of an existing WhatsApp library).
-
-- No wrappers around third-party WhatsApp SDKs
-- No forks of existing WhatsApp client libraries
-- No copied protocol abstractions from community libraries
-- `WAProto.proto` is sourced from `wppconnect-team/wa-proto` and compiled locally for runtime/types
-
-The protocol source of truth is the deobfuscated WhatsApp Web.
-The target is behavior parity with WhatsApp Web, while improving internal performance and memory efficiency.
-
-## Core Principles
-
-These principles drive implementation decisions:
-
-- `index-first`: validate protocol behavior against WhatsApp Web before implementing anything
-- `performance-first`: optimize for low CPU, low RAM, low allocations, and zero-copy in hot paths
-- `async-first`: I/O, network, and crypto operations are async
-
-## Architecture at a Glance
-
-### Patterns
-
-- Coordinator-first feature design in `src/client/coordinators/`
-- Pure node builders in `src/transport/node/builders/` for reusable protocol stanzas
-- Incoming parsers/normalizers in `src/client/events/`, with coordinators handling orchestration only
-- Typed store contracts in `src/store/contracts/` with `memory` and `sqlite` providers
-- Protocol constants in `src/protocol/` using `Object.freeze({...} as const)`
-
-### Engineering conventions
-
-- `Uint8Array` everywhere for binary data (`Buffer` is avoided)
-- Zero-copy (`subarray`, byte views) in critical paths
-- Bounded in-memory structures to prevent unbounded growth
-- Path aliases (`@client`, `@crypto`, `@store`, etc.), no relative `../` imports
-- Named exports only, no default exports
-- No enums (`Object.freeze` + `as const` instead)
-
-## Requirements
-
-- Node.js `>= 20.9.0`
-- npm
-
-Runtime dependencies:
-
-- Mandatory: none
+<p align="center">
+  📚 <strong>Documentation:</strong> <a href="https://zapo.to/">zapo.to</a> ·
+  🛠 <strong>Contributing:</strong> <a href="CONTRIBUTING.md">CONTRIBUTING.md</a> ·
+  💛 <strong>Sponsor:</strong> <a href="https://github.com/sponsors/vinikjkkj">GitHub Sponsors</a>
+</p>
 
-Optional peer dependencies:
+---
 
-- `better-sqlite3` for SQLite-backed stores
-- `pino` and `pino-pretty` for structured logging
+## Stability Notice
 
-## Quick Start
+> `zapo-js` is stable as of `1.0.0`. The public API follows SemVer:
+> breaking changes ship only in a major release; minors add features,
+> patches fix bugs.
 
-1. Install dependencies.
+## Install
 
 ```bash
-npm install
+npm install zapo-js
 ```
 
-2. Run the real-flow example.
+Zero mandatory runtime dependencies. Pick the optional packages you need
+on top: a persistent store and (optionally) the media processor for
+thumbnails / voice-note metadata.
 
 ```bash
-npm run example
+# Persistent store - choose one
+npm install @zapo-js/store-sqlite better-sqlite3
+# or @zapo-js/store-redis ioredis
+# or @zapo-js/store-postgres pg
+# or @zapo-js/store-mysql mysql2
+# or @zapo-js/store-mongo mongodb
+
+# Optional - thumbnails + waveforms + voice-note normalization
+npm install @zapo-js/media-utils sharp
+# plus a system `ffmpeg` + `ffprobe` on PATH (see media-utils README)
+
+# Optional - structured logging
+npm install pino pino-pretty
 ```
 
-3. Scan the QR code emitted by `auth_qr`.
-4. Send `ping` to the connected session, the example replies with `pong`.
-
-Auth state is persisted in `.auth/state.sqlite`.
-
-## Minimal Usage
+## Quick Start
 
 ```ts
-import { createPinoLogger, createStore, WaClient } from 'zapo-js'
+import { ConsoleLogger, createStore, WaClient } from 'zapo-js'
 import { createSqliteStore } from '@zapo-js/store-sqlite'
 
-const logger = await createPinoLogger({
-    level: 'info',
-    pretty: true
-})
-
 const store = createStore({
     backends: {
-        sqlite: createSqliteStore({
-            path: '.auth/state.sqlite',
-            driver: 'auto'
-        })
+        sqlite: createSqliteStore({ path: '.auth/state.sqlite' })
     },
     providers: {
         auth: 'sqlite',
@@ -136,117 +74,99 @@ const store = createStore({
         identity: 'sqlite',
         senderKey: 'sqlite',
         appState: 'sqlite',
-        messages: 'sqlite',
-        threads: 'sqlite',
-        contacts: 'sqlite'
+        privacyToken: 'sqlite',
+        messages: 'sqlite', // 'none' to skip the message archive
+        threads: 'sqlite', // 'none' to skip
+        contacts: 'sqlite' // 'none' to skip
     }
 })
 
-const client = new WaClient(
-    {
-        store,
-        sessionId: 'default',
-        connectTimeoutMs: 15_000,
-        nodeQueryTimeoutMs: 30_000,
-        history: {
-            enabled: true,
-            requireFullSync: true
-        }
-    },
-    logger
-)
+const client = new WaClient({ store, sessionId: 'default' }, new ConsoleLogger('info'))
 
-client.on('auth_qr', ({ qr, ttlMs }) => {
-    console.log('qr', { qr, ttlMs })
+client.on('auth_qr', ({ qr }) => {
+    console.log('scan this:', qr)
 })
 
-client.on('message', (event) => {
-    console.log('incoming', {
-        chatJid: event.chatJid,
-        senderJid: event.senderJid
-    })
+client.on('auth_paired', ({ credentials }) => {
+    console.log('paired as', credentials.meJid)
+})
+
+client.on('message', async (event) => {
+    if (event.message?.conversation === 'ping') {
+        await client.message.send(event.key.remoteJid, 'pong')
+    }
 })
 
 await client.connect()
 ```
 
-## Useful Scripts
-
-- `npm run build` - build CJS, ESM, and types
-- `npm run test` - run unit tests (non-flow)
-- `npm run test:flow` - run real-flow tests
-- `npm run test:coverage` - run coverage report
-- `npm run typecheck` - type-check project
-- `npm run lint` - lint source files
-- `npm run format` - format codebase
-- `npm run proto:generate` - regenerate protobuf runtime/types from `proto/WAProto.proto`
-- `npm run changeset` - create a versioning entry (`patch`/`minor`/`major`)
-- `npm run changeset:status` - show pending versioning entries
-- `npm run version:packages` - apply pending versions and update `CHANGELOG.md`
-- `npm run release:publish` - build and publish to npm with Changesets
+That's the minimum to pair, listen for messages, and reply. For everything
+else - sending media, reactions, polls, groups, newsletters, app-state
+mutations, business profile, events catalog, store providers, the typed
+event map, and the architectural reasoning - read the guides at
+**[zapo.to](https://zapo.to/)**.
 
-## Versioning and Releases
+## Packages
 
-Versioning is managed with [Changesets](https://github.com/changesets/changesets).
+The core lives at the repo root (`zapo-js`). Optional packages live in
+[`packages/`](packages/) and ship under the `@zapo-js/*` scope. Install
+only what you need.
 
-Release flow:
+| Package                                              | Peer dependency             | Purpose                                                                                                                                          |
+| ---------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [`@zapo-js/store-sqlite`](packages/store-sqlite)     | `better-sqlite3`            | SQLite persistent store (single-process bots, dev sessions, small-to-medium prod).                                                               |
+| [`@zapo-js/store-redis`](packages/store-redis)       | `ioredis`                   | Redis-backed store with native TTL eviction.                                                                                                     |
+| [`@zapo-js/store-mongo`](packages/store-mongo)       | `mongodb`                   | MongoDB-backed store with TTL-index eviction.                                                                                                    |
+| [`@zapo-js/store-mysql`](packages/store-mysql)       | `mysql2`                    | MySQL / MariaDB-backed store with background cleanup poller.                                                                                     |
+| [`@zapo-js/store-postgres`](packages/store-postgres) | `pg`                        | PostgreSQL-backed store with background cleanup poller.                                                                                          |
+| [`@zapo-js/media-utils`](packages/media-utils)       | `sharp` + `ffmpeg`          | `WaMediaProcessor`: thumbnails, waveforms, voice-note normalization.                                                                             |
+| [`@zapo-js/fake-server`](packages/fake-server)       | (none)                      | In-process fake WhatsApp Web server for end-to-end testing.                                                                                      |
+| [`@zapo-js/mcp-server`](packages/mcp-server)         | `@modelcontextprotocol/sdk` | **Dev-only.** MCP server exposing multi-session `WaClient`s as dynamic tools for an LLM agent (Claude Code / Cursor / etc.). Not for production. |
 
-```bash
-npm run changeset
-npm run changeset:status
-npm run version:packages
-npm run release:publish
-```
-
-Notes:
+Each package's README has the install + config + integration notes.
 
-- Changesets are stored in `.changeset/*.md`
-- Multiple changesets are merged automatically into the next release
-- SemVer is manual and intentional: `patch`, `minor`, `major`
+## Documentation
 
-## GitHub Release Notes
+- **[zapo.to](https://zapo.to/)** - guides, full API reference, examples,
+  protocol notes ([llms.txt](https://zapo.to/llms.txt) index or
+  [llms-full.txt](https://zapo.to/llms-full.txt) for LLM context)
+- **[`vinikjkkj/zapo-docs`](https://github.com/vinikjkkj/zapo-docs)** -
+  source of zapo.to (open issues/PRs there for doc fixes)
+- **Per-package READMEs** under [`packages/`](packages/) - one per
+  optional package
+- **[`AGENTS.md`](AGENTS.md)** - architecture spec + coding rules
+  (contributor-facing)
 
-Release notes are generated automatically (including grouped changes and contributors) when a version tag is pushed.
+## Contributing
 
-- Workflow: `.github/workflows/github-release.yml`
-- Categories config: `.github/release.yml`
+Pull requests are welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for
+setup, repo layout, CI, release flow, and the conventions PRs must follow.
 
-Trigger example:
-
-```bash
-git tag v0.1.1
-git push origin v0.1.1
-```
+Contributors also agree to the [Code of Conduct](CODE_OF_CONDUCT.md),
+which includes an **AI-Assisted Contributions** policy covering
+disclosure, human ownership, and the rule against bundle-hallucinated
+protocol claims.
 
-If the tag contains `-` (example: `v0.2.0-rc.1`), the release is marked as prerelease.
+## Security
 
-## Protobuf Generation
+Found a vulnerability in the crypto, auth, or Signal layer? Please
+**do not open a public issue**. Report it privately via
+[GitHub Security Advisories](https://github.com/vinikjkkj/zapo/security/advisories/new)
+or email `contact@vinicius.email`. Scope, response window, and
+disclosure timeline are documented in [`SECURITY.md`](SECURITY.md).
 
-`WAProto.proto` source: https://github.com/wppconnect-team/wa-proto
+## License
 
-`npm run proto:generate` runs `scripts/generate-proto.cjs`, which:
-
-- Ensures proto tooling dependencies are installed in `proto/`
-- Generates and minifies `proto/index.js`
-- Regenerates compact typings at `proto/index.d.ts`
+[MIT](LICENSE) © vinikjkkj
 
 ## Support the Project
 
-If `zapo` is useful in your production or study setup, you can support ongoing development on GitHub Sponsors:
-
-- https://github.com/sponsors/vinikjkkj
-
-## Contribution Notes
-
-Before opening a PR:
-
-- Validate behavior against WhatsApp Web
-- Keep performance and memory constraints in mind
-- Keep node building/parsing aligned with project patterns
-- Avoid API changes that diverge from observed WhatsApp Web behavior
-- Test real flows when touching auth, transport, app state, retry, or signal paths
+If `zapo` is useful in your production or study setup, you can support
+ongoing development on GitHub Sponsors:
+[github.com/sponsors/vinikjkkj](https://github.com/sponsors/vinikjkkj).
 
 ## Disclaimer
 
-This project is an independent implementation for engineering and interoperability research.
-It is not affiliated with or endorsed by WhatsApp.
+This project is an independent implementation for engineering and
+interoperability research. It is not affiliated with or endorsed by
+WhatsApp.

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

@@ -1,16 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WaAppStateCrypto = void 0;
-const constants_1 = require("./constants");
-const hkdf_1 = require("../crypto/core/hkdf");
-const primitives_1 = require("../crypto/core/primitives");
-const random_1 = require("../crypto/core/random");
-const _proto_1 = require("../proto.js");
-const constants_2 = require("../protocol/constants");
-const bytes_1 = require("../util/bytes");
-const collections_1 = require("../util/collections");
-const primitives_2 = require("../util/primitives");
+const constants_1 = require("../constants");
+const hkdf_1 = require("../../crypto/core/hkdf");
+const primitives_1 = require("../../crypto/core/primitives");
+const random_1 = require("../../crypto/core/random");
+const _proto_1 = require("../../proto.js");
+const constants_2 = require("../../protocol/constants");
+const bytes_1 = require("../../util/bytes");
+const collections_1 = require("../../util/collections");
+const primitives_2 = require("../../util/primitives");
 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.
+ */
 class WaAppStateCrypto {
     constructor(derivedKeysCacheMaxSize = DEFAULT_DERIVED_KEYS_CACHE_MAX_SIZE, skipMacVerification = false) {
         this.derivedKeysCache = new Map();
@@ -20,39 +25,39 @@ class WaAppStateCrypto {
     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 = (0, bytes_1.bytesToBase64)(keyData);
         const cached = this.derivedKeysCache.get(cacheKey);
         if (cached) {
             this.touchDerivedKeysCacheEntry(cacheKey, cached);
             return cached;
         }
-        const derived = await (0, hkdf_1.hkdf)(keyData, null, constants_2.WA_APP_STATE_KDF_INFO.MUTATION_KEYS, constants_1.APP_STATE_DERIVED_KEY_LENGTH);
-        const [indexHmacKey, valueEncryptionAesKey, valueMacHmacKey, snapshotMacHmacKey, patchMacHmacKey] = await Promise.all([
-            (0, primitives_1.importHmacKey)(derived.subarray(0, constants_1.APP_STATE_DERIVED_INDEX_KEY_END)),
-            (0, primitives_1.importAesCbcKey)(derived.subarray(constants_1.APP_STATE_DERIVED_INDEX_KEY_END, constants_1.APP_STATE_DERIVED_VALUE_ENCRYPTION_KEY_END)),
-            (0, primitives_1.importHmacSha512Key)(derived.subarray(constants_1.APP_STATE_DERIVED_VALUE_ENCRYPTION_KEY_END, constants_1.APP_STATE_DERIVED_VALUE_MAC_KEY_END)),
-            (0, primitives_1.importHmacKey)(derived.subarray(constants_1.APP_STATE_DERIVED_VALUE_MAC_KEY_END, constants_1.APP_STATE_DERIVED_SNAPSHOT_MAC_KEY_END)),
-            (0, primitives_1.importHmacKey)(derived.subarray(constants_1.APP_STATE_DERIVED_SNAPSHOT_MAC_KEY_END, constants_1.APP_STATE_DERIVED_PATCH_MAC_KEY_END))
-        ]);
+        const derived = (0, hkdf_1.hkdf)(keyData, null, constants_2.WA_APP_STATE_KDF_INFO.MUTATION_KEYS, constants_1.APP_STATE_DERIVED_KEY_LENGTH);
         const keys = {
-            indexHmacKey,
-            valueEncryptionAesKey,
-            valueMacHmacKey,
-            snapshotMacHmacKey,
-            patchMacHmacKey
+            indexHmacKey: derived.subarray(0, constants_1.APP_STATE_DERIVED_INDEX_KEY_END),
+            valueEncryptionAesKey: derived.subarray(constants_1.APP_STATE_DERIVED_INDEX_KEY_END, constants_1.APP_STATE_DERIVED_VALUE_ENCRYPTION_KEY_END),
+            valueMacHmacKey: derived.subarray(constants_1.APP_STATE_DERIVED_VALUE_ENCRYPTION_KEY_END, constants_1.APP_STATE_DERIVED_VALUE_MAC_KEY_END),
+            snapshotMacHmacKey: derived.subarray(constants_1.APP_STATE_DERIVED_VALUE_MAC_KEY_END, constants_1.APP_STATE_DERIVED_SNAPSHOT_MAC_KEY_END),
+            patchMacHmacKey: derived.subarray(constants_1.APP_STATE_DERIVED_SNAPSHOT_MAC_KEY_END, constants_1.APP_STATE_DERIVED_PATCH_MAC_KEY_END)
         };
         this.touchDerivedKeysCacheEntry(cacheKey, keys);
         return keys;
     }
-    async generateIndexMac(indexHmacKey, indexBytes) {
-        return (0, primitives_1.hmacSign)(indexHmacKey, indexBytes);
+    /** Computes the HMAC-SHA-256 index MAC over `indexBytes`. */
+    generateIndexMac(indexHmacKey, indexBytes) {
+        return (0, primitives_1.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 = bytes_1.TEXT_ENCODER.encode(args.index);
         const encoded = _proto_1.proto.SyncActionData.encode({
             index: indexBytes,
@@ -64,37 +69,34 @@ class WaAppStateCrypto {
         if (iv.byteLength !== constants_1.APP_STATE_IV_LENGTH) {
             throw new Error(`invalid IV length ${iv.byteLength}`);
         }
-        const indexMacPromise = this.generateIndexMac(derivedKeys.indexHmacKey, indexBytes);
-        const cipherText = await (0, primitives_1.aesCbcEncrypt)(derivedKeys.valueEncryptionAesKey, iv, encoded);
-        const cipherWithIv = (0, bytes_1.concatBytes)([iv, cipherText]);
+        const indexMac = this.generateIndexMac(derivedKeys.indexHmacKey, indexBytes);
+        const cipherText = (0, primitives_1.aesCbcEncrypt)(derivedKeys.valueEncryptionAesKey, iv, encoded);
         const associatedData = this.generateAssociatedData(args.operation, args.keyId);
-        const [valueMac, indexMac] = await Promise.all([
-            this.generateValueMac(derivedKeys.valueMacHmacKey, associatedData, cipherWithIv),
-            indexMacPromise
-        ]);
+        const valueMac = this.generateValueMac(derivedKeys.valueMacHmacKey, associatedData, iv, cipherText);
         return {
             indexMac,
-            valueBlob: (0, bytes_1.concatBytes)([cipherWithIv, valueMac]),
+            valueBlob: (0, bytes_1.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 < constants_1.APP_STATE_IV_LENGTH + constants_1.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, constants_1.APP_STATE_IV_LENGTH);
         const mac = args.valueBlob.subarray(args.valueBlob.byteLength - constants_1.APP_STATE_VALUE_MAC_LENGTH);
         const cipherText = args.valueBlob.subarray(constants_1.APP_STATE_IV_LENGTH, args.valueBlob.byteLength - constants_1.APP_STATE_VALUE_MAC_LENGTH);
-        const cipherWithIv = args.valueBlob.subarray(0, args.valueBlob.byteLength - constants_1.APP_STATE_VALUE_MAC_LENGTH);
         if (!this.skipMacVerification) {
             const associatedData = this.generateAssociatedData(args.operation, args.keyId);
-            const expectedMac = await this.generateValueMac(derivedKeys.valueMacHmacKey, associatedData, cipherWithIv);
+            const expectedMac = this.generateValueMac(derivedKeys.valueMacHmacKey, associatedData, iv, cipherText);
             if (!(0, bytes_1.uint8TimingSafeEqual)(mac, expectedMac)) {
                 throw new Error('mutation value MAC mismatch');
             }
         }
-        const plaintext = await (0, primitives_1.aesCbcDecrypt)(derivedKeys.valueEncryptionAesKey, iv, cipherText);
+        const plaintext = (0, primitives_1.aesCbcDecrypt)(derivedKeys.valueEncryptionAesKey, iv, cipherText);
         const syncActionData = _proto_1.proto.SyncActionData.decode(plaintext);
         if (!syncActionData.index) {
             throw new Error('missing sync action index');
@@ -103,7 +105,7 @@ class WaAppStateCrypto {
             throw new Error('missing sync action version');
         }
         if (!this.skipMacVerification) {
-            const generatedIndexMac = await this.generateIndexMac(derivedKeys.indexHmacKey, syncActionData.index);
+            const generatedIndexMac = this.generateIndexMac(derivedKeys.indexHmacKey, syncActionData.index);
             if (!(0, bytes_1.uint8TimingSafeEqual)(generatedIndexMac, args.indexMac)) {
                 throw new Error('mutation index MAC mismatch');
             }
@@ -116,41 +118,48 @@ 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 = (0, bytes_1.concatBytes)([
+        const derivedKeys = this.deriveKeys(keyData);
+        return (0, primitives_1.hmacSha256Sign)(derivedKeys.snapshotMacHmacKey, [
             ltHash,
             (0, bytes_1.intToBytes)(8, version),
             bytes_1.TEXT_ENCODER.encode(collectionName)
         ]);
-        return (0, primitives_1.hmacSign)(derivedKeys.snapshotMacHmacKey, 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 = (0, bytes_1.concatBytes)([
+        const derivedKeys = this.deriveKeys(keyData);
+        return (0, primitives_1.hmacSha256Sign)(derivedKeys.patchMacHmacKey, [
             snapshotMac,
             ...valueMacs,
             (0, bytes_1.intToBytes)(8, version),
             bytes_1.TEXT_ENCODER.encode(collectionName)
         ]);
-        return (0, primitives_1.hmacSign)(derivedKeys.patchMacHmacKey, 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) => (0, hkdf_1.hkdf)(value, null, constants_2.WA_APP_STATE_KDF_INFO.PATCH_INTEGRITY, constants_1.APP_STATE_EMPTY_LT_HASH.byteLength)));
+        const expandedValues = values.map((value) => (0, hkdf_1.hkdf)(value, null, constants_2.WA_APP_STATE_KDF_INFO.PATCH_INTEGRITY, constants_1.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) {
@@ -187,10 +196,10 @@ class WaAppStateCrypto {
         out.set(keyId, 1);
         return out;
     }
-    async generateValueMac(valueMacHmacKey, associatedData, cipherWithIv) {
+    generateValueMac(valueMacHmacKey, associatedData, iv, cipherText) {
         const octetLength = new Uint8Array(constants_1.APP_STATE_MAC_OCTET_LENGTH);
         octetLength[octetLength.length - 1] = associatedData.byteLength & 0xff;
-        const full = await (0, primitives_1.hmacSign)(valueMacHmacKey, (0, bytes_1.concatBytes)([associatedData, cipherWithIv, octetLength]));
+        const full = (0, primitives_1.hmacSha512Sign)(valueMacHmacKey, (0, bytes_1.concatBytes)([associatedData, iv, cipherText, octetLength]));
         return full.subarray(0, constants_1.APP_STATE_VALUE_MAC_LENGTH);
     }
     touchDerivedKeysCacheEntry(cacheKey, keys) {

package/dist/appstate/index.js

@@ -14,17 +14,18 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WaAppStateSyncClient = exports.parseSyncResponse = exports.WaAppStateCrypto = exports.decodeAppStateSyncKeys = exports.decodeAppStateCollections = exports.decodeAppStateFingerprint = exports.encodeAppStateFingerprint = void 0;
-__exportStar(require("./constants"), exports);
-var encoding_1 = require("./encoding");
+exports.WaAppStateSyncClient = exports.parseSyncResponse = exports.WaAppStateCrypto = exports.decodeAppStateSyncKeys = exports.decodeAppStateCollections = exports.decodeAppStateFingerprint = exports.encodeAppStateFingerprint = exports.APP_STATE_EMPTY_LT_HASH = void 0;
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "APP_STATE_EMPTY_LT_HASH", { enumerable: true, get: function () { return constants_1.APP_STATE_EMPTY_LT_HASH; } });
+var encoding_1 = require("./parsers/encoding");
 Object.defineProperty(exports, "encodeAppStateFingerprint", { enumerable: true, get: function () { return encoding_1.encodeAppStateFingerprint; } });
 Object.defineProperty(exports, "decodeAppStateFingerprint", { enumerable: true, get: function () { return encoding_1.decodeAppStateFingerprint; } });
 Object.defineProperty(exports, "decodeAppStateCollections", { enumerable: true, get: function () { return encoding_1.decodeAppStateCollections; } });
 Object.defineProperty(exports, "decodeAppStateSyncKeys", { enumerable: true, get: function () { return encoding_1.decodeAppStateSyncKeys; } });
 __exportStar(require("./utils"), exports);
-var WaAppStateCrypto_1 = require("./WaAppStateCrypto");
+var WaAppStateCrypto_1 = require("./crypto/WaAppStateCrypto");
 Object.defineProperty(exports, "WaAppStateCrypto", { enumerable: true, get: function () { return WaAppStateCrypto_1.WaAppStateCrypto; } });
-var response_parser_1 = require("./response-parser");
+var response_parser_1 = require("./parsers/response-parser");
 Object.defineProperty(exports, "parseSyncResponse", { enumerable: true, get: function () { return response_parser_1.parseSyncResponse; } });
-var WaAppStateSyncClient_1 = require("./WaAppStateSyncClient");
+var WaAppStateSyncClient_1 = require("./sync/WaAppStateSyncClient");
 Object.defineProperty(exports, "WaAppStateSyncClient", { enumerable: true, get: function () { return WaAppStateSyncClient_1.WaAppStateSyncClient; } });

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

@@ -4,14 +4,17 @@ exports.encodeAppStateFingerprint = encodeAppStateFingerprint;
 exports.decodeAppStateFingerprint = decodeAppStateFingerprint;
 exports.decodeAppStateSyncKeys = decodeAppStateSyncKeys;
 exports.decodeAppStateCollections = decodeAppStateCollections;
-const _proto_1 = require("../proto.js");
-const coercion_1 = require("../util/coercion");
+const _proto_1 = require("../../proto.js");
+const coercion_1 = require("../../util/coercion");
+const primitives_1 = require("../../util/primitives");
+/** Serializes an app-state sync key fingerprint to its protobuf bytes, or `null` when absent. */
 function encodeAppStateFingerprint(fingerprint) {
     if (!fingerprint) {
         return null;
     }
     return _proto_1.proto.Message.AppStateSyncKeyFingerprint.encode(fingerprint).finish();
 }
+/** Inverse of {@link encodeAppStateFingerprint}; throws on malformed input. */
 function decodeAppStateFingerprint(raw) {
     const bytes = (0, coercion_1.asOptionalBytes)(raw, 'appstate_sync_keys.fingerprint');
     if (!bytes) {
@@ -21,10 +24,10 @@ function decodeAppStateFingerprint(raw) {
         return _proto_1.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: ${(0, primitives_1.toError)(error).message}`);
     }
 }
+/** Decodes app-state sync-key SQL rows into {@link WaAppStateSyncKey} records. */
 function decodeAppStateSyncKeys(rows) {
     const decoded = new Array(rows.length);
     for (let i = 0; i < rows.length; i += 1) {
@@ -38,6 +41,10 @@ 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.
+ */
 function decodeAppStateCollections(versionRows, valueRows) {
     const valueMapByCollection = new Map();
     for (const row of valueRows) {