kersiosocket 0.0.0-stage → 0.5.0-dev

package/src/utils/lru.js

@@ -0,0 +1,76 @@
+'use strict'
+/**
+ * Cache LRU dengan batas jumlah entri, batas ukuran (byte) opsional, dan TTL opsional.
+ * Memakai urutan sisip Map, jadi get/set O(1) tanpa struktur tambahan.
+ *
+ * new LRUCache({ max: 1000, maxBytes: 8 * 1024 * 1024, sizeOf: (v) => v.length, ttl: 60000 })
+ */
+class LRUCache {
+  constructor({ max = 500, maxBytes = Infinity, sizeOf = null, ttl = 0, onEvict = null } = {}) {
+    if (!(max > 0)) throw new Error('LRUCache: max harus > 0')
+    this.max = max
+    this.maxBytes = maxBytes
+    this.sizeOf = sizeOf
+    this.ttl = ttl
+    this.onEvict = onEvict
+    this.map = new Map() // key -> { v, size, exp }
+    this.bytes = 0
+    this.hits = 0
+    this.misses = 0
+  }
+
+  get size() { return this.map.size }
+
+  get(key) {
+    const e = this.map.get(key)
+    if (!e) { this.misses++; return undefined }
+    if (e.exp && e.exp <= Date.now()) { this._drop(key, e, 'expired'); this.misses++; return undefined }
+    this.map.delete(key)
+    this.map.set(key, e) // pindah ke ujung = paling baru dipakai
+    this.hits++
+    return e.v
+  }
+
+  has(key) {
+    const e = this.map.get(key)
+    if (!e) return false
+    if (e.exp && e.exp <= Date.now()) { this._drop(key, e, 'expired'); return false }
+    return true
+  }
+
+  set(key, v) {
+    const old = this.map.get(key)
+    if (old) { this.bytes -= old.size; this.map.delete(key) }
+    const size = this.sizeOf ? this.sizeOf(v) : 0
+    this.map.set(key, { v, size, exp: this.ttl ? Date.now() + this.ttl : 0 })
+    this.bytes += size
+    while (this.map.size > this.max || this.bytes > this.maxBytes) {
+      const [k, e] = this.map.entries().next().value
+      if (k === key && this.map.size === 1) break // satu entri raksasa tetap disimpan
+      this._drop(k, e, 'evicted')
+    }
+    return this
+  }
+
+  delete(key) {
+    const e = this.map.get(key)
+    if (!e) return false
+    this.bytes -= e.size
+    return this.map.delete(key)
+  }
+
+  clear() { this.map.clear(); this.bytes = 0 }
+
+  _drop(key, e, reason) {
+    this.map.delete(key)
+    this.bytes -= e.size
+    if (this.onEvict) this.onEvict(key, e.v, reason)
+  }
+
+  stats() {
+    const n = this.hits + this.misses
+    return { size: this.map.size, bytes: this.bytes, hits: this.hits, misses: this.misses, hitRate: n ? +(this.hits / n).toFixed(3) : 0 }
+  }
+}
+
+module.exports = { LRUCache }

package/src/wabinary/codec.js

