wscall-client 0.3.0

package/src/index.js

@@ -0,0 +1,50 @@
+/**
+ * wscall-client - High-performance JavaScript client SDK for the WSCALL framework.
+ *
+ * @example
+ * ```js
+ * import { WscallClient, WscallClientConfig, createTextAttachment, attachmentRef } from 'wscall-client';
+ *
+ * const client = await WscallClient.connect('ws://127.0.0.1:9001/socket', WscallClientConfig.ecdh());
+ *
+ * // Make an API call
+ * const result = await client.call('system.echo', { message: 'hello' });
+ *
+ * // Listen for server events
+ * client.onEvent('chat.message', (event) => {
+ *   console.log('New message:', event.data);
+ *   return { received: true };
+ * });
+ *
+ * // Send an event
+ * const ack = await client.sendEvent('chat.message', { message: 'hi!' });
+ *
+ * client.close();
+ * ```
+ */
+
+export { WscallClient, WscallClientConfig, ClientError } from './client.js';
+export {
+  FrameCodec,
+  ProtocolError,
+  MessageType,
+  EncryptionKind,
+  DEFAULT_MAX_FRAME_BYTES,
+  K_API_REQUEST,
+  K_EVENT_EMIT,
+  K_API_RESPONSE,
+  K_EVENT_ACK,
+  ECDH_DOMAIN_TAG,
+  ECDH_KEY_LEN,
+  buildApiRequest,
+  buildEventEmit,
+  buildEventAck,
+  createAttachment,
+  createTextAttachment,
+  createBytesAttachment,
+  attachmentRef,
+  initCiphers,
+  generateEcdhKeypair,
+  parsePeerPublic,
+  deriveEcdhSessionKey,
+} from './protocol.js';

package/src/protocol.js

