kersiosocket 0.0.0-stage → 0.5.0-dev

package/src/proto/wire.js

@@ -0,0 +1,137 @@
+'use strict'
+/**
+ * Tiny protobuf wire-format codec used by KersioSocket.
+ *
+ * This intentionally implements the protobuf wire primitives, not a generated
+ * copy of another project's WAProto code. Field meanings live in our own schema
+ * modules. Supported wire types: varint (0), fixed64 (1), bytes/message (2),
+ * and fixed32 (5). No implicit string conversion for binary fields.
+ */
+
+const MAX_FIELD_NUMBER = 0x1fffffff
+
+function asBigInt(value, name = 'value') {
+  if (typeof value === 'bigint') {
+    if (value < 0n || value > 0xffffffffffffffffn) throw new RangeError(`${name} di luar rentang uint64`)
+    return value
+  }
+  if (!Number.isSafeInteger(value) || value < 0) throw new TypeError(`${name} harus integer aman non-negatif`)
+  return BigInt(value)
+}
+
+function encodeVarint(value) {
+  let n = asBigInt(value)
+  const out = []
+  while (n > 0x7fn) {
+    out.push(Number((n & 0x7fn) | 0x80n))
+    n >>= 7n
+  }
+  out.push(Number(n))
+  return Buffer.from(out)
+}
+
+function tag(fieldNumber, wireType) {
+  if (!Number.isInteger(fieldNumber) || fieldNumber < 1 || fieldNumber > MAX_FIELD_NUMBER) {
+    throw new RangeError('nomor field protobuf tidak valid')
+  }
+  if (![0, 1, 2, 5].includes(wireType)) throw new RangeError('wire type protobuf tidak didukung')
+  return encodeVarint(BigInt(fieldNumber * 8 + wireType))
+}
+
+function fieldVarint(fieldNumber, value) {
+  if (value === undefined || value === null) return null
+  return Buffer.concat([tag(fieldNumber, 0), encodeVarint(value)])
+}
+
+function fieldBool(fieldNumber, value) {
+  if (value === undefined || value === null) return null
+  if (typeof value !== 'boolean') throw new TypeError(`field ${fieldNumber} harus boolean`)
+  return fieldVarint(fieldNumber, value ? 1 : 0)
+}
+
+function fieldBytes(fieldNumber, value) {
+  if (value === undefined || value === null) return null
+  if (!(Buffer.isBuffer(value) || value instanceof Uint8Array)) {
+    throw new TypeError(`field ${fieldNumber} harus Buffer/Uint8Array`)
+  }
+  const bytes = Buffer.from(value.buffer, value.byteOffset, value.byteLength)
+  return Buffer.concat([tag(fieldNumber, 2), encodeVarint(bytes.length), bytes])
+}
+
+function fieldString(fieldNumber, value) {
+  if (value === undefined || value === null) return null
+  if (typeof value !== 'string') throw new TypeError(`field ${fieldNumber} harus string`)
+  return fieldBytes(fieldNumber, Buffer.from(value, 'utf8'))
+}
+
+function fieldMessage(fieldNumber, value) {
+  return fieldBytes(fieldNumber, value)
+}
+
+function fieldFixed32(fieldNumber, value) {
+  if (value === undefined || value === null) return null
+  if (!Number.isInteger(value) || value < -0x80000000 || value > 0x7fffffff) {
+    throw new RangeError(`field ${fieldNumber} harus signed int32`)
+  }
+  const data = Buffer.allocUnsafe(4)
+  data.writeInt32LE(value)
+  return Buffer.concat([tag(fieldNumber, 5), data])
+}
+
+function pack(parts) {
+  const present = parts.filter((part) => part !== null && part !== undefined)
+  return present.length ? Buffer.concat(present) : Buffer.alloc(0)
+}
+
+function readVarint(buffer, state) {
+  let value = 0n
+  let shift = 0n
+  for (let count = 0; count < 10; count++) {
+    if (state.offset >= buffer.length) throw new Error('protobuf: varint terpotong')
+    const byte = buffer[state.offset++]
+    value |= BigInt(byte & 0x7f) << shift
+    if ((byte & 0x80) === 0) return value
+    shift += 7n
+  }
+  throw new Error('protobuf: varint melebihi 10 byte')
+}
+
+/** Decode wire entries without applying any application-specific schema. */
+function parseFields(input) {
+  const buffer = Buffer.from(input)
+  const state = { offset: 0 }
+  const fields = []
+  while (state.offset < buffer.length) {
+    const rawTag = readVarint(buffer, state)
+    const fieldNumber = Number(rawTag >> 3n)
+    const wireType = Number(rawTag & 7n)
+    if (fieldNumber < 1 || fieldNumber > MAX_FIELD_NUMBER) throw new Error('protobuf: nomor field tidak valid')
+    let value
+    if (wireType === 0) {
+      value = readVarint(buffer, state)
+    } else if (wireType === 1) {
+      if (state.offset + 8 > buffer.length) throw new Error('protobuf: fixed64 terpotong')
+      value = Buffer.from(buffer.subarray(state.offset, state.offset + 8))
+      state.offset += 8
+    } else if (wireType === 2) {
+      const length = readVarint(buffer, state)
+      if (length > BigInt(buffer.length - state.offset)) throw new Error('protobuf: panjang field melebihi buffer')
+      const end = state.offset + Number(length)
+      value = Buffer.from(buffer.subarray(state.offset, end))
+      state.offset = end
+    } else if (wireType === 5) {
+      if (state.offset + 4 > buffer.length) throw new Error('protobuf: fixed32 terpotong')
+      value = Buffer.from(buffer.subarray(state.offset, state.offset + 4))
+      state.offset += 4
+    } else {
+      throw new Error(`protobuf: wire type ${wireType} tidak didukung`)
+    }
+    fields.push({ fieldNumber, wireType, value })
+  }
+  return fields
+}
+
+module.exports = {
+  encodeVarint, fieldVarint, fieldBool, fieldBytes, fieldString,
+  fieldMessage, fieldFixed32, pack, parseFields
+}

