kersiosocket 0.0.0-stage → 0.5.0-dev

package/src/socket/connection.js

@@ -0,0 +1,265 @@
+'use strict'
+/**
+ * Connection: WebSocket + Noise handshake + reconnect (exponential backoff + jitter).
+ *
+ * Event:
+ *   connection.update  { connection: 'connecting'|'handshaking'|'noise-ready'|'close', ... }
+ *   frame              Buffer plaintext hasil dekripsi Noise
+ *   connection.error   Error protokol/transport
+ *   handler.error      Error sinkron/async dari satu listener; listener lain tetap dipanggil
+ */
+const { EventEmitter } = require('node:events')
+const { createTransport } = require('./transport')
+const { FrameDecoder, encodeFrame } = require('./frame')
+const { ClientHandshake, WA_HEADER } = require('./noise')
+const { generateKeyPair, EMPTY } = require('../utils/crypto')
+const { LatencyTracker } = require('../utils/latency')
+const { encodeClientPayload } = require('../proto/client-payload')
+
+const noopLog = { debug() {}, info() {}, warn() {}, error() {} }
+
+const DEFAULTS = {
+  url: 'wss://web.whatsapp.com/ws/chat',
+  origin: 'https://web.whatsapp.com',
+  clientPayload: EMPTY, // empty buffer is transport smoke-test only; real login needs verified auth payload
+  // stableMs: koneksi baru dianggap 'sehat' (counter backoff direset) kalau bertahan selama ini
+  reconnect: { enabled: true, minDelay: 1000, maxDelay: 30000, factor: 2, stableMs: 30000 }
+}
+
+class Connection extends EventEmitter {
+  constructor(config = {}) {
+    super()
+    this.config = { ...DEFAULTS, ...config, reconnect: { ...DEFAULTS.reconnect, ...config.reconnect } }
+    this.log = config.logger || noopLog
+    const requestedPayload = this.config.clientPayload
+    if (Buffer.isBuffer(requestedPayload) || requestedPayload instanceof Uint8Array) {
+      this.clientPayload = Buffer.from(requestedPayload.buffer, requestedPayload.byteOffset, requestedPayload.byteLength)
+    } else if (requestedPayload && typeof requestedPayload === 'object') {
+      this.clientPayload = encodeClientPayload(requestedPayload)
+    } else {
+      throw new TypeError('clientPayload harus Buffer atau objek ClientPayload')
+    }
+    this.staticKey = config.staticKey || generateKeyPair()
+    this.state = 'close'
+    this.ended = false
+    this.attempt = 0
+    this.startedAt = 0
+    this.readyAt = 0
+    this.counters = { bytesIn: 0, bytesOut: 0, framesIn: 0, framesOut: 0 }
+    this.frameLatency = new LatencyTracker() // dekripsi + dispatch per frame
+    this.handshakeMs = 0
+    this._t = null
+    this._decoder = null
+    this._hs = null
+    this._noise = null
+    this._timer = null
+    this._generation = 0
+    this._closeHandled = false
+  }
+
+  connect() {
+    if (this._t) return
+    clearTimeout(this._timer)
+    this._timer = null
+    this.ended = false
+    this._setState('connecting')
+    const factory = this.config.transportFactory || createTransport
+    let t
+    try {
+      t = factory(this.config.url, { origin: this.config.origin, headers: this.config.headers })
+    } catch (err) {
+      this._safeEmit('connection.error', err)
+      this._setState('close', { error: err })
+      this._scheduleReconnect()
+      return
+    }
+    this._t = t
+    const generation = ++this._generation
+    this._closeHandled = false
+    t.on('open', () => {
+      if (this._t !== t || generation !== this._generation) return
+      try { this._onOpen() } catch (err) { this._abortConnection(err, t, generation) }
+    })
+    t.on('message', (d) => {
+      if (this._t !== t || generation !== this._generation) return
+      this._onMessage(d)
+    })
+    t.on('close', (code, reason) => this._onClose(code, reason, t, generation))
+    t.on('transport.error', (err) => {
+      if (this._t === t && generation === this._generation) this._safeEmit('connection.error', err)
+    })
+  }
+
+  end() {
+    this.ended = true
+    clearTimeout(this._timer)
+    if (this._t) this._t.close()
+  }
+
+  /** Kirim data (plaintext) lewat kanal Noise terenkripsi. */
+  sendFrame(plain) {
+    if (this.state !== 'noise-ready') throw new Error('koneksi belum siap (handshake belum selesai)')
+    this._write(encodeFrame(this._noise.encrypt(plain)))
+  }
+
+  stats() {
+    const m = process.memoryUsage()
+    return {
+      state: this.state,
+      uptimeMs: this.startedAt ? Date.now() - this.startedAt : 0,
+      ...this.counters,
+      handshakeMs: this.handshakeMs,
+      frameLatencyMs: this.frameLatency.summary(),
+      serverCertificateVerified: false,
+      rssMB: +(m.rss / 1048576).toFixed(1),
+      heapUsedMB: +(m.heapUsed / 1048576).toFixed(1)
+    }
+  }
+
+  _setState(connection, extra) {
+    this.state = connection
+    this._safeEmit('connection.update', { connection, ...extra })
+  }
+
+  _write(buf) {
+    this.counters.bytesOut += buf.length
+    this.counters.framesOut++
+    this._t.send(buf)
+  }
+
+  _onOpen() {
+    this._decoder = new FrameDecoder()
+    this._hs = new ClientHandshake({ staticKey: this.staticKey })
+    this.startedAt = Date.now()
+    this._setState('handshaking')
+    this._write(encodeFrame(this._hs.hello(), WA_HEADER))
+  }
+
+  _onMessage(chunk) {
+    if (!this._decoder || !this._t) return
+    try {
+      this.counters.bytesIn += chunk && typeof chunk.length === 'number' ? chunk.length : 0
+      const frames = this._decoder.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))
+      for (const frame of frames) {
+        if (!this._t) break
+        this.counters.framesIn++
+        try {
+          this._onFrame(frame)
+        } catch (err) {
+          this._abortConnection(err, this._t, this._generation)
+          break
+        }
+      }
+    } catch (err) {
+      this._abortConnection(err, this._t, this._generation)
+    }
+  }
+
+  _onFrame(frame) {
+    if (this._hs) {
+      const hs = this._hs
+      const finish = hs.processServerHello(frame, this.clientPayload)
+      this._noise = hs.noise
+      this._hs = null
+      // Publish the completed Noise state before writing ClientFinish. A fake or
+      // custom transport may synchronously deliver the server reply from send().
+      this.readyAt = Date.now()
+      this.handshakeMs = Date.now() - this.startedAt
+      this._setState('noise-ready', {
+        serverStatic: hs.serverStatic,
+        serverCertificateVerified: false
+      })
+      this._write(encodeFrame(finish))
+      return
+    }
+    if (!this._noise) throw new Error('Noise state tidak tersedia di luar handshake')
+    const done = this.frameLatency.start()
+    try {
+      const plain = this._noise.decrypt(frame)
+      this._safeEmit('frame', plain)
+    } finally {
+      done()
+    }
+  }
+
+  /** Dispatch each listener independently, so one user callback cannot starve others. */
+  _safeEmit(event, ...args) {
+    const listeners = this.rawListeners(event)
+    if (listeners.length === 0) return false
+    for (const listener of listeners) {
+      try {
+        const result = Reflect.apply(listener, this, args)
+        if (result && typeof result.then === 'function') {
+          Promise.resolve(result).catch((err) => this._reportHandlerError(err, event))
+        }
+      } catch (err) {
+        this._reportHandlerError(err, event)
+      }
+    }
+    return true
+  }
+
+  _reportHandlerError(error, sourceEvent) {
+    const err = error instanceof Error ? error : new Error(String(error))
+    this.log.error(`listener '${sourceEvent}' melempar error: ${err.message}`)
+    if (sourceEvent === 'handler.error') return
+    const listeners = this.rawListeners('handler.error')
+    for (const listener of listeners) {
+      try {
+        const result = Reflect.apply(listener, this, [err, sourceEvent])
+        if (result && typeof result.then === 'function') {
+          Promise.resolve(result).catch((nested) => this.log.error(`listener 'handler.error' melempar error: ${nested.message}`))
+        }
+      } catch (nested) {
+        this.log.error(`listener 'handler.error' melempar error: ${nested.message}`)
+      }
+    }
+  }
+
+  _abortConnection(error, transport = this._t, generation = this._generation) {
+    const err = error instanceof Error ? error : new Error(String(error))
+    this._safeEmit('connection.error', err)
+    if (!transport || transport !== this._t || generation !== this._generation) return
+    // Transition/cleanup synchronously. The transport's eventual close event is de-duplicated.
+    this._onClose(1002, Buffer.from('protocol/transport failure'), transport, generation)
+    try { transport.close() } catch (closeError) {
+      this.log.warn(`gagal menutup transport: ${closeError.message}`)
+    }
+  }
+
+  _onClose(code, reason, source = this._t, generation = this._generation) {
+    if (!source || source !== this._t || generation !== this._generation || this._closeHandled) return
+    this._closeHandled = true
+    const lived = this.readyAt ? Date.now() - this.readyAt : 0
+    const wasReady = this.readyAt > 0
+    this.readyAt = 0
+    this._t = this._hs = this._noise = this._decoder = null
+    this._setState('close', { code, reason: Buffer.isBuffer(reason) ? reason.toString('utf8') : reason })
+    const r = this.config.reconnect
+    if (lived >= r.stableMs) this.attempt = 0
+    else if (wasReady && this.clientPayload.length === 0) {
+      this.log.warn('server menutup koneksi tepat setelah handshake: clientPayload masih kosong (login/registrasi belum diimplementasi)')
+    }
+    this._scheduleReconnect()
+  }
+
+  _scheduleReconnect() {
+    const r = this.config.reconnect
+    if (this.ended || !r.enabled || this._timer) return
+    const base = Math.min(r.maxDelay, r.minDelay * Math.pow(r.factor, this.attempt++))
+    const delay = Math.round(base * (0.8 + Math.random() * 0.4))
+    this.log.info(`reconnect dalam ${delay}ms (percobaan ${this.attempt})`)
+    this._timer = setTimeout(() => {
+      this._timer = null
+      if (!this.ended && !this._t) this.connect()
+    }, delay)
+  }
+
+  /** Fail a decrypted protocol frame closed, while preserving configured backoff behavior. */
+  failProtocol(error) {
+    this._abortConnection(error)
+  }
+
+}
+
+module.exports = { Connection }