@@ -0,0 +1,548 @@
+/**
+ * WSCALL binary protocol codec (protocol v3).
+ *
+ * Frame layout (big-endian):
+ * ┌──────────────────────────────────────────────────────────────────────┐
+ * │ 4 bytes frame_len (u32 BE) │ 1 byte msg_type │        payload        │
+ * └──────────────────────────────────────────────────────────────────────┘
+ * frame_len = 1 + payload.length
+ *
+ * The encryption mode is a connection-level property configured on the codec
+ * (via withChaCha20Key / withAes256Key); it is NOT carried per-frame.
+ *
+ * Protocol v3 composite payload (after decryption):
+ * ┌──────────────────────────────────────────────────────────────────────┐
+ * │ 4 bytes meta_len (u32 BE) │ JSON_bytes │ 1 byte att_count │ [att sections] │
+ * └──────────────────────────────────────────────────────────────────────┘
+ *
+ * Each attachment binary section:
+ * │ id_len:u8 │ id │ name_len:u8 │ name │ ct_len:u8 │ content_type │ data_len:u32(be) │ raw_data │
+ *
+ * JSON body uses compact single-letter keys with a numeric `k` discriminator:
+ *   k=0 ApiRequest:  { k, i, r, p, m }
+ *   k=1 EventEmit:   { k, i, n, d, m, e }
+ *   k=2 ApiResponse: { k, i, o, s, d, er?, m }
+ *   k=3 EventAck:    { k, i, o, rc, er? }
+ */
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+export const MessageType = Object.freeze({ Api: 0x00, Event: 0x01 });
+export const EncryptionKind = Object.freeze({ None: 0x00, ChaCha20: 0x01, Aes256: 0x02 });
+
+export const K_API_REQUEST = 0;
+export const K_EVENT_EMIT = 1;
+export const K_API_RESPONSE = 2;
+export const K_EVENT_ACK = 3;
+
+// ─── ECDH Constants ──────────────────────────────────────────────────────────
+
+/** Domain-separation tag for the ECDH session key KDF (must match the Rust side). */
+export const ECDH_DOMAIN_TAG = 'wscall-ecdh-v1';
+/** Byte length of an X25519 public key. */
+export const ECDH_KEY_LEN = 32;
+
+const NONCE_LEN = 12;
+
+/** Default maximum frame size: 100 MiB (configurable). */
+export const DEFAULT_MAX_FRAME_BYTES = 100 * 1024 * 1024;
+
+// Shared, stateless UTF-8 codecs. TextEncoder/TextDecoder are reusable, so
+// hoisting them to module scope avoids re-instantiating them on every frame
+// and attachment (which previously added GC pressure on hot paths).
+const TEXT_ENCODER = new TextEncoder();
+const TEXT_DECODER = new TextDecoder();
+
+// ─── Errors ───────────────────────────────────────────────────────────────────
+
+export class ProtocolError extends Error {
+  constructor(message, code = 'PROTOCOL_ERROR') {
+    super(message);
+    this.name = 'ProtocolError';
+    this.code = code;
+  }
+}
+
+// ─── Frame Codec ──────────────────────────────────────────────────────────────
+
+/**
+ * High-performance binary frame codec for the WSCALL protocol.
+ * Supports plaintext, ChaCha20-Poly1305, and AES-256-GCM encryption.
+ */
+export class FrameCodec {
+  #chacha20Key = null; // Uint8Array(32)
+  #aes256Key = null;   // CryptoKey (imported lazily)
+  #aes256RawKey = null; // Uint8Array(32) raw bytes for lazy import
+  #wireEncryption = EncryptionKind.None; // connection-level encryption mode
+  #maxFrameBytes = DEFAULT_MAX_FRAME_BYTES;
+
+  constructor() {}
+
+  /** Configure ChaCha20-Poly1305 key (32 bytes). Sets wire encryption to ChaCha20. */
+  withChaCha20Key(key) {
+    if (!(key instanceof Uint8Array) || key.length !== 32) {
+      throw new ProtocolError('ChaCha20 key must be a 32-byte Uint8Array');
+    }
+    this.#chacha20Key = key;
+    this.#wireEncryption = EncryptionKind.ChaCha20;
+    return this;
+  }
+
+  /** Configure AES-256-GCM key (32 bytes). Sets wire encryption to Aes256. */
+  withAes256Key(key) {
+    if (!(key instanceof Uint8Array) || key.length !== 32) {
+      throw new ProtocolError('AES-256 key must be a 32-byte Uint8Array');
+    }
+    this.#aes256RawKey = key;
+    this.#aes256Key = null; // will be imported lazily
+    this.#wireEncryption = EncryptionKind.Aes256;
+    return this;
+  }
+
+  /** Returns the connection-level encryption mode. */
+  get wireEncryption() { return this.#wireEncryption; }
+
+  /** Set maximum frame size. */
+  withMaxFrameBytes(max) {
+    this.#maxFrameBytes = max;
+    return this;
+  }
+
+  /** Lazily import AES key into Web Crypto. */
+  async #getAesKey() {
+    if (!this.#aes256Key && this.#aes256RawKey) {
+      this.#aes256Key = await crypto.subtle.importKey(
+        'raw', this.#aes256RawKey, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']
+      );
+    }
+    return this.#aes256Key;
+  }
+
+  /**
+   * Encode a packet body object into a binary WSCALL frame (protocol v3).
+   * Attachments in body.a are extracted and encoded as raw binary sections.
+   * Encryption mode is taken from the codec's wireEncryption (connection-level).
+   * @param {object} body - Packet body (will be serialized with short keys)
+   * @returns {Promise<Uint8Array>} Encoded binary frame
+   */
+  async encode(body) {
+    const messageType = messageTypeForBody(body);
+    const encryption = this.#wireEncryption;
+    const maxPayload = this.#maxFrameBytes - 5;
+
+    // Extract attachments and remove from JSON serialization.
+    const attachments = body.a || [];
+    const jsonBody = { ...body };
+    delete jsonBody.a;
+
+    const jsonBytes = TEXT_ENCODER.encode(JSON.stringify(jsonBody));
+    const attSections = attachments.map(att => encodeAttachmentWire(att));
+    const attTotalSize = attSections.reduce((sum, s) => sum + s.length, 0);
+
+    // Plaintext fast path: write directly into the final frame buffer.
+    if (encryption === EncryptionKind.None) {
+      const frameLen = 1 + 4 + jsonBytes.length + 1 + attTotalSize;
+      if (frameLen - 1 > maxPayload) {
+        throw new ProtocolError(`Payload too large: ${frameLen - 1} > ${maxPayload}`);
+      }
+      const frame = new Uint8Array(4 + frameLen);
+      const view = new DataView(frame.buffer);
+      view.setUint32(0, frameLen, false);
+      frame[4] = messageType;
+      view.setUint32(5, jsonBytes.length, false);
+      frame.set(jsonBytes, 9);
+      frame[9 + jsonBytes.length] = attachments.length;
+      let offset = 10 + jsonBytes.length;
+      for (const section of attSections) {
+        frame.set(section, offset);
+        offset += section.length;
+      }
+      return frame;
+    }
+
+    // Encrypted path: build the composite, encrypt it, then wrap the frame.
+    const composite = new Uint8Array(4 + jsonBytes.length + 1 + attTotalSize);
+    const cView = new DataView(composite.buffer);
+    cView.setUint32(0, jsonBytes.length, false);
+    composite.set(jsonBytes, 4);
+    composite[4 + jsonBytes.length] = attachments.length;
+    let offset = 4 + jsonBytes.length + 1;
+    for (const section of attSections) {
+      composite.set(section, offset);
+      offset += section.length;
+    }
+
+    if (composite.length > maxPayload) {
+      throw new ProtocolError(`Payload too large: ${composite.length} > ${maxPayload}`);
+    }
+
+    let payload;
+    switch (encryption) {
+      case EncryptionKind.ChaCha20:
+        payload = this.#encryptChaCha20(composite);
+        break;
+      case EncryptionKind.Aes256:
+        payload = await this.#encryptAes256(composite);
+        break;
+      default:
+        throw new ProtocolError(`Unknown encryption kind: ${encryption}`);
+    }
+
+    if (payload.length > maxPayload) {
+      throw new ProtocolError(`Encrypted payload too large: ${payload.length} > ${maxPayload}`);
+    }
+
+    const frameLen = 1 + payload.length;
+    const frame = new Uint8Array(4 + frameLen);
+    const view = new DataView(frame.buffer);
+    view.setUint32(0, frameLen, false); // big-endian
+    frame[4] = messageType;
+    frame.set(payload, 5);
+    return frame;
+  }
+
+  /**
+   * Decode a binary WSCALL frame into a packet body object (protocol v3).
+   * Attachments are parsed from binary sections and injected as body.a.
+   * Encryption mode is taken from the codec's wireEncryption (connection-level).
+   * @param {Uint8Array|ArrayBuffer} data - Raw frame bytes
+   * @returns {Promise<{messageType: number, body: object}>}
+   */
+  async decode(data) {
+    const frame = data instanceof Uint8Array ? data : new Uint8Array(data);
+    if (frame.length < 5) {
+      throw new ProtocolError('Frame too short');
+    }
+
+    const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+    const declared = view.getUint32(0, false);
+    const actual = frame.length - 4;
+    if (declared !== actual) {
+      throw new ProtocolError(`Frame length mismatch: declared=${declared}, actual=${actual}`);
+    }
+
+    if (frame.length > this.#maxFrameBytes) {
+      throw new ProtocolError(`Frame too large: ${frame.length} > ${this.#maxFrameBytes}`);
+    }
+
+    const messageType = frame[4];
+    const encryptedPayload = frame.subarray(5);
+
+    let composite;
+    switch (this.#wireEncryption) {
+      case EncryptionKind.None:
+        composite = encryptedPayload;
+        break;
+      case EncryptionKind.ChaCha20:
+        composite = this.#decryptChaCha20(encryptedPayload);
+        break;
+      case EncryptionKind.Aes256:
+        composite = await this.#decryptAes256(encryptedPayload);
+        break;
+      default:
+        throw new ProtocolError(`Unknown encryption kind: ${this.#wireEncryption}`);
+    }
+
+    // Parse composite: meta_len:u32 | JSON | att_count:u8 | [att sections]
+    if (composite.length < 5) {
+      throw new ProtocolError('Composite payload too short');
+    }
+    const cView = new DataView(composite.buffer, composite.byteOffset, composite.byteLength);
+    const metaLen = cView.getUint32(0, false);
+    if (composite.length < 4 + metaLen + 1) {
+      throw new ProtocolError('Composite payload truncated');
+    }
+    const jsonBytes = composite.subarray(4, 4 + metaLen);
+    const attCount = composite[4 + metaLen];
+    let attOffset = 4 + metaLen + 1;
+
+    const body = JSON.parse(TEXT_DECODER.decode(jsonBytes));
+
+    // Parse binary attachment sections.
+    const attachments = [];
+    for (let i = 0; i < attCount; i++) {
+      const [att, newOffset] = decodeAttachmentWire(composite, attOffset);
+      attachments.push(att);
+      attOffset = newOffset;
+    }
+    if (attachments.length > 0) {
+      body.a = attachments;
+    }
+
+    return { messageType, body };
+  }
+
+  // ─── ChaCha20-Poly1305 (uses @noble/ciphers) ──────────────────────────────
+
+  #encryptChaCha20(plaintext) {
+    // NOTE: chacha20poly1305(key, nonce) is constructed per frame by design —
+    // the AEAD requires a fresh nonce each call and @noble/ciphers exposes no
+    // safe cross-frame key-schedule cache, so there is nothing to hoist here.
+    if (!this.#chacha20Key) throw new ProtocolError('Missing ChaCha20 key');
+    const { chacha20poly1305 } = getCiphers();
+    const nonce = crypto.getRandomValues(new Uint8Array(NONCE_LEN));
+    const cipher = chacha20poly1305(this.#chacha20Key, nonce);
+    const ciphertext = cipher.encrypt(plaintext);
+    // nonce || ciphertext+tag
+    const result = new Uint8Array(NONCE_LEN + ciphertext.length);
+    result.set(nonce, 0);
+    result.set(ciphertext, NONCE_LEN);
+    return result;
+  }
+
+  #decryptChaCha20(payload) {
+    if (!this.#chacha20Key) throw new ProtocolError('Missing ChaCha20 key');
+    if (payload.length < NONCE_LEN) throw new ProtocolError('Encrypted payload too short for ChaCha20');
+    const { chacha20poly1305 } = getCiphers();
+    const nonce = payload.subarray(0, NONCE_LEN);
+    const ciphertext = payload.subarray(NONCE_LEN);
+    const cipher = chacha20poly1305(this.#chacha20Key, nonce);
+    return cipher.decrypt(ciphertext);
+  }
+
+  // ─── AES-256-GCM (uses Web Crypto API) ────────────────────────────────────
+
+  async #encryptAes256(plaintext) {
+    const key = await this.#getAesKey();
+    if (!key) throw new ProtocolError('Missing AES-256 key');
+    const nonce = crypto.getRandomValues(new Uint8Array(NONCE_LEN));
+    const ciphertext = new Uint8Array(
+      await crypto.subtle.encrypt({ name: 'AES-GCM', iv: nonce }, key, plaintext)
+    );
+    const result = new Uint8Array(NONCE_LEN + ciphertext.length);
+    result.set(nonce, 0);
+    result.set(ciphertext, NONCE_LEN);
+    return result;
+  }
+
+  async #decryptAes256(payload) {
+    const key = await this.#getAesKey();
+    if (!key) throw new ProtocolError('Missing AES-256 key');
+    if (payload.length < NONCE_LEN) throw new ProtocolError('Encrypted payload too short for AES-256');
+    const nonce = payload.subarray(0, NONCE_LEN);
+    const ciphertext = payload.subarray(NONCE_LEN);
+    const plaintext = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: nonce }, key, ciphertext);
+    return new Uint8Array(plaintext);
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function messageTypeForBody(body) {
+  const k = body.k;
+  if (k === K_API_REQUEST || k === K_API_RESPONSE) return MessageType.Api;
+  if (k === K_EVENT_EMIT || k === K_EVENT_ACK) return MessageType.Event;
+  throw new ProtocolError(`Unknown packet kind: ${k}`);
+}
+
+// ─── Attachment Wire Encoding ───────────────────────────────────────────────
+
+/**
+ * Encode a single attachment into its binary wire section.
+ * Layout: id_len:u8 | id | name_len:u8 | name | ct_len:u8 | content_type | data_len:u32(be) | raw_data
+ */
+function encodeAttachmentWire(att) {
+  const idBytes = TEXT_ENCODER.encode(att.id);
+  const nameBytes = TEXT_ENCODER.encode(att.name);
+  const ctBytes = TEXT_ENCODER.encode(att.content_type);
+  const data = att.data instanceof Uint8Array ? att.data : new Uint8Array(att.data);
+  const total = 1 + idBytes.length + 1 + nameBytes.length + 1 + ctBytes.length + 4 + data.length;
+  const buf = new Uint8Array(total);
+  const view = new DataView(buf.buffer);
+  let pos = 0;
+  buf[pos++] = idBytes.length;
+  buf.set(idBytes, pos); pos += idBytes.length;
+  buf[pos++] = nameBytes.length;
+  buf.set(nameBytes, pos); pos += nameBytes.length;
+  buf[pos++] = ctBytes.length;
+  buf.set(ctBytes, pos); pos += ctBytes.length;
+  view.setUint32(pos, data.length, false); pos += 4;
+  buf.set(data, pos);
+  return buf;
+}
+
+/**
+ * Decode a single attachment binary section from a composite buffer.
+ * @returns {[object, number]} [attachment, newOffset]
+ */
+function decodeAttachmentWire(buf, offset) {
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+  let pos = offset;
+
+  const idLen = buf[pos++];
+  const id = TEXT_DECODER.decode(buf.subarray(pos, pos + idLen)); pos += idLen;
+
+  const nameLen = buf[pos++];
+  const name = TEXT_DECODER.decode(buf.subarray(pos, pos + nameLen)); pos += nameLen;
+
+  const ctLen = buf[pos++];
+  const content_type = TEXT_DECODER.decode(buf.subarray(pos, pos + ctLen)); pos += ctLen;
+
+  const dataLen = view.getUint32(pos, false); pos += 4;
+  // Zero-copy view into the (plaintext) frame buffer. The view retains the
+  // underlying buffer until released; for encrypted frames `buf` is already a
+  // fresh decrypted allocation, so no extra large buffer is pinned.
+  const data = buf.subarray(pos, pos + dataLen); pos += dataLen;
+
+  return [{ id, name, content_type, data }, pos];
+}
+
+// Lazy-load @noble/ciphers to keep it optional
+let _ciphers = null;
+function getCiphers() {
+  if (!_ciphers) {
+    try {
+      // Dynamic import won't work synchronously; use createRequire pattern
+      // In practice this is loaded at module init via the top-level import
+      _ciphers = globalThis.__wscall_ciphers;
+    } catch { /* ignore */ }
+  }
+  if (!_ciphers) {
+    throw new ProtocolError(
+      'ChaCha20-Poly1305 requires @noble/ciphers. Install it: npm i @noble/ciphers'
+    );
+  }
+  return _ciphers;
+}
+
+/**
+ * Initialize the cipher backend. Called automatically by WscallClient.
+ * @param {{ chacha20poly1305: Function }} ciphers
+ */
+export function initCiphers(ciphers) {
+  globalThis.__wscall_ciphers = ciphers;
+}
+
+// ─── Packet Builders ──────────────────────────────────────────────────────────
+
+/** Build an ApiRequest packet body. */
+export function buildApiRequest(requestId, route, params = {}, attachments = [], metadata = {}) {
+  const body = { k: K_API_REQUEST, i: requestId, r: route, p: params };
+  if (metadata && Object.keys(metadata).length > 0) body.m = metadata;
+  if (attachments.length > 0) body.a = attachments;
+  return body;
+}
+
+/** Build an EventEmit packet body. */
+export function buildEventEmit(eventId, name, data = {}, attachments = [], metadata = {}, expectAck = true) {
+  const body = { k: K_EVENT_EMIT, i: eventId, n: name, d: data, e: expectAck };
+  if (metadata && Object.keys(metadata).length > 0) body.m = metadata;
+  if (attachments.length > 0) body.a = attachments;
+  return body;
+}
+
+/** Build an EventAck packet body. */
+export function buildEventAck(eventId, ok = true, receipt = {}, error = undefined) {
+  const body = { k: K_EVENT_ACK, i: eventId, o: ok, rc: receipt };
+  if (error) body.er = error;
+  return body;
+}
+
+/**
+ * Create a file attachment object (raw binary, protocol v3).
+ * @param {string} id - Attachment identifier
+ * @param {string} name - File name
+ * @param {string} contentType - MIME type
+ * @param {Uint8Array} data - Raw file bytes
+ */
+export function createAttachment(id, name, contentType, data) {
+  return { id, name, content_type: contentType, data: data instanceof Uint8Array ? data : new Uint8Array(data) };
+}
+
+/** Create a text attachment (encodes string to UTF-8 bytes). */
+export function createTextAttachment(id, name, contentType, text) {
+  return { id, name, content_type: contentType, data: new TextEncoder().encode(text) };
+}
+
+/** Create a binary attachment from Uint8Array (stored as-is, no Base64). */
+export function createBytesAttachment(id, name, contentType, bytes) {
+  return { id, name, content_type: contentType, data: bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes) };
+}
+
+/** Returns a JSON reference object pointing to an attachment by id. */
+export function attachmentRef(id) {
+  return { $file: id };
+}
+
+// ─── ECDH Key Agreement ──────────────────────────────────────────────────────
+
+/**
+ * Lazy-loads the X25519 module from @noble/curves.
+ * Keeps the import optional so projects that only use PSK don't pay the cost.
+ */
+let _x25519 = null;
+async function getX25519() {
+  if (!_x25519) {
+    let mod;
+    try {
+      // In @noble/curves v1.x, x25519 is re-exported from the main entry.
+      mod = await import('@noble/curves');
+    } catch {
+      try {
+        // Fallback: import from the ed25519 submodule directly.
+        mod = await import('@noble/curves/ed25519.js');
+      } catch {
+        throw new ProtocolError(
+          'ECDH requires @noble/curves. Install it: npm i @noble/curves'
+        );
+      }
+    }
+    if (!mod.x25519) {
+      throw new ProtocolError(
+        'ECDH requires @noble/curves. Install it: npm i @noble/curves'
+      );
+    }
+    _x25519 = mod.x25519;
+  }
+  return _x25519;
+}
+
+/**
+ * Generates a random X25519 keypair for the ECDH handshake.
+ * @returns {Promise<{ privateKey: Uint8Array, publicKey: Uint8Array }>}
+ */
+export async function generateEcdhKeypair() {
+  const x25519 = await getX25519();
+  const privateKey = x25519.utils.randomPrivateKey();
+  const publicKey = x25519.getPublicKey(privateKey);
+  return { privateKey, publicKey };
+}
+
+/**
+ * Validates that `bytes` is exactly 32 bytes (a valid X25519 public key).
+ * @param {Uint8Array} bytes
+ * @returns {Uint8Array} the same bytes if valid
+ * @throws {ProtocolError} if the length is wrong
+ */
+export function parsePeerPublic(bytes) {
+  const arr = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  if (arr.length !== ECDH_KEY_LEN) {
+    throw new ProtocolError(
+      `Invalid ECDH public key: expected ${ECDH_KEY_LEN} bytes, got ${arr.length}`
+    );
+  }
+  return arr;
+}
+
+/**
+ * Derives a 32-byte ChaCha20-Poly1305 session key from an X25519 shared secret.
+ *
+ * Uses SHA-256(domain ‖ sharedSecret) for domain separation,
+ * matching the Rust implementation.
+ *
+ * @param {Uint8Array} privateKey - our X25519 private key
+ * @param {Uint8Array} peerPublicKey - peer's 32-byte public key
+ * @returns {Promise<Uint8Array>} 32-byte session key
+ */
+export async function deriveEcdhSessionKey(privateKey, peerPublicKey) {
+  const x25519 = await getX25519();
+  const sharedSecret = x25519.getSharedSecret(privateKey, peerPublicKey);
+
+  const domainBytes = new TextEncoder().encode(ECDH_DOMAIN_TAG);
+  const input = new Uint8Array(domainBytes.length + sharedSecret.length);
+  input.set(domainBytes, 0);
+  input.set(sharedSecret, domainBytes.length);
+
+  const hashBuffer = await crypto.subtle.digest('SHA-256', input);
+  return new Uint8Array(hashBuffer);
+}