kersiosocket 0.5.0-dev → 0.6.0-dev

package/BUILD-INFO.md

@@ -1,14 +1,15 @@
-# Build information — KersioSocket v0.5.0-dev
+# Build information — KersioSocket v0.6.0-dev
 
-- Package version: `0.5.0-dev`
+- Package version: `0.6.0-dev`
 - Verification runtime: Node.js `v22.16.0`
-- Test suite: `60/60` passing with `npm test`
-- Serial test suite: `60/60` passing with `npm run test:serial`
-- Syntax checks: core WABinary, NodeProtocol, DeviceProps, and pairing adapter passed
-- Examples checked: `examples/wabinary.js`, `examples/device-props.js`, `examples/client-payload.js`
+- 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 only. They do not establish successful live WhatsApp authentication, current server compatibility, Noise server-certificate verification, signed pairing-success validation, Pairing Code flow, Signal Protocol interoperability, or `sendMessage` functionality. See `docs/RESEARCH-BASELINE.md` and `docs/PROTOCOL-ROADMAP.md`.
+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

@@ -1,5 +1,16 @@
 # 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.

package/README.md

@@ -1,146 +1,192 @@
-# KersioSocket
-
-Library protokol WhatsApp Web eksperimental yang ditulis sebagai proyek mandiri. Target desainnya adalah API event yang mudah dipakai, session store yang bisa diganti, isolasi multi-session, dan jalur data berbasis `Buffer` dengan batas input eksplisit.
-
-> **Status v0.5.0-dev: belum siap dipakai login WhatsApp secara live.** Tes lokal menguji format dan state internal. Kode ini belum memverifikasi rantai sertifikat Noise server, belum memiliki implementasi Signal Protocol, dan belum memverifikasi signature/HMAC `pair-success`. Karena itu, handshake Noise atau event QR bukan bukti akun berhasil tertaut.
-
-## Upgrade v0.5.0-dev
-
-- WABinary: prefix standar `0x00`, prefix zlib `0x02`, single/double token dictionary, raw UTF-8, binary values, packed nibble/hex, JID pair dan AD-JID, validasi panjang/kedalaman, serta fixture byte eksplisit.
-- Protobuf: encoder manual untuk subset `ClientPayload` berdasarkan schema snapshot yang tercatat, termasuk field opsional yang sebelumnya belum ada.
-- `DeviceProps`: encoder schema eksplisit, builder `createDevicePairingData()` dari kunci dan signed prekey **yang disediakan pemanggil**, ID big-endian, dan build hash MD5 dari versi aplikasi bertitik.
-- `NodeProtocol`: decoding node dari frame Noise, event `node`, `node:<tag>`, `iq`, `query()` dengan timeout/abort, penanganan error remote dan pembatas IQ pending.
-- QR adapter: menanggapi node `iq/pair-device` yang sudah di-decode, ack sesuai referensi, dan memancarkan kandidat payload QR dari `ref` yang diterima server. Adapter ini **tidak** mengesahkan `pair-success` atau menyimpan akun sebagai paired.
-- `EncryptedStore`: AES-256-GCM dengan IV acak, AAD terikat ke storage key, serta fail-closed jika kunci salah atau envelope dimodifikasi.
-- Koneksi: listener error terisolasi, kegagalan frame protokol fail-closed, dan metrik secara eksplisit melaporkan `serverCertificateVerified: false` sampai verifier sertifikat diterapkan.
-- Benchmark lokal WABinary dan dokumentasi baseline riset/versi.
-
-## Fitur dan batasannya
-
-| Bagian | Status di v0.5.0-dev |
-|---|---|
-| WebSocket, frame length prefix, reconnect backoff | Ada; koneksi target live belum diverifikasi menyeluruh |
-| Noise XX, X25519, AES-GCM | Lulus tes loopback; **verifikasi sertifikat server belum ada** |
-| WABinary encode/decode dan token version pin | Ada; fixture/golden test lokal. Token table tidak dibundel penuh dan perlu diimpor |
-| Node layer / IQ query | Ada; diuji dengan transport tiruan, belum seluruh alur server live |
-| `ClientPayload` / `DeviceProps` protobuf | Encoder schema snapshot dan fixture; bukan jaminan server menerima payload |
-| QR adapter dari `pair-device` | Ada sebagai adapter awal; butuh kredensial asli yang dibuat secara benar |
-| Verifikasi cryptographic `pair-success` dan simpan auth final | **Belum ada** |
-| Pairing code / PBKDF2 + AES-CTR end-to-end | **Belum ada** |
-| Signal Protocol, prekey upload, message encryption | **Belum ada** |
-| `messages.upsert`, `sendMessage`, media, group/app-state sync | **Belum ada** |
-| Store memory/file/SQLite/Redis/Mongo, LRU, multi-session | Ada; Redis/Mongo diuji dengan fake client, perlu integrasi server sungguhan |
-| Store AES-GCM untuk kredensial | Ada; kunci master harus dipasok dari secret manager/environment |
-
-## Setup di CMD Windows
-
-Ekstrak ZIP ke folder proyek, lalu di CMD:
-
-```bat
-cd /d C:\kersiosocket
+# KersioSocket v0.6.0-dev
+
+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
 ```
 