package/src/socket/frame.js

@@ -0,0 +1,77 @@
+'use strict'
+/**
+ * Framing WhatsApp: [prefix opsional][panjang 3 byte big-endian][payload].
+ * Prefix (WA_HEADER) hanya dikirim di frame pertama.
+ */
+const MAX_FRAME = 0xffffff
+
+function encodeFrame(payload, prefix) {
+  if (payload.length > MAX_FRAME) throw new Error('frame terlalu besar')
+  const head = Buffer.allocUnsafe(3)
+  head[0] = payload.length >>> 16
+  head[1] = (payload.length >>> 8) & 0xff
+  head[2] = payload.length & 0xff
+  return prefix ? Buffer.concat([prefix, head, payload]) : Buffer.concat([head, payload])
+}
+
+/**
+ * Penyusun frame dari potongan data WebSocket (frame bisa terbelah/menyatu).
+ * Potongan disimpan dalam daftar dan baru digabung SEKALI saat satu frame lengkap,
+ * jadi frame besar yang datang bertahap tidak memicu concat berulang (O(n^2)).
+ * Sisa data yang belum lengkap disalin supaya tidak menahan buffer induk yang besar.
+ */
+class FrameDecoder {
+  constructor() {
+    this.chunks = []
+    this.total = 0
+    this.need = 0 // total byte (header + payload) frame yang sedang dirakit; 0 = belum tahu
+  }
+
+  push(chunk) {
+    if (chunk.length) { this.chunks.push(chunk); this.total += chunk.length }
+    const frames = []
+    for (;;) {
+      if (this.need === 0) {
+        if (this.total < 3) break
+        this.need = 3 + ((this._byte(0) << 16) | (this._byte(1) << 8) | this._byte(2))
+      }
+      if (this.total < this.need) break
+      frames.push(this._take(this.need).subarray(3))
+      this.need = 0
+    }
+    if (this.chunks.length === 1 && this.chunks[0].length) this.chunks[0] = Buffer.from(this.chunks[0])
+    return frames
+  }
+
+  _byte(i) {
+    for (const c of this.chunks) {
+      if (i < c.length) return c[i]
+      i -= c.length
+    }
+    return 0
+  }
+
+  /** Ambil n byte dari depan. Tanpa salinan bila seluruhnya ada di satu potongan. */
+  _take(n) {
+    const first = this.chunks[0]
+    this.total -= n
+    if (first.length >= n) {
+      if (first.length === n) this.chunks.shift()
+      else this.chunks[0] = first.subarray(n)
+      return first.subarray(0, n)
+    }
+    const out = Buffer.allocUnsafe(n)
+    let off = 0
+    while (off < n) {
+      const c = this.chunks[0]
+      const take = Math.min(c.length, n - off)
+      c.copy(out, off, 0, take)
+      off += take
+      if (take === c.length) this.chunks.shift()
+      else this.chunks[0] = c.subarray(take)
+    }
+    return out
+  }
+}
+
+module.exports = { encodeFrame, FrameDecoder, MAX_FRAME }

