Socket X Client for Web

This guide provides instructions for integrating the MteRelayWebSocket client into your existing TypeScript application to enable end-to-end MTE (MicroToken Exchange) encryption. The client is designed as a near drop-in replacement for the standard WebSocket API, minimizing the changes required to secure your real-time communications.

Prerequisites

Before you begin, ensure you have the following:

1. The MteRelayWebSocket.ts module and its helpers (e.g., mte-helpers.ts) added to your project's source code.
2. The URL of your running MTE Relay server.

Replace WebSocket with MteRelayWebSocket

In your code, replace the instantiation of the standard WebSocket with MteRelayWebSocket. 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 Socket X server. The pathname of the URL would stay the same.

For example, if your MTE Relay 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: MteRelayWebSocket

To implement the MTE wrapper, change the import, update the class name, and point the URL to your MTE Relay server. The rest of your application logic for handling events remains the same. The data in the message event is automatically decrypted.

// Import the MTE wrapper
import { MteRelayWebSocket } from "./MteRelayWebSocket";

// Replace WebSocket with MteRelayWebSocket and point to the MTE Relay
const mteWs = new MteRelayWebSocket(
  "wss://socketx.your-domain.com/api/v1/chat"
);

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

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

Complete Example

Here is a complete example demonstrating the implementation from initialization to event handling.

import { MteRelayWebSocket } from "./MteRelayWebSocket";

// Instantiate the MteRelayWebSocket
// The URL points to the MTE Relay server.
// The path (`/api/chat`) is the upstream service.
const mteWs = new MteRelayWebSocket("wss://relay.your-domain.com/api/chat");

// 3. Add event listeners just like a standard WebSocket
mteWs.addEventListener("open", () => {
  console.log("MTE WebSocket connection established and ready.");
  mteWs.send("Hello, this message is end-to-end encrypted!");
});

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

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

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

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

API Quick Reference

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

Constructor

• new MteRelayWebSocket(url: string | URL, protocols?: string | string[]): Creates and opens a connection.

Methods

• send(data: string | ArrayBufferLike | Blob | ArrayBufferView): Encrypts and sends data.
• close(code?: number, reason?: string): Closes the connection.
• addEventListener(type, listener, options): Attaches an event listener.
• removeEventListener(type, listener, options): Removes an event listener.

Events

• open: Fires when the secure MTE handshake is complete and the connection is ready for data exchange.
• message: Fires when an encrypted message is received and successfully decrypted. event.data contains the plaintext.
• error: Fires when an error occurs.
• close: Fires when the connection is closed.

Properties

Standard WebSocket properties are passed through directly:

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