kersiosocket 0.0.0-stage → 0.6.0-dev

package/BUILD-INFO.md

@@ -0,0 +1,15 @@
+# Build information — KersioSocket v0.6.0-dev
+
+- Package version: `0.6.0-dev`
+- Verification runtime: Node.js `v22.16.0`
+- Full automated suite: `78/78` passing with `npm test`
+- Serial suite: `78/78` passing with `npm run test:serial`
+- Backend/facade bridge suite: `9/9` passing with `npm run test:backends`
+- JavaScript syntax: `node --check` passed for every project `.js` file outside `node_modules`
+- Packaging: `npm pack --dry-run` completed; 70 package files listed
+- Token data inside this archive: intentionally empty placeholder
+- Refresh token data after extraction: `npm run refresh:tokens`
+
+## Evidence boundary
+
+The tests establish local behavior and adapter contracts only. They do not establish successful live WhatsApp authentication, server trust/pinning, cryptographic verification of a real WhatsApp pairing-success response, Pairing Code end-to-end, Signal Protocol interoperability, actual live media/group/app-state support, or performance relative to Baileys, Zapo-JS, or whatsmeow. The native engine still fails closed when no server-certificate verifier is configured and does not yet implement a complete native Signal/message engine. Baileys and Zapo-JS features are delegated through adapters; whatsmeow is an external JSONL sidecar contract and its Go binary is not included. See `README.md`, `docs/ENGINE-MATRIX.md`, `docs/RESEARCH-BASELINE.md`, and `docs/PROTOCOL-ROADMAP.md`.

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 0.6.0-dev — unified engine facade and hardening
+
+- Adds `KersioClient` / `createKersioClient()` with normalized connection, pairing, message, credential, and history events plus explicit capability errors.
+- Adds adapters for an existing `zapo-js` `WaClient`, an `@whiskeysockets/baileys` socket/factory, and a bounded JSONL-RPC Go `whatsmeow` process bridge.
+- Adds normalized high-level message builders for text, media, location, contacts, polls, reactions, edit and delete. The selected engine remains the implementation of transport/protocol semantics; backend coverage varies.
+- Adds `KersioSessionManager` so distinct accounts may select distinct engines in one process.
+- Adds `MessageArchive` (bounded per-chat history + `getMessage()`), `KeyedMutex`, local-filesystem `FileLockManager`, and `LockedStore`.
+- Makes native `Connection` fail closed by default if no Noise server-certificate verifier is configured; adds optional synchronous verifier hook and verified-pairing commit guard.
+- Documents that the Go sidecar is a separate executable and the bridge test is transport-only; does not ship or claim an untested Go protocol implementation.
+- Adds mocked adapter/bridge, archive/lock, secure-pairing and strict-Noise tests. No live WhatsApp account test is claimed.
+
+## 0.5.0-dev — major protocol foundations upgrade
+
+- WABinary defaults to the `0x00` uncompressed prefix; adds explicit golden-byte test, optional zlib `0x02` prefix, packed digit/hex strings, AD-JID and decode fixtures for FB/INTEROP JIDs, plus bounded parser checks.
+- Adds `NodeProtocol` for inbound node events and outbound IQ queries, pending request limits, timeout, cancellation, remote IQ errors, and connection-close cleanup. A non-empty dictionary is required unless a caller explicitly enables an empty table for tests.
+- Adds `DeviceProps` / `HistorySyncConfig` encoders and a builder for registration fields from caller-provided keys/signature. The helper never generates or verifies cryptographic material.
+- Connects an early QR adapter to the node event surface, sends the observed IQ acknowledgement, and emits QR candidates. It deliberately does not mark a `pair-success` stanza verified.
+- Adds `EncryptedStore` using AES-256-GCM with AAD bound to the key, and clear no-plaintext-fallback behavior.
+- Adds a local WABinary performance baseline, source snapshot inventory and refreshed roadmap.
+- Improves listener isolation and reconnect/error regression tests.
+
+## Existing foundations retained
+
+Noise XX transport loopback, framing, atomic file store, SQLite and fake-client Redis/Mongo adapters, session manager, LRU, and token-source importer remain in place.
+
+## Important status
+
+This is still development code. The server Noise certificate chain is not verified, full pairing-success signatures/HMAC are not verified, pairing code is not implemented, Signal Protocol is not implemented, and no live WhatsApp login/send-message capability is claimed.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KersioSocket contributors
+
+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

