kersiosocket 0.5.0-dev → 0.6.0-dev

package/src/client/kersio-client.js

@@ -0,0 +1,305 @@
+'use strict'
+
+const { EventEmitter } = require('node:events')
+const { assertJid, assertMessageContent, BackendNotSupportedError } = require('../backends/base')
+const { ZapoBackend } = require('../backends/zapo')
+const { BaileysBackend } = require('../backends/baileys')
+const { WhatsmeowProcessBackend } = require('../backends/whatsmeow-process')
+
+const EVENT_FORWARD = [
+  'connection.update', 'pairing.qr', 'pairing.code', 'pairing.success',
+  'messages.upsert', 'messages.update', 'messages.delete', 'message',
+  'message.receipt', 'contacts.upsert', 'contacts.update', 'chats.upsert',
+  'chats.update', 'groups.upsert', 'groups.update', 'group-participants.update',
+  'messaging-history.set', 'creds.update', 'credentials.update', 'protocol.error',
+  'protocol.warning', 'backend.error', 'bridge.stderr'
+]
+
+class KersioClient extends EventEmitter {
+  constructor(backend, { sessionId = 'default', archive = null } = {}) {
+    super()
+    if (!backend || typeof backend.sendMessage !== 'function' || typeof backend.connect !== 'function') {
+      throw new TypeError('KersioClient membutuhkan backend adapter yang valid')
+    }
+    this.backend = backend
+    this.engine = backend.engine || 'custom'
+    this.sessionId = sessionId
+    this.archive = archive
+    this._lastReplayable = new Map()
+    this.state = 'idle'
+    this._closed = false
+    this._unsubs = []
+    for (const event of EVENT_FORWARD) {
+      const handler = (payload) => {
+        if (event === 'connection.update' && payload && typeof payload.connection === 'string') {
+          if (payload.connection === 'open' || payload.connection === 'noise-ready') this.state = 'open'
+          else if (payload.connection === 'close') this.state = 'close'
+          else if (payload.connection === 'connecting' || payload.connection === 'handshaking') this.state = 'connecting'
+          this._emitSafely('client.state', { state: this.state, engine: this.engine, update: payload })
+        }
+        this._emitSafely(event, payload)
+        if (event === 'messages.upsert' && this.archive && payload && Array.isArray(payload.messages)) {
+          this._archiveMessages(payload.messages).catch((error) => this._emitSafely('archive.error', error))
+        }
+      }
+      backend.on(event, handler)
+      this._unsubs.push(() => backend.off(event, handler))
+      if (typeof backend.replay === 'function') backend.replay(event, handler)
+    }
+  }
+
+  on(event, listener) {
+    super.on(event, listener)
+    if (this._lastReplayable.has(event)) {
+      const payload = this._lastReplayable.get(event)
+      queueMicrotask(() => {
+        if (this._closed || this.listeners(event).length === 0) return
+        try { Reflect.apply(listener, this, [payload]) } catch (error) {
+          if (event !== 'client.error') this._emitSafely('client.error', { error, sourceEvent: event })
+        }
+      })
+    }
+    return this
+  }
+
+  _emitSafely(event, payload) {
+    if (event === 'pairing.success' || (event === 'connection.update' && payload?.connection === 'close')) {
+      this._lastReplayable.delete('pairing.qr')
+      this._lastReplayable.delete('pairing.code')
+    }
+    if (['connection.update', 'pairing.qr', 'pairing.code', 'pairing.success'].includes(event)) this._lastReplayable.set(event, payload)
+    for (const listener of this.rawListeners(event)) {
+      try { listener.call(this, payload) } catch (error) {
+        if (event !== 'client.error') {
+          for (const onError of this.rawListeners('client.error')) {
+            try { onError.call(this, { error, sourceEvent: event }) } catch { /* listeners remain isolated */ }
+          }
+        }
+      }
+    }
+  }
+
+  async _archiveMessages(messages) {
+    for (const message of messages) await this.archive.put(message)
+  }
+
+  async connect() {
+    this._assertOpen()
+    if (this.state === 'connecting' || this.state === 'open') return this
+    this.state = 'connecting'
+    this._emitSafely('client.state', { state: this.state, engine: this.engine })
+    try {
+      await this.backend.connect()
+      // Do not infer authentication from a resolved connect() call. Only a backend
+      // connection.update event may mark the unified facade as open.
+      this._emitSafely('client.state', { state: this.state, engine: this.engine })
+      return this
+    } catch (error) {
+      this.state = 'close'
+      this._emitSafely('client.state', { state: this.state, engine: this.engine, error })
+      throw error
+    }
+  }
+
+  async sendMessage(jid, content, options) {
+    this._assertOpen()
+    assertJid(jid)
+    assertMessageContent(content)
+    if (this.state !== 'open') {
+      throw new Error(`client belum open (state=${this.state}); panggil connect() dulu`)
+    }
+    return this.backend.sendMessage(jid, content, options)
+  }
+
+  async sendText(jid, text, options) {
+    if (typeof text !== 'string' || !text.trim()) throw new TypeError('text harus string non-kosong')
+    return this.sendMessage(jid, { text }, options)
+  }
+
+  async sendImage(jid, image, options = {}) {
+    requireMedia(image, 'image')
+    return this.sendMessage(jid, { image, ...assertOptions(options) })
+  }
+
+  async sendVideo(jid, video, options = {}) {
+    requireMedia(video, 'video')
+    return this.sendMessage(jid, { video, ...assertOptions(options) })
+  }
+
+  async sendAudio(jid, audio, options = {}) {
+    requireMedia(audio, 'audio')
+    return this.sendMessage(jid, { audio, ...assertOptions(options) })
+  }
+
+  async sendDocument(jid, document, options = {}) {
+    requireMedia(document, 'document')
+    return this.sendMessage(jid, { document, ...assertOptions(options) })
+  }
+
+  async sendSticker(jid, sticker, options = {}) {
+    requireMedia(sticker, 'sticker')
+    return this.sendMessage(jid, { sticker, ...assertOptions(options) })
+  }
+
+  async sendLocation(jid, { latitude, longitude, name, address } = {}, options = {}) {
+    if (!Number.isFinite(latitude) || !Number.isFinite(longitude) || latitude < -90 || latitude > 90 || longitude < -180 || longitude > 180) {
+      throw new TypeError('latitude/longitude tidak valid')
+    }
+    return this.sendMessage(jid, {
+      location: {
+        degreesLatitude: latitude,
+        degreesLongitude: longitude,
+        ...(name == null ? {} : { name: String(name) }),
+        ...(address == null ? {} : { address: String(address) })
+      }, ...assertOptions(options)
+    })
+  }
+
+  async sendContact(jid, { displayName, vcard } = {}, options = {}) {
+    if (typeof displayName !== 'string' || !displayName.trim()) throw new TypeError('displayName wajib diisi')
+    if (typeof vcard !== 'string' || !vcard.includes('BEGIN:VCARD') || !vcard.includes('END:VCARD')) throw new TypeError('vcard harus berisi BEGIN:VCARD dan END:VCARD')
+    return this.sendMessage(jid, {
+      contacts: { displayName, contacts: [{ displayName, vcard }] }, ...assertOptions(options)
+    })
+  }
+
+  async sendPoll(jid, { name, values, selectableCount = 1 } = {}, options = {}) {
+    if (typeof name !== 'string' || !name.trim()) throw new TypeError('name polling wajib diisi')
+    if (!Array.isArray(values) || values.length < 2 || values.length > 12 || values.some((v) => typeof v !== 'string' || !v.trim())) {
+      throw new TypeError('values polling harus 2–12 opsi berupa string non-kosong')
+    }
+    if (!Number.isSafeInteger(selectableCount) || selectableCount < 0 || selectableCount > values.length) throw new RangeError('selectableCount tidak valid')
+    return this.sendMessage(jid, { poll: { name, values, selectableCount }, ...assertOptions(options) })
+  }
+
+  async react(jid, key, text) {
+    assertMessageKey(key)
+    if (typeof text !== 'string') throw new TypeError('reaction harus string')
+    return this.sendMessage(jid, { react: { text, key } })
+  }
+
+  async editMessage(jid, key, text) {
+    assertMessageKey(key)
+    if (typeof text !== 'string' || !text.trim()) throw new TypeError('text edit tidak boleh kosong')
+    return this.sendMessage(jid, { text, edit: key })
+  }
+
+  async deleteMessage(jid, key) {
+    assertMessageKey(key)
+    return this.sendMessage(jid, { delete: key })
+  }
+
+  async requestPairingCode(phoneNumber) {
+    this._assertOpen()
+    if (typeof this.backend.requestPairingCode !== 'function') throw new BackendNotSupportedError(this.engine, 'requestPairingCode')
+    return this.backend.requestPairingCode(phoneNumber)
+  }
+
+  async downloadMedia(message, options) {
+    this._assertOpen()
+    if (typeof this.backend.downloadMedia !== 'function') throw new BackendNotSupportedError(this.engine, 'downloadMedia')
+    return this.backend.downloadMedia(message, options)
+  }
+
+  async invoke(method, ...args) {
+    this._assertOpen()
+    if (typeof this.backend.invoke !== 'function') throw new BackendNotSupportedError(this.engine, method)
+    return this.backend.invoke(method, ...args)
+  }
+
+  capabilities() {
+    return typeof this.backend.capabilities === 'function'
+      ? this.backend.capabilities()
+      : { engine: this.engine, live: false, messaging: true, media: false, groups: false, historySync: false }
+  }
+
+  async close() {
+    if (this._closed) return
+    this._closed = true
+    this.state = 'closing'
+    for (const off of this._unsubs.splice(0)) {
+      try { off() } catch { /* best effort */ }
+    }
+    try { await this.backend.close() } finally {
+      this.state = 'closed'
+      this._emitSafely('client.state', { state: this.state, engine: this.engine })
+      this.removeAllListeners()
+    }
+  }
+
+  _assertOpen() { if (this._closed) throw new Error('KersioClient sudah ditutup') }
+}
+
+async function createKersioClient(options = {}) {
+  const sessionId = options.sessionId || 'default'
+  let backend = options.backend
+  if (!backend) {
+    switch (options.engine) {
+      case 'zapo':
+      case 'zapo-js': {
+        const { client } = options
+        if (client) backend = new ZapoBackend(client, { sessionId })
+        else {
+          let mod
+          try { mod = await import('zapo-js') } catch (error) { throw dependencyError('zapo-js', error) }
+          const clientFactory = options.clientFactory
+          if (typeof clientFactory === 'function') {
+            const zapoClient = await clientFactory(mod, options)
+            backend = new ZapoBackend(zapoClient, { sessionId })
+          } else {
+            const store = options.store || (typeof options.storeFactory === 'function' ? await options.storeFactory(mod, options) : null)
+            if (!store) throw new TypeError("engine 'zapo' perlu options.client atau options.store/storeFactory; Kersio tidak menebak konfigurasi provider penyimpanan kredensial")
+            const WaClient = mod.WaClient
+            if (typeof WaClient !== 'function') throw new TypeError("versi zapo-js ini tidak mengekspor 'WaClient'")
+            const logger = options.logger || (typeof mod.ConsoleLogger === 'function' ? new mod.ConsoleLogger(options.logLevel || 'info') : undefined)
+            const args = [{ store, sessionId }, logger].filter((v) => v !== undefined)
+            const client = new WaClient(...args)
+            backend = new ZapoBackend(client, { sessionId })
+          }
+        }
+        break
+      }
+      case 'baileys':
+        backend = await BaileysBackend.create(options)
+        break
+      case 'whatsmeow':
+      case 'whatsmeow-go':
+        backend = new WhatsmeowProcessBackend({ ...options.bridge, sessionId })
+        break
+      case 'native':
+        throw new Error('engine native hanya menyediakan transport/protokol tingkat rendah di v0.6.0-dev; pairing kriptografis, Signal dan message engine native belum complete. Pilih engine zapo, baileys, atau whatsmeow dengan bridge yang kompatibel untuk fitur pesan live.')
+      default:
+        throw new TypeError("options.engine wajib salah satu: 'zapo', 'baileys', 'whatsmeow', atau berikan options.backend")
+    }
+  }
+  return new KersioClient(backend, { sessionId, archive: options.archive || null })
+}
+
+function requireMedia(value, type) {
+  if (value === undefined || value === null || value === '') throw new TypeError(`${type} wajib diisi`)
+  if (typeof value === 'object' && !Buffer.isBuffer(value) && !(value instanceof Uint8Array) && !('url' in value) && !('stream' in value) && !('path' in value)) {
+    throw new TypeError(`${type} harus Buffer, Uint8Array, URL/path/stream, atau input yang didukung backend`)
+  }
+}
+
+function assertOptions(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('options harus objek')
+  const copy = { ...value }
+  for (const forbidden of ['image', 'video', 'audio', 'document', 'sticker', 'location', 'contacts', 'poll', 'react', 'edit', 'delete']) {
+    if (Object.hasOwn(copy, forbidden)) throw new TypeError(`jangan isi options.${forbidden}; gunakan parameter konten khusus`)
+  }
+  return copy
+}
+
+function assertMessageKey(key) {
+  if (!key || typeof key !== 'object' || typeof key.id !== 'string' || !key.id) throw new TypeError('message key harus objek dengan id non-kosong')
+}
+
+function dependencyError(pkg, cause) {
+  const error = new Error(`Backend '${pkg}' belum terpasang. Instal '${pkg}' atau pass instance client yang sudah dibuat.`)
+  error.code = 'ERR_OPTIONAL_DEPENDENCY_MISSING'
+  error.cause = cause
+  return error
+}
+
+module.exports = { KersioClient, createKersioClient, EVENT_FORWARD }