package/src/protocol/node-protocol.js

@@ -0,0 +1,155 @@
+'use strict'
+
+const crypto = require('node:crypto')
+const { encodeBinaryNode, decodeBinaryNode, loadTokenTable, makeTokenTables } = require('../wabinary/codec')
+
+class QueryTimeoutError extends Error {
+  constructor(id, timeoutMs) {
+    super(`WABinary IQ ${id} timeout setelah ${timeoutMs} ms`)
+    this.name = 'QueryTimeoutError'
+    this.code = 'ERR_QUERY_TIMEOUT'
+    this.id = id
+    this.timeoutMs = timeoutMs
+  }
+}
+
+class RemoteIQError extends Error {
+  constructor(node) {
+    const code = node?.attrs?.code ? ` (code ${node.attrs.code})` : ''
+    super(`server mengembalikan IQ error${code}`)
+    this.name = 'RemoteIQError'
+    this.code = 'ERR_REMOTE_IQ'
+    this.node = node
+  }
+}
+
+/**
+ * Node-level protocol layer above Noise transport. It does not implement Signal,
+ * registration credentials, or authenticated pairing-success verification.
+ */
+class NodeProtocol {
+  constructor(connection, options = {}) {
+    this.connection = connection
+    const hasExplicitTokenTable = options.tokens !== undefined && options.tokens !== null
+    this.tokens = hasExplicitTokenTable ? options.tokens : loadTokenTable(options.tokenTablePath)
+    makeTokenTables(this.tokens) // validate dictionary structure at construction time
+    const populated = (this.tokens.single || []).some(Boolean) || (this.tokens.double || []).some((page) => page.some(Boolean))
+    if (!populated && options.allowEmptyTokenTable !== true) {
+      throw new Error('NodeProtocol membutuhkan token dictionary non-kosong; jalankan npm run refresh:tokens terlebih dahulu (allowEmptyTokenTable hanya untuk tes lokal)')
+    }
+    if (this.tokens._metadata && this.tokens._metadata.dictVersion !== 3) {
+      throw new Error(`NodeProtocol mendukung DictVersion 3, menerima ${this.tokens._metadata.dictVersion}`)
+    }
+    this.timeoutMs = options.timeoutMs ?? 30000
+    this.maxPending = options.maxPending ?? 1024
+    this.closeOnDecodeError = options.closeOnDecodeError !== false
+    if (!Number.isSafeInteger(this.timeoutMs) || this.timeoutMs < 1) throw new TypeError('timeoutMs harus integer positif')
+    if (!Number.isSafeInteger(this.maxPending) || this.maxPending < 1) throw new TypeError('maxPending harus integer positif')
+    this.pending = new Map()
+    this.closed = false
+    this.onFrame = (frame) => this._handleFrame(frame)
+    this.onConnectionUpdate = ({ connection: state }) => {
+      if (state === 'close') this._rejectAll(new Error('koneksi ditutup sebelum IQ selesai'))
+    }
+    connection.on('frame', this.onFrame)
+    connection.on('connection.update', this.onConnectionUpdate)
+  }
+
+  sendNode(node) {
+    if (this.closed) throw new Error('NodeProtocol sudah ditutup')
+    const bytes = encodeBinaryNode(node, { tokens: this.tokens })
+    this.connection.sendFrame(bytes)
+    return bytes.length
+  }
+
+  query(node, options = {}) {
+    if (this.closed) return Promise.reject(new Error('NodeProtocol sudah ditutup'))
+    if (!node || node.tag !== 'iq') return Promise.reject(new TypeError('query() hanya menerima node IQ'))
+    if (this.pending.size >= this.maxPending) return Promise.reject(new Error('batas IQ pending tercapai'))
+    const timeoutMs = options.timeoutMs ?? this.timeoutMs
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) return Promise.reject(new TypeError('timeoutMs harus integer positif'))
+    const attrs = { ...(node.attrs || {}) }
+    const id = attrs.id === undefined || attrs.id === null ? this._newId() : String(attrs.id)
+    if (this.pending.has(id)) return Promise.reject(new Error(`IQ id duplikat: ${id}`))
+    attrs.id = id
+    const outgoing = { ...node, attrs }
+    if (options.signal?.aborted) return Promise.reject(options.signal.reason || new Error('IQ dibatalkan'))
+
+    return new Promise((resolve, reject) => {
+      const entry = { resolve, reject, timer: null, signal: options.signal, abort: null }
+      entry.timer = setTimeout(() => {
+        this._dropPending(id)
+        reject(new QueryTimeoutError(id, timeoutMs))
+      }, timeoutMs)
+      if (entry.signal) {
+        entry.abort = () => {
+          this._dropPending(id)
+          reject(entry.signal.reason || new Error('IQ dibatalkan'))
+        }
+        entry.signal.addEventListener('abort', entry.abort, { once: true })
+      }
+      this.pending.set(id, entry)
+      try { this.sendNode(outgoing) } catch (error) {
+        this._dropPending(id)
+        reject(error)
+      }
+    })
+  }
+
+  close(reason = new Error('NodeProtocol ditutup')) {
+    if (this.closed) return
+    this.closed = true
+    this.connection.off('frame', this.onFrame)
+    this.connection.off('connection.update', this.onConnectionUpdate)
+    this._rejectAll(reason)
+  }
+
+  stats() {
+    return { pendingQueries: this.pending.size, maxPending: this.maxPending, closed: this.closed }
+  }
+
+  _newId() {
+    return `${Date.now().toString(36)}-${crypto.randomBytes(6).toString('hex')}`
+  }
+
+  _handleFrame(frame) {
+    if (this.closed) return
+    let node
+    try {
+      node = decodeBinaryNode(frame, { tokens: this.tokens, requirePrefix: true })
+    } catch (error) {
+      this.connection._safeEmit('protocol.error', error)
+      if (this.closeOnDecodeError) this.connection.failProtocol(error)
+      return
+    }
+    this.connection._safeEmit('node', node)
+    this.connection._safeEmit(`node:${node.tag}`, node)
+    if (node.tag === 'iq') {
+      this.connection._safeEmit('iq', node)
+      const id = node.attrs?.id
+      const entry = id === undefined ? undefined : this.pending.get(String(id))
+      if (entry && (node.attrs?.type === 'result' || node.attrs?.type === 'error')) {
+        this._dropPending(String(id))
+        if (node.attrs.type === 'error') entry.reject(new RemoteIQError(node))
+        else entry.resolve(node)
+      }
+    }
+  }
+
+  _dropPending(id) {
+    const entry = this.pending.get(id)
+    if (!entry) return
+    clearTimeout(entry.timer)
+    if (entry.signal && entry.abort) entry.signal.removeEventListener('abort', entry.abort)
+    this.pending.delete(id)
+  }
+
+  _rejectAll(error) {
+    for (const [id, entry] of this.pending) {
+      this._dropPending(id)
+      entry.reject(error)
+    }
+  }
+}
+
+module.exports = { NodeProtocol, QueryTimeoutError, RemoteIQError }

