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,17 @@ 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 +754,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

@@ -433,6 +433,7 @@ export interface MqttClientEventCallbacks {
 	reconnect: VoidCallback
 	offline: VoidCallback
 	outgoingEmpty: VoidCallback
+	reauth: OnPacketCallback
 }
 
 /**
@@ -521,6 +522,8 @@ export default class MqttClient extends TypedEventEmitter<MqttClientEventCallbac
 
 	private connackPacket: IConnackPacket
 
+	private _reauthCallback: PacketCallback
+
 	public static defaultId() {
 		return `mqttjs_${Math.random().toString(16).substr(2, 8)}`
 	}
@@ -1678,6 +1681,105 @@ 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 {
+		let error: Error | null = null
+
+		if (this._reauthCallback) {
+			this._handleReauthCompleted(
+				new Error(
+					'reauthenticate: interrupted by new reauthentication request',
+				),
+			)
+		}
+
+		if (this.options.protocolVersion !== 5) {
+			error = new Error(
+				'reauthenticate: this feature works only with mqtt-v5',
+			)
+		} else if (!this.connected) {
+			error = new Error('reauthenticate: client is not connected')
+		} else if (!reauthOptions.authenticationData) {
+			error = new Error('reauthenticate: authenticationData is required')
+		}
+
+		const method = this.options.properties?.authenticationMethod
+
+		if (!error && !method) {
+			error = new Error(
+				'reauthenticate: authenticationMethod is required from initial CONNECT',
+			)
+		}
+
+		if (error) {
+			if (callback) {
+				callback(error)
+			} else {
+				this.emit('error', error)
+			}
+			return this
+		}
+
+		if (
+			reauthOptions.authenticationData &&
+			Buffer.isBuffer(this.options.properties.authenticationData) &&
+			reauthOptions.authenticationData.equals(
+				this.options.properties.authenticationData,
+			)
+		) {
+			this.log(
+				'reauthenticate: sending same authenticationData as initial connection',
+			)
+		}
+
+		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
+	}
+
+	/**
+	 * _handleReauthCompleted
+	 * 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
+	 */
+	public _handleReauthCompleted(err: Error | null, packet?: IAuthPacket) {
+		if (this._reauthCallback) {
+			const cb = this._reauthCallback
+			this._reauthCallback = null
+			cb(err, packet)
+		}
+
+		if (!err && packet) {
+			this.emit('reauth', packet)
+		}
+	}
+
 	/**
 	 * PRIVATE METHODS
 	 * =====================
@@ -1864,6 +1966,10 @@ export default class MqttClient extends TypedEventEmitter<MqttClientEventCallbac
 			})
 		}
 
+		if (this._reauthCallback) {
+			this._handleReauthCompleted(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,26 +19,40 @@ const handleAuth: PacketHandler = (
 		return
 	}
 
+	if (rc === 0) {
+		client._handleReauthCompleted(null, packet)
+		return
+	}
+
 	client.handleAuth(
 		packet,
 		(err: ErrorWithReasonCode, packet2: IAuthPacket) => {
 			if (err) {
-				client.emit('error', err)
+				if (client.connected) client._handleReauthCompleted(err, packet)
+				else client.emit('error', err)
 				return
 			}
 
 			if (rc === 24) {
 				client.reconnecting = false
 				client['_sendPacket'](packet2)
 			} else {
+				console.log('### DEBUGGING rc: ', rc, ' ####')
 				const error = new ErrorWithReasonCode(
 					`Connection refused: ${ReasonCodes[rc]}`,
 					rc,
 				)
-				client.emit('error', error)
+				if (client.connected) {
+					client._handleReauthCompleted(error, packet)
+				} else {
+					client.emit('error', error)
+				}
 			}
 		},
 	)
+	console.log(
+		'DEBUG 3: Finished calling handleAuth (but did the callback run?)',
+	)
 }
 
 export default handleAuth