package/src/client/session-manager.js

@@ -0,0 +1,67 @@
+'use strict'
+
+const { createKersioClient } = require('./kersio-client')
+
+class KersioSessionManager {
+  constructor({ clientFactory = createKersioClient } = {}) {
+    if (typeof clientFactory !== 'function') throw new TypeError('clientFactory harus function')
+    this.clientFactory = clientFactory
+    this.sessions = new Map()
+    this.opening = new Map()
+    this.closed = false
+  }
+
+  async open(sessionId, options = {}) {
+    assertSessionId(sessionId)
+    if (this.closed) throw new Error('KersioSessionManager sudah ditutup')
+    if (this.sessions.has(sessionId)) throw new Error(`session '${sessionId}' sudah dibuka`)
+    if (this.opening.has(sessionId)) return this.opening.get(sessionId)
+    const operation = (async () => {
+      const client = await this.clientFactory({ ...options, sessionId })
+      if (this.closed) { await client.close(); throw new Error('manager ditutup saat session dibuka') }
+      this.sessions.set(sessionId, client)
+      if (options.autoConnect !== false) {
+        try { await client.connect() } catch (error) { this.sessions.delete(sessionId); await client.close().catch(() => {}); throw error }
+      }
+      return client
+    })()
+    this.opening.set(sessionId, operation)
+    try { return await operation } finally { if (this.opening.get(sessionId) === operation) this.opening.delete(sessionId) }
+  }
+
+  get(sessionId) { return this.sessions.get(sessionId) }
+
+  async close(sessionId) {
+    const opening = this.opening.get(sessionId)
+    if (opening) { try { await opening } catch { /* no live session to close */ } }
+    const client = this.sessions.get(sessionId)
+    if (!client) return false
+    this.sessions.delete(sessionId)
+    await client.close()
+    return true
+  }
+
+  async closeAll() {
+    this.closed = true
+    await Promise.allSettled([...this.sessions.keys()].map((id) => this.close(id)))
+    await Promise.allSettled([...this.opening.values()])
+    this.sessions.clear()
+    this.opening.clear()
+  }
+
+  list() {
+    return [...this.sessions.entries()].map(([sessionId, client]) => ({ sessionId, engine: client.engine, state: client.state }))
+  }
+
+  stats() {
+    const sessions = this.list()
+    return { total: sessions.length, connecting: sessions.filter((x) => x.state === 'connecting').length, open: sessions.filter((x) => x.state === 'open').length, closed: this.closed, sessions }
+  }
+}
+
+function createKersioSessionManager(options) { return new KersioSessionManager(options) }
+function assertSessionId(id) {
+  if (typeof id !== 'string' || !id.trim() || id.length > 128 || /[\0\r\n]/.test(id)) throw new TypeError('sessionId harus string non-kosong maksimal 128 karakter')
+}
+
+module.exports = { KersioSessionManager, createKersioSessionManager }

