@seriousme/opifex 1.11.3 → 2.0.3

package/dev_utils/generateCert.ts

@@ -0,0 +1,95 @@
+import forge from "node-forge";
+
+/**
+ * Generates a minimal, in-memory TLS certificate bundle for localhost development.
+ * Includes Root CA, Server Certificate, and Server Private Key with SAN support (IPv4 & IPv6).
+ */
+export function generateLocalhostCerts(): {
+  caCert: string;
+  key: string;
+  cert: string;
+  fullChain: string;
+} {
+  // Generate the keypairs
+  // 2048-bit RSA is used here for fast generation during local development/testing
+  const caKeys = forge.pki.rsa.generateKeyPair(2048);
+  const serverKeys = forge.pki.rsa.generateKeyPair(2048);
+
+  // Create root CA
+  const caCert = forge.pki.createCertificate();
+  caCert.publicKey = caKeys.publicKey;
+  caCert.serialNumber = "01";
+  caCert.validity.notBefore = new Date();
+  caCert.validity.notAfter = new Date();
+  caCert.validity.notAfter.setFullYear(
+    caCert.validity.notBefore.getFullYear() + 1,
+  ); // Valid for 1 year
+
+  // Hardcoded CA Attributes
+  const caAttrs = [{ name: "commonName", value: "Local Dev Root CA" }];
+  caCert.setSubject(caAttrs);
+  caCert.setIssuer(caAttrs); // Self-signed: issuer equals subject
+
+  // Critical for CA: Define basic constraints to flag this certificate as a trusted issuer
+  caCert.setExtensions([
+    { name: "basicConstraints", cA: true, critical: true },
+    {
+      name: "keyUsage",
+      keyCertSign: true,
+      digitalSignature: true,
+      critical: true,
+    },
+  ]);
+
+  // Sign the CA certificate using its own private key
+  caCert.sign(caKeys.privateKey, forge.md.sha256.create());
+
+  // Create server certificate for localhost, valid for a year
+  const serverCert = forge.pki.createCertificate();
+  serverCert.publicKey = serverKeys.publicKey;
+  serverCert.serialNumber = "02"; // Unique serial number within this CA scope
+  serverCert.validity.notBefore = new Date();
+  serverCert.validity.notAfter = new Date();
+  serverCert.validity.notAfter.setFullYear(
+    serverCert.validity.notBefore.getFullYear() + 1,
+  );
+
+  // Hardcoded Server Attributes
+  serverCert.setSubject([{ name: "commonName", value: "localhost" }]);
+  serverCert.setIssuer(caCert.subject.attributes); // Issued by our custom Root CA
+
+  // Critical for Modern TLS: X509v3 Extensions containing Subject Alternative Names (SAN)
+  // Ensures compatibility with strict TLS parsers (like Deno/rustls, Go, Node.js, and modern browsers)
+  serverCert.setExtensions([
+    { name: "basicConstraints", cA: false, critical: true },
+    {
+      name: "keyUsage",
+      digitalSignature: true,
+      keyEncipherment: true,
+      critical: true,
+    },
+    {
+      name: "subjectAltName",
+      altNames: [
+        { type: 2, value: "localhost" }, // type 2 = DNS
+        { type: 7, ip: "127.0.0.1" }, // type 7 = IPv4 loopback
+        { type: 7, ip: "::1" }, // type 7 = IPv6 loopback
+      ],
+    },
+  ]);
+
+  // Sign the server certificate using the Root CA's private key
+  serverCert.sign(caKeys.privateKey, forge.md.sha256.create());
+
+  // convert data to PEM
+  const caCertPem = forge.pki.certificateToPem(caCert);
+  const serverCertPem = forge.pki.certificateToPem(serverCert);
+  const serverKeyPem = forge.pki.privateKeyToPem(serverKeys.privateKey);
+
+  return {
+    caCert: caCertPem,
+    key: serverKeyPem,
+    cert: serverCertPem,
+    fullChain: `${serverCertPem}\n${caCertPem}`, // Full certificate chain (Server + CA)
+  };
+}

package/dev_utils/mockConn.ts