package/src/socket/make.js

@@ -0,0 +1,70 @@
+'use strict'
+const { Connection } = require('./connection')
+const { generateKeyPair } = require('../utils/crypto')
+const { scoped } = require('../session/stores')
+const { PairingLifecycle } = require('../pairing/lifecycle')
+const { NodeProtocol } = require('../protocol/node-protocol')
+
+/**
+ * Buat socket kersiosocket.
+ *
+ * @param {object} [config]
+ *   autoConnect  true  -> sambung otomatis (default)
+ *   store        store session {get,set,delete}; bila ada, kredensial disimpan/dimuat otomatis
+ *   sessionId    nama sesi di dalam store (default 'default')
+ *   logger, reconnect, url, origin, staticKey, clientPayload
+ *
+ * Event (sock.ev): connection.update, creds.update, frame, connection.error, handler.error
+ * sock.ready: Promise yang selesai setelah kredensial dimuat (dan koneksi dimulai bila autoConnect).
+ */
+function makeSocket(config = {}) {
+  const conn = new Connection(config)
+  const pairing = new PairingLifecycle({ sessionId: config.sessionId || 'default' })
+  const protocolConfig = config.nodeProtocol
+  const protocol = protocolConfig ? new NodeProtocol(conn, protocolConfig === true ? {} : protocolConfig) : null
+  const store = config.store ? scoped(config.store, config.sessionId || 'default') : null
+  let creds = null
+
+  const saveCreds = async () => {
+    if (!store || !creds) return
+    await store.set('creds', creds)
+    conn._safeEmit('creds.update', creds)
+  }
+
+  const start = async () => {
+    if (store) {
+      creds = (await store.get('creds')) || null
+      if (!creds) {
+        creds = { staticKey: config.staticKey || generateKeyPair(), createdAt: Date.now() }
+        await saveCreds()
+      }
+      conn.staticKey = creds.staticKey
+    }
+    if (config.autoConnect !== false) conn.connect()
+  }
+
+  const sock = {
+    ev: conn,
+    sessionId: config.sessionId || 'default',
+    pairing,
+    connect: () => conn.connect(),
+    end: () => { protocol?.close(); pairing.close(); conn.end() },
+    sendFrame: (buf) => conn.sendFrame(buf),
+    protocol,
+    sendNode: (node) => { if (!protocol) throw new Error('aktifkan nodeProtocol pada makeSocket() untuk sendNode()'); return protocol.sendNode(node) },
+    query: (node, options) => { if (!protocol) return Promise.reject(new Error('aktifkan nodeProtocol pada makeSocket() untuk query()')); return protocol.query(node, options) },
+    stats: () => conn.stats(),
+    saveCreds,
+    get creds() { return creds },
+    get state() { return conn.state }
+  }
+
+  // tunda satu tick supaya pemanggil sempat memasang listener
+  sock.ready = new Promise((resolve) => process.nextTick(resolve))
+    .then(start)
+    .catch((err) => { conn._safeEmit('connection.error', err) })
+
+  return sock
+}
+
+module.exports = { makeSocket }