package/src/session/codec.js

@@ -0,0 +1,25 @@
+'use strict'
+/**
+ * Serialisasi nilai session ke JSON dengan dukungan Buffer/Uint8Array (base64) dan bigint.
+ * Dipakai oleh store berbasis teks (file, SQLite, Redis, Mongo).
+ */
+function encode(value) {
+  return JSON.stringify(value, function (key, v) {
+    const raw = this[key] // JSON.stringify sudah memanggil Buffer.toJSON sebelum replacer
+    if (raw instanceof Uint8Array) return { $b: Buffer.from(raw.buffer, raw.byteOffset, raw.byteLength).toString('base64') }
+    if (typeof raw === 'bigint') return { $n: raw.toString() }
+    return v
+  })
+}
+
+function decode(text) {
+  return JSON.parse(text, (key, v) => {
+    if (v && typeof v === 'object') {
+      if (typeof v.$b === 'string' && Object.keys(v).length === 1) return Buffer.from(v.$b, 'base64')
+      if (typeof v.$n === 'string' && Object.keys(v).length === 1) return BigInt(v.$n)
+    }
+    return v
+  })
+}
+
+module.exports = { encode, decode }

package/src/session/encrypted-store.js

@@ -0,0 +1,107 @@
+'use strict'
+
+const crypto = require('node:crypto')
+const { encode, decode } = require('./codec')
+
+const FORMAT = 'kersiosocket:aes-256-gcm:v1'
+const IV_BYTES = 12
+const TAG_BYTES = 16
+
+/**
+ * Authenticated-encryption wrapper for any compatible session store.
+ * Supply a 32-byte master key from a secret manager or environment variable.
+ * The wrapper never generates or persists its own master key.
+ */
+class EncryptedStore {
+  constructor(store, masterKey) {
+    if (!store || typeof store.get !== 'function' || typeof store.set !== 'function' || typeof store.delete !== 'function') {
+      throw new TypeError('EncryptedStore memerlukan store dengan get/set/delete')
+    }
+    if (!Buffer.isBuffer(masterKey) && !(masterKey instanceof Uint8Array)) {
+      throw new TypeError('masterKey harus Buffer/Uint8Array 32 byte; jangan simpan key di source code')
+    }
+    const key = Buffer.from(masterKey.buffer, masterKey.byteOffset, masterKey.byteLength)
+    if (key.length !== 32) throw new RangeError('masterKey harus tepat 32 byte untuk AES-256-GCM')
+    this.store = store
+    this.key = Buffer.from(key)
+    this.closed = false
+  }
+
+  async get(key) {
+    this._assertOpen()
+    assertStorageKey(key)
+    const envelope = await this.store.get(key)
+    if (envelope === undefined) return undefined
+    if (!envelope || envelope.format !== FORMAT || typeof envelope.iv !== 'string' || typeof envelope.tag !== 'string' || typeof envelope.data !== 'string') {
+      throw new Error(`EncryptedStore: data '${key}' tidak memiliki format terenkripsi yang dikenali; tidak ada fallback plaintext`)
+    }
+    const iv = decodeBase64Strict(envelope.iv, 'iv')
+    const tag = decodeBase64Strict(envelope.tag, 'tag')
+    const data = decodeBase64Strict(envelope.data, 'data')
+    if (iv.length !== IV_BYTES || tag.length !== TAG_BYTES) throw new Error(`EncryptedStore: envelope '${key}' malformed`)
+    try {
+      const decipher = crypto.createDecipheriv('aes-256-gcm', this.key, iv)
+      decipher.setAAD(this._aad(key))
+      decipher.setAuthTag(tag)
+      const plain = Buffer.concat([decipher.update(data), decipher.final()])
+      return decode(plain.toString('utf8'))
+    } catch {
+      throw new Error(`EncryptedStore: autentikasi/dekripsi gagal untuk '${key}' (key salah atau data diubah)`)
+    }
+  }
+
+  async set(key, value) {
+    this._assertOpen()
+    assertStorageKey(key)
+    const iv = crypto.randomBytes(IV_BYTES)
+    const cipher = crypto.createCipheriv('aes-256-gcm', this.key, iv)
+    cipher.setAAD(this._aad(key))
+    const plain = Buffer.from(encode(value), 'utf8')
+    const data = Buffer.concat([cipher.update(plain), cipher.final()])
+    await this.store.set(key, {
+      format: FORMAT,
+      iv: iv.toString('base64'),
+      tag: cipher.getAuthTag().toString('base64'),
+      data: data.toString('base64')
+    })
+  }
+
+  async delete(key) {
+    this._assertOpen()
+    assertStorageKey(key)
+    await this.store.delete(key)
+  }
+
+  async keys(prefix = '') {
+    this._assertOpen()
+    if (typeof prefix !== 'string') throw new TypeError('prefix harus string')
+    if (typeof this.store.keys !== 'function') throw new Error('store dasar tidak mendukung keys()')
+    return this.store.keys(prefix)
+  }
+
+  async close() {
+    if (this.closed) return
+    this.closed = true
+    this.key.fill(0)
+    if (typeof this.store.close === 'function') await this.store.close()
+  }
+
+  _assertOpen() {
+    if (this.closed) throw new Error('EncryptedStore sudah ditutup')
+  }
+
+  _aad(key) { return Buffer.from(`${FORMAT}\0${key}`, 'utf8') }
+}
+
+function assertStorageKey(key) {
+  if (typeof key !== 'string' || key.length === 0 || key.includes('\0')) throw new TypeError('key harus string non-kosong tanpa NUL')
+}
+
+function decodeBase64Strict(value, name) {
+  if (value.length % 4 !== 0 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+    throw new Error(`EncryptedStore: ${name} bukan base64 valid`)
+  }
+  return Buffer.from(value, 'base64')
+}
+
+module.exports = { EncryptedStore, ENCRYPTED_STORE_FORMAT: FORMAT }