-`ws` dipakai oleh adapter WebSocket dan merupakan peer dependency opsional:
+Instal engine yang memang ingin dipakai:
 
-```bat
-npm install ws
+```bash
+npm install zapo-js
+# atau
+npm install @whiskeysockets/baileys
 ```
 
-### Impor token table
+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.
 
-ZIP sengaja menyertakan `src/wabinary/tokens.json` kosong. Untuk penggunaan NodeProtocol yang membaca traffic tokenized, jalankan importer yang mengambil data dari commit publik terpin dan memvalidasi source blob SHA-1 serta lisensi:
+## API umum
 
-```bat
-npm run refresh:tokens
-```
+```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))
 
-Importer memerlukan internet dari mesinmu. Hasilnya adalah dataset reverse-engineering publik, bukan tabel resmi WhatsApp dan bukan jaminan kompatibilitas versi server aktif. Simpan `licenses/whatsmeow-MPL-2.0.txt` dan `licenses/THIRD-PARTY-NOTICES.md` saat mendistribusikan hasil impor.
+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()
+```
 
-## API singkat
+Ganti `createYourConfiguredZapoClient()` dengan inisialisasi `WaClient` milikmu, seperti contoh lengkap pada bagian Zapo-JS di bawah.
 
-### Codec WABinary lokal
+### Zapo-JS
 
 ```js
-const { encodeBinaryNode, decodeBinaryNode, loadTokenTable } = require('./src')
-const tokens = loadTokenTable()
-const node = { tag: 'iq', attrs: { id: 'fixture-1', type: 'get' }, content: [{ tag: 'ping', attrs: {} }] }
-const bytes = encodeBinaryNode(node, { tokens }) // sudah menyertakan prefix 0x00
-const decoded = decodeBinaryNode(bytes, { tokens, requirePrefix: true })
-console.log(bytes.toString('hex'), decoded)
+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()
 ```
 
-### Socket + NodeProtocol
+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.
 
-Gunakan setelah token table sudah diimpor. Contoh ini membangun lapisan API, bukan berarti login aktif tersedia:
+### Baileys
 
 ```js
-const { makeSocket, loadTokenTable } = require('./src')
-const sock = makeSocket({
-  sessionId: 'fixture-session',
-  clientPayload: Buffer.alloc(0), // smoke-test transport saja; bukan payload login
-  nodeProtocol: { tokens: loadTokenTable() }
+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
 })
-
-sock.ev.on('connection.update', (update) => console.log(update.connection))
-sock.ev.on('node', (node) => console.log('node diterima:', node.tag))
-sock.ev.on('protocol.error', (error) => console.error(error.message))
-// sock.query({ tag: 'iq', attrs: { type: 'get', to: 's.whatsapp.net' }, content: [...] })
+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 NodeProtocol, jangan kirim query sesuka hati ke server live; panggil query hanya ketika koneksi dan sesi autentikasi memang sudah siap. `clientPayload: Buffer.alloc(0)` di atas sengaja menandakan smoke-test transport, bukan login.
+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.
 
-### DeviceProps dan registration bundle
+### Go `whatsmeow`
 
 ```js
-const { encodeDeviceProps, createDevicePairingData, encodeClientPayload } = require('./src')
-const deviceProps = encodeDeviceProps({
-  os: 'Windows', version: [10, 15, 7], platformType: 'CHROME', requireFullSync: true,
-  historySyncConfig: { storageQuotaMb: 10240, inlineInitialPayloadInE2EeMsg: true }
+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')
+```
 
-// identityPublicKey, signedPreKey.publicKey dan signedPreKey.signature harus berasal
-// dari implementasi kriptografi yang benar; helper ini TIDAK membuat atau memvalidasinya.
-const pairingData = createDevicePairingData({
-  registrationId: existingRegistrationId,
-  identityPublicKey: existingIdentityPublicKey,
-  signedPreKey: { keyId: existingSignedPreKeyId, publicKey: existingSignedPreKeyPublic, signature: existingValidSignature },
-  appVersion: [2, 3000, 1043857760],
-  deviceProps
-})
+`./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
 
-const bytes = encodeClientPayload({ mode: 'registration', userAgent, webInfo, devicePairingData: pairingData })
+```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)
 ```
 
-Nama `existing...` di atas adalah placeholder penjelas dan harus diganti oleh caller; contoh tersebut sengaja bukan file yang langsung bisa dijalankan. **Jangan** mengisi signature dengan data acak: ukuran yang benar tidak berarti signature sah. Proyek ini belum membuat signed prekey, belum memverifikasi cert chain Noise, dan belum menyelesaikan verifikasi pairing.
+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 + encrypted store
+## Multi-session
 
 ```js
