@seriousme/opifex 1.11.3 → 2.0.3

package/client/context.ts

@@ -9,7 +9,7 @@ import {
 import type {
   AnyPacket,
   ConnectPacket,
-  MemoryStore,
+  IStore,
   PacketId,
   ProtocolLevel,
   PublishPacket,
@@ -17,6 +17,8 @@ import type {
   SockConn,
   SubscribePacket,
   TAuthenticationResult,
+  TPacketType,
+  TReasonCode,
   UnsubscribePacket,
 } from "./deps.ts";
 
@@ -26,6 +28,24 @@ import { ConnectionState } from "./ConnectionState.ts";
 import type { Client } from "./client.ts";
 import { assert } from "../utils/assert.ts";
 
+/**
+ * packets not allowed during authentication
+ */
+function blockedDuringAuthentication(pktType: TPacketType) {
+  return (
+    pktType === PacketType.publish ||
+    pktType === PacketType.subscribe ||
+    pktType === PacketType.unsubscribe
+  );
+}
+
+/** Possible results from authHandler */
+export type AuthenticatedResult = {
+  reasonCode: TReasonCode;
+  reasonString?: string;
+  authData?: Uint8Array;
+};
+
 export class Context {
   mqttConn?: MqttConn;
   #connectionState: TConnectionState;
@@ -35,10 +55,10 @@ export class Context {
   unresolvedPublish: Map<PacketId, Deferred<void>>;
   unresolvedSubscribe: Map<PacketId, Deferred<ReturnCodes>>;
   unresolvedUnSubscribe: Map<PacketId, Deferred<void>>;
-  store: MemoryStore;
+  store: IStore;
   #client: Client;
 
-  constructor(store: MemoryStore, client: Client) {
+  constructor(store: IStore, client: Client) {
     this.#client = client;
     this.store = store;
     this.#connectionState = ConnectionState.offline;
@@ -64,6 +84,25 @@ export class Context {
     }
   }
 
+  authHandler(
+    _ctx: Context,
+    authMethod: string,
+    authData: Uint8Array,
+  ): AuthenticatedResult | Promise<AuthenticatedResult> {
+    return this.#client.onAuth(authMethod, authData);
+  }
+
+  setPingTimer(interval: number) {
+    if (this.pingTimer) {
+      this.pingTimer.clear();
+    }
+    this.pingTimer = new Timer(
+      this.sendPing.bind(this),
+      interval * 1000,
+      true,
+    );
+  }
+
   async connect(packet: ConnectPacket) {
     this.connectionState = ConnectionState.connecting;
     if (packet.protocolLevel === MQTTLevel.unknown) {
@@ -73,16 +112,15 @@ export class Context {
     await this.mqttConn?.send(packet);
     const keepAlive = packet.keepAlive || 0;
     if (keepAlive > 0) {
-      this.pingTimer = new Timer(
-        this.sendPing.bind(this),
-        keepAlive * 1000,
-        true,
-      );
+      this.setPingTimer(keepAlive);
     }
   }
 
   async disconnect() {
-    if (this.connectionState !== ConnectionState.connected) {
+    if (
+      this.connectionState !== ConnectionState.connected &&
+      this.connectionState !== ConnectionState.authenticating
+    ) {
       throw "Not connected";
     }
     if (this.mqttConn) {
@@ -97,14 +135,29 @@ export class Context {
   }
 
   async send(packet: AnyPacket) {
-    logger.debug({ send: packet });
-    if (
-      this.connectionState === ConnectionState.connected &&
-      !this.mqttConn?.isClosed
-    ) {
-      await this.mqttConn?.send(packet);
-      this.pingTimer?.reset();
-      return;
+    logger.debug("client.ctx.send", this.#connectionState, { packet });
+    if (!this.mqttConn?.isClosed) {
+      if (this.connectionState === ConnectionState.connected) {
+        await this.mqttConn?.send(packet);
+        this.pingTimer?.reset();
+        return;
+      }
+      if (
+        this.connectionState === ConnectionState.connecting &&
+        packet.type === PacketType.auth
+      ) {
+        await this.mqttConn?.send(packet);
+        this.pingTimer?.reset();
+        return;
+      }
+      if (
+        this.connectionState === ConnectionState.authenticating &&
+        !blockedDuringAuthentication(packet.type)
+      ) {
+        await this.mqttConn?.send(packet);
+        this.pingTimer?.reset();
+        return;
+      }
     }
     logger.debug("not connected");
     this.pingTimer?.clear();
@@ -122,6 +175,7 @@ export class Context {
     connectPacket: ConnectPacket,
   ): Promise<boolean> {
     this.mqttConn = new MqttConn({ conn });
+    this.mqttConn.codecOpts.protocolLevel = connectPacket.protocolLevel;
     try {
       logger.debug("Send connect packet", connectPacket);
       await this.connect(connectPacket);
@@ -136,7 +190,7 @@ export class Context {
         `Caught something that is not an instance of Error: ${err}`,
       );
       queueMicrotask(() => this.#client.onError(err));
-      logger.debug(`error ${err}`);
+      logger.debug("error", err);
       if (!this.mqttConn.isClosed) {
         this.mqttConn.close();
       }
@@ -164,7 +218,7 @@ export class Context {
       await this.send(packet);
       return;
     }
-    packet.id = this.store.nextId();
+    packet.id = await this.store.nextId();
     this.store.pendingOutgoing.set(packet.id, packet);
     const deferred = new Deferred<void>();
     this.unresolvedPublish.set(packet.id, deferred);
@@ -173,7 +227,7 @@ export class Context {
   }
 
   async subscribe(packet: SubscribePacket): Promise<ReturnCodes> {
-    packet.id = this.store.nextId();
+    packet.id = await this.store.nextId();
     this.store.pendingOutgoing.set(packet.id, packet);
     const deferred = new Deferred<ReturnCodes>();
     this.unresolvedSubscribe.set(packet.id, deferred);
@@ -182,7 +236,7 @@ export class Context {
   }
 
   async unsubscribe(packet: UnsubscribePacket): Promise<void> {
-    packet.id = this.store.nextId();
+    packet.id = await this.store.nextId();
     this.store.pendingOutgoing.set(packet.id, packet);
     const deferred = new Deferred<void>();
     this.unresolvedUnSubscribe.set(packet.id, deferred);

package/client/deps.ts

@@ -1,5 +1,6 @@
 export type {
   AnyPacket,
+  AuthPacket,
   ConnackPacket,
   ConnectPacket,
   DisconnectPacket,
@@ -18,6 +19,7 @@ export type {
   SubscribePacket,
   TAuthenticationResult,
   Topic,
+  TPacketType,
   TReasonCode,
   UnsubackPacket,
   UnsubscribePacket,
@@ -31,6 +33,7 @@ export {
   MQTTLevel,
   PacketNameByType,
   PacketType,
+  ReasonCode,
   ReasonCodeByNumber,
 } from "../mqttPacket/mod.ts";
 
@@ -39,3 +42,4 @@ export type { SockConn } from "../socket/socket.ts";
 export { Timer } from "../timer/timer.ts";
 export { BufferedAsyncIterable, Deferred, logger } from "../utils/mod.ts";
 export { MemoryStore } from "./store/memoryStore.ts";
+export type { IStore } from "./store/store.ts";

package/client/handlers/handleAuth.test.ts

@@ -0,0 +1,193 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { handleAuth } from "./handleAuth.ts";
+import { ConnectionState } from "../ConnectionState.ts";
+import { PacketType, ReasonCode } from "../deps.ts";
+import type { AuthPacket } from "../deps.ts";
+import type { AuthenticatedResult } from "../context.ts";
+import { Deferred } from "../../utils/mod.ts";
+
+function createMockContext() {
+  const sentPackets: unknown[] = [];
+  return {
+    connectionState: ConnectionState.connecting as string,
+    pingTimer: { clear: () => {} },
+    unresolvedConnect: new Deferred<number>(),
+    authHandler: (
+      _ctx: unknown,
+      _authMethod: string,
+      _authData: Uint8Array,
+    ): Promise<AuthenticatedResult> => {
+      return Promise.resolve({
+        reasonCode: ReasonCode.continueAuthentication,
+        authData: new Uint8Array([1, 2, 3]),
+      });
+    },
+    send: (packet: unknown) => {
+      sentPackets.push(packet);
+    },
+    sentPackets,
+  };
+}
+
+test("handleAuth sets connected state on ReasonCode.success", async () => {
+  const ctx = createMockContext();
+  const packet: AuthPacket = {
+    type: PacketType.auth,
+    protocolLevel: 5 as const,
+    reasonCode: ReasonCode.success,
+  };
+
+  await handleAuth(ctx as never, packet);
+
+  assert.deepStrictEqual(
+    ctx.connectionState,
+    ConnectionState.connected,
+    "Should set connection state to connected when reasonCode is success",
+  );
+});
+
+test("handleAuth handles authentication failure when connecting", async () => {
+  const ctx = createMockContext();
+  ctx.connectionState = ConnectionState.connecting;
+
+  const packet: AuthPacket = {
+    type: PacketType.auth,
+    protocolLevel: 5 as const,
+    reasonCode: ReasonCode.badAuthenticationMethod,
+  };
+
+  await handleAuth(ctx as never, packet);
+
+  assert.deepStrictEqual(
+    ctx.connectionState,
+    ConnectionState.disconnecting,
+    "Should transition state to disconnecting on failure during connect",
+  );
+
+  await assert.rejects(
+    ctx.unresolvedConnect.promise,
+    /Connect failed/,
+    "Should reject unresolvedConnect with connect failed error",
+  );
+});
+
+test("handleAuth throws error on authentication failure when connected", async () => {
+  const ctx = createMockContext();
+  ctx.connectionState = ConnectionState.connected;
+
+  const packet: AuthPacket = {
+    type: PacketType.auth,
+    protocolLevel: 5 as const,
+    reasonCode: ReasonCode.badAuthenticationMethod,
+  };
+
+  await assert.rejects(
+    async () => {
+      await handleAuth(ctx as never, packet);
+    },
+    Error,
+    "Should throw an error if reasonCode indicates failure after already connected",
+  );
+});
+
+test("handleAuth throws error if authMethod or authData is missing", async () => {
+  const ctx = createMockContext();
+  const packet: AuthPacket = {
+    type: PacketType.auth,
+    protocolLevel: 5 as const,
+    reasonCode: ReasonCode.continueAuthentication,
+    properties: {
+      authenticationMethod: "SCRAM-SHA-256",
+      // authenticationData missing
+    },
+  };
+
+  await assert.rejects(
+    async () => {
+      await handleAuth(ctx as never, packet);
+    },
+    /Auth method and\/or Auth data missing/,
+    "Should throw when missing required auth properties",
+  );
+});
+
+test("handleAuth transitions state and sends response packet on continueAuthentication success", async () => {
+  const ctx = createMockContext();
+  ctx.connectionState = ConnectionState.connected;
+
+  ctx.authHandler = () =>
+    Promise.resolve({
+      reasonCode: ReasonCode.continueAuthentication,
+      authData: new Uint8Array([4, 5, 6]),
+      reasonString: "Continue",
+    });
+
+  const packet: AuthPacket = {
+    type: PacketType.auth,
+    protocolLevel: 5 as const,
+    reasonCode: ReasonCode.continueAuthentication,
+    properties: {
+      authenticationMethod: "SCRAM-SHA-256",
+      authenticationData: new Uint8Array([1, 2, 3]),
+    },
+  };
+
+  await handleAuth(ctx as never, packet);
+
+  assert.deepStrictEqual(
+    ctx.connectionState,
+    ConnectionState.authenticating,
+    "Should transition connection state to authenticating",
+  );
+  assert.deepStrictEqual(
+    ctx.sentPackets.length,
+    1,
+    "Should send a response auth packet",
+  );
+  assert.deepStrictEqual(ctx.sentPackets[0], {
+    type: PacketType.auth,
+    protocolLevel: 5,
+    reasonCode: ReasonCode.continueAuthentication,
+    properties: {
+      authenticationMethod: "SCRAM-SHA-256",
+      authenticationData: new Uint8Array([4, 5, 6]),
+      reasonString: "Continue",
+    },
+  });
+});
+
+test("handleAuth handles failure result from authHandler", async () => {
+  const ctx = createMockContext();
+  ctx.connectionState = ConnectionState.connecting;
+
+  ctx.authHandler = () =>
+    Promise.resolve({
+      reasonCode: ReasonCode.notAuthorized,
+      reasonString: "Not authorized to proceed",
+    });
+
+  const packet: AuthPacket = {
+    type: PacketType.auth,
+    protocolLevel: 5 as const,
+    reasonCode: ReasonCode.continueAuthentication,
+    properties: {
+      authenticationMethod: "SCRAM-SHA-256",
+      authenticationData: new Uint8Array([1, 2, 3]),
+    },
+  };
+
+  await handleAuth(ctx as never, packet);
+
+  assert.deepStrictEqual(
+    ctx.connectionState,
+    ConnectionState.disconnecting,
+    "Should set state to disconnecting on authHandler failure",
+  );
+
+  await assert.rejects(
+    ctx.unresolvedConnect.promise,
+    /Connect failed: Not authorized to proceed/,
+    "Should reject unresolvedConnect with the reasonString provided by authHandler",
+  );
+});

package/client/handlers/handleAuth.ts

@@ -0,0 +1,89 @@
+import type { AuthenticatedResult, Context } from "../context.ts";
+import { ConnectionState } from "../ConnectionState.ts";
+import { PacketType, ReasonCode, ReasonCodeByNumber } from "../deps.ts";
+import type { AuthPacket } from "../deps.ts";
+
+/**
+ * Handle error
+ */
+
+function handleError(ctx: Context, errMsg: string) {
+  if (ctx.connectionState === ConnectionState.connecting) {
+    const err = new Error(
+      `Connect failed: ${errMsg}`,
+    );
+    ctx.connectionState = ConnectionState.disconnecting;
+    ctx.pingTimer?.clear();
+    ctx.unresolvedConnect?.reject(err);
+    return;
+  }
+  throw new Error(errMsg);
+}
+
+/**
+ * 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,
+      }
+      : {},
+  });
+}
+
+/**
+ * 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> {
+  const reasonCode = authPacket.reasonCode;
+  if (reasonCode === ReasonCode.success) {
+    // we are connected again
+    ctx.connectionState = ConnectionState.connected;
+    return;
+  }
+
+  if (reasonCode !== ReasonCode.continueAuthentication) {
+    // something went wrong
+    handleError(ctx, ReasonCodeByNumber[reasonCode]);
+    return;
+  }
+
+  // we need to send something back
+  if (ctx.connectionState === ConnectionState.connected) {
+    // pauze auther activities
+    ctx.connectionState = ConnectionState.authenticating;
+  }
+
+  const authMethod = authPacket.properties?.authenticationMethod;
+  const authData = authPacket.properties?.authenticationData;
+  if (!(authMethod && authData)) {
+    throw new Error("Auth method and/or Auth data missing");
+  }
+  const result = await ctx.authHandler(
+    ctx,
+    authMethod,
+    authData,
+  );
+  if (result.reasonCode === ReasonCode.continueAuthentication) {
+    return handleResult(ctx, authMethod, result);
+  }
+  return handleError(ctx, result.reasonString || "Error during authentication");
+}

package/client/handlers/handleConnack.test.ts

@@ -0,0 +1,173 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { handleConnack } from "./handleConnack.ts";
+import { ConnectionState } from "../ConnectionState.ts";
+import { AuthenticationResult, MQTTLevel } from "../deps.ts";
+import type { ConnackPacket } from "../deps.ts";
+import { Deferred } from "../../utils/mod.ts";
+
+function createMockContext() {
+  const sentPackets: unknown[] = [];
+  return {
+    connectionState: ConnectionState.connecting as string,
+    protocolLevel: 4 as const,
+    mqttConn: { codecOpts: { protocolLevel: MQTTLevel.unknown } },
+    pingTimer: { reset: () => {}, clear: () => {} },
+    unresolvedConnect: new Deferred<number>(),
+    store: {
+      pendingOutgoing: new Map(),
+      pendingIncoming: new Map(),
+      pendingAckOutgoing: new Map(),
+      async *pendingOutgoingPackets() {},
+    },
+    send: (packet: unknown) => {
+      sentPackets.push(packet);
+    },
+    sentPackets,
+  };
+}
+
+test("handleConnack sets connected state on success", async () => {
+  const ctx = createMockContext();
+  const packet = {
+    type: 2,
+    protocolLevel: 4 as const,
+    sessionPresent: false,
+    returnCode: AuthenticationResult.ok,
+  } as ConnackPacket;
+
+  await handleConnack(ctx as never, packet);
+
+  assert.deepStrictEqual(
+    ctx.connectionState,
+    ConnectionState.connected,
+    "Should be connected after successful CONNACK",
+  );
+});
+
+test("handleConnack resolves connect promise on success", async () => {
+  const ctx = createMockContext();
+  const packet = {
+    type: 2,
+    protocolLevel: 4 as const,
+    sessionPresent: false,
+    returnCode: AuthenticationResult.ok,
+  } as ConnackPacket;
+
+  await handleConnack(ctx as never, packet);
+
+  const result = await ctx.unresolvedConnect.promise;
+  assert.deepStrictEqual(result, 0, "Should resolve with success code 0");
+});
+
+test("handleConnack rejects on bad username/password", async () => {
+  const ctx = createMockContext();
+  const packet = {
+    type: 2,
+    protocolLevel: 4 as const,
+    sessionPresent: false,
+    returnCode: AuthenticationResult.badUsernameOrPassword,
+  } as ConnackPacket;
+
+  await handleConnack(ctx as never, packet);
+
+  assert.deepStrictEqual(
+    ctx.connectionState,
+    ConnectionState.disconnecting,
+    "Should be disconnecting on auth failure",
+  );
+
+  await assert.rejects(
+    ctx.unresolvedConnect.promise,
+    /Connect failed/,
+    "Should reject with connect failed error",
+  );
+});
+
+test("handleConnack rejects on not authorized", async () => {
+  const ctx = createMockContext();
+  const packet = {
+    type: 2,
+    protocolLevel: 4 as const,
+    sessionPresent: false,
+    returnCode: AuthenticationResult.notAuthorized,
+  } as ConnackPacket;
+
+  await handleConnack(ctx as never, packet);
+
+  assert.deepStrictEqual(
+    ctx.connectionState,
+    ConnectionState.disconnecting,
+  );
+
+  await assert.rejects(
+    ctx.unresolvedConnect.promise,
+    /Connect failed/,
+  );
+});
+
+test("handleConnack handles MQTT v5 reason codes", async () => {
+  const ctx = createMockContext();
+  (ctx as { protocolLevel: number }).protocolLevel = 5;
+  const packet = {
+    type: 2,
+    protocolLevel: 5 as const,
+    sessionPresent: false,
+    reasonCode: 0,
+  } as ConnackPacket;
+
+  await handleConnack(ctx as never, packet);
+
+  assert.deepStrictEqual(
+    ctx.connectionState,
+    ConnectionState.connected,
+    "Should be connected with v5 success reason code",
+  );
+});
+
+test("handleConnack resets ping timer on success", async () => {
+  let timerReset = false;
+  const ctx = createMockContext();
+  ctx.pingTimer = {
+    reset: () => {
+      timerReset = true;
+    },
+    clear: () => {},
+  };
+
+  const packet = {
+    type: 2,
+    protocolLevel: 4 as const,
+    sessionPresent: false,
+    returnCode: AuthenticationResult.ok,
+  } as ConnackPacket;
+
+  await handleConnack(ctx as never, packet);
+
+  assert.deepStrictEqual(timerReset, true, "Ping timer should be reset");
+});
+
+test("handleConnack clears ping timer on failure", async () => {
+  let timerCleared = false;
+  const ctx = createMockContext();
+  ctx.pingTimer = {
+    reset: () => {},
+    clear: () => {
+      timerCleared = true;
+    },
+  };
+
+  const packet = {
+    type: 2,
+    protocolLevel: 4 as const,
+    sessionPresent: false,
+    returnCode: AuthenticationResult.badUsernameOrPassword,
+  } as ConnackPacket;
+
+  await handleConnack(ctx as never, packet);
+  assert.deepStrictEqual(timerCleared, true, "Ping timer should be cleared");
+  await assert.rejects(
+    ctx.unresolvedConnect.promise,
+    /Connect failed/,
+  );
+});

package/client/handlers/handleConnack.ts

@@ -5,20 +5,30 @@ import type { ConnackPacket, TReasonCode } from "../deps.ts";
 
 /**
  * Handles the CONNACK packet received from the MQTT broker
- * @param packet - The CONNACK packet containing the connection acknowledgment
  * @param ctx - The connection context
+ * @param packet - The CONNACK packet containing the connection acknowledgment
  * @returns Promise that resolves when handling is complete
  */
-export async function handleConnack(packet: ConnackPacket, ctx: Context) {
-  const result = packet.protocolLevel === 5
-    ? packet.reasonCode
-    : packet.returnCode;
+export async function handleConnack(ctx: Context, packet: ConnackPacket) {
+  const isVersion5 = packet.protocolLevel === 5;
+  const result = isVersion5 ? packet.reasonCode : packet.returnCode;
   if (result === 0) {
     ctx.connectionState = ConnectionState.connected;
     if (ctx.mqttConn) {
       ctx.mqttConn.codecOpts.protocolLevel = ctx.protocolLevel;
     }
-    ctx.pingTimer?.reset();
+
+    const serverKeepAlive = isVersion5
+      ? packet.properties?.serverKeepAlive
+      : undefined;
+
+    if (serverKeepAlive === 0) {
+      ctx.pingTimer?.clear(); // Server disabled keepalive
+    } else if (serverKeepAlive !== undefined) {
+      ctx.setPingTimer(serverKeepAlive); // Server set a new interval
+    } else {
+      ctx.pingTimer?.reset(); // Default fallback for V4 or V5 without override
+    }
     ctx.unresolvedConnect?.resolve(result);
     // start transmitting packets that were queued before
     for await (const packet of ctx.store.pendingOutgoingPackets()) {