package/src/session/manager.js

@@ -0,0 +1,61 @@
+'use strict'
+const { makeSocket } = require('../socket/make')
+
+/**
+ * Banyak sesi (banyak nomor) dalam satu proses, semuanya memakai satu store.
+ *
+ *   const sessions = createSessionManager({ store: new FileStore('./sessions'), logger })
+ *   const a = sessions.open('nomor-a')   // dibuat sekali, dipakai ulang
+ *   const b = sessions.open('nomor-b')
+ *   await sessions.list()                // semua sesi yang tersimpan di store
+ *   sessions.stats()                     // ringkasan per sesi + total RAM proses
+ */
+function createSessionManager({ store, ...defaults } = {}) {
+  if (!store) throw new Error('createSessionManager: store wajib diisi')
+  const live = new Map()
+
+  return {
+    open(id, overrides = {}) {
+      if (!id || /[:/\\]/.test(id)) throw new Error('id sesi tidak valid (tanpa : / \\)')
+      let sock = live.get(id)
+      if (!sock) {
+        sock = makeSocket({ ...defaults, ...overrides, store, sessionId: id })
+        live.set(id, sock)
+      }
+      return sock
+    },
+
+    get: (id) => live.get(id),
+
+    /** Hentikan koneksi sebuah sesi. Dengan { purge: true } kredensialnya juga dihapus dari store. */
+    async close(id, { purge = false } = {}) {
+      const sock = live.get(id)
+      if (sock) { await sock.ready; sock.end(); live.delete(id) }
+      if (purge) await store.delete(`${id}:creds`)
+    },
+
+    async closeAll() {
+      await Promise.all([...live.keys()].map((id) => this.close(id)))
+      if (store.close) await store.close()
+    },
+
+    async list() {
+      if (!store.keys) throw new Error('store ini tidak mendukung keys()')
+      const ids = new Set()
+      for (const k of await store.keys()) {
+        const i = k.indexOf(':')
+        if (i > 0 && k.slice(i + 1) === 'creds') ids.add(k.slice(0, i))
+      }
+      return [...ids]
+    },
+
+    stats() {
+      const m = process.memoryUsage()
+      const sessions = {}
+      for (const [id, s] of live) sessions[id] = s.stats()
+      return { sessions, active: live.size, rssMB: +(m.rss / 1048576).toFixed(1), heapUsedMB: +(m.heapUsed / 1048576).toFixed(1) }
+    }
+  }
+}
+
+module.exports = { createSessionManager }