package/src/socket/noise.js

@@ -0,0 +1,126 @@
+'use strict'
+/**
+ * Noise Protocol (pola XX, X25519, AES-GCM, SHA-256) untuk transport WhatsApp Web.
+ * Ditulis dari spesifikasi Noise (noiseprotocol.org), bukan salinan library lain.
+ *
+ * NoiseState      : state mesin Noise (hash, chaining key, kunci, counter)
+ * ClientHandshake : alur sisi klien (initiator)
+ */
+const {
+  EMPTY, generateKeyPair, sharedKey, sha256, hkdf, aesGcmEncrypt, aesGcmDecrypt
+} = require('../utils/crypto')
+const { encodeClientHello, encodeClientFinish, decodeServerHello } = require('../proto/handshake')
+
+// Nama protokol, dipad nol sampai 32 byte (panjang hash SHA-256)
+const NOISE_MODE = Buffer.from('Noise_XX_25519_AESGCM_SHA256\0\0\0\0')
+// 'W','A', versi magic, versi dictionary. PERLU diverifikasi ke versi WA Web terbaru.
+const WA_HEADER = Buffer.from([0x57, 0x41, 6, 3])
+// IV AES-GCM memakai counter 32 bit; lewat ini nonce akan berulang (fatal), jadi berhenti.
+const MAX_COUNTER = 0xffffffff
+
+class NoiseState {
+  constructor(header) {
+    this.hash = NOISE_MODE.length === 32 ? NOISE_MODE : sha256(NOISE_MODE)
+    this.salt = this.hash // chaining key
+    this.encKey = this.hash
+    this.decKey = this.hash
+    this.readCounter = 0
+    this.writeCounter = 0
+    this.finished = false
+    this.authenticate(header)
+  }
+
+  /** hash = SHA256(hash || data). Tidak dilakukan setelah handshake selesai. */
+  authenticate(data) {
+    if (!this.finished) this.hash = sha256(Buffer.concat([this.hash, data]))
+  }
+
+  _iv(counter) {
+    const iv = Buffer.alloc(12)
+    iv.writeUInt32BE(counter, 8)
+    return iv
+  }
+
+  encrypt(plaintext) {
+    if (this.writeCounter >= MAX_COUNTER) throw new Error('noise: counter tulis habis, koneksi harus dibuat ulang')
+    const aad = this.finished ? EMPTY : this.hash
+    const out = aesGcmEncrypt(this.encKey, this._iv(this.writeCounter++), plaintext, aad)
+    this.authenticate(out)
+    return out
+  }
+
+  decrypt(ciphertext) {
+    if (this.readCounter >= MAX_COUNTER) throw new Error('noise: counter baca habis, koneksi harus dibuat ulang')
+    const aad = this.finished ? EMPTY : this.hash
+    const out = aesGcmDecrypt(this.decKey, this._iv(this.readCounter++), ciphertext, aad)
+    this.authenticate(ciphertext)
+    return out
+  }
+
+  /** MixKey: (ck, k) = HKDF(ck, input). Counter di-reset. */
+  mixIntoKey(data) {
+    const out = hkdf(data, 64, this.salt)
+    this.salt = out.subarray(0, 32)
+    this.encKey = this.decKey = out.subarray(32)
+    this.readCounter = this.writeCounter = 0
+  }
+
+  /** Split: turunkan kunci transport akhir. */
+  finish(isInitiator) {
+    const out = hkdf(EMPTY, 64, this.salt)
+    const a = out.subarray(0, 32), b = out.subarray(32)
+    this.encKey = isInitiator ? a : b
+    this.decKey = isInitiator ? b : a
+    this.hash = EMPTY
+    this.readCounter = this.writeCounter = 0
+    this.finished = true
+  }
+}
+
+class ClientHandshake {
+  /**
+   * @param {{ staticKey: {public:Buffer, private:Buffer}, ephemeralKey?: object, header?: Buffer }} opts
+   */
+  constructor({ staticKey, ephemeralKey = generateKeyPair(), header = WA_HEADER }) {
+    this.staticKey = staticKey
+    this.ephemeralKey = ephemeralKey
+    this.noise = new NoiseState(header)
+    this.noise.authenticate(ephemeralKey.public)
+    this.serverStatic = null
+    this.serverCertificate = null
+  }
+
+  /** Pesan pertama (ClientHello), sudah di-encode protobuf. */
+  hello() {
+    return encodeClientHello(this.ephemeralKey.public)
+  }
+
+  /**
+   * Proses ServerHello, kembalikan ClientFinish (protobuf).
+   * TODO v0.2: verifikasi rantai sertifikat server terhadap root key WhatsApp.
+   * @param {Buffer} data  isi frame ServerHello
+   * @param {Buffer} clientPayload  ClientPayload (login/registrasi), sudah di-encode protobuf
+   */
+  processServerHello(data, clientPayload) {
+    const n = this.noise
+    const sh = decodeServerHello(data)
+
+    n.authenticate(sh.ephemeral)
+    n.mixIntoKey(sharedKey(this.ephemeralKey.private, sh.ephemeral))
+
+    this.serverStatic = n.decrypt(sh.static)
+    n.mixIntoKey(sharedKey(this.ephemeralKey.private, this.serverStatic))
+
+    this.serverCertificate = n.decrypt(sh.payload)
+
+    const encStatic = n.encrypt(this.staticKey.public)
+    n.mixIntoKey(sharedKey(this.staticKey.private, sh.ephemeral))
+
+    const encPayload = n.encrypt(clientPayload)
+    n.finish(true)
+
+    return encodeClientFinish({ static: encStatic, payload: encPayload })
+  }
+}
+
+module.exports = { NoiseState, ClientHandshake, WA_HEADER, NOISE_MODE, MAX_COUNTER }