@@ -0,0 +1,374 @@
+'use strict'
+
+const zlib = require('node:zlib')
+const fs = require('node:fs')
+const path = require('node:path')
+const { TAGS } = require('./tags')
+const { validateTokenTable } = require('./token-source')
+
+const DEFAULT_LIMITS = Object.freeze({ maxDepth: 64, maxNodes: 100000, maxBytes: 16 * 1024 * 1024 })
+const NIBBLE_ALPHABET = '0123456789-.'
+const HEX_ALPHABET = '0123456789ABCDEF'
+
+function asBuffer(value, label = 'value') {
+  if (Buffer.isBuffer(value)) return value
+  if (value instanceof Uint8Array) return Buffer.from(value.buffer, value.byteOffset, value.byteLength)
+  throw new TypeError(`${label} harus Buffer atau Uint8Array`)
+}
+
+function loadTokenTable(filePath = path.join(__dirname, 'tokens.json')) {
+  const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'))
+  if (parsed._metadata && parsed._metadata.dictVersion !== 3) {
+    throw new Error(`WABinary token DictVersion mismatch: codec supports 3, file declares ${parsed._metadata.dictVersion}`)
+  }
+  if (parsed._metadata?.upstreamBlobSha1 && !/^[0-9a-f]{40}$/.test(parsed._metadata.upstreamBlobSha1)) {
+    throw new Error('WABinary token metadata has an invalid source blob SHA-1')
+  }
+  makeTokenTables(parsed)
+  if (parsed._metadata) {
+    validateTokenTable({ dictVersion: parsed._metadata.dictVersion, single: parsed.single, double: parsed.double }, { dictVersion: 3 })
+  }
+  return parsed
+}
+
+function makeTokenTables(tokens = {}) {
+  const single = tokens.single || []
+  const double = tokens.double || [[], [], [], []]
+  if (!Array.isArray(single) || !Array.isArray(double) || double.length !== 4 || double.some((p) => !Array.isArray(p))) {
+    throw new TypeError('token table harus { single: string[], double: [string[], string[], string[], string[]] }')
+  }
+  const singleToId = new Map()
+  for (let i = 1; i < single.length && i < TAGS.DICTIONARY_0; i++) {
+    if (typeof single[i] === 'string' && single[i] && !singleToId.has(single[i])) singleToId.set(single[i], i)
+  }
+  const doubleToId = new Map()
+  for (let page = 0; page < 4; page++) {
+    for (let i = 0; i < double[page].length && i <= 255; i++) {
+      const token = double[page][i]
+      if (typeof token === 'string' && token && !doubleToId.has(token)) doubleToId.set(token, [page, i])
+    }
+  }
+  return { single, double, singleToId, doubleToId }
+}
+
+function pushUInt20(n, out) {
+  if (!Number.isInteger(n) || n < 0 || n > 0xfffff) throw new RangeError('panjang BINARY_20 di luar rentang')
+  out.push((n >>> 16) & 0x0f, (n >>> 8) & 0xff, n & 0xff)
+}
+function readUInt20(buf, state) {
+  need(buf, state, 3)
+  const a = buf[state.offset++], b = buf[state.offset++], c = buf[state.offset++]
+  return ((a & 0x0f) << 16) | (b << 8) | c
+}
+function need(buf, state, n) {
+  if (!Number.isSafeInteger(n) || n < 0 || state.offset + n > buf.length) throw new Error('WABinary: data terpotong')
+}
+function encodeListSize(size, out) {
+  if (!Number.isInteger(size) || size < 0 || size > 0xffff) throw new RangeError('ukuran list node di luar rentang')
+  if (size === 0) out.push(TAGS.LIST_EMPTY)
+  else if (size < 256) out.push(TAGS.LIST_8, size)
+  else { out.push(TAGS.LIST_16, (size >>> 8) & 0xff, size & 0xff) }
+}
+function encodeLengthAndBytes(bytes, out) {
+  if (bytes.length <= 0xff) out.push(TAGS.BINARY_8, bytes.length)
+  else if (bytes.length <= 0xfffff) { out.push(TAGS.BINARY_20); pushUInt20(bytes.length, out) }
+  else if (bytes.length <= 0x7fffffff) {
+    out.push(TAGS.BINARY_32, (bytes.length >>> 24) & 0xff, (bytes.length >>> 16) & 0xff, (bytes.length >>> 8) & 0xff, bytes.length & 0xff)
+  } else throw new RangeError('payload biner terlalu besar')
+  for (const b of bytes) out.push(b)
+}
+
+function packNibble(value, out) {
+  if (value.length > TAGS.PACKED_MAX || !/^[0-9.-]+$/.test(value)) return false
+  out.push(TAGS.NIBBLE_8)
+  const pairs = Math.ceil(value.length / 2)
+  out.push(pairs | (value.length % 2 ? 0x80 : 0))
+  for (let i = 0; i < value.length; i += 2) {
+    const first = NIBBLE_ALPHABET.indexOf(value[i])
+    const second = i + 1 < value.length ? NIBBLE_ALPHABET.indexOf(value[i + 1]) : 15
+    out.push((first << 4) | second)
+  }
+  return true
+}
+function packHex(value, out) {
+  if (value.length > TAGS.PACKED_MAX || !/^[0-9A-F]+$/.test(value)) return false
+  out.push(TAGS.HEX_8)
+  const pairs = Math.ceil(value.length / 2)
+  out.push(pairs | (value.length % 2 ? 0x80 : 0))
+  for (let i = 0; i < value.length; i += 2) {
+    const first = Number.parseInt(value[i], 16)
+    const second = i + 1 < value.length ? Number.parseInt(value[i + 1], 16) : 15
+    out.push((first << 4) | second)
+  }
+  return true
+}
+
+function parseJid(value) {
+  const at = value.indexOf('@')
+  if (at < 0 || at !== value.lastIndexOf('@') || at === value.length - 1) return null
+  const local = value.slice(0, at)
+  const server = value.slice(at + 1)
+  const match = /^([^:@_]*)(?:_(\d+))?(?::(\d+))?$/.exec(local)
+  if (!match) return null
+  const user = match[1]
+  const agent = match[2] === undefined ? 0 : Number(match[2])
+  const device = match[3] === undefined ? undefined : Number(match[3])
+  if (device !== undefined && (!Number.isInteger(device) || device < 0 || device > 255)) return null
+  if (!Number.isSafeInteger(agent) || agent < 0 || agent > 255) return null
+  return { user, server, agent, device, local }
+}
+function encodeJid(value, out, table) {
+  const jid = parseJid(value)
+  if (!jid) return false
+  if (jid.device !== undefined && ['s.whatsapp.net', 'lid', 'hosted', 'hosted.lid'].includes(jid.server)) {
+    const mapped = { 's.whatsapp.net': 0, lid: 1, hosted: 128, 'hosted.lid': 129 }[jid.server]
+    const domainType = jid.agent || mapped
+    out.push(TAGS.AD_JID, domainType, jid.device)
+    encodeString(jid.user, out, table, { jidPairs: false, allowJid: false })
+    return true
+  }
+  // Match the reference's JID_PAIR shape: encode decoded user and server separately;
+  // an empty user is represented by LIST_EMPTY, not an empty raw string.
+  out.push(TAGS.JID_PAIR)
+  if (jid.user.length) encodeString(jid.user, out, table, { jidPairs: false, allowJid: false })
+  else out.push(TAGS.LIST_EMPTY)
+  encodeString(jid.server, out, table, { jidPairs: false, allowJid: false })
+  return true
+}
+
+function encodeString(value, out, table, options = {}) {
+  if (typeof value !== 'string') throw new TypeError('tag/atribut/string content harus string')
+  const token = table.singleToId.get(value)
+  if (token !== undefined) { out.push(token); return }
+  const double = table.doubleToId.get(value)
+  if (double) { out.push(TAGS.DICTIONARY_0 + double[0], double[1]); return }
+  if (options.jidPairs !== false && options.allowJid !== false && encodeJid(value, out, table)) return
+  if (packNibble(value, out) || packHex(value, out)) return
+  encodeLengthAndBytes(Buffer.from(value, 'utf8'), out)
+}
+
+function encodeNode(node, out, table, depth, limits, counter) {
+  if (depth > limits.maxDepth) throw new RangeError('WABinary: kedalaman node melampaui batas')
+  if (++counter.nodes > limits.maxNodes) throw new RangeError('WABinary: jumlah node melampaui batas')
+  if (!node || typeof node !== 'object' || Array.isArray(node)) throw new TypeError('node harus objek')
+  if (typeof node.tag !== 'string' || node.tag.length === 0) throw new TypeError('node.tag wajib string non-kosong')
+  const attrsObject = node.attrs || {}
+  if (!attrsObject || typeof attrsObject !== 'object' || Array.isArray(attrsObject)) throw new TypeError('node.attrs harus objek')
+  const entries = Object.entries(attrsObject).filter(([, value]) => value !== undefined && value !== null)
+  const content = node.content
+  const hasContent = content !== undefined && content !== null
+  const isChildren = Array.isArray(content)
+  if (hasContent && !isChildren && typeof content !== 'string' && !Buffer.isBuffer(content) && !(content instanceof Uint8Array)) {
+    throw new TypeError(`WABinary: tipe content node tidak didukung: ${typeof content}`)
+  }
+  const listSize = 1 + entries.length * 2 + (hasContent ? 1 : 0)
+  encodeListSize(listSize, out)
+  encodeString(node.tag, out, table)
+  for (const [key, value] of entries) {
+    if (typeof value !== 'string') throw new TypeError(`atribut ${key} harus string`)
+    encodeString(key, out, table)
+    encodeString(value, out, table)
+  }
+  if (!hasContent) return
+  if (isChildren) {
+    encodeListSize(content.length, out)
+    for (const child of content) encodeNode(child, out, table, depth + 1, limits, counter)
+  } else if (typeof content === 'string') encodeString(content, out, table)
+  else encodeLengthAndBytes(asBuffer(content, 'content'), out)
+}
+
+/**
+ * Encode a WABinary node. By default the standard 0x00 uncompressed node prefix
+ * is included. Set withPrefix:false only for raw codec fixtures, not socket sends.
+ * compress:true emits 0x02 followed by a zlib-compressed node body.
+ */
+function encodeBinaryNode(node, options = {}) {
+  const table = makeTokenTables(options.tokens)
+  const limits = { ...DEFAULT_LIMITS, ...(options.limits || {}) }
+  validateLimits(limits)
+  const out = []
+  encodeNode(node, out, table, 0, limits, { nodes: 0 })
+  const body = Buffer.from(out)
+  if (body.length > limits.maxBytes) throw new RangeError('WABinary: hasil melebihi maxBytes')
+  let result
+  if (options.compress) result = Buffer.concat([Buffer.from([0x02]), zlib.deflateSync(body, options.zlibOptions)])
+  else if (options.withPrefix !== false) result = Buffer.concat([Buffer.from([0x00]), body])
+  else result = body
+  if (result.length > limits.maxBytes) throw new RangeError('WABinary: hasil melebihi maxBytes')
+  return result
+}
+
+function validateLimits(limits) {
+  for (const name of ['maxDepth', 'maxNodes', 'maxBytes']) {
+    if (!Number.isSafeInteger(limits[name]) || limits[name] < 1) throw new TypeError(`WABinary limits.${name} harus integer positif`)
+  }
+}
+
+function readByte(buf, state) { need(buf, state, 1); return buf[state.offset++] }
+function readUInt16(buf, state) { need(buf, state, 2); const n = buf.readUInt16BE(state.offset); state.offset += 2; return n }
+function readLength(buf, state, marker) {
+  if (marker === TAGS.BINARY_8) return readByte(buf, state)
+  if (marker === TAGS.BINARY_20) return readUInt20(buf, state)
+  if (marker === TAGS.BINARY_32) {
+    need(buf, state, 4)
+    const n = buf.readUInt32BE(state.offset); state.offset += 4
+    if (n > 0x7fffffff) throw new RangeError('WABinary: panjang binary terlalu besar')
+    return n
+  }
+  throw new Error(`WABinary: marker panjang tidak valid ${marker}`)
+}
+function readRawString(buf, state, length) {
+  need(buf, state, length)
+  const s = buf.toString('utf8', state.offset, state.offset + length)
+  state.offset += length
+  return s
+}
+function unpackNibble(n) {
+  if (n >= 0 && n <= 9) return String(n)
+  if (n === 10) return '-'
+  if (n === 11) return '.'
+  if (n === 15) return '\0'
+  throw new Error(`WABinary: nibble tidak valid ${n}`)
+}
+function unpackHex(n) {
+  if (n >= 0 && n <= 15) return HEX_ALPHABET[n]
+  throw new Error(`WABinary: hex nibble tidak valid ${n}`)
+}
+function readPacked8(buf, state, marker) {
+  const packedLength = readByte(buf, state)
+  const odd = (packedLength & 0x80) !== 0
+  const byteLength = packedLength & 0x7f
+  need(buf, state, byteLength)
+  let result = ''
+  for (let i = 0; i < byteLength; i++) {
+    const byte = buf[state.offset++]
+    result += marker === TAGS.HEX_8 ? unpackHex(byte >>> 4) : unpackNibble(byte >>> 4)
+    const low = byte & 0x0f
+    result += marker === TAGS.HEX_8 ? unpackHex(low) : unpackNibble(low)
+  }
+  if (odd) {
+    if (!result.endsWith('\0')) throw new Error('WABinary: filler nibble packed tidak valid')
+    result = result.slice(0, -1)
+  } else if (result.includes('\0')) throw new Error('WABinary: filler nibble tidak diizinkan di tengah string')
+  return result
+}
+function readListSize(buf, state, marker = readByte(buf, state)) {
+  if (marker === TAGS.LIST_EMPTY) return 0
+  if (marker === TAGS.LIST_8) return readByte(buf, state)
+  if (marker === TAGS.LIST_16) return readUInt16(buf, state)
+  throw new Error(`WABinary: marker list tidak valid ${marker}`)
+}
+function decodeString(buf, state, table, marker = readByte(buf, state)) {
+  if (marker > 0 && marker < TAGS.DICTIONARY_0) {
+    const value = table.single[marker]
+    if (typeof value !== 'string' || !value) throw new Error(`WABinary: token tunggal ${marker} tidak ada di tabel`)
+    return value
+  }
+  if (marker >= TAGS.DICTIONARY_0 && marker <= TAGS.DICTIONARY_3) {
+    const page = marker - TAGS.DICTIONARY_0
+    const id = readByte(buf, state)
+    const value = table.double[page][id]
+    if (typeof value !== 'string' || !value) throw new Error(`WABinary: token dictionary ${page}:${id} tidak ada di tabel`)
+    return value
+  }
+  if (marker === TAGS.LIST_EMPTY) return ''
+  if (marker === TAGS.BINARY_8 || marker === TAGS.BINARY_20 || marker === TAGS.BINARY_32) return readRawString(buf, state, readLength(buf, state, marker))
+  if (marker === TAGS.JID_PAIR) {
+    const user = decodeString(buf, state, table)
+    const server = decodeString(buf, state, table)
+    if (!server) throw new Error('WABinary: JID_PAIR tanpa server')
+    return `${user}@${server}`
+  }
+  if (marker === TAGS.AD_JID) {
+    const domainType = readByte(buf, state)
+    const device = readByte(buf, state)
+    const user = decodeString(buf, state, table)
+    const server = ({ 0: 's.whatsapp.net', 1: 'lid', 128: 'hosted', 129: 'hosted.lid' })[domainType]
+    if (!server) throw new Error(`WABinary: domainType AD_JID tidak dikenal ${domainType}`)
+    return device === 0 ? `${user}@${server}` : `${user}:${device}@${server}`
+  }
+  if (marker === TAGS.FB_JID) {
+    const user = decodeString(buf, state, table)
+    const device = readUInt16(buf, state)
+    const server = decodeString(buf, state, table)
+    if (!server) throw new Error('WABinary: FB_JID tanpa server')
+    return `${user}:${device}@${server}`
+  }
+  if (marker === TAGS.INTEROP_JID) {
+    const user = decodeString(buf, state, table)
+    const device = readUInt16(buf, state)
+    const integrator = readUInt16(buf, state)
+    let server = 'interop'
+    // The server suffix is optional in the observed wire format.
+    if (state.offset < buf.length) {
+      const before = state.offset
+      try {
+        server = decodeString(buf, state, table)
+      } catch {
+        state.offset = before
+      }
+    }
+    return `${integrator}-${user}:${device}@${server}`
+  }
+  if (marker === TAGS.HEX_8 || marker === TAGS.NIBBLE_8) return readPacked8(buf, state, marker)
+  throw new Error(`WABinary: string marker tidak dikenal ${marker}`)
+}
+function decodeContent(buf, state, table, depth, limits) {
+  const marker = readByte(buf, state)
+  if (marker === TAGS.LIST_EMPTY || marker === TAGS.LIST_8 || marker === TAGS.LIST_16) {
+    const size = readListSize(buf, state, marker)
+    if (state.nodes + size > limits.maxNodes) throw new RangeError('WABinary: jumlah node melampaui batas')
+    const children = []
+    for (let i = 0; i < size; i++) children.push(decodeNode(buf, state, table, depth + 1, limits))
+    return children
+  }
+  if (marker === TAGS.BINARY_8 || marker === TAGS.BINARY_20 || marker === TAGS.BINARY_32) {
+    const length = readLength(buf, state, marker)
+    need(buf, state, length)
+    const data = Buffer.from(buf.subarray(state.offset, state.offset + length)); state.offset += length
+    return data
+  }
+  return decodeString(buf, state, table, marker)
+}
+function decodeNode(buf, state, table, depth, limits) {
+  if (depth > limits.maxDepth) throw new RangeError('WABinary: kedalaman node melampaui batas')
+  if (++state.nodes > limits.maxNodes) throw new RangeError('WABinary: jumlah node melampaui batas')
+  const size = readListSize(buf, state)
+  if (size < 1) throw new Error('WABinary: node list kosong')
+  if (size % 2 === 0 && size < 2) throw new Error('WABinary: ukuran node tidak valid')
+  const tag = decodeString(buf, state, table)
+  if (!tag) throw new Error('WABinary: tag node kosong')
+  const attrCount = Math.floor((size - 1) / 2)
+  const attrs = Object.create(null)
+  for (let i = 0; i < attrCount; i++) {
+    const key = decodeString(buf, state, table)
+    const value = decodeString(buf, state, table)
+    if (Object.hasOwn(attrs, key)) throw new Error(`WABinary: atribut duplikat ${key}`)
+    attrs[key] = value
+  }
+  let content
+  if (size % 2 === 0) content = decodeContent(buf, state, table, depth, limits)
+  return { tag, attrs, ...(content === undefined ? {} : { content }) }
+}
+
+function decodeBinaryNode(input, options = {}) {
+  let buf = asBuffer(input, 'input')
+  const limits = { ...DEFAULT_LIMITS, ...(options.limits || {}) }
+  validateLimits(limits)
+  if (buf.length > limits.maxBytes) throw new RangeError('WABinary: input melebihi maxBytes')
+  if (!buf.length) throw new Error('WABinary: input kosong')
+  if (options.decompress !== false) {
+    const prefix = buf[0]
+    if (prefix === 0x02) buf = zlib.inflateSync(buf.subarray(1), { maxOutputLength: limits.maxBytes })
+    else if (prefix === 0x00) buf = buf.subarray(1)
+    else if (options.requirePrefix === true) throw new Error(`WABinary: prefix node tidak dikenal ${prefix}`)
+  }
+  if (buf.length > limits.maxBytes) throw new RangeError('WABinary: hasil dekompresi melebihi maxBytes')
+  const table = makeTokenTables(options.tokens)
+  const state = { offset: 0, nodes: 0 }
+  const node = decodeNode(buf, state, table, 0, limits)
+  if (state.offset !== buf.length) throw new Error(`WABinary: ${buf.length - state.offset} byte tersisa setelah node`)
+  return node
+}
+
+module.exports = { encodeBinaryNode, decodeBinaryNode, makeTokenTables, loadTokenTable, TAGS, DEFAULT_LIMITS }