package/src/session/stores.js

@@ -0,0 +1,154 @@
+'use strict'
+/**
+ * Store session. Satu interface untuk semua backend:
+ *
+ *   get(key)            -> Promise<value | undefined>
+ *   set(key, value)     -> Promise<void>
+ *   delete(key)         -> Promise<void>
+ *   keys(prefix?)       -> Promise<string[]>   (opsional, dipakai daftar sesi)
+ *   close?()            -> Promise<void>
+ *
+ * Mau backend sendiri? Cukup buat objek dengan get/set/delete.
+ */
+const fs = require('node:fs')
+const fsp = fs.promises
+const path = require('node:path')
+const crypto = require('node:crypto')
+const { encode, decode } = require('./codec')
+
+/** Store di memori. Untuk test atau sesi sementara. */
+class MemoryStore {
+  constructor() { this.m = new Map() }
+  async get(key) { const v = this.m.get(key); return v === undefined ? undefined : decode(v) }
+  async set(key, value) { this.m.set(key, encode(value)) }
+  async delete(key) { this.m.delete(key) }
+  async keys(prefix = '') { return [...this.m.keys()].filter((k) => k.startsWith(prefix)) }
+}
+
+// Nama file aman di Windows/Linux/Termux, dan bisa dibalik jadi key asli.
+const fileName = (key) => encodeURIComponent(key).replace(/\./g, '%2E').replace(/\*/g, '%2A') + '.json'
+const keyOf = (name) => decodeURIComponent(name.slice(0, -5))
+
+/**
+ * Store file. Satu key = satu file JSON.
+ * Penulisan atomik: tulis ke file sementara, fsync, lalu rename. Bila proses mati di tengah
+ * penulisan, file lama tetap utuh. File yang rusak dipindah ke *.corrupt, bukan dihapus.
+ */
+class FileStore {
+  constructor(dir, { fsync = true } = {}) {
+    this.dir = path.resolve(dir)
+    this.fsync = fsync
+    this.queues = new Map() // key -> promise terakhir; menjaga urutan tulis per key
+    fs.mkdirSync(this.dir, { recursive: true })
+    for (const f of fs.readdirSync(this.dir)) if (f.endsWith('.tmp')) fs.rmSync(path.join(this.dir, f), { force: true })
+  }
+
+  _file(key) { return path.join(this.dir, fileName(key)) }
+
+  async get(key) {
+    const file = this._file(key)
+    let text
+    try { text = await fsp.readFile(file, 'utf8') } catch (e) {
+      if (e.code === 'ENOENT') return undefined
+      throw e
+    }
+    try { return decode(text) } catch {
+      await fsp.rename(file, `${file}.${Date.now()}.corrupt`).catch(() => {})
+      return undefined
+    }
+  }
+
+  set(key, value) { return this._queue(key, () => this._writeAtomic(this._file(key), encode(value))) }
+
+  delete(key) { return this._queue(key, () => fsp.rm(this._file(key), { force: true })) }
+
+  async keys(prefix = '') {
+    const names = await fsp.readdir(this.dir)
+    return names.filter((n) => n.endsWith('.json')).map(keyOf).filter((k) => k.startsWith(prefix))
+  }
+
+  _queue(key, job) {
+    const prev = this.queues.get(key) || Promise.resolve()
+    const next = prev.catch(() => {}).then(job)
+    this.queues.set(key, next)
+    const clean = () => { if (this.queues.get(key) === next) this.queues.delete(key) }
+    next.then(clean, clean)
+    return next
+  }
+
+  async _writeAtomic(file, text) {
+    const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`
+    const fh = await fsp.open(tmp, 'w')
+    try {
+      await fh.writeFile(text)
+      if (this.fsync) await fh.sync()
+    } finally { await fh.close() }
+    try { await fsp.rename(tmp, file) } catch (e) { await fsp.rm(tmp, { force: true }); throw e }
+  }
+}
+
+/** Store SQLite memakai node:sqlite bawaan Node (>= 22.5). Tanpa dependensi. */
+class SQLiteStore {
+  constructor(file = ':memory:') {
+    let DatabaseSync
+    try { ({ DatabaseSync } = require('node:sqlite')) } catch {
+      throw new Error('SQLiteStore butuh node:sqlite (Node >= 22.5)')
+    }
+    this.db = new DatabaseSync(file)
+    this.db.exec('PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL; CREATE TABLE IF NOT EXISTS kv (k TEXT PRIMARY KEY, v TEXT NOT NULL) WITHOUT ROWID')
+    this._get = this.db.prepare('SELECT v FROM kv WHERE k = ?')
+    this._set = this.db.prepare('INSERT INTO kv (k, v) VALUES (?, ?) ON CONFLICT(k) DO UPDATE SET v = excluded.v')
+    this._del = this.db.prepare('DELETE FROM kv WHERE k = ?')
+    this._keys = this.db.prepare("SELECT k FROM kv WHERE substr(k, 1, ?) = ?")
+  }
+  async get(key) { const r = this._get.get(key); return r ? decode(r.v) : undefined }
+  async set(key, value) { this._set.run(key, encode(value)) }
+  async delete(key) { this._del.run(key) }
+  async keys(prefix = '') { return this._keys.all(prefix.length, prefix).map((r) => r.k) }
+  async close() { this.db.close() }
+}
+
+/**
+ * Adapter Redis. Berikan klien yang SUDAH dibuat (node-redis v4+ atau ioredis).
+ * Library ini tidak ikut membawa dependensi Redis.
+ */
+class RedisStore {
+  constructor(client, { prefix = 'kersio:' } = {}) { this.c = client; this.prefix = prefix }
+  async get(key) { const v = await this.c.get(this.prefix + key); return v == null ? undefined : decode(String(v)) }
+  async set(key, value) { await this.c.set(this.prefix + key, encode(value)) }
+  async delete(key) { await this.c.del(this.prefix + key) }
+  async keys(prefix = '') {
+    const pattern = `${this.prefix}${prefix}`.replace(/[\\*?\[\]]/g, '\\$&') + '*'
+    const out = []
+    if (typeof this.c.scanIterator === 'function') {
+      for await (const batch of this.c.scanIterator({ MATCH: pattern, COUNT: 200 })) {
+        for (const k of Array.isArray(batch) ? batch : [batch]) out.push(k)
+      }
+    } else out.push(...(await this.c.keys(pattern)))
+    return out.map((k) => k.slice(this.prefix.length))
+  }
+}
+
+/** Adapter MongoDB. Berikan objek collection dari driver `mongodb`. */
+class MongoStore {
+  constructor(collection) { this.col = collection }
+  async get(key) { const d = await this.col.findOne({ _id: key }); return d ? decode(d.v) : undefined }
+  async set(key, value) { await this.col.replaceOne({ _id: key }, { _id: key, v: encode(value) }, { upsert: true }) }
+  async delete(key) { await this.col.deleteOne({ _id: key }) }
+  async keys(prefix = '') {
+    const re = '^' + prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    return (await this.col.find({ _id: { $regex: re } }, { projection: { _id: 1 } }).toArray()).map((d) => d._id)
+  }
+}
+
+/** Bungkus store dengan namespace: semua key diawali `${ns}:`. */
+function scoped(store, ns) {
+  const p = `${ns}:`
+  return {
+    get: (k) => store.get(p + k),
+    set: (k, v) => store.set(p + k, v),
+    delete: (k) => store.delete(p + k)
+  }
+}
+
+module.exports = { MemoryStore, FileStore, SQLiteStore, RedisStore, MongoStore, scoped }