package/src/socket/transport.js

@@ -0,0 +1,39 @@
+'use strict'
+/**
+ * Adapter WebSocket. Memakai paket `ws` bila terpasang (bisa set header Origin,
+ * disarankan untuk WhatsApp), jika tidak jatuh ke WebSocket bawaan Node.
+ * Event yang dipancarkan: open, message(Buffer), close(code, reason), transport.error(err)
+ */
+const { EventEmitter } = require('node:events')
+
+function createTransport(url, { origin, headers } = {}) {
+  const t = new EventEmitter()
+  let WS = null
+  try { WS = require('ws') } catch { /* opsional */ }
+
+  if (WS) {
+    const ws = new WS(url, { origin, headers, handshakeTimeout: 20000 })
+    ws.on('open', () => t.emit('open'))
+    ws.on('message', (d) => t.emit('message', Buffer.isBuffer(d) ? d : Buffer.from(d)))
+    ws.on('close', (code, reason) => t.emit('close', code, String(reason || '')))
+    ws.on('error', (err) => t.emit('transport.error', err))
+    t.send = (buf) => ws.send(buf)
+    t.close = () => ws.close()
+    return t
+  }
+
+  if (typeof WebSocket === 'undefined') {
+    throw new Error('WebSocket tidak tersedia. Pakai Node >= 22 atau jalankan: npm i ws')
+  }
+  const ws = new WebSocket(url)
+  ws.binaryType = 'arraybuffer'
+  ws.onopen = () => t.emit('open')
+  ws.onmessage = (e) => t.emit('message', Buffer.from(e.data))
+  ws.onclose = (e) => t.emit('close', e.code, e.reason)
+  ws.onerror = (e) => t.emit('transport.error', e.error || new Error('WebSocket error'))
+  t.send = (buf) => ws.send(buf)
+  t.close = () => ws.close()
+  return t
+}
+
+module.exports = { createTransport }