@@ -1,3 +1,192 @@
-# Temporary Holding Version
+# KersioSocket v0.6.0-dev
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+KersioSocket v0.6 adds a **common API facade** for three independently maintained WhatsApp Web client engines: `zapo-js`, `@whiskeysockets/baileys`, and a Go `whatsmeow` process bridge. It keeps the original KersioSocket native transport/protocol research code and adds message helpers, event normalization, selectable multi-session engines, message archive, and file-based locking.
+
+> **Honest status:** this is a development build. The Zapo and Baileys adapters are tested with mocked clients, and the Go bridge transport is tested with a mock JSONL process; there is no live-account integration test in this ZIP. The Go `whatsmeow` executable is **not bundled**. The native KersioSocket engine remains experimental: by default it fails closed when Noise server-certificate verification is not configured, and this package does not include a verified WhatsApp certificate-root chain, a full native Signal Protocol implementation, or an internal cryptographic verifier for pairing-success. Choose a maintained backend for live messaging rather than disabling security checks.
+
+## Apa arti “digabung” di v0.6?
+
+KersioSocket menyatukan API dan lifecycle backend di satu package, bukan mencampur tiga set auth key/Signal session menjadi satu sesi protokol. Untuk setiap akun WhatsApp, pilih **satu** engine pemilik transport, autentikasi, dan state. Beberapa akun boleh menggunakan engine berbeda di satu proses melalui `KersioSessionManager`. Menjalankan Baileys, Zapo, dan whatsmeow bersamaan dengan kredensial akun yang sama tidak disarankan karena ketiganya mengelola sesi dan counter protokol sendiri.
+
+Engine:
+
+- **Zapo-JS** — adapter ke API `WaClient` dan `.message.send()`; sesi, Signal, prekey, media, dan app-state dikelola Zapo. Konfigurasi store diberikan oleh pemanggil agar KersioSocket tidak menebak backend/credential provider.
+- **Baileys** — adapter ke socket Baileys; meneruskan event, QR/pairing code, credential updates, pesan, media download bila modul helper tersedia, dan method socket yang diizinkan.
+- **Go whatsmeow process** — JSON Lines RPC bridge terbatasi ke executable Go yang dibuat terpisah. Lihat `bridges/whatsmeow/README.md` untuk protokolnya. Hasil mock test bukan bukti bahwa binary Go atau koneksi WhatsApp live sudah diuji.
+- **Native KersioSocket** — tetap menyediakan codec WABinary, Noise framing, IQ/node protocol, dan adapter pairing awal; fitur autentikasi dan enkripsi pesan native belum lengkap untuk sesi live.
+
+## Install dan tests
+
+Butuh Node.js **22.5 atau lebih baru**. Engine eksternal bersifat opsional supaya pemasangan core tidak memaksa dua client tambahan.
+
+```bash
+npm install
+npm test
+npm run test:serial
+npm run test:backends
+npm run bench:wabinary
+```
+
+Instal engine yang memang ingin dipakai:
+
+```bash
+npm install zapo-js
+# atau
+npm install @whiskeysockets/baileys
+```
+
+Untuk Zapo dengan SQLite gunakan paket add-on yang didokumentasikan Zapo, misalnya `@zapo-js/store-sqlite` bersama driver `better-sqlite3`. Ikuti persyaratan OS/runtime driver dan dokumentasi upstream. Library ini tidak memasang/mengonfigurasi database server secara otomatis.
+
+## API umum
+
+```js
+const { createKersioClient } = require('kersiosocket')
+
+// zapoClient adalah instance WaClient zapo-js yang sudah kamu konfigurasi dan kelola
+const zapoClient = createYourConfiguredZapoClient()
+const client = await createKersioClient({ engine: 'zapo', client: zapoClient, sessionId: 'akun-1' })
+client.on('pairing.qr', ({ qr }) => console.log('QR:', qr))
+client.on('pairing.code', ({ code }) => console.log('Pairing code:', code))
+client.on('messages.upsert', async ({ messages }) => {
+  for (const message of messages) console.log(message.key?.remoteJid, message.message)
+})
+client.on('connection.update', (update) => console.log('connection:', update.connection))
+client.on('backend.error', ({ error }) => console.error(error))
+
+await client.connect()
+// Kirim hanya sesudah backend memberi status connection.update open.
+await client.sendText('6281234567890@s.whatsapp.net', 'Halo dari KersioSocket')
+await client.close()
+```
+
+Ganti `createYourConfiguredZapoClient()` dengan inisialisasi `WaClient` milikmu, seperti contoh lengkap pada bagian Zapo-JS di bawah.
+
+### Zapo-JS
+
+```js
+const { createKersioClient } = require('./src')
+const { createStore, WaClient, ConsoleLogger } = require('zapo-js')
+const { createSqliteStore } = require('@zapo-js/store-sqlite')
+
+const store = createStore({
+  backends: { sqlite: createSqliteStore({ path: '.auth/state.sqlite' }) },
+  providers: {
+    auth: 'sqlite', signal: 'sqlite', preKey: 'sqlite', session: 'sqlite',
+    identity: 'sqlite', senderKey: 'sqlite', appState: 'sqlite', privacyToken: 'sqlite',
+    messages: 'sqlite', threads: 'sqlite', contacts: 'sqlite'
+  }
+})
+const zapoClient = new WaClient({ store, sessionId: 'akun-1' }, new ConsoleLogger('info'))
+const client = await createKersioClient({ engine: 'zapo', client: zapoClient, sessionId: 'akun-1' })
+client.on('pairing.qr', ({ qr }) => console.log(qr))
+client.on('messages.upsert', ({ messages }) => console.log(messages.length, 'pesan'))
+await client.connect()
+```
+
+KersioSocket tidak otomatis menyimpan credentials Zapo sendiri. Store milik Zapo harus menyimpan provider `auth`, `signal`, `preKey`, `session`, `identity`, `senderKey`, dan `appState` sebagaimana dibutuhkan engine. Pertahankan dokumentasi dan versi Zapo yang dipakai.
+
+### Baileys
+
+```js
+const baileys = await import('@whiskeysockets/baileys')
+const { state, saveCreds } = await baileys.useMultiFileAuthState('./auth-baileys')
+const client = await require('./src').createKersioClient({
+  engine: 'baileys',
+  socketOptions: { auth: state, printQRInTerminal: false },
+  baileysModule: baileys
+})
+client.on('creds.update', saveCreds)
+client.on('pairing.qr', ({ qr }) => console.log(qr))
+client.on('messages.upsert', ({ messages }) => console.log(messages.length))
+await client.connect()
+```
+
+Untuk penggunaan serius, ikuti panduan upstream tentang penyimpanan credentials/Signal keys dan dampak perubahan versi API Baileys. `useMultiFileAuthState` ditujukan sebagai contoh/kemudahan; rancang storage persisten yang tepat untuk production.
+
+### Go `whatsmeow`
+
+```js
+const { createKersioClient } = require('./src')
+const client = await createKersioClient({
+  engine: 'whatsmeow',
+  sessionId: 'akun-go',
+  bridge: { command: './whatsmeow-bridge', args: [] }
+})
+client.on('messages.upsert', ({ messages }) => console.log(messages))
+await client.connect()
+await client.sendText('6281234567890@s.whatsapp.net', 'Halo dari bridge Go')
+```
+
+`./whatsmeow-bridge` harus executable sidecar yang implementasi JSONL RPC-nya mengikuti `bridges/whatsmeow/README.md`; binary tersebut tidak ada di ZIP ini. KersioSocket tidak mengklaim API Go live sampai sidecar yang dipilih terbangun dan diuji sendiri.
+
+## API pesan terpadu
+
+```js
+await client.sendMessage(jid, { text: 'Halo' })
+await client.sendText(jid, 'Halo')
+await client.sendImage(jid, Buffer.from(imageBytes), { caption: 'Foto' })
+await client.sendVideo(jid, Buffer.from(videoBytes), { caption: 'Video' })
+await client.sendAudio(jid, Buffer.from(audioBytes), { mimetype: 'audio/ogg' })
+await client.sendDocument(jid, Buffer.from(fileBytes), { fileName: 'contoh.pdf', mimetype: 'application/pdf' })
+await client.sendSticker(jid, Buffer.from(webpBytes))
+await client.sendLocation(jid, { latitude: -6.2, longitude: 106.8, name: 'Jakarta' })
+await client.sendContact(jid, { displayName: 'Nama', vcard: 'BEGIN:VCARD\\nVERSION:3.0\\nFN:Nama\\nEND:VCARD' })
+await client.sendPoll(jid, { name: 'Pilih', values: ['A', 'B'], selectableCount: 1 })
+await client.react(jid, messageKey, '👍')
+await client.editMessage(jid, messageKey, 'Teks baru')
+await client.deleteMessage(jid, messageKey)
+```
+
+These are normalized content objects passed to the selected engine. Not every backend/version supports every payload. Feature-specific operations fail explicitly when no implementation is exposed; KersioSocket does not claim that constructing an object proves server support. Group/app-state methods can be accessed through `client.invoke(...)`, using the method/path documented by the chosen backend. Avoid invoking untrusted method names from user input.
+
+## Multi-session
+
+```js
+const { createKersioSessionManager } = require('./src')
+const manager = createKersioSessionManager()
+const a = await manager.open('akun-zapo', { engine: 'zapo', client: zapoClient })
+const b = await manager.open('akun-baileys', { engine: 'baileys', socketOptions: { auth: baileysAuth } })
+console.log(manager.stats())
+await manager.close('akun-zapo')
+await manager.closeAll()
+```
+
+This manager prevents duplicate session IDs within one process. It is not a substitute for a distributed scheduler or lock when several processes share one auth database.
+
+## Storage dan stabilitas
+
+- Existing `MemoryStore`, `FileStore`, `SQLiteStore`, `RedisStore`, `MongoStore`, and `EncryptedStore` are retained.
+- `MessageArchive` stores per-chat message history up to a configurable limit and exposes `getMessage(key)` for retry/reply retrieval.
+- `FileLockManager` provides cooperative local-filesystem lock leases; `LockedStore` wraps operations under those locks. Do not treat this as a distributed lock for network filesystems.
+- Existing Redis/Mongo adapter tests use fake clients. Set up real services and integration-test them before production.
+- Benchmarks cover local WABinary codec paths only. No cross-library speed claim is made.
+
+Example encrypted storage:
+
+```js
+const { FileStore, EncryptedStore } = require('./src')
+const key = Buffer.from(process.env.KERSIO_STORE_KEY_HEX || '', 'hex')
+if (key.length !== 32) throw new Error('KERSIO_STORE_KEY_HEX wajib 64 digit hex')
+const store = new EncryptedStore(new FileStore('./sessions'), key)
+```
+
+Use a secret manager or environment injection for the master key; never commit it with the source. Use an encrypted store for auth state when storing it through generic Kersio stores.
+
+## Security gates — native engine
+
+- `Connection` now defaults to `strictServerCertificateVerification: true`. Without `verifyServerCertificate` returning exactly `true`, a synthetic/local Noise handshake may be tested only with explicit `strictServerCertificateVerification: false`. Do not turn this off against a live server.
+- A verifier callback is a hook, not a built-in WhatsApp root certificate chain. Pin and independently test the exact root/intermediate certificates before supplying one.
+- `commitVerifiedPairSuccess()` requires a supplied, independently tested verifier returning `deviceIdentity`, `accountSignature`, and `advHmac` checks, credentials, and a reply node. It is a fail-closed persistence guard, not the cryptographic verifier itself.
+- Native `Signal Protocol`, prekey upload, session crypto and message-node transforms are not implemented end-to-end. Native mode intentionally throws for high-level message use.
+
+## Tests & evidence
+
+`npm test` covers local unit/mocked tests. This package was **not** connected to a real WhatsApp account during this build. Do not interpret passing unit tests as proof of pairing, media upload, message delivery, app-state sync, or engine interoperability. See `docs/ENGINE-MATRIX.md`, `docs/RESEARCH-BASELINE.md`, and `docs/PROTOCOL-ROADMAP.md`.
+
+## Upstream references / licenses
+
+- [Baileys](https://github.com/WhiskeySockets/Baileys) — review current v7 migration notes and license before use.
+- [Zapo-JS](https://github.com/vinikjkkj/zapo) — package + optional storage/media/native add-ons; MIT upstream license.
+- [whatsmeow](https://github.com/tulir/whatsmeow) — Go implementation, MPL-2.0 upstream license.
+
+KersioSocket is not affiliated with WhatsApp. Respect the respective upstream licenses and WhatsApp's applicable terms. Do not use this library for unsolicited bulk messaging or abusive automation.

package/bench/wabinary.js

@@ -0,0 +1,31 @@
+'use strict'
+
+const { performance } = require('node:perf_hooks')
+const { encodeBinaryNode, decodeBinaryNode, loadTokenTable } = require('../src/wabinary/codec')
+
+const iterations = Number.parseInt(process.env.KERSIO_BENCH_ITERATIONS || '25000', 10)
+if (!Number.isSafeInteger(iterations) || iterations < 100 || iterations > 2_000_000) {
+  throw new RangeError('KERSIO_BENCH_ITERATIONS harus 100..2000000')
+}
+const tokens = loadTokenTable()
+const node = {
+  tag: 'iq',
+  attrs: { id: 'kersiosocket-benchmark-0001', type: 'get', to: 's.whatsapp.net', xmlns: 'w:p' },
+  content: [{ tag: 'ping', attrs: { t: '1234567890' } }]
+}
+const bytes = encodeBinaryNode(node, { tokens })
+for (let i = 0; i < Math.min(2000, iterations); i++) {
+  encodeBinaryNode(node, { tokens })
+  decodeBinaryNode(bytes, { tokens, requirePrefix: true })
+}
+function measure(label, fn) {
+  const start = performance.now()
+  for (let i = 0; i < iterations; i++) fn()
+  const elapsedMs = performance.now() - start
+  console.log(`${label}: ${Math.round(iterations / (elapsedMs / 1000)).toLocaleString()} ops/s (${elapsedMs.toFixed(1)} ms, ${iterations} ops)`)
+}
+console.log('KersioSocket WABinary local benchmark')
+console.log(`Node ${process.version}; iterations=${iterations}; sampleBytes=${bytes.length}; DictVersion=${tokens._metadata?.dictVersion ?? 'custom/empty'}`)
+console.log('Warm-up applied. Run on an otherwise idle machine; this is not a comparison against Go/Baileys.')
+measure('encode', () => { encodeBinaryNode(node, { tokens }) })
+measure('decode', () => { decodeBinaryNode(bytes, { tokens, requirePrefix: true }) })

package/bridges/whatsmeow/README.md

@@ -0,0 +1,42 @@
+# KersioSocket ↔ Go `whatsmeow` bridge contract
+
+KersioSocket includes a tested JSON Lines RPC transport in `src/backends/whatsmeow-process.js`. It does **not** bundle a precompiled Go executable or claim that an uncompiled Go sample is production-ready. Build and audit the Go sidecar against the exact `whatsmeow` version you choose, then pass its executable to `createKersioClient({ engine: 'whatsmeow', bridge: { command, args } })`.
+
+This is deliberately a transport contract, not an invented WhatsApp protocol implementation. The Go process must use the public `whatsmeow` client, its supported store and its own event handlers. `whatsmeow` has a separate MPL-2.0 license; retain its notices if you distribute its source or binary. KersioSocket itself does not copy its protocol implementation.
+
+## Standard input / standard output
+
+Each request is one UTF-8 JSON object terminated by `\n`:
+
+```json
+{"id":"request-1","method":"connect","params":{"sessionId":"account-a"}}
+```
+
+The sidecar returns one matching response line:
+
+```json
+{"id":"request-1","result":{"connected":true}}
+```
+
+Errors have this shape:
+
+```json
+{"id":"request-2","error":{"code":"ERR_OPERATION","message":"Readable explanation"}}
+```
+
+Asynchronous events use a line without `id`:
+
+```json
+{"event":"messages.upsert","data":{"type":"notify","messages":[]}}
+```
+
+The client currently sends these method names: `connect`, `sendMessage`, `requestPairingCode`, `downloadMedia`, `capabilities`, `invoke`, and `close`. A sidecar may implement additional operations through `invoke`, but the method should be allow-listed by the Go program. Buffers/Uint8Arrays are encoded as `{"$base64":"..."}`; the Go sidecar is responsible for decoding that marker where appropriate. Large media should preferably be streamed or passed by file reference rather than copied through JSONL.
+
+## Security and process model
+
+- The bridge is spawned with `shell: false`; command and args must be provided separately.
+- Use a private working directory and a dedicated session database per account.
+- Never log QR payloads, pairing codes, auth credentials, or message content to stderr.
+- Return structured errors; do not write non-JSON diagnostics to stdout.
+- The Node adapter bounds the maximum response line and the number of pending RPCs, and times out requests.
+- This bridge contract has a mock-process test. That test proves JSONL transport semantics only, not a live `whatsmeow` connection.

package/docs/ENGINE-MATRIX.md

@@ -0,0 +1,23 @@
+# v0.6.0-dev engine matrix
+
+This matrix separates features supplied by an upstream engine from features implemented in KersioSocket's own native transport. A green-looking facade method is never evidence of a successful live server operation.
+
+| Capability | Zapo-JS adapter | Baileys adapter | Go `whatsmeow` bridge | Native KersioSocket |
+|---|---|---|---|---|
+| QR / pairing code | Delegated to Zapo; observed auth events normalized | Delegated to Baileys; QR and requestPairingCode mapped | Only if sidecar implements RPC method/events | QR candidate helper only; no verified pair-success implementation |
+| Noise/TLS-like transport trust | Managed by upstream engine | Managed by upstream engine | Managed by whatsmeow in the sidecar | Fail-closed by default; verifier must be injected and independently tested |
+| Signal identity, prekeys, sessions, message crypto | Delegated to Zapo | Delegated to Baileys | Delegated to whatsmeow sidecar | Not implemented end-to-end |
+| Text send and inbound message events | Delegated through `message.send` and event adapter | Delegated through `sendMessage` / `messages.upsert` | Delegated through JSONL RPC | Not supported by native high-level API |
+| Image/video/audio/document/sticker | Delegated; check engine version and media package | Delegated; media upload helpers belong to Baileys | Sidecar must implement media operations | Not implemented |
+| Reactions, polls, edit/delete | Delegated content object; backend support varies | Delegated content object; backend support varies | Sidecar must implement operation | Not implemented |
+| Groups, contacts, app-state/history | Feature detect / backend `invoke()` | Socket methods/events / backend `invoke()` | Sidecar `invoke()` and events | Not implemented end-to-end |
+| Session persistence | Zapo store providers | Baileys auth state/keys | Go store in sidecar | Generic stores and EncryptedStore, but no full native WA auth bundle |
+| Multi-session facade | Supported per distinct session/client | Supported per distinct socket | Supported per distinct bridge process/session | Existing low-level manager retained; live auth not complete |
+| Production live integration evidence in this ZIP | **Not run** | **Not run** | **Not run; sidecar absent** | **Not run; intentionally incomplete** |
+
+## Boundaries
+
+- The engine adapters normalize the public API surface; they do not exchange live crypto keys between implementations.
+- For one linked WhatsApp account, use one selected engine as the owner of transport, auth, and Signal state. Don't open the same credentials in all engines concurrently.
+- Zapo and Baileys adapter tests use fake EventEmitters. The Go bridge tests use a fake child process. Tests cover event and RPC semantics only.
+- Native Noise certificate verification callback returns a trusted boolean only if the caller has implemented and tested the complete chain. A callback that merely accepts all certificates defeats the default protection.

package/docs/PROTOCOL-ROADMAP.md

@@ -0,0 +1,74 @@
+# Protocol roadmap — KersioSocket v0.6.0-dev
+
+## Layer saat ini
+
+```text
+WebSocket transport + reconnect
+  └─ raw 3-byte length framing
+      └─ Noise XX + encrypted transport (server certificate verification: NOT IMPLEMENTED)
+          └─ ClientPayload protobuf encoder + DeviceProps helper
+              └─ WABinary node codec + versioned token data
+                  └─ NodeProtocol events / pending IQ query
+                      └─ early QR adapter (pair-device refs; no success verification)
+                          └─ credential persistence / authenticated pairing [NEXT GATE]
+                              └─ Signal Protocol + prekeys [NOT IMPLEMENTED]
+                                  └─ messages / media / groups / app-state [NOT IMPLEMENTED]
+```
+
+## v0.5.0-dev implemented and locally tested
+
+- WABinary standard prefix and compression prefix, single/double dictionary indexes, packed nibble/hex, JID pair/AD-JID encode/decode, bounded parse and explicit fixture bytes.
+- Node-level event dispatch and IQ request tracking with timeout, AbortSignal cancellation, result/error response handling, max-pending cap, connection-close cleanup.
+- DeviceProps/HistorySyncConfig encoders and construction of ClientPayload registration data from caller-supplied values. `createDevicePairingData()` does not generate or validate key/signature data.
+- Early QR adapter acknowledges `iq/pair-device`, formats QR payload candidates from server `ref` values, and refuses to label `pair-success` as verified.
+- AES-256-GCM encrypted store wrapper with 12-byte random IV, 16-byte auth tag, AAD binding to storage key, no plaintext fallback.
+- Listener-error isolation, protocol fail-closed path, tests and local benchmark.
+
+## Blocking gates before a live account attempt
+
+1. Implement and independently test Noise certificate-chain verification against the correct root/issuer and schema. Today stats explicitly report `serverCertificateVerified: false`.
+2. Obtain byte-level interoperability fixtures for a pinned Web build from an independent encoder/decoder. Current WABinary golden fixtures verify a limited sample, not all server-generated node variants.
+3. Build proper auth credentials: separate Noise static key, Signal identity key, registration ID, signed prekey and verifiable signature. Use only crypto primitives and encodings whose behavior is independently tested.
+4. Verify the complete `pair-success` chain: decode device identity; validate ADV HMAC, account signature and required fields; produce the `pair-device-sign` reply; persist updated auth credentials atomically; only then transition lifecycle to paired.
+5. Implement pairing-code flow with test vectors for PBKDF2 parameters, IV handling, AES-CTR, framing and exact wire node layout. No pairing-code event is claimed by this version.
+6. Implement Signal Protocol, prekey upload, session state, incoming/outgoing message crypto, retry receipts, then event APIs such as `messages.upsert` and `sendMessage`.
+7. Run integration tests against live Redis/Mongo (if used) and multi-session soak tests; quantify RAM and latency with repeatable benchmarks.
+
+## Security notes
+
+- Noise static/ephemeral keys and Signal identity/signed-prekey keys have separate roles.
+- Correct protobuf field lengths do not make a cryptographic signature valid.
+- Receiving `pair-success` is not sufficient to mark paired.
+- Session encryption depends on user-managed master key storage/rotation; a lost key means stored session values cannot be decrypted.
+- Public reverse-engineering material is not an official stable specification; record commits/blob hashes and revalidate when targeting another server build.
+
+## v0.6 integrated engine architecture
+
+The high-level facade can select a maintained backend, while keeping the native protocol research layer separate:
+
+```text
+KersioClient / KersioSessionManager
+  ├─ Zapo-JS WaClient adapter (auth + Signal + messages delegated upstream)
+  ├─ Baileys socket adapter (auth + Signal + messages delegated upstream)
+  ├─ Go whatsmeow JSONL-RPC process transport (the Go binary is external)
+  └─ native KersioSocket research transport (not a complete live WA engine)
+```
+
+This is an API-level integration, not one merged auth/Signal state machine. A linked account must be owned by one engine at a time. The adapters are tested against mocks; real upstream integration remains a separate verification gate.
+
+## v0.6 local improvements
+
+- Native Noise handshake defaults to requiring an explicitly supplied certificate verifier; no pinned WhatsApp certificate-chain verifier is included, so strict native connection intentionally fails closed until one is implemented and audited.
+- `commitVerifiedPairSuccess` rejects state transitions unless an external verifier returns successful device identity, account signature and ADV-HMAC checks plus credentials/reply node. The callback contract is a safety gate, not an implementation of the cryptographic verifier.
+- Common client facade, event normalization, message helpers, multi-engine session manager, bounded message archive, and cooperative local file locks.
+- Go adapter implements request/reply correlation, JSONL size bound, request timeout/pending cap, abort handling, structured errors and async events. It does not bundle a Go sidecar or prove live whatsmeow connectivity.
+
+## Remaining native protocol gates
+
+1. Obtain and pin the current trusted Noise certificate/root chain, implement verification against independent vectors, and confirm behavior against a live-compatible fixture. Do not accept all certificates.
+2. Implement/test verified account pairing: device identity parsing, ADV HMAC, account/device signatures, correct `pair-device-sign` node, and atomic credential update.
+3. Implement a standards-compatible Signal layer with identity/signed prekeys, signature validation, prekey upload, session creation/rotation, group sender keys, and encrypted inbound/outbound message tests.
+4. Implement real WABinary message stanza lifecycle, receipts, offline retry/decryption retry and deduplication.
+5. Add per-backend media upload/download, group APIs, sync/app-state/status/newsletter features, each gated on live or independently captured interoperability tests.
+6. Build/compile the selected Go sidecar against a pinned whatsmeow release and run Go+Node integration tests; the bundled mock only checks bridge protocol semantics.
+7. Run real Redis/Mongo, crash-recovery, cross-process lock, long-duration memory and fair side-by-side latency tests before making production or performance claims.

package/docs/RESEARCH-BASELINE.md

@@ -0,0 +1,36 @@
+# Protocol research baseline
+
+Snapshot prepared for KersioSocket v0.5.0-dev. These references are useful for understanding observed wire behavior, not official support contracts. The Git blob hashes below identify the specific retrieved file contents; branch URLs can move later.
+
+| Topic | Reference file | Retrieved Git blob SHA / revision | How used |
+|---|---|---|---|
+| WABinary encoder | [Baileys `src/WABinary/encode.ts`](https://github.com/WhiskeySockets/Baileys/blob/master/src/WABinary/encode.ts) | `c883e6ed21d1fd5d54619b9427435f1eb6166941` | Standard prefix, list/string encoding, packed strings, JID encoding decisions |
+| WABinary decoder | [Baileys `src/WABinary/decode.ts`](https://github.com/WhiskeySockets/Baileys/blob/master/src/WABinary/decode.ts) | `b0183d858c2d42dfc24feb1a00108d649f87df89` | Prefix handling, packed-length semantics, JID token variants |
+| WAProto schema | [Baileys `WAProto/WAProto.proto`](https://github.com/WhiskeySockets/Baileys/blob/master/WAProto/WAProto.proto) | `d76317480be18c2f7576efc8e86b8608a3b655ca` | Snapshot field numbers/enums for ClientPayload, UserAgent, WebInfo, DeviceProps, HistorySyncConfig |
+| Connection defaults | [Baileys `src/Defaults/index.ts`](https://github.com/WhiskeySockets/Baileys/blob/master/src/Defaults/index.ts) | `b4c7810087194d39e311e4f38702befb2c779258` | Observed dictionary version/header convention and connection config concepts |
+| QR/pair-success | [Baileys `src/Utils/validate-connection.ts`](https://github.com/WhiskeySockets/Baileys/blob/master/src/Utils/validate-connection.ts) | `9bfc5d6891e16dd37881606f5e5300b301b7e646` | Ref-based QR flow, registration fields, `DeviceProps`, HMAC/signature verification path |
+| Token data | [whatsmeow `binary/token/token.go`](https://github.com/tulir/whatsmeow/blob/b2b1e71d45e2ff171153b025b5a42f475bb30ef8/binary/token/token.go) | commit `b2b1e71d45e2ff171153b025b5a42f475bb30ef8`; Git blob SHA-1 `361acd19d93c8dea30f516e27ce8c77fdaecc56f`; `DictVersion=3` | Version-pinned third-party token data imported by script; MPL-2.0 notice retained |
+
+## Facts established by the referenced source snapshots
+
+- Baileys WABinary encoder initializes its output with one byte `0x00`; the decoder recognizes an uncompressed prefix and a compressed prefix. KersioSocket now has a pinned golden fixture for a small `iq/get/ping` node, not a complete conformance suite.
+- `NIBBLE_8` and `HEX_8` store the count of packed bytes in the low seven bits and use the high bit to indicate odd character count. KersioSocket tests odd-length packed values.
+- `DeviceProps` snapshot fields are `os=1`, `version=2`, `platformType=3`, `requireFullSync=4`, `historySyncConfig=5`; HistorySyncConfig field numbers are recorded in `src/proto/device-props.js`.
+- In the inspected registration code, `eRegid` is encoded big-endian, `eKeytype` is `[5]`, `eIdent` is an identity public key, `eSkeyId` is 3-byte big-endian, `eSkeyVal` is a signed-prekey public key, `eSkeySig` is the pre-existing signature, `buildHash` is MD5 of dotted version text, and `deviceProps` is protobuf bytes.
+- Pairing success handling validates HMAC/signatures and returns a `pair-device-sign` reply in the inspected source; KersioSocket has not implemented that verifier/reply and does not mark `pair-success` as completed.
+- The token table is from a public reverse-engineering repository under MPL-2.0, not from an official WhatsApp-issued schema. Importer validation checks exact upstream blob hash, dictionary version and table dimensions; it does not independently validate against a live server.
+
+## Not claimed
+
+No successful live WhatsApp login/pair was observed in this build. No live WebSocket interoperability, Noise server certificate verification, Signal session crypto, or `sendMessage` is claimed. Node.js unit tests and local round-trips are only local evidence.
+
+
+## v0.6.0-dev adapter research update (2026-10-23)
+
+This release adds adapters around public upstream client APIs rather than copying their protocol implementation into KersioSocket:
+
+- Baileys public repository/docs: https://github.com/WhiskeySockets/Baileys — adapter targets the current socket factory/event API; upstream notes v7 has breaking changes, so pin versions and run an integration test.
+- Zapo-JS public repository/docs: https://github.com/vinikjkkj/zapo — adapter targets `WaClient`, `connect()`, `message.send()`, and public auth/message events; the chosen store providers are configured by the caller.
+- whatsmeow public repository: https://github.com/tulir/whatsmeow — KersioSocket only provides JSONL-RPC process transport. It does not include a Go implementation or executable; the bridge's transport tests use a fake process.
+
+No live account/session was connected during this build. The v0.6 adapter tests demonstrate method forwarding and event normalization, not protocol interoperability or upstream-version compatibility.

package/docs/WABINARY.md

@@ -0,0 +1,37 @@
+# KersioSocket WABinary codec — v0.5.0-dev
+
+## Shape data
+
+Node yang didukung:
+
+```js
+{ tag: 'iq', attrs: { id: 'fixture-1', type: 'get' }, content: [ { tag: 'ping', attrs: {} } ] }
+```
+
+`encodeBinaryNode()` mengeluarkan `0x00` + node tanpa kompresi secara default. Dengan `{ compress: true }`, ia mengeluarkan `0x02` + zlib-deflate body. `decodeBinaryNode()` membaca prefix itu secara default; `requirePrefix: true` menolak data yang tidak diawali prefix dikenal. `withPrefix: false` hanya tersedia untuk fixture/alat lokal, bukan untuk `sock.sendNode()`.
+
+Codec mendukung list `LIST_EMPTY/8/16`, raw UTF-8 `BINARY_8/20/32`, empat halaman dictionary double-byte, single-byte tokens, binary node content, packed `NIBBLE_8` dan `HEX_8`, JID pair dan AD-JID, serta decode FB-JID/INTEROP-JID berdasarkan bentuk referensi yang dipelajari. Penulisan FB-JID/INTEROP-JID khusus belum diimplementasikan; nilai JID tersebut dapat jatuh kembali ke JID_PAIR biasa. Validasi membatasi byte input/output, kedalaman, node count, index token, list, dan data terpotong.
+
+## Token dictionary
+
+`src/wabinary/tokens.json` sengaja dikemas kosong pada ZIP; jalankan `npm run refresh:tokens`. Importer menggunakan sumber `tulir/whatsmeow/binary/token/token.go` pada commit `b2b1e71d45e2ff171153b025b5a42f475bb30ef8`, memastikan Git blob SHA-1 `361acd19d93c8dea30f516e27ce8c77fdaecc56f`, `DictVersion=3`, 236 entri single-byte dan empat page berisi 256 entri. Data itu memiliki atribusi/lisensi MPL-2.0 tersendiri; lihat `licenses/THIRD-PARTY-NOTICES.md`.
+
+Parser token table memverifikasi dimensi dan versi bila metadata importer ada. Ini memvalidasi asal dan bentuk data, **bukan** keaktifan tabel terhadap WhatsApp server tertentu. Jangan ubah nomor token dengan perkiraan.
+
+## Fixtures dan bukti
+
+`test/wabinary.test.js` berisi byte fixture eksplisit untuk node ping dengan token indeks yang tercatat pada data v3, tes binary string, JID device, kompresi, malformed input, serta round-trip. Golden fixture menguji format pada sample khusus itu; belum mewakili semua node yang dikeluarkan server. Tes live/interoperability independen masih harus dilakukan.
+
+## Cara terhubung ke socket
+
+`NodeProtocol` mendengarkan plaintext frame setelah decrypt Noise dan memanggil `decodeBinaryNode`. Jika decode gagal, defaultnya fail-closed: ia mengeluarkan `protocol.error` dan menutup koneksi. `sendNode()` meng-encode prefix standar dan mengirimnya melalui Noise transport. `query()` mengelola IQ pending berdasarkan ID, timer timeout, AbortSignal, dan error balasan.
+
+NodeProtocol memerlukan dictionary nonkosong ketika menggunakan tabel default. Untuk smoke tests internal, boleh memasok token table fixture secara eksplisit. Jangan gunakan empty table untuk menganggap decoder siap menangani server tokenized.
+
+## Batas yang diketahui
+
+- Prefix/codec dan token table sudah diuji lokal, belum dibandingkan dengan server aktif.
+- Decoder tidak mengimplementasikan semua variasi node/JID yang pernah diamati.
+- Decoder ini mengharapkan satu node WABinary per plaintext frame; stream framing di lapisan sebelumnya yang menentukan batas frame.
+- Kompresi hanya didukung melalui bentuk prefix dan zlib yang diuji; tidak berarti semua variasi kompresi server didukung.
+- `NodeProtocol` bukan message layer: belum ada Signal session, message stanza transforms, upload media atau receipts.

package/examples/basic.js

@@ -0,0 +1,10 @@
+'use strict'
+const { makeSocket } = require('../src')
+
+// Native transport/protocol research only. It fails closed by default because this
+// project version does not ship a pinned Noise certificate-chain verifier. Do not
+// disable strictServerCertificateVerification for a live server.
+const sock = makeSocket({ autoConnect: false, reconnect: { enabled: false } })
+console.log('[KersioSocket] native research socket created; no network connection was opened.')
+console.log('state:', sock.state, 'stats:', sock.stats())
+sock.end()

package/examples/client-payload.js

@@ -0,0 +1,21 @@
+'use strict'
+// Local encoding smoke test only. These values are synthetic, not valid credentials.
+const { encodeClientPayload } = require('../src')
+
+const bytes = encodeClientPayload({
+  mode: 'login',
+  username: '6281234567890',
+  passive: false,
+  pushName: 'Kersio local test',
+  userAgent: {
+    platform: 'WEB',
+    appVersion: [2, 3000, 1040000000],
+    localeLanguage: 'id',
+    localeCountry: 'ID'
+  },
+  webInfo: { version: 'test-version-only', webSubPlatform: 'WEB_BROWSER' },
+  connectType: 'WIFI_UNKNOWN',
+  connectReason: 'USER_ACTIVATED'
+})
+
+console.log({ bytes: bytes.length, hexPrefix: bytes.subarray(0, 16).toString('hex') })

package/examples/device-props.js

@@ -0,0 +1,18 @@
+'use strict'
+const { encodeDeviceProps, buildAppVersionHash } = require('../src')
+
+// Local schema example only. It creates protobuf bytes, not account credentials.
+const appVersion = [2, 3000, 1043857760]
+const deviceProps = encodeDeviceProps({
+  os: 'Windows',
+  version: [10, 15, 7],
+  platformType: 'CHROME',
+  requireFullSync: true,
+  historySyncConfig: {
+    storageQuotaMb: 10240,
+    inlineInitialPayloadInE2EeMsg: true,
+    supportCagReactionsAndPolls: true
+  }
+})
+console.log({ devicePropsBytes: deviceProps.length, devicePropsHex: deviceProps.toString('hex'), appVersionHash: buildAppVersionHash(appVersion).toString('hex') })
+console.log('Fixture only: no private key, signed prekey signature, pairing, or live login is generated.')

package/examples/sessions.js

@@ -0,0 +1,11 @@
+'use strict'
+const { createSessionManager, FileStore } = require('../src')
+
+const sessions = createSessionManager({ store: new FileStore('./sessions'), logger: console })
+for (const id of ['nomor-a', 'nomor-b']) {
+  const sock = sessions.open(id)
+  sock.ev.on('connection.update', (u) => console.log(id, u.connection))
+  sock.ev.on('connection.error', (e) => console.error(id, e.message))
+}
+setInterval(() => console.log(JSON.stringify(sessions.stats())), 10000)
+process.on('SIGINT', async () => { await sessions.closeAll(); process.exit(0) })

package/examples/wabinary.js

@@ -0,0 +1,15 @@
+'use strict'
+
+const { encodeBinaryNode, decodeBinaryNode, loadTokenTable } = require('../src')
+
+// This demonstrates the codec with the project's intentionally empty token table.
+// It validates local structure/round-trip only; it is NOT a live WhatsApp fixture.
+const tokens = loadTokenTable()
+const sample = {
+  tag: 'iq',
+  attrs: { id: 'kersio-local-test', type: 'get', to: 's.whatsapp.net' },
+  content: [{ tag: 'ping', attrs: {} }]
+}
+const bytes = encodeBinaryNode(sample, { tokens })
+const decoded = decodeBinaryNode(bytes, { tokens })
+console.log({ bytes: bytes.length, hex: bytes.toString('hex'), decoded })

package/licenses/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,12 @@
+# Third-party notices
+
+KersioSocket implementation source is distributed under the MIT license stated in `package.json` and `LICENSE`.
+
+When `npm run refresh:tokens` is executed, the importer retrieves token **data** from [`tulir/whatsmeow`](https://github.com/tulir/whatsmeow/blob/b2b1e71d45e2ff171153b025b5a42f475bb30ef8/binary/token/token.go), commit `b2b1e71d45e2ff171153b025b5a42f475bb30ef8`, source blob SHA-1 `361acd19d93c8dea30f516e27ce8c77fdaecc56f`. That token data is identified by the upstream project as MPL-2.0. The importer saves the source license at `licenses/whatsmeow-MPL-2.0.txt` and embeds the source metadata in `src/wabinary/tokens.json`.
+
+Keep the generated metadata and license if redistributing an imported token table. The token table is reverse-engineered third-party data, not an official WhatsApp-issued table or a guarantee of current server compatibility. KersioSocket protocol/codec code is implemented separately; refer to `docs/RESEARCH-BASELINE.md` for researched source snapshots.
+
+
+## v0.6 adapter notes
+
+The Baileys and Zapo-JS adapters invoke their public package APIs at runtime and do not bundle their implementation source. Review the currently installed upstream versions' licenses before redistributing them. The optional Go whatsmeow process bridge is an RPC transport, not a copy or bundle of whatsmeow code; whatsmeow itself is distributed under MPL-2.0. See the upstream license files before distributing a Go sidecar.