SocketX Javascript Client

This module provides SocketXClient, a TypeScript class that wraps the standard WebSocket API to provide end-to-end encryption using Eclypses MTE (MicroToken Exchange). It is designed to communicate with a corresponding MTE Relay server, handling the MTE handshake, session management, and data encryption/decryption automatically.

The primary goal of this class is to act as a near drop-in replacement for the native WebSocket class, allowing developers to integrate MTE security with minimal changes to their existing application logic.

Features

• Drop-in Replacement: Mimics the standard WebSocket interface (send, close, addEventListener, etc.).
• End-to-End Encryption: All data sent and received is encrypted using MTE.
• Secure Handshake: Uses a post-quantum key exchange (Kyber) to securely establish MTE entropy for the session.
• Post-Quantum Data Protection Each payload is secured uniquely, with a single-use key, that is never repeated and not derived from the data being secured.
• Automated Protocol Handling: Manages the entire lifecycle of the MTE Relay connection, from initial request to data proxying.
• Type-Safe: Written in TypeScript with defined event maps for better developer experience.

Installation

npm i socketxclient

Usage

First, ensure the MTE WASM library is initialized. Then, instantiate SocketXClient just as you would a standard WebSocket. The class handles the MTE pairing and session setup before dispatching the open event.

import { SocketXClient } from "socketxclient";
import { instantiateMteWasm } from "./mte-helpers";

// The Host of the URL should point to your SocketX server.
const socket = new SocketXClient("ws://localhost:8080/api/chat");

socket.addEventListener("open", () => {
  console.log("MTE WebSocket connection established and ready.");
  socket.send("Hello, this message is encrypted!");
});

socket.addEventListener("message", (event) => {
  // event.data will be the decrypted payload (string or Uint8Array)
  console.log("Received decrypted message:", event.data);
});

socket.addEventListener("error", (event) => {
  console.error("MTE WebSocket error:", event);
});

socket.addEventListener("close", (event) => {
  console.log("MTE WebSocket connection closed.", {
    code: event.code,
    reason: event.reason,
  });
});

API Reference

constructor(url: string | URL, protocols?: string | string[])

Creates a new SocketXClient instance. The url should point to the SocketX server, and its pathname will be used as the target upstream service.

send(data: string | ArrayBufferLike | Blob | ArrayBufferView)

Encrypts the provided data using the MTE encoder and sends it to the SocketX server.

close(code?: number, reason?: string)

Closes the underlying WebSocket connection.

Event Listeners

The class implements EventTarget and provides a typed interface for the standard WebSocket events.

• open: Fired when the MTE handshake is complete and the connection to the upstream service is established.
• message: Fired when an encrypted message is received and successfully decrypted. The event.data contains the plaintext payload.
• error: Fired when a connection error occurs.
• close: Fired when the connection is closed.