kxco-pq-tls 1.0.0

package/LICENSE

@@ -0,0 +1,34 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution.
+"Licensor" shall mean KXCO by Knightsbridge.
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity.
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+"Source" form shall mean the preferred form for making modifications.
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form.
+"Work" shall mean the work of authorship made available under the License.
+"Derivative Works" shall mean any work that is based on the Work.
+"Contribution" shall mean any work of authorship submitted to the Licensor for inclusion in the Work.
+"Contributor" shall mean Licensor and any Legal Entity on behalf of whom a Contribution has been received by the Licensor and incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work; and (d) If the Work includes a "NOTICE" text file, You must include a readable copy of the attribution notices contained within such NOTICE file.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor.
+
+7. Disclaimer of Warranty. THE WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
+
+8. Limitation of Liability. IN NO EVENT SHALL ANY CONTRIBUTOR BE LIABLE FOR ANY DAMAGES ARISING FROM THIS LICENSE OR THE USE OF THE WORK.
+
+Copyright 2026 KXCO by Knightsbridge

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "kxco-pq-tls",
+  "version": "1.0.0",
+  "description": "Hybrid post-quantum secure channels: ML-KEM-768 + X25519 key exchange, AES-256-GCM data encryption. Wraps Node.js streams and Cloudflare Workers WebSockets. Drop-in quantum-safe channel layer.",
+  "keywords": [
+    "post-quantum",
+    "pqc",
+    "ml-kem",
+    "kyber",
+    "x25519",
+    "tls",
+    "secure-channel",
+    "cloudflare-workers",
+    "nist",
+    "fips-203",
+    "kxco"
+  ],
+  "license": "Apache-2.0",
+  "author": "KXCO by Knightsbridge <hello@kxco.ai>",
+  "homepage": "https://kxco.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JackKXCO/kxco-pq-tls.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JackKXCO/kxco-pq-tls/issues"
+  },
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "dependencies": {
+    "@noble/ciphers": "^1.0.0",
+    "@noble/curves": "^1.8.0",
+    "@noble/hashes": "^1.7.0",
+    "kxco-post-quantum": "^1.1.6"
+  },
+  "devDependencies": {},
+  "scripts": {
+    "test": "node --test --test-timeout=15000 test/primitives.test.js test/handshake.test.js test/stream.test.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/errors.js

@@ -0,0 +1,3 @@
+export class KxcoPqTlsError extends Error {
+  constructor(message) { super(message); this.name = 'KxcoPqTlsError' }
+}

package/src/handshake.js

@@ -0,0 +1,174 @@
+/**
+ * kxco-pq-tls handshake protocol v1
+ *
+ * ClientHello (1218 bytes):
+ *   [1]    version = 0x01
+ *   [1]    flags   (bit 0 = mutual_auth_requested)
+ *   [1184] ML-KEM-768 ephemeral encap key
+ *   [32]   X25519 ephemeral public key
+ *
+ * ServerHello (1122 bytes):
+ *   [1]    version = 0x01
+ *   [1]    flags
+ *   [1088] ML-KEM-768 ciphertext
+ *   [32]   X25519 ephemeral public key
+ *
+ * Session keys: HKDF(ss_kem || ss_dh, salt=c_x25519_pk||s_x25519_pk, info="kxco-pq-tls-v1")
+ * then split into keyC2S and keyS2C.
+ *
+ * If mutual auth requested, after key establishment both sides exchange a
+ * Finished frame (sent encrypted over the new session) containing their
+ * ML-DSA-65 identity public key and a signature over SHA-256(clientHello||serverHello).
+ *
+ * Finished plaintext (5262 bytes):
+ *   [1]    msg_type = 0x01
+ *   [1952] ML-DSA-65 public key
+ *   [3309] ML-DSA-65 signature over SHA-256(clientHello || serverHello)
+ */
+
+import {
+  generateKemKeypair, generateX25519Keypair,
+  kemEncapsulate, kemDecapsulate, x25519DH,
+  deriveKeys, sealFrame, openFrame,
+  dsaSign, dsaVerify, sha256,
+} from './primitives.js'
+import { KxcoPqTlsError } from './errors.js'
+
+const VERSION      = 0x01
+const FLAG_AUTH    = 0x01
+const MSG_FINISHED = 0x01
+
+const CLIENT_HELLO_SIZE = 1218   // 1 + 1 + 1184 + 32
+const SERVER_HELLO_SIZE = 1122   // 1 + 1 + 1088 + 32
+const FINISHED_SIZE     = 5262   // 1 + 1952 + 3309
+
+/**
+ * Perform handshake as initiator.
+ * send(buf)  → Promise<void>   — write one framed message
+ * recv(n)    → Promise<Buffer> — read exactly n bytes (stream) or one message (WS)
+ * options.identity → optional { publicKey, secretKey } (ML-DSA-65) for mutual auth
+ * Returns { txKey, rxKey } — tx is initiator→responder (C2S), rx is S2C
+ */
+export async function initiatorHandshake(send, recv, options = {}) {
+  const kem  = generateKemKeypair()
+  const dh   = generateX25519Keypair()
+  const flags = options.identity ? FLAG_AUTH : 0x00
+
+  const clientHello = buildClientHello(flags, kem.publicKey, dh.publicKey)
+  await send(clientHello)
+
+  const serverHello = await recv(SERVER_HELLO_SIZE)
+  validateHello(serverHello, SERVER_HELLO_SIZE, 'ServerHello')
+
+  const kemCt       = serverHello.slice(2, 2 + 1088)
+  const serverX25519 = serverHello.slice(2 + 1088)
+
+  const ssKem = kemDecapsulate(kemCt, kem.secretKey)
+  const ssDh  = x25519DH(dh.secretKey, serverX25519)
+  const salt  = concat(dh.publicKey, serverX25519)
+  const { keyC2S, keyS2C } = deriveKeys(ssKem, ssDh, salt)
+
+  if (options.identity) {
+    const transcript = sha256.create()
+      .update(clientHello).update(serverHello).digest()
+    await exchangeFinished(send, recv, keyC2S, keyS2C, options.identity, transcript, 'initiator')
+  }
+
+  return { txKey: keyC2S, rxKey: keyS2C }
+}
+
+/**
+ * Perform handshake as responder.
+ * Returns { txKey, rxKey } — tx is responder→initiator (S2C), rx is C2S
+ */
+export async function responderHandshake(send, recv, options = {}) {
+  const clientHello = await recv(CLIENT_HELLO_SIZE)
+  validateHello(clientHello, CLIENT_HELLO_SIZE, 'ClientHello')
+
+  const flags        = clientHello[1]
+  const clientKemEk  = clientHello.slice(2, 2 + 1184)
+  const clientX25519 = clientHello.slice(2 + 1184)
+
+  const { ciphertext, sharedSecret: ssKem } = kemEncapsulate(clientKemEk)
+  const dh  = generateX25519Keypair()
+  const ssDh = x25519DH(dh.secretKey, clientX25519)
+  const salt = concat(clientX25519, dh.publicKey)
+  const { keyC2S, keyS2C } = deriveKeys(ssKem, ssDh, salt)
+
+  const serverHello = buildServerHello(flags, ciphertext, dh.publicKey)
+  await send(serverHello)
+
+  if ((flags & FLAG_AUTH) && options.identity) {
+    const transcript = sha256.create()
+      .update(clientHello).update(serverHello).digest()
+    await exchangeFinished(send, recv, keyS2C, keyC2S, options.identity, transcript, 'responder')
+  }
+
+  return { txKey: keyS2C, rxKey: keyC2S }
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function buildClientHello(flags, kemEk, x25519Pk) {
+  const buf = new Uint8Array(CLIENT_HELLO_SIZE)
+  buf[0] = VERSION
+  buf[1] = flags
+  buf.set(kemEk,    2)
+  buf.set(x25519Pk, 2 + 1184)
+  return Buffer.from(buf)
+}
+
+function buildServerHello(flags, kemCt, x25519Pk) {
+  const buf = new Uint8Array(SERVER_HELLO_SIZE)
+  buf[0] = VERSION
+  buf[1] = flags
+  buf.set(kemCt,    2)
+  buf.set(x25519Pk, 2 + 1088)
+  return Buffer.from(buf)
+}
+
+function validateHello(buf, expectedLen, name) {
+  if (buf.length !== expectedLen)
+    throw new KxcoPqTlsError(`${name}: expected ${expectedLen} bytes, got ${buf.length}`)
+  if (buf[0] !== VERSION)
+    throw new KxcoPqTlsError(`${name}: unsupported version 0x${buf[0].toString(16)}`)
+}
+
+async function exchangeFinished(send, recv, txKey, rxKey, identity, transcript, role) {
+  // Send our Finished first, then receive theirs.
+  // The encrypted sequence starts at 0 for each direction.
+  const sig      = dsaSign(identity.secretKey, transcript)
+  const finished = buildFinished(identity.publicKey, sig)
+  await send(sealFrame(txKey, 0, finished))
+
+  const rxBuf     = await recv(FINISHED_SIZE + 16)  // +16 GCM tag
+  const plaintext = openFrame(rxKey, 0, Buffer.from(rxBuf))
+  verifyFinished(plaintext, transcript, role)
+}
+
+function buildFinished(identityPk, sig) {
+  const buf = new Uint8Array(FINISHED_SIZE)
+  buf[0] = MSG_FINISHED
+  buf.set(identityPk, 1)
+  buf.set(sig, 1 + 1952)
+  return buf
+}
+
+function verifyFinished(plaintext, transcript, role) {
+  if (plaintext[0] !== MSG_FINISHED)
+    throw new KxcoPqTlsError('unexpected finished message type')
+  const identityPk = plaintext.slice(1, 1 + 1952)
+  const sig        = plaintext.slice(1 + 1952)
+  if (!dsaVerify(identityPk, transcript, sig))
+    throw new KxcoPqTlsError(`${role}: peer identity verification failed`)
+}
+
+function concat(...arrays) {
+  const total = arrays.reduce((n, a) => n + a.length, 0)
+  const out = new Uint8Array(total)
+  let off = 0
+  for (const a of arrays) { out.set(a, off); off += a.length }
+  return out
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export { wrapStream }                       from './stream.js'
+export { wrapWebSocket, PqTlsWebSocket }   from './websocket.js'
+export { initiatorHandshake, responderHandshake } from './handshake.js'
+export { KxcoPqTlsError }                  from './errors.js'

package/src/primitives.js

@@ -0,0 +1,82 @@
+import { mlKem, mlDsa } from 'kxco-post-quantum'
+import { x25519 } from '@noble/curves/ed25519'
+import { hkdf } from '@noble/hashes/hkdf'
+import { sha256 } from '@noble/hashes/sha256'
+import { gcm } from '@noble/ciphers/aes'
+import { randomBytes } from '@noble/ciphers/webcrypto'
+import { KxcoPqTlsError } from './errors.js'
+
+const PROTOCOL = new TextEncoder().encode('kxco-pq-tls-v1')
+const INFO_C2S  = new TextEncoder().encode('kxco-pq-tls-v1-c2s')
+const INFO_S2C  = new TextEncoder().encode('kxco-pq-tls-v1-s2c')
+
+export function generateKemKeypair() {
+  return mlKem.ml_kem768.keygen()
+}
+
+export function generateX25519Keypair() {
+  const secretKey = x25519.utils.randomPrivateKey()
+  const publicKey = x25519.getPublicKey(secretKey)
+  return { publicKey, secretKey }
+}
+
+export function kemEncapsulate(publicKey) {
+  const { cipherText, sharedSecret } = mlKem.ml_kem768.encapsulate(publicKey)
+  return { ciphertext: new Uint8Array(cipherText), sharedSecret: new Uint8Array(sharedSecret) }
+}
+
+export function kemDecapsulate(ciphertext, secretKey) {
+  return mlKem.ml_kem768.decapsulate(new Uint8Array(ciphertext), new Uint8Array(secretKey))
+}
+
+export function x25519DH(sk, pk) {
+  return x25519.getSharedSecret(sk, pk)  // Uint8Array(32)
+}
+
+// Derive per-direction session keys from the two shared secrets.
+// salt = initiator_x25519_pk || responder_x25519_pk (64 bytes, transcript-bound)
+export function deriveKeys(ssKem, ssDh, salt) {
+  const ikm = new Uint8Array(64)
+  ikm.set(ssKem)
+  ikm.set(ssDh, 32)
+  const base = hkdf(sha256, ikm, salt, PROTOCOL, 32)
+  return {
+    keyC2S: hkdf(sha256, base, new Uint8Array(0), INFO_C2S, 32),
+    keyS2C: hkdf(sha256, base, new Uint8Array(0), INFO_S2C, 32),
+  }
+}
+
+// Returns ciphertext with 16-byte GCM tag appended.
+export function sealFrame(key, seq, plaintext) {
+  const nonce = seqNonce(seq)
+  return gcm(key, nonce).encrypt(plaintext)
+}
+
+// Throws KxcoPqTlsError on authentication failure.
+export function openFrame(key, seq, ciphertext) {
+  try {
+    return gcm(key, seqNonce(seq)).decrypt(ciphertext)
+  } catch {
+    throw new KxcoPqTlsError('frame authentication failed')
+  }
+}
+
+function seqNonce(seq) {
+  const nonce = new Uint8Array(12)
+  const v = new DataView(nonce.buffer)
+  // 64-bit big-endian sequence number in bytes 0–7; bytes 8–11 remain zero
+  v.setUint32(0, Math.floor(seq / 0x100000000) >>> 0, false)
+  v.setUint32(4, seq >>> 0, false)
+  return nonce
+}
+
+// ML-DSA-65 identity helpers for mutual auth
+export function dsaSign(secretKey, message) {
+  return mlDsa.ml_dsa65.sign(new Uint8Array(secretKey), message)
+}
+
+export function dsaVerify(publicKey, message, signature) {
+  return mlDsa.ml_dsa65.verify(new Uint8Array(publicKey), message, new Uint8Array(signature))
+}
+
+export { randomBytes, sha256 }

package/src/stream.js

@@ -0,0 +1,116 @@
+import { Duplex } from 'node:stream'
+import { initiatorHandshake, responderHandshake } from './handshake.js'
+import { sealFrame, openFrame } from './primitives.js'
+import { KxcoPqTlsError } from './errors.js'
+
+/**
+ * Wrap a Node.js Duplex (net.Socket, etc.) with a PQ-TLS channel.
+ * Returns a Promise<Duplex> that resolves once the handshake completes.
+ *
+ * options.role     — 'initiator' | 'responder'  (required)
+ * options.identity — { publicKey, secretKey }    (ML-DSA-65, optional — mutual auth)
+ */
+export async function wrapStream(socket, options = {}) {
+  if (!options.role) throw new KxcoPqTlsError('wrapStream: options.role is required')
+
+  // Handshake messages have fixed known sizes so no framing needed.
+  const send = (data) => new Promise((res, rej) =>
+    socket.write(Buffer.from(data), (err) => err ? rej(err) : res())
+  )
+  const recv = (n) => readExactly(socket, n)
+
+  const { txKey, rxKey } =
+    options.role === 'initiator'
+      ? await initiatorHandshake(send, recv, options)
+      : await responderHandshake(send, recv, options)
+
+  return new PqTlsStream(socket, txKey, rxKey)
+}
+
+// ---------------------------------------------------------------------------
+// Encrypted Duplex stream
+// ---------------------------------------------------------------------------
+
+class PqTlsStream extends Duplex {
+  constructor(socket, txKey, rxKey) {
+    super()
+    this._socket = socket
+    this._txKey  = txKey
+    this._rxKey  = rxKey
+    this._txSeq  = 0
+    this._rxSeq  = 0
+    this._buf    = Buffer.alloc(0)
+
+    socket.on('data',  (chunk) => this._onData(chunk))
+    socket.once('end', ()      => this.push(null))
+    socket.once('error', (err) => this.destroy(err))
+    this.once('finish', ()     => socket.end())
+  }
+
+  _write(chunk, _enc, cb) {
+    const ct = sealFrame(this._txKey, this._txSeq++, Buffer.from(chunk))
+    const hdr = Buffer.allocUnsafe(4)
+    hdr.writeUInt32BE(ct.length, 0)
+    this._socket.write(Buffer.concat([hdr, ct]), cb)
+  }
+
+  _read() {}  // push-based; driven by socket 'data' events
+
+  _onData(chunk) {
+    this._buf = Buffer.concat([this._buf, chunk])
+    while (this._buf.length >= 4) {
+      const frameLen = this._buf.readUInt32BE(0)
+      if (this._buf.length < 4 + frameLen) break
+      const ct = this._buf.slice(4, 4 + frameLen)
+      this._buf = this._buf.slice(4 + frameLen)
+      let plain
+      try {
+        plain = openFrame(this._rxKey, this._rxSeq++, ct)
+      } catch (err) {
+        this.destroy(err)
+        return
+      }
+      if (!this.push(Buffer.from(plain))) this._socket.pause()
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Stream I/O helpers for handshake
+// ---------------------------------------------------------------------------
+
+async function readExactly(socket, n) {
+  return new Promise((resolve, reject) => {
+    const buf = Buffer.allocUnsafe(n)
+    let offset = 0
+
+    const cleanup = () => {
+      socket.off('data',  onData)
+      socket.off('error', onError)
+      socket.off('end',   onEnd)
+    }
+
+    const onData = (chunk) => {
+      const needed = n - offset
+      if (chunk.length <= needed) {
+        chunk.copy(buf, offset)
+        offset += chunk.length
+      } else {
+        chunk.copy(buf, offset, 0, needed)
+        socket.unshift(chunk.slice(needed))
+        offset = n
+      }
+      if (offset === n) {
+        cleanup()
+        resolve(buf)
+      }
+    }
+
+    const onError = (err) => { cleanup(); reject(err) }
+    const onEnd   = ()    => { cleanup(); reject(new KxcoPqTlsError('stream ended during handshake')) }
+
+    socket.on('data',  onData)
+    socket.once('error', onError)
+    socket.once('end',   onEnd)
+  })
+}

package/src/websocket.js

@@ -0,0 +1,134 @@
+import { EventEmitter } from 'node:events'
+import { initiatorHandshake, responderHandshake } from './handshake.js'
+import { sealFrame, openFrame } from './primitives.js'
+import { KxcoPqTlsError } from './errors.js'
+
+/**
+ * Wrap a WebSocket with a PQ-TLS channel.
+ * Compatible with the `ws` npm package (Node.js) and the native WebSocket API
+ * (Cloudflare Workers, browsers, Node.js 22+).
+ *
+ * Returns a Promise<PqTlsWebSocket> that resolves once the handshake completes.
+ *
+ * options.role     — 'initiator' | 'responder'  (required)
+ * options.identity — { publicKey, secretKey }    (ML-DSA-65, optional — mutual auth)
+ */
+export async function wrapWebSocket(ws, options = {}) {
+  if (!options.role) throw new KxcoPqTlsError('wrapWebSocket: options.role is required')
+
+  const send = (data) => wsSend(ws, data)
+  const recv = ()     => wsRecv(ws)
+
+  const { txKey, rxKey } =
+    options.role === 'initiator'
+      ? await initiatorHandshake(send, recv, options)
+      : await responderHandshake(send, recv, options)
+
+  return new PqTlsWebSocket(ws, txKey, rxKey)
+}
+
+// ---------------------------------------------------------------------------
+// Encrypted WebSocket wrapper
+// ---------------------------------------------------------------------------
+
+export class PqTlsWebSocket extends EventEmitter {
+  constructor(ws, txKey, rxKey) {
+    super()
+    this._ws    = ws
+    this._txKey = txKey
+    this._rxKey = rxKey
+    this._txSeq = 0
+    this._rxSeq = 0
+
+    const onMsg = (data) => {
+      try {
+        const plain = openFrame(this._rxKey, this._rxSeq++, toBuffer(data))
+        this.emit('message', Buffer.from(plain))
+      } catch (err) {
+        this.emit('error', err)
+      }
+    }
+
+    const onClose  = (code, reason) => this.emit('close', code, reason)
+    const onError  = (err)          => this.emit('error', err)
+
+    // Support both ws (Node.js) and native WebSocket (Workers/browser) event APIs
+    if (typeof ws.on === 'function') {
+      ws.on('message', onMsg)
+      ws.on('close',   onClose)
+      ws.on('error',   onError)
+    } else {
+      ws.addEventListener('message', (e) => onMsg(e.data))
+      ws.addEventListener('close',   (e) => this.emit('close', e.code, e.reason))
+      ws.addEventListener('error',   (e) => this.emit('error', e))
+    }
+  }
+
+  send(data) {
+    const ct = sealFrame(this._txKey, this._txSeq++, toBuffer(data))
+    wsSend(this._ws, ct)
+  }
+
+  close(code, reason) { this._ws.close(code, reason) }
+}
+
+// ---------------------------------------------------------------------------
+// WebSocket helpers
+// ---------------------------------------------------------------------------
+
+function wsSend(ws, data) {
+  return new Promise((resolve, reject) => {
+    const buf = Buffer.isBuffer(data) ? data : Buffer.from(data)
+    if (typeof ws.send === 'function') {
+      // ws package: send(data, callback)
+      try {
+        const result = ws.send(buf, (err) => err ? reject(err) : resolve())
+        // Native WebSocket (Workers/browser) returns undefined and has no callback
+        if (result === undefined && typeof ws.readyState !== 'undefined') resolve()
+      } catch (err) {
+        reject(err)
+      }
+    } else {
+      reject(new KxcoPqTlsError('ws.send is not a function'))
+    }
+  })
+}
+
+function wsRecv(ws) {
+  return new Promise((resolve, reject) => {
+    const onMsg   = (data)  => { cleanup(); resolve(toBuffer(data)) }
+    const onClose = ()      => { cleanup(); reject(new KxcoPqTlsError('WebSocket closed during handshake')) }
+    const onError = (err)   => { cleanup(); reject(err) }
+
+    const cleanup = () => {
+      if (typeof ws.off === 'function') {
+        ws.off('message', onMsg)
+        ws.off('close',   onClose)
+        ws.off('error',   onError)
+      } else {
+        ws.removeEventListener('message', onMsgNative)
+        ws.removeEventListener('close',   onClose)
+        ws.removeEventListener('error',   onError)
+      }
+    }
+
+    const onMsgNative = (e) => onMsg(e.data)
+
+    if (typeof ws.once === 'function') {
+      ws.once('message', onMsg)
+      ws.once('close',   onClose)
+      ws.once('error',   onError)
+    } else {
+      ws.addEventListener('message', onMsgNative, { once: true })
+      ws.addEventListener('close',   onClose,     { once: true })
+      ws.addEventListener('error',   onError,     { once: true })
+    }
+  })
+}
+
+function toBuffer(data) {
+  if (Buffer.isBuffer(data)) return data
+  if (data instanceof Uint8Array) return Buffer.from(data.buffer, data.byteOffset, data.byteLength)
+  if (data instanceof ArrayBuffer) return Buffer.from(data)
+  return Buffer.from(String(data))
+}