package/src/utils/crypto.js

@@ -0,0 +1,52 @@
+'use strict'
+/**
+ * Helper kripto kersiosocket. Hanya memakai node:crypto (tanpa dependensi).
+ * Semua fungsi bekerja langsung di atas Buffer agar hemat memori.
+ */
+const crypto = require('node:crypto')
+
+const EMPTY = Buffer.alloc(0)
+// Prefix DER untuk membungkus kunci mentah X25519 (32 byte)
+const X25519_SPKI = Buffer.from('302a300506032b656e032100', 'hex')
+const X25519_PKCS8 = Buffer.from('302e020100300506032b656e04220420', 'hex')
+
+/** Buat pasangan kunci Curve25519 mentah (32 byte masing-masing). */
+function generateKeyPair() {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('x25519')
+  return {
+    public: publicKey.export({ type: 'spki', format: 'der' }).subarray(X25519_SPKI.length),
+    private: privateKey.export({ type: 'pkcs8', format: 'der' }).subarray(X25519_PKCS8.length)
+  }
+}
+
+/** Diffie-Hellman X25519: rahasia bersama dari kunci privat sendiri + publik lawan. */
+function sharedKey(privateKey, publicKey) {
+  const priv = crypto.createPrivateKey({ key: Buffer.concat([X25519_PKCS8, privateKey]), format: 'der', type: 'pkcs8' })
+  const pub = crypto.createPublicKey({ key: Buffer.concat([X25519_SPKI, publicKey]), format: 'der', type: 'spki' })
+  return crypto.diffieHellman({ privateKey: priv, publicKey: pub })
+}
+
+function sha256(data) {
+  return crypto.createHash('sha256').update(data).digest()
+}
+
+function hkdf(ikm, length, salt, info = EMPTY) {
+  return Buffer.from(crypto.hkdfSync('sha256', ikm, salt, info, length))
+}
+
+/** AES-256-GCM. Hasil = ciphertext || tag(16). */
+function aesGcmEncrypt(key, iv, plaintext, aad = EMPTY) {
+  const c = crypto.createCipheriv('aes-256-gcm', key, iv)
+  c.setAAD(aad)
+  return Buffer.concat([c.update(plaintext), c.final(), c.getAuthTag()])
+}
+
+function aesGcmDecrypt(key, iv, data, aad = EMPTY) {
+  if (data.length < 16) throw new Error('ciphertext terlalu pendek')
+  const d = crypto.createDecipheriv('aes-256-gcm', key, iv)
+  d.setAAD(aad)
+  d.setAuthTag(data.subarray(data.length - 16))
+  return Buffer.concat([d.update(data.subarray(0, data.length - 16)), d.final()])
+}
+
+module.exports = { EMPTY, generateKeyPair, sharedKey, sha256, hkdf, aesGcmEncrypt, aesGcmDecrypt }