@@ -0,0 +1,36 @@
+class Uint8Writer implements WritableStreamDefaultWriter {
+  private buff: Uint8Array;
+  private pos: number;
+  closed = Promise.resolve(undefined);
+  close = () => Promise.resolve();
+  abort = () => Promise.resolve();
+  ready = Promise.resolve(undefined);
+  releaseLock = () => {};
+  desiredSize = 20;
+
+  constructor(
+    buff: Uint8Array,
+  ) {
+    this.buff = buff;
+    this.pos = 0;
+  }
+  write(chunk: Uint8Array): Promise<void> {
+    this.buff.set(chunk, this.pos);
+    this.pos += chunk.length;
+    return Promise.resolve();
+  }
+}
+
+export function createMockSockConn(
+  readerBuffs: Uint8Array[],
+  writerBuf: Uint8Array,
+  close = () => {},
+) {
+  const readable = ReadableStream.from(readerBuffs);
+  const writable = new WritableStream(new Uint8Writer(writerBuf));
+  return {
+    readable,
+    writable,
+    close,
+  };
+}

package/dev_utils/mockServer.ts

@@ -0,0 +1,28 @@
+import { createWebStreamPair } from "./webStreamPair.ts";
+import { MqttConn } from "../mqttConn/mqttConn.ts";
+import { Context, MqttServer } from "../server/mod.ts";
+import { handlers } from "./test-handlers.ts";
+import type { MqttServerOptions } from "../server/mod.ts";
+
+export function startMockServer(opts: MqttServerOptions = {}): {
+  mqttConn: MqttConn;
+  mqttServer: MqttServer;
+} {
+  const serverOpts = { handlers, ...opts };
+  // start with a fresh clientlist
+  Context.clientList.clear();
+  // create a new MQTT server
+
+  const mqttServer = new MqttServer(serverOpts);
+  const { input, output } = createWebStreamPair();
+  const mqttConn = new MqttConn({ conn: output });
+  mqttServer.serve(input);
+  return { mqttConn, mqttServer };
+}
+
+export function addMockClient(mqttServer: MqttServer): MqttConn {
+  const { input, output } = createWebStreamPair();
+  const mqttConn = new MqttConn({ conn: output });
+  mqttServer.serve(input);
+  return mqttConn;
+}

package/dev_utils/mod.ts

@@ -1,3 +1,30 @@
-export { makeDummyQueueSockConn, makeDummySockConn } from "./dummyConn.ts";
-export { createWebSocketPair } from "./socketPair.ts";
-export { resolveAsap, resolveNextTick, runAsap } from "./timers.ts";
+export { createMockSockConn } from "./mockConn.ts";
+export { createWebStreamPair } from "./webStreamPair.ts";
+export {
+  delay,
+  resolveAsap,
+  resolveNextTick,
+  runAsap,
+  withTimeout,
+} from "./timers.ts";
+export { addMockClient, startMockServer } from "./mockServer.ts";
+export {
+  auth,
+  checkNoPacket,
+  connect,
+  connect5,
+  disconnect,
+  disconnect5,
+  nextPacketWithTimeOut,
+  ping,
+  publish,
+  publish5,
+  receiveMessages,
+  receiveMessages5,
+  subscribe,
+  subscribe5,
+  unsubscribe,
+  unsubscribe5,
+} from "./packetHelpers.ts";
+export { generateLocalhostCerts } from "./generateCert.ts";
+export { handlers, isAuthenticatedBroker } from "./test-handlers.ts";

package/dev_utils/packetHelpers.ts

