kersiosocket 0.0.0-stage → 0.5.0-dev

package/BUILD-INFO.md

@@ -0,0 +1,14 @@
+# Build information — KersioSocket v0.5.0-dev
+
+- Package version: `0.5.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`
+- 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`.

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 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,146 @@
-# Temporary Holding Version
+# KersioSocket
 
-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.
+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
+npm install
+npm test
+```
+
+`ws` dipakai oleh adapter WebSocket dan merupakan peer dependency opsional:
+
+```bat
+npm install ws
+```
+
+### Impor token table
+
+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:
+
+```bat
+npm run refresh:tokens
+```
+
+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.
+
+## API singkat
+
+### Codec WABinary lokal
+
+```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)
+```
+
+### Socket + NodeProtocol
+
+Gunakan setelah token table sudah diimpor. Contoh ini membangun lapisan API, bukan berarti login aktif tersedia:
+
+```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() }
+})
+
+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: [...] })
+```
+
+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.
+
+### DeviceProps dan registration bundle
+
+```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 }
+})
+
+// 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
+})
+
+const bytes = encodeClientPayload({ mode: 'registration', userAgent, webInfo, devicePairingData: pairingData })
+```
+
+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.
+
+### Multi-session + encrypted store
+
+```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()
+```
+
+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.
+
+## Tes dan benchmark
+
+```bat
+npm test
+npm run test:serial
+npm run bench:wabinary
+```
+
+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.
+
+## Referensi riset
+
+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.

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/docs/PROTOCOL-ROADMAP.md

@@ -0,0 +1,43 @@
+# Protocol roadmap — KersioSocket v0.5.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.

package/docs/RESEARCH-BASELINE.md

@@ -0,0 +1,25 @@
+# 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.

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,18 @@
+'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'))

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