@seriousme/opifex 1.11.3 → 2.1.0

package/server/deps.ts

@@ -1,12 +1,18 @@
-export type { SockConn } from "../socket/socket.ts";
+export type { SockAddr, SockConn } from "../socket/socket.ts";
 export { MqttConn } from "../mqttConn/mqttConn.ts";
-export type { IPersistence } from "../persistence/persistence.ts";
-export type { IStore } from "../persistence/store.ts";
+export type {
+  ClientSubscription,
+  ExtPublishPacket,
+  Persistence,
+  ShareName,
+} from "../persistence/persistence.ts";
 export { MemoryPersistence } from "../persistence/memory/memoryPersistence.ts";
 export type {
   AnyPacket,
+  AuthPacket,
   ClientId,
   ConnackPacket,
+  ConnackProperties,
   ConnectPacket,
   DisconnectPacket,
   PacketId,
@@ -16,13 +22,14 @@ export type {
   PubackPacket,
   PubcompPacket,
   PublishPacket,
+  PublishPacketV5,
   PubrecPacket,
   PubrelPacket,
   QoS,
   SubackPacket,
   SubscribePacket,
   Subscription,
-  TAuthenticationResult,
+  SubscriptionV5,
   Topic,
   TopicFilter,
   UnsubackPacket,
@@ -34,6 +41,18 @@ export {
   MQTTLevel,
   PacketNameByType,
   PacketType,
+  ReasonCode,
 } from "../mqttPacket/mod.ts";
 export { Timer } from "../timer/timer.ts";
-export { logger } from "../utils/mod.ts";
+export {
+  assert,
+  hasWildcards,
+  invalidmaxTopicLevels,
+  invalidTopic,
+  invalidTopicFilter,
+  joinTopicFilter,
+  logger,
+  LogLevel,
+  OutboundTopicAliasManager,
+  parseTopicFilter,
+} from "../utils/mod.ts";

package/server/handlers/completeConnect.ts

@@ -0,0 +1,93 @@
+import { AuthenticationResult, PacketType, ReasonCode } from "../deps.ts";
+import type { ProtocolLevel } from "../deps.ts";
+import type { Context } from "../context.ts";
+
+/**
+ * Maps MQTT v5 ReasonCodes to MQTT v3.1.1 ReturnCodes (AuthenticationResult)
+ */
+const V4_RETURN_CODE_MAP: Record<number, number> = {
+  [ReasonCode.success]: AuthenticationResult.ok, // 0x00
+  [ReasonCode.unsupportedProtocolVersion]:
+    AuthenticationResult.unacceptableProtocol, // 0x01
+  [ReasonCode.clientIdentifierNotValid]: AuthenticationResult.rejectedUsername, // 0x02
+  [ReasonCode.badUserNameOrPassword]:
+    AuthenticationResult.badUsernameOrPassword, // 0x04
+  [ReasonCode.badAuthenticationMethod]:
+    AuthenticationResult.badUsernameOrPassword, // 0x04
+  [ReasonCode.notAuthorized]: AuthenticationResult.notAuthorized, // 0x05
+  [ReasonCode.banned]: AuthenticationResult.notAuthorized, // 0x05
+};
+
+export function reasonToReturnCode(reasonCode: number): number {
+  return V4_RETURN_CODE_MAP[reasonCode] ??
+    AuthenticationResult.serverUnavailable; // 0x03
+}
+
+/**
+ * complete connect
+ */
+export async function completeConnect(
+  ctx: Context,
+  protocolLevel: ProtocolLevel,
+  reasonCode: ReasonCode,
+  reasonString: string | undefined,
+) {
+  const cfg = ctx.config.context;
+  const connectOpts = ctx.connectOptions || {};
+  const isSuccess = reasonCode === ReasonCode.success;
+  const isProtocolV5 = protocolLevel === 5;
+
+  let sessionPresent = false;
+  if (isSuccess) {
+    // Establish Session on Success
+    sessionPresent = await ctx.connect();
+  }
+
+  // Send CONNACK
+  const result = isProtocolV5
+    ? {
+      reasonCode,
+      properties: {
+        // only send full details on success
+        ...(isSuccess
+          ? {
+            receiveMaximum: cfg.receiveMaximum,
+            maximumQos: cfg.maximumQos,
+            retainAvailable: cfg.retainAvailable,
+            maximumPacketSize: cfg.maximumIncomingPacketSize,
+            topicAliasMaximum: cfg.topicAliasMaximum,
+            wildcardSubscriptionAvailable: cfg.wildcardSubscriptionAvailable,
+            subscriptionIdentifierAvailable:
+              cfg.subscriptionIdentifierAvailable,
+            sharedSubscriptionAvailable: cfg.sharedSubscriptionAvailable,
+            serverKeepAlive: cfg.serverKeepAlive,
+            assignedClientIdentifier: connectOpts.assignedClientIdentifier,
+            sessionExpiryInterval: connectOpts.sessionExpiryInterval,
+          }
+          : {}),
+        reasonString: reasonString,
+      },
+    }
+    : { returnCode: reasonToReturnCode(reasonCode) };
+
+  await ctx.send({
+    type: PacketType.connack,
+    protocolLevel,
+    sessionPresent,
+    ...result,
+  });
+
+  // Finalize or Terminate Connection
+  if (!isSuccess) {
+    await ctx.close(false);
+    return;
+  }
+
+  // reset connectOptions
+  ctx.connectOptions = undefined;
+
+  // start redelivery
+  if (sessionPresent) {
+    await ctx.handleRedelivery();
+  }
+}

package/server/handlers/duplicate.test.ts

@@ -0,0 +1,196 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  connect,
+  disconnect,
+  ping,
+  startMockServer,
+} from "../../dev_utils/mod.ts";
+import type { AnyPacket } from "../deps.ts";
+import { MQTTLevel, PacketType } from "../deps.ts";
+
+const txtEncoder = new TextEncoder();
+
+test("MQTT-4.3.1: QoS 1 duplicate PUBLISH is acknowledged", async () => {
+  const { mqttConn } = startMockServer();
+
+  await connect(mqttConn);
+
+  // Send QoS 1 PUBLISH with dup=false
+  const publishPacket: AnyPacket = {
+    type: PacketType.publish,
+    protocolLevel: MQTTLevel.v4,
+    topic: "test/topic",
+    payload: txtEncoder.encode("message"),
+    qos: 1,
+    retain: false,
+    dup: false,
+    id: 1,
+  };
+  mqttConn.send(publishPacket);
+
+  // Receive first PUBACK
+  const { value: puback1 } = await mqttConn.next();
+  assert.deepStrictEqual(puback1.type, PacketType.puback);
+  if (puback1.type === PacketType.puback) {
+    assert.deepStrictEqual(puback1.id, 1);
+  }
+
+  // Send duplicate PUBLISH with dup=true and same packet ID
+  const duplicatePublishPacket: AnyPacket = {
+    type: PacketType.publish,
+    protocolLevel: MQTTLevel.v4,
+    topic: "test/topic",
+    payload: txtEncoder.encode("message"),
+    qos: 1,
+    retain: false,
+    dup: true,
+    id: 1,
+  };
+  mqttConn.send(duplicatePublishPacket);
+
+  // Should receive PUBACK for duplicate as well
+  const { value: puback2 } = await mqttConn.next();
+  assert.deepStrictEqual(
+    puback2.type,
+    PacketType.puback,
+    "Duplicate PUBLISH should receive PUBACK",
+  );
+  if (puback2.type === PacketType.puback) {
+    assert.deepStrictEqual(puback2.id, 1, "PUBACK ID should match");
+  }
+
+  await disconnect(mqttConn);
+});
+
+test("MQTT-4.3.2: QoS 2 duplicate PUBLISH returns PUBREC without redelivery", async () => {
+  const { mqttConn } = startMockServer();
+
+  await connect(mqttConn);
+
+  // Send QoS 2 PUBLISH with dup=false
+  const publishPacket: AnyPacket = {
+    type: PacketType.publish,
+    protocolLevel: MQTTLevel.v4,
+    topic: "test/topic",
+    payload: txtEncoder.encode("qos2message"),
+    qos: 2,
+    retain: false,
+    dup: false,
+    id: 2,
+  };
+  mqttConn.send(publishPacket);
+
+  // Receive first PUBREC
+  const { value: pubrec1 } = await mqttConn.next();
+  assert.deepStrictEqual(pubrec1.type, PacketType.pubrec);
+  if (pubrec1.type === PacketType.pubrec) {
+    assert.deepStrictEqual(pubrec1.id, 2);
+  }
+
+  // Send duplicate PUBLISH with dup=true and same packet ID
+  // Per MQTT spec: "the Receiver MUST acknowledge any subsequent
+  // PUBLISH packet with the same Packet Identifier by sending a PUBREC.
+  // It MUST NOT cause duplicate messages to be delivered to any onward recipients"
+  const duplicatePublishPacket: AnyPacket = {
+    type: PacketType.publish,
+    protocolLevel: MQTTLevel.v4,
+    topic: "test/topic",
+    payload: txtEncoder.encode("qos2message"),
+    qos: 2,
+    retain: false,
+    dup: true,
+    id: 2,
+  };
+  mqttConn.send(duplicatePublishPacket);
+
+  // Should receive PUBREC for duplicate without redelivery
+  const { value: pubrec2 } = await mqttConn.next();
+  assert.deepStrictEqual(
+    pubrec2.type,
+    PacketType.pubrec,
+    "Duplicate QoS 2 PUBLISH should return PUBREC",
+  );
+  if (pubrec2.type === PacketType.pubrec) {
+    assert.deepStrictEqual(pubrec2.id, 2);
+  }
+
+  // Complete the QoS 2 exchange with PUBREL
+  const pubrelPacket: AnyPacket = {
+    type: PacketType.pubrel,
+    protocolLevel: MQTTLevel.v4,
+    id: 2,
+  };
+  mqttConn.send(pubrelPacket);
+
+  // Should receive PUBCOMP
+  const { value: pubcomp } = await mqttConn.next();
+  assert.deepStrictEqual(pubcomp.type, PacketType.pubcomp);
+
+  await disconnect(mqttConn);
+});
+
+test("ignores duplicate PUBACK gracefully", async () => {
+  const { mqttConn } = startMockServer();
+
+  await connect(mqttConn);
+
+  // Send QoS 1 PUBLISH (incoming)
+  const publishPacket: AnyPacket = {
+    type: PacketType.publish,
+    protocolLevel: MQTTLevel.v4,
+    topic: "test/topic",
+    payload: txtEncoder.encode("message"),
+    qos: 1,
+    retain: false,
+    dup: false,
+    id: 3,
+  };
+  mqttConn.send(publishPacket);
+
+  // Receive PUBACK
+  const { value: puback } = await mqttConn.next();
+  assert.deepStrictEqual(puback.type, PacketType.puback);
+
+  // Send duplicate PUBACK (shouldn't cause any issue or response)
+  const duplicatePubackPacket: AnyPacket = {
+    type: PacketType.puback,
+    protocolLevel: MQTTLevel.v4,
+    id: 3,
+  };
+  mqttConn.send(duplicatePubackPacket);
+
+  // Send PINGREQ to verify server is still responsive
+  // Should receive PINGRES (duplicate PUBACK should be silently ignored)
+  await ping(mqttConn);
+
+  await disconnect(mqttConn);
+});
+
+test("PUBREL without prior PUBREC still returns PUBCOMP", async () => {
+  const { mqttConn } = startMockServer();
+
+  await connect(mqttConn);
+
+  // Send PUBREL directly without prior QoS 2 PUBLISH/PUBREC sequence
+  // This can happen if PUBREC was lost and client retransmits PUBREL
+  const pubrelPacket: AnyPacket = {
+    type: PacketType.pubrel,
+    protocolLevel: MQTTLevel.v4,
+    id: 99,
+  };
+  mqttConn.send(pubrelPacket);
+
+  // Should still receive PUBCOMP per MQTT spec [MQTT-4.3.3-1]
+  const { value: pubcomp } = await mqttConn.next();
+  assert.deepStrictEqual(
+    pubcomp.type,
+    PacketType.pubcomp,
+    "PUBREL without prior PUBREC should still return PUBCOMP",
+  );
+  if (pubcomp.type === PacketType.pubcomp) {
+    assert.deepStrictEqual(pubcomp.id, 99);
+  }
+
+  await disconnect(mqttConn);
+});

package/server/handlers/handleAuth.test.ts

@@ -0,0 +1,225 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import type { Context } from "../context.ts";
+import { PacketType, ReasonCode } from "../deps.ts";
+import {
+  auth,
+  connect5,
+  publish5,
+  startMockServer,
+  subscribe5,
+  unsubscribe5,
+} from "../../dev_utils/mod.ts";
+
+const successHandler = () => {
+  return {
+    reasonCode: ReasonCode.success,
+    authData: new Uint8Array([9, 9]),
+    reasonString: "Re-auth successful",
+  };
+};
+
+const multiStepHandler = (
+  _ctx: Context,
+  _clientId: string,
+  _authMethod: string,
+  authData: Uint8Array,
+) => {
+  if (authData[0] === 2) {
+    return {
+      reasonCode: ReasonCode.success,
+    };
+  }
+  return {
+    reasonCode: ReasonCode.continueAuthentication,
+    authData: new Uint8Array([12]),
+  };
+};
+
+test("Auth packet with no handler, closes connection", async () => {
+  const { mqttConn } = startMockServer();
+
+  // Connect first
+  await connect5(mqttConn);
+
+  // Send AUTH packet
+  await auth(mqttConn);
+  await mqttConn.next();
+
+  assert.strictEqual(mqttConn.isClosed, true);
+});
+
+test("Auth packet without authenticationMethod or authenticationData closes connection", async () => {
+  const { mqttConn } = startMockServer({
+    handlers: { processAuth: successHandler },
+  });
+
+  await connect5(mqttConn);
+  // Missing authenticationMethod and authenticationData
+  await auth(mqttConn, { noMethod: true, noData: true });
+  await mqttConn.next();
+  assert.strictEqual(mqttConn.isClosed, true);
+});
+
+test("Auth packet triggers continueAuthentication response", async () => {
+  const { mqttConn } = startMockServer({
+    handlers: {
+      processAuth(_ctx, _clientId, authMethod, authData) {
+        assert.strictEqual(authMethod, "SCRAM-SHA-256");
+        assert.deepStrictEqual(authData, new Uint8Array([1, 2, 3]));
+        return {
+          reasonCode: ReasonCode.continueAuthentication,
+          authData: new Uint8Array([4, 5, 6]),
+          reasonString: "Continue auth",
+        };
+      },
+    },
+  });
+
+  await connect5(mqttConn);
+  const response = await auth(mqttConn, {
+    authMethod: "SCRAM-SHA-256",
+    authData: new Uint8Array([1, 2, 3]),
+  });
+
+  assert.strictEqual(response?.type, PacketType.auth);
+  assert.strictEqual(response?.reasonCode, ReasonCode.continueAuthentication);
+  assert.strictEqual(
+    response?.properties?.authenticationMethod,
+    "SCRAM-SHA-256",
+  );
+  assert.deepStrictEqual(
+    response?.properties?.authenticationData,
+    new Uint8Array([4, 5, 6]),
+  );
+  assert.strictEqual(mqttConn.isClosed, false);
+});
+
+test("Connect packet completes initial connection with auth data", async () => {
+  const { mqttConn } = startMockServer({
+    handlers: { processAuth: successHandler },
+  });
+
+  await connect5(mqttConn, {
+    clientId: "test",
+    properties: {
+      authenticationMethod: "SCRAM-SHA-256",
+      authenticationData: new Uint8Array([1]),
+    },
+  });
+});
+
+test("Auth packet completes initial connection when in connecting state", async () => {
+  const { mqttConn } = startMockServer({
+    handlers: { processAuth: multiStepHandler },
+  });
+
+  const authResponse = await connect5(mqttConn, {
+    clientId: "test",
+    properties: {
+      authenticationMethod: "SCRAM-SHA-256",
+      authenticationData: new Uint8Array([1]),
+    },
+    checkAck: false,
+  });
+
+  assert.strictEqual(authResponse?.type, PacketType.auth);
+  assert.strictEqual(
+    authResponse?.reasonCode,
+    ReasonCode.continueAuthentication,
+  );
+  assert.deepEqual(
+    authResponse?.properties?.authenticationData,
+    new Uint8Array([12]),
+  );
+
+  const connack = await auth(mqttConn, {
+    authMethod: "SCRAM-SHA-256",
+    authData: new Uint8Array([2]),
+  });
+
+  assert.strictEqual(connack?.type, PacketType.connack);
+  assert.strictEqual(
+    connack?.reasonCode,
+    ReasonCode.success,
+  );
+
+  // check if connection is active by sending a qos1 and verifying puback
+  await publish5(mqttConn, "test/topic", 1);
+});
+
+test("Auth packet re-authentication success transitions state back to connected", async () => {
+  const { mqttConn } = startMockServer({
+    handlers: { processAuth: successHandler },
+  });
+
+  await connect5(mqttConn);
+  const response = await auth(mqttConn);
+  assert.strictEqual(response?.type, PacketType.auth);
+  assert.strictEqual(response?.reasonCode, ReasonCode.success);
+  assert.deepStrictEqual(
+    response?.properties?.authenticationData,
+    new Uint8Array([9, 9]),
+  );
+
+  // check if connection is active by sending a qos1 and verifying puback
+  await publish5(mqttConn, "test/topic", 1);
+});
+
+test("Auth packet re-authentication failure sends DISCONNECT and closes connection", async () => {
+  const { mqttConn } = startMockServer({
+    handlers: {
+      processAuth() {
+        return {
+          reasonCode: ReasonCode.notAuthorized,
+          reasonString: "Re-auth failed",
+        };
+      },
+    },
+  });
+
+  await connect5(mqttConn);
+  const response = await auth(mqttConn);
+  assert.strictEqual(response?.type, PacketType.disconnect);
+  assert.strictEqual(response?.reasonCode, ReasonCode.notAuthorized);
+  await mqttConn.next();
+  assert.strictEqual(mqttConn.isClosed, true);
+});
+
+test("Packets are blocked/rejected while state is authenticating", async () => {
+  const { mqttConn } = startMockServer({
+    handlers: { processAuth: multiStepHandler },
+  });
+
+  await connect5(mqttConn);
+
+  // subscribeso we can unsubscribe later
+  await subscribe5(mqttConn, [{
+    topicFilter: "test/topicToUnsubscribe",
+    qos: 0,
+  }]);
+  // start reauthentication
+  await auth(mqttConn);
+  // Publish attempt must be rejected with notAuthorized
+  const pubResp = await publish5(mqttConn, "test/topic", 1);
+  assert.strictEqual(pubResp?.type, PacketType.puback);
+  assert.strictEqual(pubResp?.reasonCode, ReasonCode.notAuthorized);
+
+  // Subscribe attempt must be rejected with notAuthorized
+  const subResp = await subscribe5(mqttConn, [{
+    topicFilter: "test/topic",
+    qos: 0,
+  }], { checkAcks: false });
+  assert.strictEqual(subResp?.type, PacketType.suback);
+  assert.strictEqual(subResp?.reasonCodes[0], ReasonCode.notAuthorized);
+
+  // Unsubscribe attempt must return noSubscriptionExisted
+  const unsubResp = await unsubscribe5(mqttConn, ["test/topicToUnsubscribe"]);
+
+  assert.strictEqual(unsubResp?.type, PacketType.unsuback);
+  assert.strictEqual(unsubResp?.protocolLevel, 5);
+  assert.strictEqual(
+    unsubResp?.reasonCodes[0],
+    ReasonCode.noSubscriptionExisted,
+  );
+});

package/server/handlers/handleAuth.ts

@@ -0,0 +1,88 @@
+import { SessionState } from "../context.ts";
+import type { AuthenticatedResult, Context } from "../context.ts";
+import { PacketType, ReasonCode } from "../deps.ts";
+import type { AuthPacket } from "../deps.ts";
+import { completeConnect } from "./completeConnect.ts";
+
+/**
+ * Handle success
+ */
+
+async function handleResult(
+  ctx: Context,
+  authMethod: string,
+  result: AuthenticatedResult,
+) {
+  await ctx.send({
+    type: PacketType.auth,
+    protocolLevel: 5,
+    reasonCode: result.reasonCode,
+    properties: result.authData
+      ? {
+        authenticationMethod: authMethod,
+        authenticationData: result.authData,
+        reasonString: result.reasonString,
+      }
+      : {},
+  });
+}
+/**
+ * Handle errors
+ */
+
+async function handleError(ctx: Context, result?: AuthenticatedResult) {
+  await ctx.send({
+    type: PacketType.disconnect,
+    protocolLevel: 5,
+    reasonCode: result?.reasonCode ?? ReasonCode.badAuthenticationMethod,
+    properties: {
+      reasonString: result?.reasonString ?? "Bad authentication mode",
+    },
+  });
+  await ctx.close(false);
+}
+
+/**
+ * Handles v5 Auth packet
+ * @param ctx - The connection context containing send method
+ * @returns Promise that resolves
+ */
+
+export async function handleAuth(
+  ctx: Context,
+  authPacket: AuthPacket,
+): Promise<void> {
+  if (ctx.handlers.processAuth) {
+    const authMethod = authPacket.properties?.authenticationMethod;
+    const authData = authPacket.properties?.authenticationData;
+    if (!(authMethod && authData)) {
+      return await ctx.close(false);
+    }
+
+    if (ctx.state === SessionState.connected) {
+      ctx.state = SessionState.authenticating;
+    }
+    const result = await ctx.handlers.processAuth(
+      ctx,
+      ctx.clientId!,
+      authMethod,
+      authData,
+    );
+    // we need more data
+    if (result.reasonCode === ReasonCode.continueAuthentication) {
+      return handleResult(ctx, authMethod, result);
+    }
+    // we are done but were still connecting
+    if (ctx.state === SessionState.connecting) {
+      await completeConnect(ctx, 5, result.reasonCode, result.reasonString);
+      return;
+    }
+    // we are done but were reauthentication in flight
+    if (result.reasonCode === ReasonCode.success) {
+      ctx.state = SessionState.connected;
+      return handleResult(ctx, authMethod, result);
+    }
+    return handleError(ctx, result);
+  }
+  return handleError(ctx);
+}