SocketX Client for Web

The socketxclient npm package provides SocketXClient, a TypeScript class that wraps the standard WebSocket API to provide end-to-end encryption using Eclypses MTE (MicroToken Exchange). It communicates with a SocketX Server, handling the MTE handshake, session management, and data encryption/decryption automatically.

SocketXClient is designed as a near drop-in replacement for the native WebSocket class, minimizing the changes required to secure your real-time communications.

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 SocketX connection, from initial request to data proxying.
• Type-Safe: Written in TypeScript with defined event maps for better developer experience.

Prerequisites

1. The URL of your running SocketX Server.
2. Node 20+ tooling for your web application build.

Installation

npm i socketxclient

Replace WebSocket with SocketXClient

In your code, replace the instantiation of the standard WebSocket with SocketXClient. The constructor and event listeners work just like the native WebSocket API.

Modify the connection URL

The URL provided to the constructor should point to your SocketX Server. The pathname of the URL stays the same — it is used as the target upstream service.

For example, if your SocketX Server is at wss://socketx.your-domain.com and your backend WebSocket service is at /api/v1/chat, the URL would be wss://socketx.your-domain.com/api/v1/chat.

Before: Standard WebSocket

// Original WebSocket implementation
const ws = new WebSocket("wss://your-app.com/api/v1/chat");

ws.addEventListener("open", () => {
  console.log("Connection open.");
  ws.send("Hello, world!");
});

ws.addEventListener("message", (event) => {
  console.log("Received message:", event.data);
});

After: SocketXClient

Change the import, update the class name, and point the URL to your SocketX Server. The rest of your application logic for handling events remains the same. The data in the message event is automatically decrypted.

// Import the SocketX client
import { SocketXClient } from "socketxclient";

// Replace WebSocket with SocketXClient and point to the SocketX Server
const socket = new SocketXClient("wss://socketx.your-domain.com/api/v1/chat");

// Event handling logic remains the same
socket.addEventListener("open", () => {
  console.log("Secure SocketX connection open.");
  socket.send("This message will be encrypted!");
});

socket.addEventListener("message", (event) => {
  // event.data is already decrypted
  console.log("Received decrypted message:", event.data);
});

Complete Example

import { SocketXClient } from "socketxclient";

// The URL points to the SocketX Server.
// The path (`/api/chat`) is the upstream service.
const socket = new SocketXClient("wss://socketx.your-domain.com/api/chat");

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

socket.addEventListener("message", (event) => {
  // The received data is automatically decrypted.
  console.log("Received decrypted message:", event.data);
});

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

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

// To send a message later
function sendMessage(message: string) {
  if (socket.readyState === WebSocket.OPEN) {
    socket.send(message);
  } else {
    console.warn("WebSocket is not open. Message not sent.");
  }
}

API Quick Reference

The SocketXClient class mirrors the standard WebSocket API for a seamless transition.

Constructor

• new SocketXClient(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.

Methods

• 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.
• addEventListener(type, listener, options): Attaches an event listener.
• removeEventListener(type, listener, options): Removes an event listener.

Events

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 (string or Uint8Array).
• error: Fired when a connection error occurs.
• close: Fired when the connection is closed.

Properties

Standard WebSocket properties are passed through directly:

• readyState
• binaryType
• bufferedAmount
• url
• protocol
• extensions