package/src/wabinary/tags.js

@@ -0,0 +1,25 @@
+'use strict'
+
+// WABinary wire markers. Dictionary entries live in the versioned token-data file.
+const TAGS = Object.freeze({
+  LIST_EMPTY: 0,
+  STREAM_END: 2,
+  DICTIONARY_0: 236,
+  DICTIONARY_1: 237,
+  DICTIONARY_2: 238,
+  DICTIONARY_3: 239,
+  INTEROP_JID: 245,
+  FB_JID: 246,
+  AD_JID: 247,
+  LIST_8: 248,
+  LIST_16: 249,
+  JID_PAIR: 250,
+  HEX_8: 251,
+  BINARY_8: 252,
+  BINARY_20: 253,
+  BINARY_32: 254,
+  NIBBLE_8: 255,
+  PACKED_MAX: 127
+})
+
+module.exports = { TAGS }

package/src/wabinary/token-source.js

@@ -0,0 +1,146 @@
+'use strict'
+
+// Small parser for the version-pinned token data source. This file does not
+// implement WABinary; it only converts the source's token arrays to JSON data.
+function readGoString(source, start) {
+  if (source[start] !== '"') throw new Error('Go token parser: expected string literal')
+  let i = start + 1
+  let value = ''
+  while (i < source.length) {
+    const char = source[i++]
+    if (char === '"') return { value, next: i }
+    if (char !== '\\') {
+      value += char
+      continue
+    }
+    if (i >= source.length) throw new Error('Go token parser: incomplete escape')
+    const escape = source[i++]
+    const simple = {
+      a: '\x07', b: '\b', f: '\f', n: '\n', r: '\r', t: '\t', v: '\v',
+      '\\': '\\', '"': '"', "'": "'"
+    }
+    if (Object.hasOwn(simple, escape)) {
+      value += simple[escape]
+      continue
+    }
+    if (escape === 'x' || escape === 'u' || escape === 'U') {
+      const digits = escape === 'x' ? 2 : escape === 'u' ? 4 : 8
+      const chunk = source.slice(i, i + digits)
+      if (chunk.length !== digits || !new RegExp(`^[0-9a-fA-F]{${digits}}$`).test(chunk)) {
+        throw new Error('Go token parser: invalid hexadecimal escape')
+      }
+      const codePoint = Number.parseInt(chunk, 16)
+      if (codePoint > 0x10ffff || (codePoint >= 0xd800 && codePoint <= 0xdfff)) {
+        throw new Error('Go token parser: invalid Unicode code point')
+      }
+      value += String.fromCodePoint(codePoint)
+      i += digits
+      continue
+    }
+    if (/[0-7]/.test(escape)) {
+      const rest = source.slice(i, i + 2)
+      if (rest.length !== 2 || !/^[0-7]{2}$/.test(rest)) throw new Error('Go token parser: invalid octal escape')
+      value += String.fromCodePoint(Number.parseInt(escape + rest, 8))
+      i += 2
+      continue
+    }
+    throw new Error(`Go token parser: unsupported escape \\${escape}`)
+  }
+  throw new Error('Go token parser: unterminated string literal')
+}
+
+function findAssignmentBrace(source, name) {
+  const match = new RegExp(`\\b${name}\\s*=`).exec(source)
+  if (!match) throw new Error(`Go token parser: assignment ${name} not found`)
+  const brace = source.indexOf('{', match.index + match[0].length)
+  if (brace < 0) throw new Error(`Go token parser: array ${name} has no opening brace`)
+  return brace
+}
+
+function parseSingleArray(source) {
+  let i = findAssignmentBrace(source, 'SingleByteTokens') + 1
+  let depth = 1
+  const values = []
+  while (i < source.length && depth > 0) {
+    const ch = source[i]
+    if (ch === '"') {
+      const parsed = readGoString(source, i)
+      values.push(parsed.value)
+      i = parsed.next
+      continue
+    }
+    if (ch === '{') depth++
+    if (ch === '}') depth--
+    i++
+  }
+  if (depth !== 0) throw new Error('Go token parser: unterminated SingleByteTokens array')
+  return values
+}
+
+function parseDoubleArray(source) {
+  let i = findAssignmentBrace(source, 'DoubleByteTokens') + 1
+  let depth = 1
+  let page = null
+  const pages = []
+  while (i < source.length && depth > 0) {
+    const ch = source[i]
+    if (ch === '"') {
+      const parsed = readGoString(source, i)
+      if (depth === 2) {
+        if (!page) throw new Error('Go token parser: token outside dictionary page')
+        page.push(parsed.value)
+      }
+      i = parsed.next
+      continue
+    }
+    if (ch === '{') {
+      depth++
+      if (depth === 2) page = []
+      i++
+      continue
+    }
+    if (ch === '}') {
+      if (depth === 2) {
+        if (!page) throw new Error('Go token parser: missing dictionary page')
+        pages.push(page)
+        page = null
+      }
+      depth--
+      i++
+      continue
+    }
+    i++
+  }
+  if (depth !== 0) throw new Error('Go token parser: unterminated DoubleByteTokens array')
+  return pages
+}
+
+function parseGoTokenTable(source) {
+  if (typeof source !== 'string' || source.length === 0) throw new TypeError('Go token source must be non-empty text')
+  const versionMatch = /\bconst\s+DictVersion\s*=\s*(\d+)\b/.exec(source)
+  if (!versionMatch) throw new Error('Go token parser: DictVersion not found')
+  return {
+    dictVersion: Number(versionMatch[1]),
+    single: parseSingleArray(source),
+    double: parseDoubleArray(source)
+  }
+}
+
+function validateTokenTable(table, expected = {}) {
+  if (!table || !Array.isArray(table.single) || !Array.isArray(table.double)) throw new TypeError('token data is missing single/double arrays')
+  if (expected.dictVersion !== undefined && table.dictVersion !== expected.dictVersion) {
+    throw new Error(`DictVersion mismatch: expected ${expected.dictVersion}, received ${table.dictVersion}`)
+  }
+  if (table.single.length !== 236 || table.single[0] !== '') {
+    throw new Error(`single-byte token table shape unexpected: expected 236 entries with empty index 0, received ${table.single.length}`)
+  }
+  if (table.double.length !== 4 || table.double.some((page) => !Array.isArray(page) || page.length !== 256)) {
+    throw new Error('double-byte token table shape unexpected: expected four pages of 256 entries')
+  }
+  if (table.single.some((entry) => typeof entry !== 'string') || table.double.some((page) => page.some((entry) => typeof entry !== 'string'))) {
+    throw new TypeError('token table entries must all be strings')
+  }
+  return true
+}
+
+module.exports = { parseGoTokenTable, validateTokenTable }