@@ -0,0 +1,404 @@
+import type { MqttConn } from "../mqttConn/mqttConn.ts";
+import { withTimeout } from "./timers.ts";
+import { delay } from "./timers.ts";
+import { MQTTLevel, PacketType, ReasonCode } from "../mqttPacket/mod.ts";
+import type {
+  AnyPacket,
+  AuthPacket,
+  ConnackPacket,
+  ConnectPacket,
+  DisconnectProperties,
+  ProtocolLevel,
+  PublishProperties,
+  QoS,
+  Topic,
+  TopicFilter,
+  UnsubackPacket,
+} from "../mqttPacket/mod.ts";
+import type {
+  ConnackPacketV4,
+  ConnackPacketV5,
+} from "../mqttPacket/connack.ts";
+import type { ConnectPacketV5 } from "../mqttPacket/connect.ts";
+import assert from "node:assert/strict";
+import { logger } from "../utils/mod.ts";
+
+const txtEncoder = new TextEncoder();
+
+let clientIdCounter = 1;
+
+const PINGREQ_PACKET: AnyPacket = Object.freeze({
+  type: PacketType.pingreq,
+  protocolLevel: MQTTLevel.v4,
+});
+
+export function nextPacketWithTimeOut(
+  conn: MqttConn,
+  timeoutMs: number,
+): Promise<IteratorResult<AnyPacket> | null> {
+  return withTimeout(conn.next(), timeoutMs);
+}
+
+export async function checkNoPacket(mqttConn: MqttConn, timeoutMs = 10) {
+  const result = await nextPacketWithTimeOut(mqttConn, timeoutMs);
+  assert.equal(result, null, "no packet received");
+}
+
+async function baseConnect(mqttConn: MqttConn, {
+  level = MQTTLevel.v4 as ProtocolLevel,
+  clientId = `testClient-${clientIdCounter++}`,
+  username = "IoTester_1",
+  password = "strong_password",
+  keepAlive = 0,
+  clean = true,
+  will = undefined as ConnectPacket["will"],
+  properties = {},
+  checkAck = true,
+} = {}): Promise<ConnackPacket | AuthPacket> {
+  mqttConn.codecOpts.protocolLevel = level;
+  const connectPacket: ConnectPacket = {
+    type: PacketType.connect,
+    protocolName: "MQTT",
+    protocolLevel: level,
+    clientId,
+    clean,
+    keepAlive,
+    username,
+    password: password !== "" ? txtEncoder.encode(password) : undefined,
+    will,
+  };
+  if (connectPacket.protocolLevel === MQTTLevel.v5) {
+    connectPacket.properties = properties;
+  }
+  logger.verbose("connectHelper: sending connect");
+  logger.debug({ connectPacket });
+
+  mqttConn.send(connectPacket);
+  const { value: connack } = await mqttConn.next();
+  logger.verbose("connectHelper: connack", connack);
+  if (checkAck) {
+    assert.deepStrictEqual(
+      connack.type,
+      PacketType.connack,
+      "Expected CONNACK",
+    );
+  }
+  mqttConn.codecOpts.protocolLevel = level;
+  return connack;
+}
+
+export async function connect(mqttConn: MqttConn, {
+  level = MQTTLevel.v4,
+  clientId = `testClient-${clientIdCounter++}`,
+  username = "IoTester_1",
+  password = "strong_password",
+  keepAlive = 0,
+  clean = true,
+  will = undefined as ConnectPacket["will"],
+  checkAck = true,
+} = {}): Promise<ConnackPacketV4> {
+  return await baseConnect(mqttConn, {
+    level,
+    clientId,
+    username,
+    password,
+    keepAlive,
+    clean,
+    will,
+    checkAck,
+  }) as ConnackPacketV4;
+}
+
+export async function connect5(mqttConn: MqttConn, {
+  clientId = `testClient-${clientIdCounter++}`,
+  username = "IoTester_1",
+  password = "strong_password",
+  keepAlive = 0,
+  clean = true,
+  will = undefined as ConnectPacket["will"],
+  properties = {} as ConnectPacketV5["properties"],
+  checkAck = true,
+} = {}): Promise<ConnackPacketV5> {
+  return await baseConnect(mqttConn, {
+    level: MQTTLevel.v5,
+    clientId,
+    username,
+    password,
+    keepAlive,
+    clean,
+    will,
+    properties,
+    checkAck,
+  }) as ConnackPacketV5;
+}
+
+export async function auth(mqttConn: MqttConn, {
+  reasonCode = ReasonCode.continueAuthentication,
+  authMethod = "SCRAM-SHA-256",
+  authData = new Uint8Array([1]),
+  noMethod = false,
+  noData = false,
+} = {}) {
+  const authPacket: AuthPacket = {
+    type: PacketType.auth,
+    protocolLevel: 5,
+    reasonCode,
+    properties: {
+      authenticationMethod: noMethod ? undefined : authMethod,
+      authenticationData: noData ? undefined : authData,
+    },
+  };
+  await mqttConn.send(authPacket);
+  const { value } = await mqttConn.next();
+  return value;
+}
+
+export async function subscribe(
+  subscriber: MqttConn,
+  subscriptions: {
+    topicFilter: TopicFilter;
+    qos: QoS;
+  }[],
+  {
+    id = 24,
+    checkAcks = true,
+  } = {},
+) {
+  const subscribePacket = {
+    type: PacketType.subscribe,
+    protocolLevel: MQTTLevel.v4,
+    id,
+    subscriptions,
+  };
+
+  subscriber.send(subscribePacket);
+
+  const { value: packet } = await subscriber.next();
+  if (checkAcks) {
+    assert.equal(packet.type, PacketType.suback, "Expected SUBACK");
+    assert.equal(packet.id, id, "SUBACK ID should match SUBSCRIBE ID");
+    const results = packet.returnCodes || packet.reasonCodes;
+    assert.equal(results.length, subscriptions.length, "ACK count match");
+    for (let i = 0; i < results.length; i++) {
+      assert.equal(results[i], subscriptions[i].qos);
+    }
+  }
+  return packet;
+}
+
+export async function subscribe5(
+  subscriber: MqttConn,
+  subscriptions: {
+    topicFilter: TopicFilter;
+    qos: QoS;
+    noLocal?: boolean;
+    retainAsPublished?: boolean;
+    retainHandling?: number;
+  }[],
+  {
+    id = 24,
+    subscriptionIdentifier = undefined as number | undefined,
+    checkAcks = true,
+  } = {},
+) {
+  const properties = subscriptionIdentifier !== undefined
+    ? { subscriptionIdentifier }
+    : {};
+
+  const subscribePacket = {
+    type: PacketType.subscribe,
+    protocolLevel: MQTTLevel.v5,
+    id,
+    subscriptions,
+    properties,
+  };
+
+  subscriber.send(subscribePacket);
+  logger.debug("subscribe helper: sent subscription request");
+
+  const { value: packet } = await subscriber.next();
+  assert.equal(packet.type, PacketType.suback, "Expected SUBACK");
+  assert.equal(packet.id, id, "SUBACK ID should match SUBSCRIBE ID");
+  logger.debug("subscribe helper: received SubAck");
+
+  if (checkAcks) {
+    const results = packet.returnCodes || packet.reasonCodes;
+    assert.equal(results.length, subscriptions.length, "ACK count match");
+    for (let i = 0; i < results.length; i++) {
+      assert.equal(results[i], subscriptions[i].qos);
+    }
+  }
+  logger.debug("subscribe helper: acks ok");
+  return packet;
+}
+
+export async function unsubscribe(
+  subscriber: MqttConn,
+  topicFilters: TopicFilter[],
+  {
+    level = MQTTLevel.v4,
+    id = 24,
+  } = {},
+) {
+  subscriber.send({
+    type: PacketType.unsubscribe,
+    protocolLevel: level,
+    id,
+    topicFilters,
+  });
+  const { value: packet } = await subscriber.next();
+  assert.equal(packet.type, PacketType.unsuback, "Expected UNSUBACK");
+  assert.equal(packet.protocolLevel, level, "received expected level");
+  assert.equal(packet.id, id, "UNSUBACK ID should match UNSUBSCRIBE ID");
+}
+
+export async function unsubscribe5(
+  subscriber: MqttConn,
+  topicFilters: TopicFilter[],
+  { id = 24 } = {},
+): Promise<UnsubackPacket> {
+  subscriber.send({
+    type: PacketType.unsubscribe,
+    protocolLevel: MQTTLevel.v5,
+    id,
+    topicFilters,
+  });
+  const { value: packet } = await subscriber.next();
+  assert.equal(packet.type, PacketType.unsuback, "Expected UNSUBACK");
+  assert.equal(packet.protocolLevel, MQTTLevel.v5, "received expected level");
+  assert.equal(packet.id, id, "UNSUBACK ID should match UNSUBSCRIBE ID");
+  return packet;
+}
+
+export async function publish(
+  publisher: MqttConn,
+  topic: Topic,
+  qos: QoS,
+  {
+    level = MQTTLevel.v4 as ProtocolLevel,
+    id = 22,
+    payload = "payload",
+    retain = false,
+    properties = {},
+    checkAcks = true,
+  } = {},
+) {
+  const encodedPayload = txtEncoder.encode(payload);
+
+  await publisher.send({
+    type: PacketType.publish,
+    protocolLevel: level,
+    id,
+    topic,
+    qos,
+    payload: encodedPayload,
+    retain,
+    properties,
+  });
+  logger.debug("publish helper: sent publish");
+  if (!checkAcks || qos === 0) return;
+
+  const { value: ackPacket } = await publisher.next();
+  const expectedAckType = qos === 1 ? PacketType.puback : PacketType.pubrec;
+  assert.equal(ackPacket.type, expectedAckType, "received expected ack");
+  assert.equal(ackPacket.protocolLevel, level, "received expected level");
+  assert.equal(ackPacket.id, id, "packetid matches");
+  logger.debug("publish helper: received pubAck");
+
+  if (qos === 1) return ackPacket;
+
+  publisher.send({
+    type: PacketType.pubrel,
+    protocolLevel: level,
+    id,
+  });
+
+  const { value: compPacket } = await publisher.next();
+  assert.equal(
+    compPacket.type,
+    PacketType.pubcomp,
+    "received expected pubcomp",
+  );
+  assert.equal(compPacket.id, id, "packetid of pubcomp matches");
+}
+
+export function publish5(
+  publisher: MqttConn,
+  topic: Topic,
+  qos: QoS,
+  opts?: {
+    id?: number;
+    payload?: string;
+    retain?: boolean;
+    properties?: PublishProperties;
+    checkAcks?: boolean;
+  },
+) {
+  return publish(
+    publisher,
+    topic,
+    qos,
+    Object.assign({}, opts, { level: MQTTLevel.v5 }),
+  );
+}
+
+export async function disconnect(
+  mqttConn: MqttConn,
+  { level = MQTTLevel.v4 } = {},
+) {
+  mqttConn.send({
+    type: PacketType.disconnect,
+    protocolLevel: level,
+  });
+  await mqttConn.next();
+
+  assert.strictEqual(
+    mqttConn.isClosed,
+    true,
+    "Expected connection to be closed",
+  );
+}
+
+export async function disconnect5(mqttConn: MqttConn, opts?: {
+  reasonCode?: number;
+  properties?: DisconnectProperties;
+}) {
+  const packet = {
+    type: PacketType.disconnect,
+    protocolLevel: MQTTLevel.v5,
+    reasonCode: opts?.reasonCode,
+    properties: opts?.properties,
+  };
+
+  mqttConn.send(packet);
+  await mqttConn.next();
+  await mqttConn.next();
+
+  assert.strictEqual(
+    mqttConn.isClosed,
+    true,
+    "Expected connection to be closed",
+  );
+}
+
+export async function ping(mqttConn: MqttConn) {
+  mqttConn.send(PINGREQ_PACKET);
+  const { value: pingres } = await mqttConn.next();
+  assert.strictEqual(pingres.type, PacketType.pingres);
+}
+
+export async function receiveMessages(conn: MqttConn) {
+  const received = Array.fromAsync(conn);
+  await delay(10);
+  await disconnect(conn);
+  const messages = await received;
+  return messages;
+}
+
+export async function receiveMessages5(conn: MqttConn) {
+  const received = Array.fromAsync(conn);
+  await delay(10);
+  await disconnect5(conn);
+  const messages = await received;
+  return messages;
+}