-const { createSessionManager, FileStore, EncryptedStore } = require('./src')
-const masterKey = Buffer.from(process.env.KERSIO_STORE_KEY_HEX || '', 'hex')
-if (masterKey.length !== 32) throw new Error('KERSIO_STORE_KEY_HEX harus 64 digit hex (32 byte) dari secret manager')
-const store = new EncryptedStore(new FileStore('./sessions'), masterKey)
-const sessions = createSessionManager({ store, autoConnect: false })
-const a = sessions.open('akun-a')
-const b = sessions.open('akun-b')
-console.log(await sessions.list(), sessions.stats())
-// Shutdown: await sessions.closeAll()
+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()
 ```
 
-Jangan taruh master key di source code. `EncryptedStore` mengenkripsi values, tetapi perlindungan backup, akses folder, kunci master, dan koordinasi multi-proses tetap tanggung jawab deployment. Jangan jalankan dua proses terhadap akun/session yang sama tanpa lock terdistribusi.
+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.
 
-## Tes dan benchmark
+## Storage dan stabilitas
 
-```bat
-npm test
-npm run test:serial
-npm run bench:wabinary
+- 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)
 ```
 
-Benchmark menggunakan codec KersioSocket sendiri, warm-up dan sample tetap. Angka ops/s hanya baseline mesin lokal, bukan pembuktian bahwa KersioSocket lebih cepat daripada Go, Baileys, atau zapo-js. Uji di mesin idle, catat versi Node dan status token table jika membandingkan run.
+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
 
-## Referensi riset
+- [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.
 
-Lihat [`docs/RESEARCH-BASELINE.md`](docs/RESEARCH-BASELINE.md) untuk file referensi, blob hash, versi schema, hasil yang dapat disimpulkan, dan batas bukti. Lihat [`docs/PROTOCOL-ROADMAP.md`](docs/PROTOCOL-ROADMAP.md) untuk gate selanjutnya.
+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/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

@@ -1,4 +1,4 @@
-# Protocol roadmap — KersioSocket v0.5.0-dev
+# Protocol roadmap — KersioSocket v0.6.0-dev
 
 ## Layer saat ini
 
@@ -41,3 +41,34 @@ WebSocket transport + reconnect
 - 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

@@ -23,3 +23,14 @@ Snapshot prepared for KersioSocket v0.5.0-dev. These references are useful for u
 ## 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/examples/basic.js

@@ -1,18 +1,10 @@
 'use strict'
 const { makeSocket } = require('../src')
 
-// Smoke test transport/Noise only. No valid login or registration ClientPayload
-// is present here, so a live WhatsApp server may close the socket after Noise.
-console.warn('[demo] transport/Noise smoke test only; this example does not log in or pair an account.')
-
-const sock = makeSocket({
-  logger: console,
-  reconnect: { enabled: false }
-})
-
-sock.ev.on('connection.update', (u) => {
-  console.log('update:', u.connection, u.code ?? '')
-  if (u.connection === 'noise-ready') console.log('Noise handshake OK. Stats:', sock.stats())
-})
-sock.ev.on('connection.error', (e) => console.error('error:', e.message))
-sock.ev.on('frame', (f) => console.log('frame', f.length, 'byte'))
+// 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/licenses/THIRD-PARTY-NOTICES.md

@@ -5,3 +5,8 @@ KersioSocket implementation source is distributed under the MIT license stated i
 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.

package/package.json

@@ -1,39 +1,33 @@
 {
   "name": "kersiosocket",
-  "version": "0.5.0-dev",
-  "description": "Experimental WhatsApp Web protocol library with WABinary, NodeProtocol, encrypted multi-session stores and pairing research.",
+  "version": "0.6.0-dev",
+  "description": "Unified multi-engine WhatsApp Web client facade with Zapo-JS, Baileys, Go whatsmeow JSONL bridge, hardened native research transport, session archive and lock manager.",
   "main": "src/index.js",
   "engines": {
     "node": ">=22.5"
   },
-  "files": [
-    "src/",
-    "examples/",
-    "scripts/import-token-table.js",
-    "bench/wabinary.js",
-    "test/",
-    "docs/",
-    "licenses/",
-    "README.md",
-    "CHANGELOG.md",
-    "BUILD-INFO.md"
-  ],
   "scripts": {
     "test": "node --test \"test/*.test.js\"",
     "test:serial": "node --test --test-concurrency=1 \"test/*.test.js\"",
     "refresh:tokens": "node scripts/import-token-table.js",
-    "bench:wabinary": "node bench/wabinary.js"
+    "bench:wabinary": "node bench/wabinary.js",
+    "test:backends": "node --test test/unified-client.test.js test/backend-adapters.test.js test/whatsmeow-process.test.js"
   },
   "peerDependencies": {
-    "ws": ">=8"
+    "ws": ">=8",
+    "zapo-js": ">=1.0.0",
+    "@whiskeysockets/baileys": ">=7.0.0"
   },
   "peerDependenciesMeta": {
     "ws": {
       "optional": true
+    },
+    "zapo-js": {
+      "optional": true
+    },
+    "@whiskeysockets/baileys": {
+      "optional": true
     }
   },
-  "publishConfig": {
-    "access": "public"
-  },
   "license": "MIT"
-}
+}