feat(mqtt5): implement re-authentication and handle auth success

README.md

@@ -341,6 +341,7 @@ Also user can manually register topic-alias pair using PUBLISH topic:'some', ta:
 - [`mqtt.Client#endAsync()`](#end-async)
 - [`mqtt.Client#removeOutgoingMessage()`](#removeOutgoingMessage)
 - [`mqtt.Client#reconnect()`](#reconnect)
+- [`mqtt.Client#reauthenticate()`](#client-reauthenticate)
 - [`mqtt.Client#handleMessage()`](#handleMessage)
 - [`mqtt.Client#connected`](#connected)
 - [`mqtt.Client#reconnecting`](#reconnecting)
@@ -599,6 +600,16 @@ and connections
 - `packet` received packet, as defined in
   [mqtt-packet](https://github.com/mcollina/mqtt-packet)
 
+#### Event `'reauth'`
+
+`function (packet) {}`
+
+Emitted when an MQTT 5 re-authentication completes successfully.
+
+- `packet` the AUTH packet received from the broker.
+
+Triggered after calling [`client.reauthenticate()`](#client-reauthenticate).
+
 ---
 
 <a name="client-connect"></a>
@@ -742,6 +753,30 @@ Connect again using the same options as connect()
 
 ---
 
+<a name="client-reauthenticate"></a>
+
+### mqtt.Client#reauthenticate(reauthOptions, [callback])
+
+Start an MQTT 5 re-authentication exchange.
+
+- `reauthOptions`:
+  - `authenticationData` (`Buffer`)
+  - `reasonString` (`string`, optional)
+  - `userProperties` (`object`, optional)
+
+- `callback` - `function (err, packet)`
+  - called when the AUTH exchange completes or fails
+
+Errors:
+- client is not connected
+- MQTT version is not 5
+- `authenticationData` is missing
+- `authenticationMethod` is missing from the initial CONNECT
+
+Emits `'reauth'` on successful completion.
+
+---
+
 <a name="handleMessage"></a>
 
 ### mqtt.Client#handleMessage(packet, callback)

src/lib/client.ts

@@ -27,8 +27,8 @@ import DefaultMessageIdProvider, {
 } from './default-message-id-provider'
 import TopicAliasRecv from './topic-alias-recv'
 import {
+	ErrorWithReasonCode,
 	type DoneCallback,
-	type ErrorWithReasonCode,
 	ErrorWithSubackPacket,
 	type GenericCallback,
 	type IStream,
@@ -433,6 +433,7 @@ export interface MqttClientEventCallbacks {
 	reconnect: VoidCallback
 	offline: VoidCallback
 	outgoingEmpty: VoidCallback
+	reauth: OnPacketCallback
 }
 
 /**
@@ -521,6 +522,9 @@ export default class MqttClient extends TypedEventEmitter<MqttClientEventCallbac
 
 	private connackPacket: IConnackPacket
 
+	/* @type {PacketCallback} - callback receives IAuthPacket */
+	private _reauthCallback: PacketCallback = null
+
 	public static defaultId() {
 		return `mqttjs_${Math.random().toString(16).substr(2, 8)}`
 	}
@@ -1678,6 +1682,91 @@ export default class MqttClient extends TypedEventEmitter<MqttClientEventCallbac
 		return this
 	}
 
+	/**
+	 * reauthenticate - MQTT 5.0 Re-authentication
+	 * @param {Object} reauthOptions - Re-authentication properties
+	 * @param {Buffer} [reauthOptions.authenticationData] - Binary data for auth exchange
+	 * @param {string} [reauthOptions.reasonString] - Human-readable reason for re-auth
+	 * @param {Object} [reauthOptions.userProperties] - Custom user properties
+	 * @param {PacketCallback} [callback] - Fired when the AUTH exchange completes or fails
+	 * @returns {MqttClient} - Returns the client instance
+	 */
+	public reauthenticate(
+		reauthOptions: Pick<
+			NonNullable<IAuthPacket['properties']>,
+			'authenticationData' | 'reasonString' | 'userProperties'
+		>,
+		callback?: PacketCallback,
+	): MqttClient {
+		const fail = (msg: string) => {
+			const err = new Error(`reauthenticate: ${msg}`)
+			if (callback) callback(err)
+			else this.emit('error', err)
+			return this
+		}
+
+		if (this._reauthCallback) {
+			this._handleReauth(
+				new Error(
+					'reauthenticate: interrupted by new reauthentication request',
+				),
+			)
+		}
+
+		if (this.options.protocolVersion !== 5)
+			return fail('this feature works only with mqtt-v5')
+		else if (!this.connected) return fail('client is not connected')
+		else if (!reauthOptions.authenticationData)
+			return fail('authenticationData is required')
+
+		const method = this.options.properties?.authenticationMethod
+
+		if (!method)
+			return fail('authenticationMethod is required from initial CONNECT')
+
+		const authPacket: IAuthPacket = {
+			cmd: 'auth',
+			reasonCode: 0x19, // Re-authentication (MQTT 5.0 Spec)
+			properties: {
+				...reauthOptions,
+				authenticationMethod: method,
+			},
+		}
+
+		this._reauthCallback = callback
+		this._sendPacket(authPacket)
+		return this
+	}
+
+	/**
+	 * _handleReauth
+	 * Internal method to finalize the re-authentication process.
+	 * Clears the pending reauth callback and signals completion via callback or event.
+	 * @param {Error | null} err - The error if the re-authentication failed
+	 * @param {IAuthPacket} [packet] - The AUTH packet received from the broker
+	 * @api private
+	 */
+	private _handleReauth(err: Error | null, packet?: IAuthPacket) {
+		if (!err && packet && packet.reasonCode !== 0) {
+			err = new ErrorWithReasonCode(
+				`Re-auth failed: ${packet.reasonCode}`,
+				packet.reasonCode,
+			)
+		}
+
+		if (this._reauthCallback) {
+			const cb = this._reauthCallback
+			this._reauthCallback = null
+			cb(err, packet)
+		} else if (err) {
+			this.emit('error', err)
+		}
+
+		if (!err && packet) {
+			this.emit('reauth', packet)
+		}
+	}
+
 	/**
 	 * PRIVATE METHODS
 	 * =====================
@@ -1864,6 +1953,10 @@ export default class MqttClient extends TypedEventEmitter<MqttClientEventCallbac
 			})
 		}
 
+		if (this._reauthCallback) {
+			this._handleReauth(new Error('client disconnected'))
+		}
+
 		if (!this.disconnecting && !this.reconnecting) {
 			this.log(
 				'_cleanUp :: client not disconnecting/reconnecting. Clearing and resetting reconnect.',

src/lib/handlers/auth.ts

@@ -19,6 +19,11 @@ const handleAuth: PacketHandler = (
 		return
 	}
 
+	if (client.connected) {
+		client['_handleReauth'](null, packet)
+		return
+	}
+
 	client.handleAuth(
 		packet,
 		(err: ErrorWithReasonCode, packet2: IAuthPacket) => {