@homaiohq/napi-quickfix 0.2.0 → 0.3.0

package/README.md

@@ -34,6 +34,9 @@ included.
   field (`MsgType`, `Side`, `ExecType`, `OrdStatus`, ...) are
   generated from the bundled QuickFIX headers with literal types, frozen, and
   importable without loading the native addon.
+- **TLS for initiators** — `createTlsTunnel` is a built-in, stunnel-style TLS
+  tunnel (mTLS, SNI, certificate verification via Node's `tls`), so you don't need
+  a separate stunnel process.
 
 ## Install
 
@@ -385,6 +388,110 @@ the engine owning it has been stopped. A constructor that fails on a later
 (so the ids are not locked out by the failed attempt) and the engine-level log
 QuickFIX had already opened for it.
 
+### TLS (stunnel-style) for initiators
+
+QuickFIX's own `SSLSocketInitiator` needs OpenSSL compiled into the engine, and
+this package's prebuilds are built without it. Instead, `createTlsTunnel` does
+what a stunnel client does, inside your process. It listens on a loopback port,
+you point the initiator's `SocketConnectHost`/`SocketConnectPort` at it, and it
+carries each connection to the counterparty over Node's
+[`tls.connect`](https://nodejs.org/api/tls.html#tlsconnectoptions-callback):
+
+```text
+Initiator --plain TCP--> 127.0.0.1:<tunnel.port> --TLS--> fix.broker.com:9443
+```
+
+```ts
+import { readFileSync } from 'node:fs';
+import { createTlsTunnel, Initiator, SessionSettings } from '@homaiohq/napi-quickfix';
+
+const tunnel = await createTlsTunnel({
+  host: 'fix.broker.com',
+  port: 9443,
+  tls: {
+    ca: readFileSync('broker-ca.pem'),   // omit to trust Node's default CAs
+    cert: readFileSync('client.pem'),    // mTLS, if the venue requires it
+    key: readFileSync('client.key'),
+    minVersion: 'TLSv1.2',
+  },
+});
+tunnel.on('secureConnect', (info) => console.log('TLS up', info.protocol, info.peerCertificate.subject));
+tunnel.on('tlsError', (err) => console.error('TLS failed:', err.message));
+
+const settings = SessionSettings.fromString(`
+[DEFAULT]
+ConnectionType=initiator
+SocketConnectHost=${tunnel.host}
+SocketConnectPort=${tunnel.port}
+...
+`);
+const initiator = new Initiator({ settings, handlers });
+await initiator.start();
+
+// Shutdown: the engine first, so its Logout still crosses the tunnel.
+await initiator.stop();
+await tunnel.close();
+```
+
+- **Options.** `tls` accepts any `tls.ConnectionOptions` except
+  `host`/`port`/`socket`/`path`. `servername` (SNI, and the name the server
+  certificate is checked against) defaults to `host`, unless `host` is an IP
+  address.
+- **Fixed port.** Pass `localPort` to listen on a fixed port, for example to
+  keep `SocketConnectPort=9001` in a static `.cfg` file. A port that is already
+  in use makes `createTlsTunnel` reject with `EADDRINUSE`.
+- **Failover.** Open one tunnel per `SocketConnectHost<n>`, and set
+  `SocketConnectHost<n>=127.0.0.1` with `SocketConnectPort<n>=${tunnelN.port}`.
+- **Failures.** If the TLS connection fails or breaks (DNS, TCP, handshake,
+  certificate, or `tls` options that `tls.connect` rejects such as an
+  unreadable key), the tunnel emits `'tlsError'` and drops the initiator's
+  loopback connection. QuickFIX then reconnects after its `ReconnectInterval`.
+  The tunnel never emits `'error'`, so a tunnel with no listeners cannot crash
+  the process.
+- **Shutdown of a connection.** When either side closes, the other is ended
+  rather than reset, so data still in the tunnel (a Logout, TLS's
+  `close_notify`) is delivered. A connection that has not fully closed 5 seconds
+  after the first side closed is destroyed.
+- **Lifecycle.** The tunnel's handles are unref'd, so the tunnel alone never
+  keeps the process alive (a started engine does). `close()` destroys live
+  connections at once. It is idempotent, and
+  `await using tunnel = await createTlsTunnel(...)` closes the tunnel at the end
+  of the block.
+
+**Security notes**
+
+- The plain-text hop listens on `127.0.0.1` only. As with stunnel, other
+  processes on the same host can still connect to that port, so treat the host
+  as trusted.
+- QuickFIX's own logs show the loopback address (`Connecting to 127.0.0.1 on
+  port ...`). Use the `'secureConnect'` event to see the real peer and its
+  certificate.
+- Tunnel traffic runs on the JS event loop, which the application handlers
+  already depend on. A blocked loop stalls both in the same way.
+
+**Acceptor side.** There is no in-process equivalent for acceptors. QuickFIX
+1.16's acceptor always listens on every interface, and it checks
+`AllowedRemoteAddresses` only after processing the Logon. A tunnel in front of
+it could therefore be bypassed by connecting to the plain port directly. To
+accept TLS, terminate it outside the process (stunnel in server mode, a load
+balancer, a service mesh) and firewall the acceptor's port.
+
+If you'd rather run stunnel as a sidecar on the initiator side, this config is
+equivalent to the example above:
+
+```ini
+[fix-broker]
+client = yes
+accept = 127.0.0.1:9001
+connect = fix.broker.com:9443
+CAfile = broker-ca.pem
+cert = client.pem
+key = client.key
+verifyChain = yes
+checkHost = fix.broker.com
+sslVersionMin = TLSv1.2
+```
+
 ### Session
 
 A handle on one **live** session, obtained from `engine.getSession(id)` or the
@@ -503,6 +610,8 @@ numSessions(): number;
 
 version(): string;               // engine / addon version string
 
+createTlsTunnel(options: TlsTunnelOptions): Promise<TlsTunnel>; // see "TLS (stunnel-style) for initiators"
+
 FIELD        // field-name -> tag number, e.g. FIELD.MsgType === 35, FIELD.Password === 554
 MsgType      // MsgType values, e.g. MsgType.Logon === 'A'
 Side         // Side values, e.g. Side.Buy === '1'

package/cpp/addon.cpp

@@ -30,7 +30,7 @@ void RegisterSessionStatic(Napi::Env env, Napi::Object exports);
 namespace {
 
 // Keep in sync with package.json "version".
-constexpr const char* kAddonVersion = "0.2.0";
+constexpr const char* kAddonVersion = "0.3.0";
 
 Napi::Value Version(const Napi::CallbackInfo& info) {
   return Napi::String::New(info.Env(), kAddonVersion);

package/dist/cjs/index.d.ts

@@ -14,6 +14,8 @@ export { Session, lookupSession, doesSessionExist, getSessions, numSessions } fr
 export { FixReject, fixReject } from './application.js';
 export type { ApplicationHandlers, FixRejectKind } from './application.js';
 export type { QuickFixError } from './native.js';
+export { createTlsTunnel } from './tls-tunnel.js';
+export type { TlsTunnel, TlsTunnelOptions, TlsTunnelEvents, TlsTunnelSecureConnectInfo, } from './tls-tunnel.js';
 export { enums, FIELD, VALUES, MsgType, Side, OrdType, TimeInForce } from './enums.js';
 export type { Enums, EnumGroup, FieldName, ValueGroups, ValueGroupName } from './enums.js';
 /**

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.quickfixParseMsgType = exports.version = exports.TimeInForce = exports.OrdType = exports.Side = exports.MsgType = exports.VALUES = exports.FIELD = exports.enums = exports.fixReject = exports.FixReject = exports.numSessions = exports.getSessions = exports.doesSessionExist = exports.lookupSession = exports.Session = exports.Engine = exports.Acceptor = exports.Initiator = exports.DataDictionary = exports.SessionSettings = exports.SessionID = exports.Group = exports.parseMessage = exports.createMessage = exports.Message = void 0;
+exports.quickfixParseMsgType = exports.version = exports.TimeInForce = exports.OrdType = exports.Side = exports.MsgType = exports.VALUES = exports.FIELD = exports.enums = exports.createTlsTunnel = exports.fixReject = exports.FixReject = exports.numSessions = exports.getSessions = exports.doesSessionExist = exports.lookupSession = exports.Session = exports.Engine = exports.Acceptor = exports.Initiator = exports.DataDictionary = exports.SessionSettings = exports.SessionID = exports.Group = exports.parseMessage = exports.createMessage = exports.Message = void 0;
 exports.sendToTarget = sendToTarget;
 /**
  * `@homaiohq/napi-quickfix` — a modern Node-API binding for the QuickFIX C++
@@ -39,6 +39,8 @@ Object.defineProperty(exports, "numSessions", { enumerable: true, get: function
 var application_js_1 = require("./application.js");
 Object.defineProperty(exports, "FixReject", { enumerable: true, get: function () { return application_js_1.FixReject; } });
 Object.defineProperty(exports, "fixReject", { enumerable: true, get: function () { return application_js_1.fixReject; } });
+var tls_tunnel_js_1 = require("./tls-tunnel.js");
+Object.defineProperty(exports, "createTlsTunnel", { enumerable: true, get: function () { return tls_tunnel_js_1.createTlsTunnel; } });
 // --- Enums / constants ----------------------------------------------------
 // Every other value group (ExecType, OrdStatus, SecurityType, ...) is reachable
 // as `enums.<Field>` / `VALUES.<Field>`, or by name from the

package/dist/cjs/tls-tunnel.d.ts

@@ -0,0 +1,143 @@
+/**
+ * In-process TLS tunnel for initiators: the stunnel client model.
+ *
+ * QuickFIX is built without its OpenSSL-based `SSLSocketInitiator` (see
+ * CMakeLists.txt), so TLS is terminated in Node instead: the tunnel listens on
+ * a loopback port, the plain `FIX::SocketInitiator` connects to it (point
+ * `SocketConnectHost`/`SocketConnectPort` at {@link TlsTunnel.host} /
+ * {@link TlsTunnel.port}), and every accepted connection is carried to the real
+ * counterparty over `tls.connect`.
+ */
+import { EventEmitter } from 'node:events';
+import { type Server } from 'node:net';
+import { type CipherNameAndProtocol, type ConnectionOptions, type PeerCertificate } from 'node:tls';
+/** Options for {@link createTlsTunnel}. */
+export interface TlsTunnelOptions {
+    /** Host name or IP of the counterparty's TLS endpoint. */
+    host: string;
+    /** Port of the counterparty's TLS endpoint. */
+    port: number;
+    /**
+     * Passed to `tls.connect()` for every connection (CA, client certificate for
+     * mTLS, `minVersion`, ciphers, ...). `servername` (SNI, and the name the
+     * server certificate is checked against) defaults to `host` unless `host` is
+     * an IP address.
+     */
+    tls?: Omit<ConnectionOptions, 'host' | 'port' | 'socket' | 'path'>;
+    /**
+     * Loopback port to listen on. Defaults to `0`, an ephemeral port read back
+     * from {@link TlsTunnel.port}. Set it to point a static `.cfg` file at the
+     * tunnel, like stunnel's `accept = 127.0.0.1:<port>`.
+     */
+    localPort?: number;
+}
+/** Details of an established TLS connection, emitted as `'secureConnect'`. */
+export interface TlsTunnelSecureConnectInfo {
+    /** Whether the server certificate was verified against the trusted CAs. */
+    authorized: boolean;
+    /**
+     * Why verification failed, as the OpenSSL verification code (e.g.
+     * `'UNABLE_TO_VERIFY_LEAF_SIGNATURE'`, the `code` a `'tlsError'` carries
+     * otherwise). Only reachable with `rejectUnauthorized: false`.
+     */
+    authorizationError?: string;
+    /** Negotiated protocol, e.g. `'TLSv1.3'`. */
+    protocol: string | null;
+    /** Negotiated cipher. */
+    cipher: CipherNameAndProtocol;
+    /** The server's certificate (an empty object if it sent none). */
+    peerCertificate: PeerCertificate;
+}
+/**
+ * Events emitted by a {@link TlsTunnel}. There is deliberately no `'error'`
+ * event: connection failures are reported as `'tlsError'`, so a tunnel without
+ * listeners never crashes the process.
+ */
+export interface TlsTunnelEvents {
+    /** A connection to the counterparty completed its TLS handshake. */
+    secureConnect: [info: TlsTunnelSecureConnectInfo];
+    /**
+     * A connection to the counterparty failed (DNS, TCP, handshake, certificate
+     * verification, `tls` options `tls.connect` rejects) or broke. The
+     * initiator's loopback connection is closed with it, so QuickFIX reconnects
+     * after its `ReconnectInterval`. Also emitted when the loopback server fails
+     * to accept a connection (e.g. `EMFILE`).
+     */
+    tlsError: [error: Error];
+}
+/**
+ * A running TLS tunnel, created by {@link createTlsTunnel}.
+ *
+ * Its handles are unref'd: the tunnel alone never keeps the process alive (a
+ * started engine does). Close it after the engine has stopped, so a graceful
+ * Logout still reaches the counterparty.
+ */
+export declare class TlsTunnel extends EventEmitter {
+    #private;
+    /** Loopback address the tunnel listens on (`SocketConnectHost`). */
+    readonly host = "127.0.0.1";
+    /** Loopback port the tunnel listens on (`SocketConnectPort`). */
+    readonly port: number;
+    /** The counterparty's TLS endpoint. */
+    readonly remote: {
+        readonly host: string;
+        readonly port: number;
+    };
+    /** @internal Use {@link createTlsTunnel}. */
+    constructor(server: Server, port: number, options: TlsTunnelOptions);
+    /**
+     * Stop listening and destroy every live connection. Idempotent: later calls
+     * return the same Promise.
+     */
+    close(): Promise<void>;
+    /** Same as {@link TlsTunnel.close}; enables `await using tunnel = ...`. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Open a TLS tunnel to `options.host`:`options.port` and resolve once it
+ * listens on a loopback port.
+ *
+ * @example
+ * ```ts
+ * const tunnel = await createTlsTunnel({
+ *   host: 'fix.broker.com',
+ *   port: 9443,
+ *   tls: { ca: readFileSync('broker-ca.pem') },
+ * });
+ * tunnel.on('tlsError', (err) => console.error('TLS:', err.message));
+ * const settings = SessionSettings.fromString(`
+ * [DEFAULT]
+ * ConnectionType=initiator
+ * SocketConnectHost=${tunnel.host}
+ * SocketConnectPort=${tunnel.port}
+ * ...`);
+ * const initiator = new Initiator({ settings, handlers });
+ * await initiator.start();
+ * // ... later: engine first, so the Logout still crosses the tunnel
+ * await initiator.stop();
+ * await tunnel.close();
+ * ```
+ *
+ * @returns A Promise that rejects with a `TypeError` if `host`, `port` or
+ *   `localPort` is invalid, and with the listen error (e.g. `EADDRINUSE` for a
+ *   fixed `localPort` already in use) if the loopback port cannot be bound.
+ */
+export declare function createTlsTunnel(options: TlsTunnelOptions): Promise<TlsTunnel>;
+export interface TlsTunnel {
+    /** Register a listener for a tunnel event (typed per {@link TlsTunnelEvents}). */
+    on<E extends keyof TlsTunnelEvents>(event: E, listener: (...args: TlsTunnelEvents[E]) => void): this;
+    /** Register a one-shot listener for a tunnel event. */
+    once<E extends keyof TlsTunnelEvents>(event: E, listener: (...args: TlsTunnelEvents[E]) => void): this;
+    /** Alias of {@link TlsTunnel.on}. */
+    addListener<E extends keyof TlsTunnelEvents>(event: E, listener: (...args: TlsTunnelEvents[E]) => void): this;
+    /** Remove a previously registered listener. */
+    off<E extends keyof TlsTunnelEvents>(event: E, listener: (...args: TlsTunnelEvents[E]) => void): this;
+    /** Alias of {@link TlsTunnel.off}. */
+    removeListener<E extends keyof TlsTunnelEvents>(event: E, listener: (...args: TlsTunnelEvents[E]) => void): this;
+    /** Remove all listeners (optionally for a single event). */
+    removeAllListeners<E extends keyof TlsTunnelEvents>(event?: E): this;
+    /** Emit a tunnel event with its typed arguments. */
+    emit<E extends keyof TlsTunnelEvents>(event: E, ...args: TlsTunnelEvents[E]): boolean;
+    /** List the listeners registered for an event. */
+    listeners<E extends keyof TlsTunnelEvents>(event: E): Array<(...args: TlsTunnelEvents[E]) => void>;
+}

package/dist/cjs/tls-tunnel.js

@@ -0,0 +1,261 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TlsTunnel = void 0;
+exports.createTlsTunnel = createTlsTunnel;
+/**
+ * In-process TLS tunnel for initiators: the stunnel client model.
+ *
+ * QuickFIX is built without its OpenSSL-based `SSLSocketInitiator` (see
+ * CMakeLists.txt), so TLS is terminated in Node instead: the tunnel listens on
+ * a loopback port, the plain `FIX::SocketInitiator` connects to it (point
+ * `SocketConnectHost`/`SocketConnectPort` at {@link TlsTunnel.host} /
+ * {@link TlsTunnel.port}), and every accepted connection is carried to the real
+ * counterparty over `tls.connect`.
+ */
+const node_events_1 = require("node:events");
+const node_net_1 = require("node:net");
+const node_tls_1 = require("node:tls");
+const LOOPBACK = '127.0.0.1';
+/** How long a connection may take to wind down once either side has ended. */
+const DRAIN_TIMEOUT_MS = 5000;
+/**
+ * A running TLS tunnel, created by {@link createTlsTunnel}.
+ *
+ * Its handles are unref'd: the tunnel alone never keeps the process alive (a
+ * started engine does). Close it after the engine has stopped, so a graceful
+ * Logout still reaches the counterparty.
+ */
+class TlsTunnel extends node_events_1.EventEmitter {
+    /** Loopback address the tunnel listens on (`SocketConnectHost`). */
+    host = LOOPBACK;
+    /** Loopback port the tunnel listens on (`SocketConnectPort`). */
+    port;
+    /** The counterparty's TLS endpoint. */
+    remote;
+    #server;
+    #tls;
+    #pairs = new Set();
+    #closing;
+    /** @internal Use {@link createTlsTunnel}. */
+    constructor(server, port, options) {
+        super();
+        this.#server = server;
+        this.port = port;
+        this.remote = Object.freeze({ host: options.host, port: options.port });
+        // `socket` and `path` are excluded by the types only: drop them for JS
+        // callers too, or every connection would go to them instead of host:port.
+        const { socket: _socket, path: _path, ...tls } = (options.tls ?? {});
+        const servername = tls.servername ?? ((0, node_net_1.isIP)(options.host) === 0 ? options.host : undefined);
+        this.#tls = {
+            ...tls,
+            ...(servername === undefined ? {} : { servername }),
+            host: options.host,
+            port: options.port,
+        };
+        server.on('connection', (local) => this.#onConnection(local));
+        // A failed accept() (EMFILE, ENFILE, ...) is emitted on the server: without
+        // a listener it would be thrown.
+        server.on('error', (err) => {
+            if (!this.#closing)
+                this.emit('tlsError', err);
+        });
+    }
+    #onConnection(local) {
+        if (this.#closing) {
+            local.destroy();
+            return;
+        }
+        local.unref();
+        // QuickFIX writes its Logon as soon as it connects: hold it until the
+        // handshake is done and the pipe below takes over. It is read rather than
+        // left in a paused socket, which is not read at all: the engine's EOF or
+        // reset would go unseen, and a handshake completing after the engine gave
+        // up would still deliver its stale Logon.
+        const pending = [];
+        const hold = (chunk) => pending.push(chunk);
+        local.on('data', hold);
+        // tls.connect throws synchronously on options it cannot build a secure
+        // context from (bad PEM, unknown minVersion, ...): report it like any other
+        // connection failure instead of letting it escape the 'connection' handler.
+        let remote;
+        try {
+            remote = (0, node_tls_1.connect)(this.#tls);
+        }
+        catch (err) {
+            local.on('error', () => { });
+            local.destroy();
+            this.emit('tlsError', err instanceof Error ? err : new Error(String(err)));
+            return;
+        }
+        remote.unref();
+        const pair = { local, remote };
+        this.#pairs.add(pair);
+        // Once piped, a side that ends or closes is wound down gracefully on the
+        // other: it is ended, so the data still queued in the tunnel (a Logout, the
+        // TLS close_notify) is delivered rather than reset, and drained of what it
+        // still receives so it sees its peer's EOF. Anything still open
+        // DRAIN_TIMEOUT_MS after the first EOF is destroyed. Before the handshake
+        // completes there is nothing to deliver: an EOF or close drops both sides,
+        // and QuickFIX reconnects on its own schedule.
+        let piped = false;
+        let open = 2;
+        let drainTimer;
+        const linger = () => {
+            drainTimer ??= setTimeout(() => {
+                local.destroy();
+                remote.destroy();
+            }, DRAIN_TIMEOUT_MS).unref();
+        };
+        const onClose = (closed, other) => () => {
+            if (--open === 0) {
+                clearTimeout(drainTimer);
+                this.#pairs.delete(pair);
+            }
+            else if (!piped) {
+                other.destroy();
+            }
+            else {
+                other.unpipe(closed);
+                other.resume();
+                other.end();
+                linger();
+            }
+        };
+        local.on('error', () => {
+            // ECONNRESET and the like from the engine's side: nothing to report.
+        });
+        remote.on('error', (err) => {
+            if (!this.#closing)
+                this.emit('tlsError', err);
+        });
+        local.once('close', onClose(local, remote));
+        remote.once('close', onClose(remote, local));
+        local.once('end', () => {
+            if (piped) {
+                linger();
+            }
+            else {
+                local.destroy();
+                remote.destroy();
+            }
+        });
+        remote.once('secureConnect', () => {
+            local.setNoDelay(true);
+            remote.setNoDelay(true);
+            // Each side's EOF ends the other. The loopback socket is half-open, so
+            // after QuickFIX's EOF the counterparty's last bytes still reach it; the
+            // TLS socket ends itself on the counterparty's EOF, so what QuickFIX
+            // still sends is discarded (its peer has gone).
+            local.off('data', hold);
+            for (const chunk of pending)
+                remote.write(chunk);
+            pending.length = 0;
+            local.pipe(remote);
+            remote.pipe(local);
+            remote.once('end', () => {
+                local.unpipe(remote);
+                local.resume();
+                linger();
+            });
+            piped = true;
+            // Typed as an Error, but a string code at runtime, and null once the
+            // certificate verified.
+            const authorizationError = remote.authorizationError;
+            this.emit('secureConnect', {
+                authorized: remote.authorized,
+                ...(authorizationError ? { authorizationError } : {}),
+                protocol: remote.getProtocol(),
+                cipher: remote.getCipher(),
+                peerCertificate: remote.getPeerCertificate(),
+            });
+        });
+    }
+    /**
+     * Stop listening and destroy every live connection. Idempotent: later calls
+     * return the same Promise.
+     */
+    close() {
+        this.#closing ??= new Promise((resolve) => {
+            for (const { local, remote } of this.#pairs) {
+                local.destroy();
+                remote.destroy();
+            }
+            this.#pairs.clear();
+            // The only possible error is "not running", which still means closed.
+            this.#server.close(() => resolve());
+        });
+        return this.#closing;
+    }
+    /** Same as {@link TlsTunnel.close}; enables `await using tunnel = ...`. */
+    [Symbol.asyncDispose]() {
+        return this.close();
+    }
+}
+exports.TlsTunnel = TlsTunnel;
+/**
+ * Open a TLS tunnel to `options.host`:`options.port` and resolve once it
+ * listens on a loopback port.
+ *
+ * @example
+ * ```ts
+ * const tunnel = await createTlsTunnel({
+ *   host: 'fix.broker.com',
+ *   port: 9443,
+ *   tls: { ca: readFileSync('broker-ca.pem') },
+ * });
+ * tunnel.on('tlsError', (err) => console.error('TLS:', err.message));
+ * const settings = SessionSettings.fromString(`
+ * [DEFAULT]
+ * ConnectionType=initiator
+ * SocketConnectHost=${tunnel.host}
+ * SocketConnectPort=${tunnel.port}
+ * ...`);
+ * const initiator = new Initiator({ settings, handlers });
+ * await initiator.start();
+ * // ... later: engine first, so the Logout still crosses the tunnel
+ * await initiator.stop();
+ * await tunnel.close();
+ * ```
+ *
+ * @returns A Promise that rejects with a `TypeError` if `host`, `port` or
+ *   `localPort` is invalid, and with the listen error (e.g. `EADDRINUSE` for a
+ *   fixed `localPort` already in use) if the loopback port cannot be bound.
+ */
+async function createTlsTunnel(options) {
+    if (typeof options !== 'object' || options === null) {
+        throw new TypeError('createTlsTunnel({ host, port, tls?, localPort? })');
+    }
+    if (typeof options.host !== 'string' || options.host === '') {
+        throw new TypeError('host must be a non-empty string');
+    }
+    if (!isPort(options.port, 1)) {
+        throw new TypeError('port must be an integer from 1 to 65535');
+    }
+    const localPort = options.localPort ?? 0;
+    if (!isPort(localPort, 0)) {
+        throw new TypeError('localPort must be an integer from 0 to 65535');
+    }
+    // Half-open, so QuickFIX's EOF does not end the loopback socket before the
+    // counterparty's last bytes have crossed it (see #onConnection).
+    const server = (0, node_net_1.createServer)({ allowHalfOpen: true });
+    await new Promise((resolve, reject) => {
+        const onError = (err) => {
+            server.off('listening', onListening);
+            reject(err);
+        };
+        const onListening = () => {
+            server.off('error', onError);
+            resolve();
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(localPort, LOOPBACK);
+    });
+    server.unref();
+    const addr = server.address();
+    const port = typeof addr === 'object' && addr ? addr.port : localPort;
+    return new TlsTunnel(server, port, options);
+}
+function isPort(value, min) {
+    return Number.isInteger(value) && value >= min && value <= 65535;
+}

package/dist/esm/index.d.ts

@@ -14,6 +14,8 @@ export { Session, lookupSession, doesSessionExist, getSessions, numSessions } fr
 export { FixReject, fixReject } from './application.js';
 export type { ApplicationHandlers, FixRejectKind } from './application.js';
 export type { QuickFixError } from './native.js';
+export { createTlsTunnel } from './tls-tunnel.js';
+export type { TlsTunnel, TlsTunnelOptions, TlsTunnelEvents, TlsTunnelSecureConnectInfo, } from './tls-tunnel.js';
 export { enums, FIELD, VALUES, MsgType, Side, OrdType, TimeInForce } from './enums.js';
 export type { Enums, EnumGroup, FieldName, ValueGroups, ValueGroupName } from './enums.js';
 /**

package/dist/esm/index.js

@@ -18,6 +18,7 @@ export { Acceptor } from './acceptor.js';
 export { Engine } from './engine.js';
 export { Session, lookupSession, doesSessionExist, getSessions, numSessions } from './session.js';
 export { FixReject, fixReject } from './application.js';
+export { createTlsTunnel } from './tls-tunnel.js';
 // --- Enums / constants ----------------------------------------------------
 // Every other value group (ExecType, OrdStatus, SecurityType, ...) is reachable
 // as `enums.<Field>` / `VALUES.<Field>`, or by name from the

package/dist/esm/tls-tunnel.d.ts

@@ -0,0 +1,143 @@
+/**
+ * In-process TLS tunnel for initiators: the stunnel client model.
+ *
+ * QuickFIX is built without its OpenSSL-based `SSLSocketInitiator` (see
+ * CMakeLists.txt), so TLS is terminated in Node instead: the tunnel listens on
+ * a loopback port, the plain `FIX::SocketInitiator` connects to it (point
+ * `SocketConnectHost`/`SocketConnectPort` at {@link TlsTunnel.host} /
+ * {@link TlsTunnel.port}), and every accepted connection is carried to the real
+ * counterparty over `tls.connect`.
+ */
+import { EventEmitter } from 'node:events';
+import { type Server } from 'node:net';
+import { type CipherNameAndProtocol, type ConnectionOptions, type PeerCertificate } from 'node:tls';
+/** Options for {@link createTlsTunnel}. */
+export interface TlsTunnelOptions {
+    /** Host name or IP of the counterparty's TLS endpoint. */
+    host: string;
+    /** Port of the counterparty's TLS endpoint. */
+    port: number;
+    /**
+     * Passed to `tls.connect()` for every connection (CA, client certificate for
+     * mTLS, `minVersion`, ciphers, ...). `servername` (SNI, and the name the
+     * server certificate is checked against) defaults to `host` unless `host` is
+     * an IP address.
+     */
+    tls?: Omit<ConnectionOptions, 'host' | 'port' | 'socket' | 'path'>;
+    /**
+     * Loopback port to listen on. Defaults to `0`, an ephemeral port read back
+     * from {@link TlsTunnel.port}. Set it to point a static `.cfg` file at the
+     * tunnel, like stunnel's `accept = 127.0.0.1:<port>`.
+     */
+    localPort?: number;
+}
+/** Details of an established TLS connection, emitted as `'secureConnect'`. */
+export interface TlsTunnelSecureConnectInfo {
+    /** Whether the server certificate was verified against the trusted CAs. */
+    authorized: boolean;
+    /**
+     * Why verification failed, as the OpenSSL verification code (e.g.
+     * `'UNABLE_TO_VERIFY_LEAF_SIGNATURE'`, the `code` a `'tlsError'` carries
+     * otherwise). Only reachable with `rejectUnauthorized: false`.
+     */
+    authorizationError?: string;
+    /** Negotiated protocol, e.g. `'TLSv1.3'`. */
+    protocol: string | null;
+    /** Negotiated cipher. */
+    cipher: CipherNameAndProtocol;
+    /** The server's certificate (an empty object if it sent none). */
+    peerCertificate: PeerCertificate;
+}
+/**
+ * Events emitted by a {@link TlsTunnel}. There is deliberately no `'error'`
+ * event: connection failures are reported as `'tlsError'`, so a tunnel without
+ * listeners never crashes the process.
+ */
+export interface TlsTunnelEvents {
+    /** A connection to the counterparty completed its TLS handshake. */
+    secureConnect: [info: TlsTunnelSecureConnectInfo];
+    /**
+     * A connection to the counterparty failed (DNS, TCP, handshake, certificate
+     * verification, `tls` options `tls.connect` rejects) or broke. The
+     * initiator's loopback connection is closed with it, so QuickFIX reconnects
+     * after its `ReconnectInterval`. Also emitted when the loopback server fails
+     * to accept a connection (e.g. `EMFILE`).
+     */
+    tlsError: [error: Error];
+}
+/**
+ * A running TLS tunnel, created by {@link createTlsTunnel}.
+ *
+ * Its handles are unref'd: the tunnel alone never keeps the process alive (a
+ * started engine does). Close it after the engine has stopped, so a graceful
+ * Logout still reaches the counterparty.
+ */
+export declare class TlsTunnel extends EventEmitter {
+    #private;
+    /** Loopback address the tunnel listens on (`SocketConnectHost`). */
+    readonly host = "127.0.0.1";
+    /** Loopback port the tunnel listens on (`SocketConnectPort`). */
+    readonly port: number;
+    /** The counterparty's TLS endpoint. */
+    readonly remote: {
+        readonly host: string;
+        readonly port: number;
+    };
+    /** @internal Use {@link createTlsTunnel}. */
+    constructor(server: Server, port: number, options: TlsTunnelOptions);
+    /**
+     * Stop listening and destroy every live connection. Idempotent: later calls
+     * return the same Promise.
+     */
+    close(): Promise<void>;
+    /** Same as {@link TlsTunnel.close}; enables `await using tunnel = ...`. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Open a TLS tunnel to `options.host`:`options.port` and resolve once it
+ * listens on a loopback port.
+ *
+ * @example
+ * ```ts
+ * const tunnel = await createTlsTunnel({
+ *   host: 'fix.broker.com',
+ *   port: 9443,
+ *   tls: { ca: readFileSync('broker-ca.pem') },
+ * });
+ * tunnel.on('tlsError', (err) => console.error('TLS:', err.message));
+ * const settings = SessionSettings.fromString(`
+ * [DEFAULT]
+ * ConnectionType=initiator
+ * SocketConnectHost=${tunnel.host}
+ * SocketConnectPort=${tunnel.port}
+ * ...`);
+ * const initiator = new Initiator({ settings, handlers });
+ * await initiator.start();
+ * // ... later: engine first, so the Logout still crosses the tunnel
+ * await initiator.stop();
+ * await tunnel.close();
+ * ```
+ *
+ * @returns A Promise that rejects with a `TypeError` if `host`, `port` or
+ *   `localPort` is invalid, and with the listen error (e.g. `EADDRINUSE` for a
+ *   fixed `localPort` already in use) if the loopback port cannot be bound.
+ */
+export declare function createTlsTunnel(options: TlsTunnelOptions): Promise<TlsTunnel>;
+export interface TlsTunnel {
+    /** Register a listener for a tunnel event (typed per {@link TlsTunnelEvents}). */
+    on<E extends keyof TlsTunnelEvents>(event: E, listener: (...args: TlsTunnelEvents[E]) => void): this;
+    /** Register a one-shot listener for a tunnel event. */
+    once<E extends keyof TlsTunnelEvents>(event: E, listener: (...args: TlsTunnelEvents[E]) => void): this;
+    /** Alias of {@link TlsTunnel.on}. */
+    addListener<E extends keyof TlsTunnelEvents>(event: E, listener: (...args: TlsTunnelEvents[E]) => void): this;
+    /** Remove a previously registered listener. */
+    off<E extends keyof TlsTunnelEvents>(event: E, listener: (...args: TlsTunnelEvents[E]) => void): this;
+    /** Alias of {@link TlsTunnel.off}. */
+    removeListener<E extends keyof TlsTunnelEvents>(event: E, listener: (...args: TlsTunnelEvents[E]) => void): this;
+    /** Remove all listeners (optionally for a single event). */
+    removeAllListeners<E extends keyof TlsTunnelEvents>(event?: E): this;
+    /** Emit a tunnel event with its typed arguments. */
+    emit<E extends keyof TlsTunnelEvents>(event: E, ...args: TlsTunnelEvents[E]): boolean;
+    /** List the listeners registered for an event. */
+    listeners<E extends keyof TlsTunnelEvents>(event: E): Array<(...args: TlsTunnelEvents[E]) => void>;
+}

package/dist/esm/tls-tunnel.js

@@ -0,0 +1,256 @@
+/**
+ * In-process TLS tunnel for initiators: the stunnel client model.
+ *
+ * QuickFIX is built without its OpenSSL-based `SSLSocketInitiator` (see
+ * CMakeLists.txt), so TLS is terminated in Node instead: the tunnel listens on
+ * a loopback port, the plain `FIX::SocketInitiator` connects to it (point
+ * `SocketConnectHost`/`SocketConnectPort` at {@link TlsTunnel.host} /
+ * {@link TlsTunnel.port}), and every accepted connection is carried to the real
+ * counterparty over `tls.connect`.
+ */
+import { EventEmitter } from 'node:events';
+import { createServer, isIP } from 'node:net';
+import { connect as tlsConnect, } from 'node:tls';
+const LOOPBACK = '127.0.0.1';
+/** How long a connection may take to wind down once either side has ended. */
+const DRAIN_TIMEOUT_MS = 5000;
+/**
+ * A running TLS tunnel, created by {@link createTlsTunnel}.
+ *
+ * Its handles are unref'd: the tunnel alone never keeps the process alive (a
+ * started engine does). Close it after the engine has stopped, so a graceful
+ * Logout still reaches the counterparty.
+ */
+export class TlsTunnel extends EventEmitter {
+    /** Loopback address the tunnel listens on (`SocketConnectHost`). */
+    host = LOOPBACK;
+    /** Loopback port the tunnel listens on (`SocketConnectPort`). */
+    port;
+    /** The counterparty's TLS endpoint. */
+    remote;
+    #server;
+    #tls;
+    #pairs = new Set();
+    #closing;
+    /** @internal Use {@link createTlsTunnel}. */
+    constructor(server, port, options) {
+        super();
+        this.#server = server;
+        this.port = port;
+        this.remote = Object.freeze({ host: options.host, port: options.port });
+        // `socket` and `path` are excluded by the types only: drop them for JS
+        // callers too, or every connection would go to them instead of host:port.
+        const { socket: _socket, path: _path, ...tls } = (options.tls ?? {});
+        const servername = tls.servername ?? (isIP(options.host) === 0 ? options.host : undefined);
+        this.#tls = {
+            ...tls,
+            ...(servername === undefined ? {} : { servername }),
+            host: options.host,
+            port: options.port,
+        };
+        server.on('connection', (local) => this.#onConnection(local));
+        // A failed accept() (EMFILE, ENFILE, ...) is emitted on the server: without
+        // a listener it would be thrown.
+        server.on('error', (err) => {
+            if (!this.#closing)
+                this.emit('tlsError', err);
+        });
+    }
+    #onConnection(local) {
+        if (this.#closing) {
+            local.destroy();
+            return;
+        }
+        local.unref();
+        // QuickFIX writes its Logon as soon as it connects: hold it until the
+        // handshake is done and the pipe below takes over. It is read rather than
+        // left in a paused socket, which is not read at all: the engine's EOF or
+        // reset would go unseen, and a handshake completing after the engine gave
+        // up would still deliver its stale Logon.
+        const pending = [];
+        const hold = (chunk) => pending.push(chunk);
+        local.on('data', hold);
+        // tls.connect throws synchronously on options it cannot build a secure
+        // context from (bad PEM, unknown minVersion, ...): report it like any other
+        // connection failure instead of letting it escape the 'connection' handler.
+        let remote;
+        try {
+            remote = tlsConnect(this.#tls);
+        }
+        catch (err) {
+            local.on('error', () => { });
+            local.destroy();
+            this.emit('tlsError', err instanceof Error ? err : new Error(String(err)));
+            return;
+        }
+        remote.unref();
+        const pair = { local, remote };
+        this.#pairs.add(pair);
+        // Once piped, a side that ends or closes is wound down gracefully on the
+        // other: it is ended, so the data still queued in the tunnel (a Logout, the
+        // TLS close_notify) is delivered rather than reset, and drained of what it
+        // still receives so it sees its peer's EOF. Anything still open
+        // DRAIN_TIMEOUT_MS after the first EOF is destroyed. Before the handshake
+        // completes there is nothing to deliver: an EOF or close drops both sides,
+        // and QuickFIX reconnects on its own schedule.
+        let piped = false;
+        let open = 2;
+        let drainTimer;
+        const linger = () => {
+            drainTimer ??= setTimeout(() => {
+                local.destroy();
+                remote.destroy();
+            }, DRAIN_TIMEOUT_MS).unref();
+        };
+        const onClose = (closed, other) => () => {
+            if (--open === 0) {
+                clearTimeout(drainTimer);
+                this.#pairs.delete(pair);
+            }
+            else if (!piped) {
+                other.destroy();
+            }
+            else {
+                other.unpipe(closed);
+                other.resume();
+                other.end();
+                linger();
+            }
+        };
+        local.on('error', () => {
+            // ECONNRESET and the like from the engine's side: nothing to report.
+        });
+        remote.on('error', (err) => {
+            if (!this.#closing)
+                this.emit('tlsError', err);
+        });
+        local.once('close', onClose(local, remote));
+        remote.once('close', onClose(remote, local));
+        local.once('end', () => {
+            if (piped) {
+                linger();
+            }
+            else {
+                local.destroy();
+                remote.destroy();
+            }
+        });
+        remote.once('secureConnect', () => {
+            local.setNoDelay(true);
+            remote.setNoDelay(true);
+            // Each side's EOF ends the other. The loopback socket is half-open, so
+            // after QuickFIX's EOF the counterparty's last bytes still reach it; the
+            // TLS socket ends itself on the counterparty's EOF, so what QuickFIX
+            // still sends is discarded (its peer has gone).
+            local.off('data', hold);
+            for (const chunk of pending)
+                remote.write(chunk);
+            pending.length = 0;
+            local.pipe(remote);
+            remote.pipe(local);
+            remote.once('end', () => {
+                local.unpipe(remote);
+                local.resume();
+                linger();
+            });
+            piped = true;
+            // Typed as an Error, but a string code at runtime, and null once the
+            // certificate verified.
+            const authorizationError = remote.authorizationError;
+            this.emit('secureConnect', {
+                authorized: remote.authorized,
+                ...(authorizationError ? { authorizationError } : {}),
+                protocol: remote.getProtocol(),
+                cipher: remote.getCipher(),
+                peerCertificate: remote.getPeerCertificate(),
+            });
+        });
+    }
+    /**
+     * Stop listening and destroy every live connection. Idempotent: later calls
+     * return the same Promise.
+     */
+    close() {
+        this.#closing ??= new Promise((resolve) => {
+            for (const { local, remote } of this.#pairs) {
+                local.destroy();
+                remote.destroy();
+            }
+            this.#pairs.clear();
+            // The only possible error is "not running", which still means closed.
+            this.#server.close(() => resolve());
+        });
+        return this.#closing;
+    }
+    /** Same as {@link TlsTunnel.close}; enables `await using tunnel = ...`. */
+    [Symbol.asyncDispose]() {
+        return this.close();
+    }
+}
+/**
+ * Open a TLS tunnel to `options.host`:`options.port` and resolve once it
+ * listens on a loopback port.
+ *
+ * @example
+ * ```ts
+ * const tunnel = await createTlsTunnel({
+ *   host: 'fix.broker.com',
+ *   port: 9443,
+ *   tls: { ca: readFileSync('broker-ca.pem') },
+ * });
+ * tunnel.on('tlsError', (err) => console.error('TLS:', err.message));
+ * const settings = SessionSettings.fromString(`
+ * [DEFAULT]
+ * ConnectionType=initiator
+ * SocketConnectHost=${tunnel.host}
+ * SocketConnectPort=${tunnel.port}
+ * ...`);
+ * const initiator = new Initiator({ settings, handlers });
+ * await initiator.start();
+ * // ... later: engine first, so the Logout still crosses the tunnel
+ * await initiator.stop();
+ * await tunnel.close();
+ * ```
+ *
+ * @returns A Promise that rejects with a `TypeError` if `host`, `port` or
+ *   `localPort` is invalid, and with the listen error (e.g. `EADDRINUSE` for a
+ *   fixed `localPort` already in use) if the loopback port cannot be bound.
+ */
+export async function createTlsTunnel(options) {
+    if (typeof options !== 'object' || options === null) {
+        throw new TypeError('createTlsTunnel({ host, port, tls?, localPort? })');
+    }
+    if (typeof options.host !== 'string' || options.host === '') {
+        throw new TypeError('host must be a non-empty string');
+    }
+    if (!isPort(options.port, 1)) {
+        throw new TypeError('port must be an integer from 1 to 65535');
+    }
+    const localPort = options.localPort ?? 0;
+    if (!isPort(localPort, 0)) {
+        throw new TypeError('localPort must be an integer from 0 to 65535');
+    }
+    // Half-open, so QuickFIX's EOF does not end the loopback socket before the
+    // counterparty's last bytes have crossed it (see #onConnection).
+    const server = createServer({ allowHalfOpen: true });
+    await new Promise((resolve, reject) => {
+        const onError = (err) => {
+            server.off('listening', onListening);
+            reject(err);
+        };
+        const onListening = () => {
+            server.off('error', onError);
+            resolve();
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(localPort, LOOPBACK);
+    });
+    server.unref();
+    const addr = server.address();
+    const port = typeof addr === 'object' && addr ? addr.port : localPort;
+    return new TlsTunnel(server, port, options);
+}
+function isPort(value, min) {
+    return Number.isInteger(value) && value >= min && value <= 65535;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homaiohq/napi-quickfix",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Modern Node-API (N-API) C++ binding for the QuickFIX FIX-protocol engine.",
   "license": "MIT",
   "repository": {