zapo-js 0.1.0

package/README.md

@@ -0,0 +1,235 @@
+# zapo
+
+<p align="center">
+  <strong>High-performance TypeScript implementation of the WhatsApp Web protocol.</strong><br />
+  Built for high-scalability workloads, multi-session operation, and full user configurability.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/zapo-js">
+    <img alt="npm version" src="https://img.shields.io/npm/v/zapo-js?color=CB3837" />
+  </a>
+  <img alt="npm package size" src="https://img.shields.io/npm/unpacked-size/zapo-js?label=package%20size&color=2F855A" />
+  <img alt="node version" src="https://img.shields.io/badge/node-%3E%3D20.9.0-339933" />
+  <img alt="language" src="https://img.shields.io/badge/language-TypeScript-3178C6" />
+  <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)
+- [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: `protobufjs`
+
+Optional peer dependencies:
+
+- `better-sqlite3` for SQLite-backed stores
+- `pino` and `pino-pretty` for structured logging
+
+## Quick Start
+
+1. Install dependencies.
+
+```bash
+npm install
+```
+
+2. Run the real-flow example.
+
+```bash
+npm run example
+```
+
+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
+
+```ts
+import { createPinoLogger, createStore, WaClient } from 'zapo-js'
+
+const logger = await createPinoLogger({
+    level: 'info',
+    pretty: true
+})
+
+const store = createStore({
+    sqlite: {
+        path: '.auth/state.sqlite',
+        driver: 'auto'
+    },
+    providers: {
+        messages: 'sqlite',
+        threads: 'sqlite',
+        contacts: 'sqlite'
+    }
+})
+
+const client = new WaClient(
+    {
+        store,
+        sessionId: 'default',
+        connectTimeoutMs: 15_000,
+        nodeQueryTimeoutMs: 30_000,
+        history: {
+            enabled: true,
+            requireFullSync: true
+        }
+    },
+    logger
+)
+
+client.on('auth_qr', ({ qr, ttlMs }) => {
+    console.log('qr', { qr, ttlMs })
+})
+
+client.on('message', (event) => {
+    console.log('incoming', {
+        chatJid: event.chatJid,
+        senderJid: event.senderJid
+    })
+})
+
+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
+
+## Versioning and Releases
+
+Versioning is managed with [Changesets](https://github.com/changesets/changesets).
+
+Release flow:
+
+```bash
+npm run changeset
+npm run changeset:status
+npm run version:packages
+npm run release:publish
+```
+
+Notes:
+
+- Changesets are stored in `.changeset/*.md`
+- Multiple changesets are merged automatically into the next release
+- SemVer is manual and intentional: `patch`, `minor`, `major`
+
+## GitHub Release Notes
+
+Release notes are generated automatically (including grouped changes and contributors) when a version tag is pushed.
+
+- Workflow: `.github/workflows/github-release.yml`
+- Categories config: `.github/release.yml`
+
+Trigger example:
+
+```bash
+git tag v0.1.1
+git push origin v0.1.1
+```
+
+If the tag contains `-` (example: `v0.2.0-rc.1`), the release is marked as prerelease.
+
+## Protobuf Generation
+
+`WAProto.proto` source: https://github.com/wppconnect-team/wa-proto
+
+`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`
+
+## 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
+
+## Disclaimer
+
+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

@@ -0,0 +1,202 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WaAppStateCrypto = void 0;
+const constants_1 = require("./constants");
+const utils_1 = require("./utils");
+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 base64_1 = require("../util/base64");
+const bytes_1 = require("../util/bytes");
+const collections_1 = require("../util/collections");
+const DEFAULT_DERIVED_KEYS_CACHE_MAX_SIZE = 256;
+class WaAppStateCrypto {
+    constructor(derivedKeysCacheMaxSize = DEFAULT_DERIVED_KEYS_CACHE_MAX_SIZE) {
+        this.derivedKeysCache = new Map();
+        this.derivedKeysCacheMaxSize =
+            this.normalizeDerivedKeysCacheMaxSize(derivedKeysCacheMaxSize);
+    }
+    clearCache() {
+        this.derivedKeysCache.clear();
+    }
+    async deriveKeys(keyData) {
+        const cacheKey = (0, base64_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 keys = {
+            indexKey: derived.subarray(0, constants_1.APP_STATE_DERIVED_INDEX_KEY_END),
+            valueEncryptionKey: derived.subarray(constants_1.APP_STATE_DERIVED_INDEX_KEY_END, constants_1.APP_STATE_DERIVED_VALUE_ENCRYPTION_KEY_END),
+            valueMacKey: derived.subarray(constants_1.APP_STATE_DERIVED_VALUE_ENCRYPTION_KEY_END, constants_1.APP_STATE_DERIVED_VALUE_MAC_KEY_END),
+            snapshotMacKey: derived.subarray(constants_1.APP_STATE_DERIVED_VALUE_MAC_KEY_END, constants_1.APP_STATE_DERIVED_SNAPSHOT_MAC_KEY_END),
+            patchMacKey: 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(indexKey, indexBytes) {
+        const key = await (0, primitives_1.importHmacKey)(indexKey);
+        return (0, primitives_1.hmacSign)(key, indexBytes);
+    }
+    async encryptMutation(args) {
+        const derivedKeys = await this.deriveKeys(args.keyData);
+        const indexBytes = bytes_1.TEXT_ENCODER.encode(args.index);
+        const encoded = _proto_1.proto.SyncActionData.encode({
+            index: indexBytes,
+            value: args.value ?? undefined,
+            padding: bytes_1.EMPTY_BYTES,
+            version: args.version
+        }).finish();
+        const iv = args.iv ?? (await (0, random_1.randomBytesAsync)(constants_1.APP_STATE_IV_LENGTH));
+        if (iv.byteLength !== constants_1.APP_STATE_IV_LENGTH) {
+            throw new Error(`invalid IV length ${iv.byteLength}`);
+        }
+        const indexMacPromise = this.generateIndexMac(derivedKeys.indexKey, indexBytes);
+        const encryptionKey = await (0, primitives_1.importAesCbcKey)(derivedKeys.valueEncryptionKey);
+        const cipherText = await (0, primitives_1.aesCbcEncrypt)(encryptionKey, iv, encoded);
+        const cipherWithIv = (0, bytes_1.concatBytes)([iv, cipherText]);
+        const associatedData = this.generateAssociatedData(args.operation, args.keyId);
+        const [valueMac, indexMac] = await Promise.all([
+            this.generateValueMac(derivedKeys.valueMacKey, associatedData, cipherWithIv),
+            indexMacPromise
+        ]);
+        return {
+            indexMac,
+            valueBlob: (0, bytes_1.concatBytes)([cipherWithIv, valueMac]),
+            valueMac
+        };
+    }
+    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 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);
+        const associatedData = this.generateAssociatedData(args.operation, args.keyId);
+        const expectedMac = await this.generateValueMac(derivedKeys.valueMacKey, associatedData, cipherWithIv);
+        if (!(0, bytes_1.uint8Equal)(mac, expectedMac)) {
+            throw new Error('mutation value MAC mismatch');
+        }
+        const decryptionKey = await (0, primitives_1.importAesCbcKey)(derivedKeys.valueEncryptionKey);
+        const plaintext = await (0, primitives_1.aesCbcDecrypt)(decryptionKey, iv, cipherText);
+        const syncActionData = _proto_1.proto.SyncActionData.decode(plaintext);
+        if (!syncActionData.index) {
+            throw new Error('missing sync action index');
+        }
+        if (syncActionData.version === null || syncActionData.version === undefined) {
+            throw new Error('missing sync action version');
+        }
+        const generatedIndexMac = await this.generateIndexMac(derivedKeys.indexKey, syncActionData.index);
+        if (!(0, bytes_1.uint8Equal)(generatedIndexMac, args.indexMac)) {
+            throw new Error('mutation index MAC mismatch');
+        }
+        return {
+            index: bytes_1.TEXT_DECODER.decode(syncActionData.index),
+            value: syncActionData.value ?? null,
+            version: syncActionData.version,
+            indexMac: args.indexMac,
+            valueMac: mac
+        };
+    }
+    async generateSnapshotMac(keyData, ltHash, version, collectionName) {
+        const derivedKeys = await this.deriveKeys(keyData);
+        const payload = (0, bytes_1.concatBytes)([
+            ltHash,
+            (0, utils_1.toNetworkOrder64)(version),
+            bytes_1.TEXT_ENCODER.encode(collectionName)
+        ]);
+        const key = await (0, primitives_1.importHmacKey)(derivedKeys.snapshotMacKey);
+        return (0, primitives_1.hmacSign)(key, payload);
+    }
+    async generatePatchMac(keyData, snapshotMac, valueMacs, version, collectionName) {
+        const derivedKeys = await this.deriveKeys(keyData);
+        const payload = (0, bytes_1.concatBytes)([
+            snapshotMac,
+            ...valueMacs,
+            (0, utils_1.toNetworkOrder64)(version),
+            bytes_1.TEXT_ENCODER.encode(collectionName)
+        ]);
+        const key = await (0, primitives_1.importHmacKey)(derivedKeys.patchMacKey);
+        return (0, primitives_1.hmacSign)(key, payload);
+    }
+    async ltHashAdd(base, addValues) {
+        return this.ltHashApply(base, addValues, (left, right) => left + right);
+    }
+    async ltHashSubtract(base, removeValues) {
+        return this.ltHashApply(base, removeValues, (left, right) => left - right);
+    }
+    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) {
+        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 out = new Uint8Array(base.byteLength);
+        this.pointwiseWithOverflow(base, expandedValues[0], combine, out);
+        for (let index = 1; index < expandedValues.length; index += 1) {
+            this.pointwiseWithOverflow(out, expandedValues[index], combine, out);
+        }
+        return out;
+    }
+    pointwiseWithOverflow(left, right, combine, out = new Uint8Array(left.byteLength)) {
+        if (left.byteLength !== right.byteLength) {
+            throw new Error('lt hash input length mismatch');
+        }
+        if (left.byteLength % constants_1.APP_STATE_POINT_SIZE !== 0) {
+            throw new Error('lt hash input alignment mismatch');
+        }
+        if (out.byteLength !== left.byteLength) {
+            throw new Error('lt hash output length mismatch');
+        }
+        const leftView = new DataView(left.buffer, left.byteOffset, left.byteLength);
+        const rightView = new DataView(right.buffer, right.byteOffset, right.byteLength);
+        const outView = new DataView(out.buffer, out.byteOffset, out.byteLength);
+        for (let offset = 0; offset < left.byteLength; offset += constants_1.APP_STATE_POINT_SIZE) {
+            const value = combine(leftView.getUint16(offset, true), rightView.getUint16(offset, true));
+            outView.setUint16(offset, value & 0xffff, true);
+        }
+        return out;
+    }
+    generateAssociatedData(operation, keyId) {
+        if (operation !== _proto_1.proto.SyncdMutation.SyncdOperation.SET &&
+            operation !== _proto_1.proto.SyncdMutation.SyncdOperation.REMOVE) {
+            throw new Error(`unsupported syncd operation ${operation}`);
+        }
+        const out = new Uint8Array(1 + keyId.byteLength);
+        out[0] = operation + 1;
+        out.set(keyId, 1);
+        return out;
+    }
+    async generateValueMac(valueMacKey, associatedData, cipherWithIv) {
+        const octetLength = new Uint8Array(constants_1.APP_STATE_MAC_OCTET_LENGTH);
+        octetLength[octetLength.length - 1] = associatedData.byteLength & 0xff;
+        const key = await (0, primitives_1.importHmacSha512Key)(valueMacKey);
+        const full = await (0, primitives_1.hmacSign)(key, (0, bytes_1.concatBytes)([associatedData, cipherWithIv, octetLength]));
+        return full.slice(0, constants_1.APP_STATE_VALUE_MAC_LENGTH);
+    }
+    normalizeDerivedKeysCacheMaxSize(value) {
+        if (!Number.isFinite(value)) {
+            return DEFAULT_DERIVED_KEYS_CACHE_MAX_SIZE;
+        }
+        return Math.max(0, Math.trunc(value));
+    }
+    touchDerivedKeysCacheEntry(cacheKey, keys) {
+        if (this.derivedKeysCacheMaxSize <= 0) {
+            return;
+        }
+        (0, collections_1.setBoundedMapEntry)(this.derivedKeysCache, cacheKey, keys, this.derivedKeysCacheMaxSize);
+    }
+}
+exports.WaAppStateCrypto = WaAppStateCrypto;