package/src/index.js

@@ -12,6 +12,14 @@ const { encodeBinaryNode, decodeBinaryNode, makeTokenTables, loadTokenTable, TAG
 const { buildPairingQrPayload, extractPairingRefs, LINKED_DEVICES_PREFIX } = require('./pairing/qr')
 const { attachQrPairingAdapter } = require('./pairing/adapter')
 const { NodeProtocol, QueryTimeoutError, RemoteIQError } = require('./protocol/node-protocol')
+const { KersioClient, createKersioClient } = require('./client/kersio-client')
+const { ZapoBackend } = require('./backends/zapo')
+const { BaileysBackend } = require('./backends/baileys')
+const { WhatsmeowProcessBackend, jsonSafe: bridgeJsonSafe } = require('./backends/whatsmeow-process')
+const { BackendNotSupportedError } = require('./backends/base')
+const { KeyedMutex, FileLockManager, LockedStore, MessageArchive, LockTimeoutError } = require('./session/locking')
+const { commitVerifiedPairSuccess } = require('./pairing/verified-commit')
+const { KersioSessionManager, createKersioSessionManager } = require('./client/session-manager')
 
 module.exports = {
   makeSocket, createSessionManager,
@@ -21,5 +29,8 @@ module.exports = {
   PLATFORM_TYPE, encodeDeviceProps, encodeHistorySyncConfig, encodeBigEndianUnsigned, buildAppVersionHash, createDevicePairingData,
   encodeBinaryNode, decodeBinaryNode, makeTokenTables, loadTokenTable, WABINARY_TAGS: TAGS,
   buildPairingQrPayload, extractPairingRefs, LINKED_DEVICES_PREFIX, attachQrPairingAdapter,
-  NodeProtocol, QueryTimeoutError, RemoteIQError
+  NodeProtocol, QueryTimeoutError, RemoteIQError,
+  KersioClient, createKersioClient, ZapoBackend, BaileysBackend, WhatsmeowProcessBackend, bridgeJsonSafe,
+  BackendNotSupportedError, KeyedMutex, FileLockManager, LockedStore, MessageArchive, LockTimeoutError,
+  commitVerifiedPairSuccess, KersioSessionManager, createKersioSessionManager
 }

package/src/pairing/verified-commit.js

@@ -0,0 +1,46 @@
+'use strict'
+
+/**
+ * Fail-closed commit guard for a protocol-specific pair-success verifier.
+ * This function is intentionally not itself the WhatsApp ADV/signature verifier: callers
+ * must supply an independently validated implementation and test vectors.
+ */
+async function commitVerifiedPairSuccess({
+  node,
+  verifyPairSuccess,
+  store,
+  sessionId,
+  sendNode,
+  lifecycle
+} = {}) {
+  if (typeof verifyPairSuccess !== 'function') throw new TypeError('verifyPairSuccess wajib diisi; pairing tidak boleh dipercaya tanpa verifier')
+  if (!store || typeof store.set !== 'function') throw new TypeError('store wajib menyediakan set() untuk menyimpan credentials')
+  if (typeof sendNode !== 'function') throw new TypeError('sendNode wajib diisi untuk mengirim balasan pairing')
+  if (!lifecycle || typeof lifecycle.complete !== 'function') throw new TypeError('lifecycle pairing tidak valid')
+
+  const effectiveSessionId = sessionId || lifecycle.sessionId || 'default'
+  const result = await verifyPairSuccess(node)
+  if (!result || result.verified !== true || !result.checks ||
+      result.checks.deviceIdentity !== true ||
+      result.checks.accountSignature !== true ||
+      result.checks.advHmac !== true) {
+    const error = new Error('pair-success ditolak: pemeriksaan identity/signature/ADV-HMAC tidak lengkap atau gagal')
+    error.code = 'ERR_PAIR_SUCCESS_UNVERIFIED'
+    throw error
+  }
+  if (!result.credentials || typeof result.credentials !== 'object' || Array.isArray(result.credentials)) {
+    throw new TypeError('verifier tidak mengembalikan credentials terverifikasi')
+  }
+  if (!result.replyNode || typeof result.replyNode !== 'object' || typeof result.replyNode.tag !== 'string') {
+    throw new TypeError('verifier tidak mengembalikan node balasan pair-device-sign yang valid')
+  }
+
+  // Persist before replying/finalizing. A crash after persistence is recoverable from
+  // auth state; a failed verification can never be saved or mark lifecycle as paired.
+  await store.set(`auth:${effectiveSessionId}:credentials`, result.credentials)
+  await sendNode(result.replyNode)
+  lifecycle.complete({ verified: true, sessionId: effectiveSessionId, completedAt: Date.now() })
+  return { verified: true, sessionId: effectiveSessionId, credentials: result.credentials }
+}
+
+module.exports = { commitVerifiedPairSuccess }

package/src/session/locking.js

@@ -0,0 +1,233 @@
+'use strict'
+
+const fs = require('node:fs/promises')
+const path = require('node:path')
+const crypto = require('node:crypto')
+
+class LockTimeoutError extends Error {
+  constructor(key, timeoutMs) {
+    super(`timeout menunggu lock '${key}' setelah ${timeoutMs} ms`)
+    this.name = 'LockTimeoutError'
+    this.code = 'ERR_LOCK_TIMEOUT'
+    this.key = key
+    this.timeoutMs = timeoutMs
+  }
+}
+
+/** In-process keyed mutex. Use FileLockManager when more than one process shares a store. */
+class KeyedMutex {
+  constructor() { this.queues = new Map() }
+
+  async run(key, task) {
+    if (typeof key !== 'string' || !key) throw new TypeError('key lock wajib string non-kosong')
+    if (typeof task !== 'function') throw new TypeError('task lock wajib function')
+    const previous = this.queues.get(key) || Promise.resolve()
+    const current = previous.catch(() => {}).then(task)
+    this.queues.set(key, current)
+    try { return await current } finally {
+      if (this.queues.get(key) === current) this.queues.delete(key)
+    }
+  }
+}
+
+/**
+ * Cross-process lease lock based on atomic mkdir().
+ * It protects cooperating processes sharing the same local filesystem; it is not a
+ * distributed lock for network filesystems with broken/weak rename semantics.
+ */
+class FileLockManager {
+  constructor(dir, { staleMs = 60000, heartbeatMs = 10000, retryMs = 40 } = {}) {
+    if (typeof dir !== 'string' || !dir.trim()) throw new TypeError('direktori lock wajib diisi')
+    if (!Number.isSafeInteger(staleMs) || staleMs < 3000) throw new RangeError('staleMs minimal 3000')
+    if (!Number.isSafeInteger(heartbeatMs) || heartbeatMs < 500 || heartbeatMs >= staleMs) throw new RangeError('heartbeatMs harus >=500 dan < staleMs')
+    if (!Number.isSafeInteger(retryMs) || retryMs < 5) throw new RangeError('retryMs minimal 5')
+    this.dir = path.resolve(dir)
+    this.staleMs = staleMs
+    this.heartbeatMs = heartbeatMs
+    this.retryMs = retryMs
+    this.ready = fs.mkdir(this.dir, { recursive: true })
+  }
+
+  run(key, task, options) { return this.withLock(key, task, options) }
+
+  async withLock(key, task, { timeoutMs = 15000, signal } = {}) {
+    if (typeof key !== 'string' || !key) throw new TypeError('key lock wajib string non-kosong')
+    if (typeof task !== 'function') throw new TypeError('task lock wajib function')
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) throw new RangeError('timeoutMs harus integer positif')
+    await this.ready
+    const token = crypto.randomUUID()
+    const lockDir = path.join(this.dir, `${crypto.createHash('sha256').update(key).digest('hex')}.lock`)
+    const deadline = Date.now() + timeoutMs
+    let acquired = false
+    while (!acquired) {
+      if (signal?.aborted) throw signal.reason || new Error('lock dibatalkan')
+      try {
+        await fs.mkdir(lockDir)
+        acquired = true
+        try {
+          await fs.writeFile(path.join(lockDir, 'owner.json'), JSON.stringify({ token, keyHash: path.basename(lockDir), pid: process.pid, createdAt: Date.now() }), { flag: 'wx', mode: 0o600 })
+          const now = new Date()
+          await fs.utimes(lockDir, now, now)
+        } catch (error) {
+          await fs.rm(lockDir, { recursive: true, force: true }).catch(() => {})
+          throw error
+        }
+      } catch (error) {
+        if (error.code !== 'EEXIST') throw error
+        await this._reclaimIfStale(lockDir)
+        if (Date.now() >= deadline) throw new LockTimeoutError(key, timeoutMs)
+        await sleep(this.retryMs + Math.floor(Math.random() * Math.max(1, this.retryMs)), signal)
+      }
+    }
+
+    const heartbeat = setInterval(async () => {
+      try {
+        const owner = JSON.parse(await fs.readFile(path.join(lockDir, 'owner.json'), 'utf8'))
+        if (owner.token !== token) return
+        const now = new Date()
+        await fs.utimes(lockDir, now, now)
+      } catch { /* lease may have been reclaimed; fn should remain responsible for errors */ }
+    }, this.heartbeatMs)
+    heartbeat.unref?.()
+    try { return await task() } finally {
+      clearInterval(heartbeat)
+      try {
+        const owner = JSON.parse(await fs.readFile(path.join(lockDir, 'owner.json'), 'utf8'))
+        if (owner.token === token) await fs.rm(lockDir, { recursive: true, force: true })
+      } catch { /* never delete a lock not proven to be ours */ }
+    }
+  }
+
+  async _reclaimIfStale(lockDir) {
+    // Serialize stale reclamation so one waiter cannot rename a newly acquired lock
+    // after another waiter has already removed the stale directory.
+    const reclaimDir = `${lockDir}.reclaim`
+    try { await fs.mkdir(reclaimDir) } catch (error) {
+      if (error.code === 'EEXIST') return
+      throw error
+    }
+    try {
+      let stat
+      try { stat = await fs.stat(lockDir) } catch (error) { if (error.code === 'ENOENT') return; throw error }
+      if (Date.now() - stat.mtimeMs <= this.staleMs) return
+      const tombstone = `${lockDir}.stale-${process.pid}-${crypto.randomBytes(4).toString('hex')}`
+      try {
+        await fs.rename(lockDir, tombstone)
+        await fs.rm(tombstone, { recursive: true, force: true })
+      } catch (error) {
+        if (!['ENOENT', 'EEXIST', 'ENOTEMPTY'].includes(error.code)) throw error
+      }
+    } finally {
+      await fs.rm(reclaimDir, { recursive: true, force: true }).catch(() => {})
+    }
+  }
+}
+
+/**
+ * Small persistent message archive. It stores full backend message objects (including
+ * buffers supported by the configured store codec) and offers Baileys-style getMessage.
+ */
+class LockedStore {
+  constructor(store, lockManager) {
+    if (!store || typeof store.get !== 'function' || typeof store.set !== 'function' || typeof store.delete !== 'function') throw new TypeError('LockedStore memerlukan store get/set/delete')
+    if (!lockManager || typeof lockManager.run !== 'function') throw new TypeError('lockManager harus menyediakan run(key, task)')
+    this.store = store
+    this.lockManager = lockManager
+  }
+  get(key) { return this.lockManager.run(`store:${key}`, () => this.store.get(key)) }
+  set(key, value) { return this.lockManager.run(`store:${key}`, () => this.store.set(key, value)) }
+  delete(key) { return this.lockManager.run(`store:${key}`, () => this.store.delete(key)) }
+  keys(prefix = '') { return this.lockManager.run('store:__keys__', () => {
+    if (typeof this.store.keys !== 'function') throw new Error('store dasar tidak mendukung keys()')
+    return this.store.keys(prefix)
+  }) }
+  close() { return typeof this.store.close === 'function' ? this.store.close() : undefined }
+}
+
+class MessageArchive {
+  constructor(store, { sessionId = 'default', maxMessagesPerChat = 1000, mutex = new KeyedMutex() } = {}) {
+    if (!store || typeof store.get !== 'function' || typeof store.set !== 'function' || typeof store.delete !== 'function') {
+      throw new TypeError('MessageArchive memerlukan store dengan get/set/delete')
+    }
+    if (!Number.isSafeInteger(maxMessagesPerChat) || maxMessagesPerChat < 1) throw new RangeError('maxMessagesPerChat harus integer positif')
+    this.store = store
+    this.sessionId = validateScope(sessionId)
+    this.maxMessagesPerChat = maxMessagesPerChat
+    this.mutex = mutex
+  }
+
+  async put(message) {
+    const key = message?.key
+    const jid = key?.remoteJid
+    const id = key?.id
+    if (typeof jid !== 'string' || !jid || typeof id !== 'string' || !id) return false
+    const indexKey = this._indexKey(jid)
+    const recordKey = this._recordKey(jid, id)
+    return this.mutex.run(indexKey, async () => {
+      await this.store.set(recordKey, message)
+      const current = await this.store.get(indexKey)
+      const ids = Array.isArray(current) ? current.filter((entry) => entry && entry.id !== id) : []
+      ids.push({ id, key: recordKey, timestamp: Date.now() })
+      const removed = ids.splice(0, Math.max(0, ids.length - this.maxMessagesPerChat))
+      await this.store.set(indexKey, ids)
+      for (const old of removed) await this.store.delete(old.key)
+      return true
+    })
+  }
+
+  async getRecord(key) {
+    if (!key || typeof key.remoteJid !== 'string' || typeof key.id !== 'string') return undefined
+    return this.store.get(this._recordKey(key.remoteJid, key.id))
+  }
+
+  async getMessage(key) {
+    const record = await this.getRecord(key)
+    return record?.message
+  }
+
+  async recent(jid, limit = 50) {
+    if (typeof jid !== 'string' || !jid) throw new TypeError('jid wajib diisi')
+    if (!Number.isSafeInteger(limit) || limit < 1) throw new RangeError('limit harus integer positif')
+    const ids = await this.store.get(this._indexKey(jid))
+    if (!Array.isArray(ids)) return []
+    const selected = ids.slice(-limit).reverse()
+    const out = []
+    for (const entry of selected) {
+      const message = await this.store.get(entry.key)
+      if (message !== undefined) out.push(message)
+    }
+    return out
+  }
+
+  async delete(key) {
+    if (!key || typeof key.remoteJid !== 'string' || typeof key.id !== 'string') return false
+    const indexKey = this._indexKey(key.remoteJid)
+    return this.mutex.run(indexKey, async () => {
+      const recordKey = this._recordKey(key.remoteJid, key.id)
+      await this.store.delete(recordKey)
+      const ids = await this.store.get(indexKey)
+      if (Array.isArray(ids)) await this.store.set(indexKey, ids.filter((entry) => entry.key !== recordKey))
+      return true
+    })
+  }
+
+  _indexKey(jid) { return `archive:${this.sessionId}:${encodeURIComponent(jid)}:index` }
+  _recordKey(jid, id) { return `archive:${this.sessionId}:${encodeURIComponent(jid)}:message:${encodeURIComponent(id)}` }
+}
+
+function validateScope(value) {
+  if (typeof value !== 'string' || !value.trim() || value.includes('\0')) throw new TypeError('sessionId harus string non-kosong')
+  return value
+}
+
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(signal.reason || new Error('operasi dibatalkan'))
+    const timer = setTimeout(done, ms)
+    const onAbort = () => { clearTimeout(timer); signal.removeEventListener('abort', onAbort); reject(signal.reason || new Error('operasi dibatalkan')) }
+    function done() { signal?.removeEventListener('abort', onAbort); resolve() }
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+module.exports = { KeyedMutex, FileLockManager, LockedStore, MessageArchive, LockTimeoutError }