package/dev_utils/test-handlers.ts

@@ -0,0 +1,98 @@
+import { ReasonCode } from "../server/mod.ts";
+import { logger } from "../utils/mod.ts";
+import type {
+  AuthenticatedResult,
+  Context,
+  ShareName,
+  Topic,
+} from "../server/mod.ts";
+
+const utf8Decoder = new TextDecoder();
+const userTable = new Map();
+userTable.set("IoTester_1", "strong_password");
+userTable.set("IoTester_2", "strong_password");
+const strictUsername = new RegExp(/^[a-zA-Z0-9]{0,23}$/);
+
+function isAuthenticated(
+  _ctx: Context,
+  clientId: string,
+  username: string,
+  password: Uint8Array,
+): AuthenticatedResult {
+  const pwd = utf8Decoder.decode(password);
+  logger.debug(
+    `Verifying authentication of client '${clientId}' with username '${username}'`,
+  );
+
+  if (!userTable.has(username)) {
+    if (!strictUsername.test(username)) {
+      return { reasonCode: ReasonCode.success };
+    }
+  }
+
+  const pass = userTable.get(username);
+  if (pwd === pass) {
+    return { reasonCode: ReasonCode.success };
+  }
+  return {
+    reasonCode: ReasonCode.badUserNameOrPassword,
+    reasonString: "Bad username or password",
+  };
+}
+
+function processAuth(
+  _ctx: Context,
+  _clientId: string,
+  _authMethod: string,
+  _authData: Uint8Array,
+) {
+  return {
+    reasonCode: ReasonCode.badAuthenticationMethod,
+    reasonString: "Authentication method not supported",
+  };
+}
+
+function isAuthorizedToPublish(ctx: Context, topic: Topic): boolean {
+  logger.debug(
+    "Checking authorization of client",
+    ctx.clientId,
+    "to publish on topic",
+    topic,
+  );
+  if (topic === "topic/unauthorized") {
+    return false;
+  }
+  return true;
+}
+function isAuthorizedToSubscribe(
+  ctx: Context,
+  topic: Topic,
+  shareName: ShareName,
+): boolean {
+  logger.debug(
+    "Checking authorization of client",
+    ctx.clientId,
+    "to subscribe to topic",
+    topic,
+    "using shareName",
+    shareName,
+  );
+  if (topic === "topic/unauthorized") {
+    return false;
+  }
+  return true;
+}
+
+export const handlers = {
+  isAuthenticated,
+  processAuth,
+  isAuthorizedToPublish,
+  isAuthorizedToSubscribe,
+};
+
+export function isAuthenticatedBroker(
+  ctx: Context,
+): AuthenticatedResult {
+  ctx.isBroker = true;
+  return { reasonCode: ReasonCode.success };
+}