node-opcua-client 2.175.6 → 2.177.0

package/dist/reverse/client_reverse_connect.js

@@ -0,0 +1,303 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientReverseConnect = void 0;
+/**
+ * @module node-opcua-client
+ *
+ * Client-side listener for OPC UA Reverse Connect (OPC UA Part 6 §7.1.3).
+ *
+ * A `ClientReverseConnect` owns a single TCP listener (`net.Server`). Servers dial into it and
+ * send a ReverseHello ("RHE"). The listener reads and validates the RHE, then hands the accepted
+ * socket to a waiting `OPCUAClient` (registered through {@link waitForConnection}), matched by
+ * `ServerUri` / `EndpointUrl`. This mirrors the OPC Foundation UA-.NETStandard
+ * `ReverseConnectManager`: one listener, many clients, demultiplexed by server identity.
+ *
+ * Security (Part 2 §6.14): reverse connect lets a Server open a socket to the Client, which is a
+ * denial-of-service surface the normal (client-initiated) connection does not have. The listener
+ * therefore (a) validates every inbound RHE against the caller's {@link ReverseConnectExpectation},
+ * (b) times out sockets that do not send a valid RHE quickly, and (c) caps the number of
+ * inbound sockets it is holding on to. Full OPC UA security (message security mode, certificate
+ * trust) is still enforced afterwards on the SecureChannel.
+ *
+ * Every accepted socket keeps a durable `error`/`close` guard for as long as the listener owns it,
+ * so a peer reset while a socket is being read or held can never surface as an unhandled `'error'`
+ * event (which Node would turn into a process-wide uncaught exception).
+ */
+const node_net_1 = require("node:net");
+const node_opcua_debug_1 = require("node-opcua-debug");
+const node_opcua_transport_1 = require("node-opcua-transport");
+const doDebug = (0, node_opcua_debug_1.checkDebugFlag)("ReverseConnect");
+const debugLog = (0, node_opcua_debug_1.make_debugLog)("ReverseConnect");
+const warningLog = (0, node_opcua_debug_1.make_warningLog)("ReverseConnect");
+// header (8) + 2 × (UInt32 length prefix (4) + up to 4096 bytes). Generous fixed cap for the RHE frame.
+const MAX_RHE_FRAME_LENGTH = 8 + 2 * (4 + node_opcua_transport_1.MAXIMUM_REVERSE_HELLO_FIELD_LENGTH);
+const DEFAULT_ACCEPT_TIMEOUT = 120000; // spec: an application shall time out sockets that do not send RHE (≤ 2 min)
+const DEFAULT_MAX_PENDING_SOCKETS = 20;
+const DEFAULT_MATCH_TIMEOUT = 30000; // how long to hold a validated connection waiting for a matching client
+function matches(expectation, accepted) {
+    if (!expectation) {
+        return true;
+    }
+    if (expectation.serverUri && expectation.serverUri !== accepted.serverUri) {
+        return false;
+    }
+    if (expectation.endpointUrl && expectation.endpointUrl !== accepted.endpointUrl) {
+        return false;
+    }
+    return true;
+}
+class ClientReverseConnect {
+    #connectionUrl;
+    #acceptTimeout;
+    #maxPendingSockets;
+    #matchTimeout;
+    #server;
+    #listeningPort = 0;
+    /** every socket the listener currently owns (being read, or held) — NOT sockets already handed to a transport */
+    #sockets = new Set();
+    #waiters = [];
+    #held = [];
+    constructor(options) {
+        const opts = typeof options === "string" ? { connectionUrl: options } : options;
+        this.#connectionUrl = opts.connectionUrl;
+        this.#acceptTimeout = opts.acceptTimeout ?? DEFAULT_ACCEPT_TIMEOUT;
+        this.#maxPendingSockets = opts.maxPendingSockets ?? DEFAULT_MAX_PENDING_SOCKETS;
+        this.#matchTimeout = opts.matchTimeout ?? DEFAULT_MATCH_TIMEOUT;
+    }
+    get connectionUrl() {
+        return this.#connectionUrl;
+    }
+    get listeningPort() {
+        return this.#listeningPort;
+    }
+    start() {
+        if (this.#server) {
+            return Promise.resolve();
+        }
+        const ep = (0, node_opcua_transport_1.parseEndpointUrl)(this.#connectionUrl);
+        const port = parseInt(ep.port || "4840", 10);
+        const host = ep.hostname;
+        const server = (0, node_net_1.createServer)((socket) => this.#handleIncomingSocket(socket));
+        this.#server = server;
+        // Permanent server-level error handler: net.Server can emit "error" AFTER a successful
+        // listen() (e.g. EMFILE/ENFILE on accept). Without a listener Node throws an uncaught
+        // exception and crashes the process, so keep one attached for the server's whole life.
+        const onServerError = (err) => {
+            // c8 ignore next
+            warningLog(`ClientReverseConnect server error: ${err.message}`);
+        };
+        server.on("error", onServerError);
+        return new Promise((resolve, reject) => {
+            const onListenError = (err) => {
+                server.removeListener("error", onServerError);
+                this.#server = undefined;
+                reject(err);
+            };
+            server.once("error", onListenError);
+            server.listen(port, host, () => {
+                server.removeListener("error", onListenError);
+                const addr = server.address();
+                this.#listeningPort = addr && typeof addr === "object" ? addr.port : port;
+                // c8 ignore next
+                doDebug && debugLog(`ClientReverseConnect listening on ${host}:${this.#listeningPort}`);
+                resolve();
+            });
+        });
+    }
+    stop() {
+        // reject any pending waiters
+        const waiters = this.#waiters;
+        this.#waiters = [];
+        for (const w of waiters) {
+            w.callback(new Error("ClientReverseConnect has been stopped"));
+        }
+        this.#held = [];
+        // destroy every socket the listener still owns (being read or held). Their durable
+        // error/close guards call forget(), which is a no-op once we clear the set below, so no
+        // dangling entries remain. This also unblocks server.close(), which otherwise waits for
+        // all live connections to end.
+        const sockets = [...this.#sockets];
+        this.#sockets.clear();
+        for (const socket of sockets) {
+            socket.destroy();
+        }
+        const server = this.#server;
+        this.#server = undefined;
+        if (!server) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => server.close(() => resolve()));
+    }
+    /**
+     * Register interest in the next reverse connection matching `expectation`.
+     * The callback fires once with an accepted, RHE-validated connection (or an error).
+     */
+    waitForConnection(expectation, callback) {
+        // a validated connection may already be waiting
+        for (let i = 0; i < this.#held.length; i++) {
+            const h = this.#held[i];
+            if (matches(expectation, h.accepted)) {
+                this.#held.splice(i, 1);
+                h.handOff();
+                callback(null, h.accepted);
+                return { cancel: () => undefined };
+            }
+        }
+        const waiter = { expectation, callback };
+        this.#waiters.push(waiter);
+        return {
+            cancel: () => {
+                const idx = this.#waiters.indexOf(waiter);
+                if (idx >= 0) {
+                    this.#waiters.splice(idx, 1);
+                }
+            }
+        };
+    }
+    #handleIncomingSocket(socket) {
+        // Track the socket and attach durable error/close guards FIRST, before any rejection path,
+        // so the socket is never without an "error" listener (an unhandled "error" would crash the
+        // whole process).
+        this.#sockets.add(socket);
+        let handedOff = false;
+        let removed = false;
+        let timer;
+        let buffer = Buffer.alloc(0);
+        const forget = () => {
+            if (removed) {
+                return;
+            }
+            removed = true;
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            this.#sockets.delete(socket);
+            const hi = this.#held.findIndex((h) => h.accepted.socket === socket);
+            if (hi >= 0) {
+                this.#held.splice(hi, 1);
+            }
+        };
+        // durable guards: kept for the socket's whole life in the listener. After hand-off they
+        // become no-ops (the adopting transport installs its own handlers), but stay attached so
+        // there is never a window with zero "error" listeners.
+        const onError = () => {
+            if (handedOff || removed) {
+                return;
+            }
+            forget();
+            socket.destroy();
+        };
+        const onClose = () => {
+            if (handedOff) {
+                return;
+            }
+            forget();
+        };
+        socket.on("error", onError);
+        socket.on("close", onClose);
+        // DoS guard: bound the number of sockets the listener holds (being read + held).
+        if (this.#sockets.size > this.#maxPendingSockets) {
+            warningLog("ClientReverseConnect: too many pending reverse connections, rejecting");
+            this.#rejectSocket(socket, forget, node_opcua_transport_1.StatusCodes2.BadTcpServerTooBusy, "too many pending reverse connections");
+            return;
+        }
+        socket.setNoDelay(true);
+        timer = setTimeout(() => {
+            this.#rejectSocket(socket, forget, node_opcua_transport_1.StatusCodes2.BadTimeout, "no ReverseHello received in time");
+        }, this.#acceptTimeout);
+        timer.unref?.();
+        const onData = (chunk) => {
+            if (removed || handedOff) {
+                return;
+            }
+            buffer = buffer.length === 0 ? chunk : Buffer.concat([buffer, chunk]);
+            if (buffer.length < 8) {
+                return;
+            }
+            const declaredLength = (0, node_opcua_transport_1.readRawMessageHeader)(buffer).length;
+            if (declaredLength > MAX_RHE_FRAME_LENGTH) {
+                socket.removeListener("data", onData);
+                this.#rejectSocket(socket, forget, node_opcua_transport_1.StatusCodes2.BadTcpMessageTooLarge, "ReverseHello message too large");
+                return;
+            }
+            if (buffer.length < declaredLength) {
+                return; // wait for the rest of the frame
+            }
+            const frame = buffer.subarray(0, declaredLength);
+            const leftover = buffer.subarray(declaredLength);
+            // stop reading the RHE and the accept timer; keep the error/close guards attached.
+            socket.removeListener("data", onData);
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            // pause before handing the socket over, then push back any bytes read past the RHE frame
+            socket.pause();
+            if (leftover.length > 0) {
+                socket.unshift(leftover);
+            }
+            let serverUri = "";
+            let endpointUrl = "";
+            try {
+                const rhe = (0, node_opcua_transport_1.decodeReverseHello)(frame);
+                serverUri = rhe.serverUri || "";
+                endpointUrl = rhe.endpointUrl || "";
+            }
+            catch (err) {
+                const statusCode = err.statusCode || node_opcua_transport_1.StatusCodes2.BadTcpEndpointUrlInvalid;
+                this.#rejectSocket(socket, forget, statusCode, err instanceof Error ? err.message : "invalid ReverseHello");
+                return;
+            }
+            const accepted = { socket, serverUri, endpointUrl };
+            const handOff = () => {
+                handedOff = true;
+                forget(); // release listener ownership; durable guards remain as no-ops
+            };
+            // immediate match?
+            for (let i = 0; i < this.#waiters.length; i++) {
+                if (matches(this.#waiters[i].expectation, accepted)) {
+                    const [waiter] = this.#waiters.splice(i, 1);
+                    handOff();
+                    waiter.callback(null, accepted);
+                    return;
+                }
+            }
+            // no waiter yet: hold the validated connection briefly in case a client registers imminently.
+            // c8 ignore next
+            doDebug && debugLog(`reverse connection from ${serverUri} held (no matching client yet)`);
+            timer = setTimeout(() => {
+                timer = undefined;
+                this.#rejectSocket(socket, forget, node_opcua_transport_1.StatusCodes2.BadTcpServerTooBusy, "no client is waiting for this reverse connection");
+            }, this.#matchTimeout);
+            timer.unref?.();
+            this.#held.push({ accepted, handOff });
+        };
+        socket.on("data", onData);
+    }
+    #rejectSocket(socket, forget, statusCode, reason) {
+        forget();
+        // destroy only AFTER the ERR has been flushed to the kernel, otherwise an immediate
+        // destroy() would discard the buffered write and the peer would never see the reason.
+        // The socket's durable "error" guard is still attached, so a failed write cannot crash.
+        let destroyed = false;
+        const destroyOnce = () => {
+            if (destroyed) {
+                return;
+            }
+            destroyed = true;
+            socket.destroy();
+        };
+        try {
+            const errorMessage = new node_opcua_transport_1.TCPErrorMessage({ statusCode, reason });
+            socket.write((0, node_opcua_transport_1.packTcpMessage)("ERR", errorMessage), () => destroyOnce());
+            // safety net in case the write callback never fires (e.g. socket already broken)
+            setTimeout(destroyOnce, 1000).unref?.();
+        }
+        catch {
+            destroyOnce();
+        }
+    }
+}
+exports.ClientReverseConnect = ClientReverseConnect;
+//# sourceMappingURL=client_reverse_connect.js.map

package/dist/reverse/client_reverse_connect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client_reverse_connect.js","sourceRoot":"","sources":["../../source/reverse/client_reverse_connect.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "node-opcua-client",
-    "version": "2.175.6",
+    "version": "2.177.0",
     "description": "pure nodejs OPCUA SDK - module client",
     "scripts": {
         "clean": "npx rimraf -g node_modules dist *.tsbuildinfo certificates",
@@ -16,54 +16,54 @@
     "dependencies": {
         "@ster5/global-mutex": "^3.3.0",
         "chalk": "4.1.2",
-        "node-opcua-alarm-condition": "2.175.6",
+        "node-opcua-alarm-condition": "2.177.0",
         "node-opcua-assert": "2.175.6",
-        "node-opcua-basic-types": "2.175.6",
-        "node-opcua-buffer-utils": "2.175.6",
-        "node-opcua-certificate-manager": "2.175.6",
-        "node-opcua-client-dynamic-extension-object": "2.175.6",
-        "node-opcua-common": "2.175.6",
-        "node-opcua-constants": "2.175.1",
-        "node-opcua-crypto": "5.4.0",
-        "node-opcua-data-model": "2.175.6",
-        "node-opcua-data-value": "2.175.6",
-        "node-opcua-date-time": "2.175.6",
+        "node-opcua-basic-types": "2.177.0",
+        "node-opcua-buffer-utils": "2.176.0",
+        "node-opcua-certificate-manager": "2.177.0",
+        "node-opcua-client-dynamic-extension-object": "2.177.0",
+        "node-opcua-common": "2.177.0",
+        "node-opcua-constants": "2.176.0",
+        "node-opcua-crypto": "5.5.0",
+        "node-opcua-data-model": "2.177.0",
+        "node-opcua-data-value": "2.177.0",
+        "node-opcua-date-time": "2.176.0",
         "node-opcua-debug": "2.175.6",
-        "node-opcua-extension-object": "2.175.6",
+        "node-opcua-extension-object": "2.177.0",
         "node-opcua-hostname": "2.175.1",
-        "node-opcua-nodeid": "2.175.6",
-        "node-opcua-numeric-range": "2.175.6",
+        "node-opcua-nodeid": "2.177.0",
+        "node-opcua-numeric-range": "2.177.0",
         "node-opcua-object-registry": "2.175.6",
-        "node-opcua-pki": "6.19.0",
-        "node-opcua-pseudo-session": "2.175.6",
-        "node-opcua-schemas": "2.175.6",
-        "node-opcua-secure-channel": "2.175.6",
-        "node-opcua-service-browse": "2.175.6",
-        "node-opcua-service-call": "2.175.6",
-        "node-opcua-service-discovery": "2.175.6",
-        "node-opcua-service-endpoints": "2.175.6",
-        "node-opcua-service-filter": "2.175.6",
-        "node-opcua-service-history": "2.175.6",
-        "node-opcua-service-query": "2.175.6",
-        "node-opcua-service-read": "2.175.6",
-        "node-opcua-service-register-node": "2.175.6",
-        "node-opcua-service-secure-channel": "2.175.6",
-        "node-opcua-service-session": "2.175.6",
-        "node-opcua-service-subscription": "2.175.6",
-        "node-opcua-service-translate-browse-path": "2.175.6",
-        "node-opcua-service-write": "2.175.6",
-        "node-opcua-status-code": "2.175.6",
-        "node-opcua-transport": "2.175.6",
-        "node-opcua-types": "2.175.6",
-        "node-opcua-utils": "2.175.6",
-        "node-opcua-variant": "2.175.6",
+        "node-opcua-pki": "6.19.1",
+        "node-opcua-pseudo-session": "2.177.0",
+        "node-opcua-schemas": "2.177.0",
+        "node-opcua-secure-channel": "2.177.0",
+        "node-opcua-service-browse": "2.177.0",
+        "node-opcua-service-call": "2.177.0",
+        "node-opcua-service-discovery": "2.177.0",
+        "node-opcua-service-endpoints": "2.177.0",
+        "node-opcua-service-filter": "2.177.0",
+        "node-opcua-service-history": "2.177.0",
+        "node-opcua-service-query": "2.177.0",
+        "node-opcua-service-read": "2.177.0",
+        "node-opcua-service-register-node": "2.177.0",
+        "node-opcua-service-secure-channel": "2.177.0",
+        "node-opcua-service-session": "2.177.0",
+        "node-opcua-service-subscription": "2.177.0",
+        "node-opcua-service-translate-browse-path": "2.177.0",
+        "node-opcua-service-write": "2.177.0",
+        "node-opcua-status-code": "2.176.0",
+        "node-opcua-transport": "2.177.0",
+        "node-opcua-types": "2.177.0",
+        "node-opcua-utils": "2.176.0",
+        "node-opcua-variant": "2.177.0",
         "thenify-ex": "4.4.0"
     },
     "devDependencies": {
         "dequeue": "^1.0.5",
-        "node-opcua-address-space": "2.175.6",
-        "node-opcua-binary-stream": "2.175.6",
-        "node-opcua-factory": "2.175.6",
+        "node-opcua-address-space": "2.177.0",
+        "node-opcua-binary-stream": "2.176.0",
+        "node-opcua-factory": "2.177.0",
         "node-opcua-leak-detector": "2.175.6",
         "node-opcua-nodesets": "2.175.3"
     },
@@ -87,7 +87,7 @@
         "internet of things"
     ],
     "homepage": "http://node-opcua.github.io/",
-    "gitHead": "e233d906138995583f42359831d1908e3cb005e7",
+    "gitHead": "a00d1d3f4db4522ed6bb2c6104d86c57df79946a",
     "files": [
         "dist",
         "source"

package/source/client_base.ts

@@ -20,6 +20,7 @@ import type { ChannelSecurityToken, MessageSecurityMode } from "node-opcua-servi
 import type { ErrorCallback } from "node-opcua-status-code";
 import type { IClientTransportFactory } from "node-opcua-transport";
 import type { Request, Response } from "./common";
+import type { ClientReverseConnect, ReverseConnectExpectation } from "./reverse/client_reverse_connect";
 
 export type FindServersRequestLike = FindServersRequestOptions;
 export type FindServersOnNetworkRequestLike = FindServersOnNetworkRequestOptions;
@@ -235,6 +236,20 @@ export interface OPCUAClientBase<Events extends OPCUAClientBaseEvents = OPCUACli
 
     connect(endpointUrl: string, callback: ErrorCallback): void;
 
+    /***
+     * Wait for a Server to initiate a Reverse Connection (OPC UA Part 6 §7.1.3).
+     *
+     * Instead of dialing the server, the client waits for the server to dial into the
+     * (already started) `reverseConnect` listener and send a ReverseHello. The optional
+     * `expectation` restricts which server may connect (matched by ServerUri / EndpointUrl).
+     *
+     * For secured connections the server certificate must be supplied up front
+     * (`serverCertificate` option) since the client cannot dial the server to fetch it.
+     */
+    connectReverse(reverseConnect: ClientReverseConnect, expectation?: ReverseConnectExpectation): Promise<void>;
+    connectReverse(reverseConnect: ClientReverseConnect, callback: ErrorCallback): void;
+    connectReverse(reverseConnect: ClientReverseConnect, expectation: ReverseConnectExpectation, callback: ErrorCallback): void;
+
     /***
      * causes the client to close and disconnect the communication with server
      *

package/source/index.ts

@@ -37,6 +37,7 @@ export * from "./client_session";
 export * from "./client_subscription";
 export * from "./client_utils";
 export * from "./opcua_client";
+export * from "./reverse/client_reverse_connect";
 export { ClientSidePublishEngine } from "./private/client_publish_engine";
 export * from "./tools/findservers";
 export * from "./tools/read_history_server_capabilities";

package/source/private/client_base_impl.ts

@@ -27,7 +27,7 @@ import {
     type Response as Response1,
     type SecurityPolicy
 } from "node-opcua-secure-channel";
-import type { IClientTransportFactory } from "node-opcua-transport";
+import { type IAcceptedReverseConnection, type IClientTransportFactory, makeReverseClientTransportFactory } from "node-opcua-transport";
 import {
     FindServersOnNetworkRequest,
     type FindServersOnNetworkRequestOptions,
@@ -60,6 +60,7 @@ import {
     type TransportSettings
 } from "../client_base";
 import type { Request, Response } from "../common";
+import type { ClientReverseConnect, ICancelableRegistration, ReverseConnectExpectation } from "../reverse/client_reverse_connect";
 import type { UserIdentityInfo } from "../user_identity_info";
 import { performCertificateSanityCheck } from "../verify";
 import type { ClientSessionImpl } from "./client_session_impl";
@@ -389,6 +390,10 @@ export class ClientBaseImpl<Events extends OPCUAClientBaseEvents = OPCUAClientBa
     private _transportSettings: TransportSettings;
     private _transportTimeout?: number;
     private _transportFactory?: IClientTransportFactory;
+    /** true once connectReverse() has been used — suppresses outbound dials that would defeat reverse connect */
+    private _isReverseConnect = false;
+    /** the current reverse-connect waiter registration, cancelled on disconnect to avoid a leaked waiter */
+    private _reverseConnectRegistration?: ICancelableRegistration;
 
     public clientCertificateManager: ICertificateStore;
 
@@ -630,8 +635,13 @@ export class ClientBaseImpl<Events extends OPCUAClientBaseEvents = OPCUAClientBa
                     }
 
                     if (
-                        err?.message.match("BadCertificateInvalid") ||
-                        err?.message.match(/socket has been disconnected by third party/)
+                        // In reverse-connect mode we must NOT fetchServerCertificate(): that dials the
+                        // server directly (via a temp client), which is impossible for a firewalled
+                        // reverse-connect server and would hang reconnection. Fall through to the plain
+                        // retry, which re-arms the reverse transport and waits for the server to re-dial.
+                        !this._isReverseConnect &&
+                        (err?.message.match("BadCertificateInvalid") ||
+                            err?.message.match(/socket has been disconnected by third party/))
                     ) {
                         // it is possible also that hte server has shutdown innapropriately the connection
                         warningLog(
@@ -892,12 +902,20 @@ export class ClientBaseImpl<Events extends OPCUAClientBaseEvents = OPCUAClientBa
 
     protected _handleUnrecoverableConnectionFailure(err: Error, callback: ErrorCallback): void {
         debugLog(err.message);
+        // Terminal connect failure: make sure the client is removed from the leak registry. A
+        // synchronous throw out of _connectStep2 (e.g. an invalid SecureChannel config) lands here
+        // WITHOUT the error-branch unregister ever running, which would otherwise leak the client.
+        // unregister() is idempotent (a no-op when the client was never registered or already removed).
+        OPCUAClientBase.registry.unregister(this);
         this.emit("connection_failed", err);
         this._setInternalState("disconnected");
         callback(err);
     }
     private _handleDisconnectionWhileConnecting(err: Error, callback: ErrorCallback) {
         debugLog(err.message);
+        // see _handleUnrecoverableConnectionFailure: idempotent unregister guards against a leaked
+        // client when a connect attempt fails before the error-branch unregister runs.
+        OPCUAClientBase.registry.unregister(this);
         this.emit("connection_failed", err);
         this._setInternalState("disconnected");
         callback(err);
@@ -975,6 +993,94 @@ export class ClientBaseImpl<Events extends OPCUAClientBaseEvents = OPCUAClientBa
             });
     }
 
+    public connectReverse(reverseConnect: ClientReverseConnect, expectation?: ReverseConnectExpectation): Promise<void>;
+    public connectReverse(reverseConnect: ClientReverseConnect, callback: ErrorCallback): void;
+    public connectReverse(reverseConnect: ClientReverseConnect, expectation: ReverseConnectExpectation, callback: ErrorCallback): void;
+    public connectReverse(...args: unknown[]): Promise<void> | void {
+        const reverseConnect = args[0] as ClientReverseConnect;
+        const callback = args[args.length - 1] as ErrorCallback;
+        const expectation = (args.length >= 3 ? args[1] : undefined) as ReverseConnectExpectation | undefined;
+        assert(typeof callback === "function", "expecting a callback");
+
+        if (!reverseConnect) {
+            callback(new Error("connectReverse expects a ClientReverseConnect instance"));
+            return;
+        }
+
+        // c8 ignore next
+        if (this._internalState !== "disconnected") {
+            callback(new Error(`client#connectReverse failed, as invalid internal state = ${this._internalState}`));
+            return;
+        }
+        if (this._secureChannel !== null) {
+            setImmediate(() => callback(new Error("connect already called")));
+            return;
+        }
+
+        // A reverse-connect client cannot dial the server to fetch its certificate (that is the whole
+        // point of reverse connect), so for a secure channel the server certificate MUST be supplied up
+        // front via OPCUAClientOptions.serverCertificate. Reject early with a clear message rather than
+        // letting the SecureChannel layer fail deep inside with an opaque error (which also used to leak
+        // the client, since that failure path never reached the connect-failure unregister).
+        if (this.securityMode !== MessageSecurityMode.None && !this.serverCertificate) {
+            callback(
+                new Error(
+                    "connectReverse: a secure connection (securityMode=" +
+                        MessageSecurityMode[this.securityMode] +
+                        ") requires the server certificate to be supplied up front " +
+                        "(OPCUAClientOptions.serverCertificate), because a reverse-connect client cannot dial the server to fetch it."
+                )
+            );
+            return;
+        }
+
+        this._isReverseConnect = true;
+
+        // Wire a reverse-connect transport factory. Because the SecureChannel layer may call
+        // transport.connect() several times (backoff / reconnection), the provider is invoked on
+        // EACH attempt so every attempt waits for the server to (re-)dial in. We keep the current
+        // waiter registration so it can be cancelled on disconnect — otherwise a leaked waiter would
+        // later hijack an incoming server socket on this (by-then disposed) transport.
+        this._transportFactory = makeReverseClientTransportFactory(
+            () =>
+                new Promise<IAcceptedReverseConnection>((resolve, reject) => {
+                    // drop any stale waiter from a previous attempt before registering a new one
+                    this._reverseConnectRegistration?.cancel();
+                    this._reverseConnectRegistration = reverseConnect.waitForConnection(expectation, (err, accepted) => {
+                        this._reverseConnectRegistration = undefined;
+                        if (err || !accepted) {
+                            reject(err || new Error("no accepted reverse connection"));
+                            return;
+                        }
+                        // reconcile our endpointUrl with the one advertised in the ReverseHello, so
+                        // subsequent session creation uses the real URL rather than the placeholder below.
+                        this.endpointUrl = accepted.endpointUrl || this.endpointUrl;
+                        resolve(accepted);
+                    });
+                })
+        );
+
+        // Placeholder endpoint URL for the SecureChannel handshake; the reverse transport overrides
+        // it from the RHE. Prefer an explicitly-expected URL when the caller provided one.
+        const placeholderEndpointUrl = expectation?.endpointUrl || reverseConnect.connectionUrl || "opc.tcp://reverse-connect";
+
+        this._setInternalState("connecting");
+
+        this.initializeCM()
+            .then(() => {
+                debugLog("ClientBaseImpl#connectReverse ", placeholderEndpointUrl, this.clientName);
+                if (this._internalState === "disconnecting" || this._internalState === "disconnected") {
+                    return this._handleDisconnectionWhileConnecting(new Error("premature disconnection 1"), callback);
+                }
+                // NOTE: unlike connect(), we deliberately do NOT fetchServerCertificate() here — that
+                // would dial the server directly, defeating the purpose of reverse connect.
+                this._connectStep2(placeholderEndpointUrl, callback);
+            })
+            .catch((err) => {
+                return this._handleUnrecoverableConnectionFailure(err, callback);
+            });
+    }
+
     /**
      * @private
      */
@@ -1289,6 +1395,10 @@ export class ClientBaseImpl<Events extends OPCUAClientBaseEvents = OPCUAClientBa
         const callback = args[0] as ErrorCallback;
         assert(typeof callback === "function", "expecting a callback function here");
         this._reconnectionIsCanceled = true;
+        // cancel any outstanding reverse-connect waiter so it cannot later hijack an incoming
+        // server socket on this (now disconnecting) client.
+        this._reverseConnectRegistration?.cancel();
+        this._reverseConnectRegistration = undefined;
         if (this._tmpClient) {
             warningLog("disconnecting client while tmpClient exists", this._tmpClient.clientName);
             this._tmpClient.disconnect((_err) => {
@@ -1888,6 +1998,7 @@ class TmpClient extends ClientBaseImpl {
 import { withCallback } from "thenify-ex";
 
 ClientBaseImpl.prototype.connect = withCallback(ClientBaseImpl.prototype.connect);
+ClientBaseImpl.prototype.connectReverse = withCallback(ClientBaseImpl.prototype.connectReverse);
 ClientBaseImpl.prototype.disconnect = withCallback(ClientBaseImpl.prototype.disconnect);
 ClientBaseImpl.prototype.getEndpoints = withCallback(ClientBaseImpl.prototype.getEndpoints);
 ClientBaseImpl.prototype.findServers = withCallback(ClientBaseImpl.prototype.findServers);