package/src/utils/latency.js

@@ -0,0 +1,32 @@
+'use strict'
+/** Pelacak latensi ringan: ring buffer Float64Array tetap (tanpa alokasi per sampel). */
+class LatencyTracker {
+  constructor(size = 256) {
+    this.buf = new Float64Array(size)
+    this.n = 0
+    this.i = 0
+    this.max = 0
+  }
+
+  /** Mulai ukur; kembalikan fungsi yang mencatat selisih (ms) saat dipanggil. */
+  start() {
+    const t0 = process.hrtime.bigint()
+    return () => this.add(Number(process.hrtime.bigint() - t0) / 1e6)
+  }
+
+  add(ms) {
+    this.buf[this.i] = ms
+    this.i = (this.i + 1) % this.buf.length
+    if (this.n < this.buf.length) this.n++
+    if (ms > this.max) this.max = ms
+  }
+
+  summary() {
+    if (!this.n) return { count: 0, p50: 0, p95: 0, max: 0 }
+    const a = Array.from(this.buf.subarray(0, this.n)).sort((x, y) => x - y)
+    const q = (p) => +a[Math.min(a.length - 1, Math.floor(p * a.length))].toFixed(3)
+    return { count: this.n, p50: q(0.5), p95: q(0.95), max: +this.max.toFixed(3) }
+  }
+}
+
+module.exports = { LatencyTracker }