QX

End-to-end encrypted communication system for MQTT

QX is a secure, end-to-end encrypted communication system leveraging MQTT for real-time data exchange. Designed with privacy in mind, QX ensures that your communications remain confidential and protected from unauthorized access - even on public brokers.

Features

• End-to-End Encryption: All messages are encrypted using robust cryptographic protocols to ensure privacy.
• MQTT Integration: Utilizes public MQTT brokers for efficient message dissemination.
• Real-Time Communication: Instant message delivery with support for online/offline status.
• Discovery Mechanism: Easily discover and connect with peers.
• Heartbeat Mechanism: Maintains active connections and detects offline peers.
• Replay Protection: Prevents replay attacks to enhance security.

Prerequisites

• Node.js: Ensure you have Node.js installed (v18+ recommended).
• MQTT Broker: You need access to an MQTT broker. You can use a public broker or set up a local one (see section below).

Installation

npm install qx

Usage

const { Bot } = require("qx");

const bot = new Bot();

bot.on("connect", () => {
  console.log("Bot connected to MQTT broker");
});

bot.on("message", (data) => {
  console.log(`Received message from ${data.from}:`, data.json);
});

bot.start();

// Sending a message
bot
  .send("recipientId", { text: "Hello!" })
  .then(() => console.log("Message sent"))
  .catch((err) => console.error("Send failed:", err));

Configuration

QX can be configured using environment variables or by passing options during initialization. Below are the primary configuration options:

Environment Variables

• MQTT_HOST: The MQTT broker URL (default: mqtt://localhost:1883)
• VERBOSE: Enable verbose logging (true or false) (default: false)

Events

QX provides several events to handle different stages of communication:

| Event | Description | Arguments | | ----------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | connect | Emitted when the bot successfully connects to the MQTT broker. | None | | error | Emitted when there is an error during connection, subscription, or messaging. | error: Error object or message. | | offline | Emitted when a registered bot/client is detected to be offline. | data: { hash } - The hash of the offline bot/client. | | online | Emitted when a bot/client becomes online. | data: { hash } - The hash of the online bot/client. | | message | Emitted when a new verified message is received. | data: { from, message, id } - Details about the sender, message content, and message ID. | | ping | Emitted when a ping message is received. | data: { from } - The hash of the sender. | | sent | Emitted when a receipt for a sent message is received. | id: The unique ID of the message that was acknowledged. | | replay | Emitted when a replay attack is detected. | message: Log message indicating the replay detection. | | unknown | Emitted when a message is received from an unregistered bot/client. | data: { from } - The hash of the unknown sender. | | discovery | Emitted when a valid discovery message is received. | data: { id, hash, data } - Information about the discovered bot/client and additional data. | | close | Emitted when the MQTT connection is closed. | None |

API Reference

Bot Methods

• start(): Connect the bot to the MQTT broker and start listening for messages.
• stop(): Disconnect the bot from the MQTT broker and clear all intervals.
• send(to, message): Send a message to a peer. Returns a promise that resolves when the message is acknowledged.
• sendSync(to, message): Send a message without waiting for an acknowledgment.
• introduce(to, options): Introduce the bot to another peer with optional metadata.
• ping(to): Send a ping message to keep the connection active.

Security

QX uses TweetNaCl to provide both encryption and authentication, ensuring that messages are confidential, integrity-protected, and authenticated. This means:

• Confidentiality: Only the intended recipient can decrypt and read the message.
• Integrity: The message cannot be tampered with without detection.
• Authentication: The recipient can verify that the message genuinely originates from the sender.

Note: this library does not currently support non-repudiation, meaning that there is no mechanism to prevent the sender from denying that they sent a message. This was an intentional design decision.

Replay protection

To prevent replay attacks, QX implements a replay protection mechanism. Each message includes a counter that ensures messages are processed in the correct order and are not duplicated. If a message with a counter value lower than or equal to the last received message from a sender is detected, it is identified as a replay and discarded.

bot.on("replay", (message) => {
  console.warn("Replay detected:", message);
});

Setting Up a Local MQTT Broker

EMQX is a highly scalable, open-source MQTT broker. Follow the steps below to install and manage EMQX locally.

brew install emqx
emqx start
emqx stop
emqx -h

Dashboard: http://localhost:18083/