@homaiohq/napi-quickfix 0.1.0 → 0.3.0

package/dist/esm/session.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Ergonomic wrapper around a live native `FIX::Session`.
+ */
+import { type NativeSession } from './native.js';
+import { SessionID } from './session-id.js';
+/**
+ * A handle on one live FIX session (wraps `FIX::Session`).
+ *
+ * Obtain one with {@link lookupSession} (any session in the process) or
+ * {@link Engine.getSession} (a session of a particular engine); sessions
+ * cannot be constructed directly.
+ *
+ * **Lifetime.** The underlying `FIX::Session` is owned by its engine. This
+ * handle stores only the {@link SessionID} and the identity of the engine it
+ * was obtained from, and re-resolves the session on every call, so it never
+ * dangles: once that engine has been stopped (which destroys its sessions)
+ * every method throws a {@link QuickFixError} whose `fixErrorName` is
+ * `'SessionNotFound'` -- also after a new engine has been created with the
+ * same id. A handle never crosses over to another engine's session; obtain a
+ * new one from the new engine.
+ *
+ * **Everything is synchronous.** State queries, sequence-number access, the
+ * runtime option getters/setters, {@link Session.logon}, {@link Session.logout}
+ * and {@link Session.refresh} never take the mutex QuickFIX holds while running
+ * your application handlers, so they cannot deadlock the main thread, and calls
+ * made in program order take effect in program order. ({@link Session.logon} /
+ * {@link Session.logout} flip a plain flag the engine's network thread reads
+ * without a lock, exactly as QuickFIX's own `Initiator::stop()` does; the
+ * engine picks the change up on its next pass.) QuickFIX's
+ * `Session::disconnect()` / `reset()` are deliberately not exposed: they are
+ * only safe on the engine's own network thread (see ARCHITECTURE.md §5). Use
+ * {@link Session.logout} to bring a session down, and the sequence-number
+ * setters to reset its numbering -- on a quiet session; see
+ * {@link Session.setNextSenderMsgSeqNum}.
+ *
+ * @example
+ * ```ts
+ * const session = initiator.getSession(sessionID)!;
+ * if (session.isLoggedOn()) {
+ *   console.log('next outbound seq', session.getExpectedSenderNum());
+ *   session.logout('maintenance');
+ * }
+ * ```
+ */
+export declare class Session {
+    #private;
+    /** @internal Use {@link lookupSession} / {@link Engine.getSession}. */
+    private constructor();
+    /** @internal Wrap an existing native session handle. */
+    static fromNative(handle: NativeSession): Session;
+    /** @internal The native handle backing this session. */
+    get nativeHandle(): NativeSession;
+    /** The id this handle refers to. Always available, even after the session is gone. */
+    get sessionID(): SessionID;
+    /** `true` once a Logon has been both sent and received. */
+    isLoggedOn(): boolean;
+    /**
+     * Whether the session is enabled. `false` after {@link Session.logout} until
+     * {@link Session.logon}; a disabled initiator session is not reconnected.
+     */
+    isEnabled(): boolean;
+    /** Whether this side has sent a Logon on the current connection. */
+    sentLogon(): boolean;
+    /** Whether this side has sent a Logout on the current connection. */
+    sentLogout(): boolean;
+    /** Whether a Logon has been received on the current connection. */
+    receivedLogon(): boolean;
+    /** `true` for a session owned by an {@link Initiator}. */
+    isInitiator(): boolean;
+    /** `true` for a session owned by an {@link Acceptor}. */
+    isAcceptor(): boolean;
+    /**
+     * Whether `now` (default: the current time) falls inside the session's
+     * configured `StartTime`/`EndTime` window. Throws `RangeError` for an
+     * invalid `Date`.
+     */
+    isSessionTime(now?: Date): boolean;
+    /**
+     * Whether `now` (default: the current time) falls inside the session's
+     * configured `LogonTime`/`LogoutTime` window. Throws `RangeError` for an
+     * invalid `Date`.
+     */
+    isLogonTime(now?: Date): boolean;
+    /** The MsgSeqNum (tag 34) the next outbound message will carry. */
+    getExpectedSenderNum(): number;
+    /** The MsgSeqNum (tag 34) expected on the next inbound message. */
+    getExpectedTargetNum(): number;
+    /**
+     * Set the MsgSeqNum the next outbound message will carry (writes to the
+     * message store; a file store may throw `IOException`).
+     *
+     * **Call it on a quiet session.** The setter is not serialised against a
+     * message the engine is sending or receiving on this session at the same
+     * time: QuickFIX reads the next number into the outbound header, runs your
+     * `toApp`/`toAdmin` handler, then increments from the store, all under a
+     * lock this call does not (and must not) take. A value set inside that
+     * window -- from a handler, or while a {@link sendToTarget} promise or a
+     * heartbeat is in flight on this session -- is overwritten by the increment,
+     * and the session ends up one off from its counterparty (a Resend Request or
+     * a "MsgSeqNum too low" Logout). Set it before {@link Engine.start}, from a
+     * `'logout'` event, or when you know nothing is in flight; never from a
+     * handler.
+     *
+     * @throws `RangeError` if `seqNum` is not a positive safe integer (MsgSeqNum is
+     * 1-based).
+     */
+    setNextSenderMsgSeqNum(seqNum: number): void;
+    /**
+     * Set the MsgSeqNum expected on the next inbound message (writes to the
+     * message store; a file store may throw `IOException`).
+     *
+     * **Call it on a quiet session.** Like {@link Session.setNextSenderMsgSeqNum},
+     * it is not serialised against a message the engine is processing on this
+     * session: QuickFIX checks the inbound number, runs your `fromApp`/`fromAdmin`
+     * handler, then increments the expected number from the store under a lock
+     * this call does not take, so a value set meanwhile is overwritten. Set it
+     * before {@link Engine.start}, from a `'logout'` event, or when you know
+     * nothing is in flight; never from a handler.
+     *
+     * @throws `RangeError` if `seqNum` is not a positive safe integer (MsgSeqNum is
+     * 1-based).
+     */
+    setNextTargetMsgSeqNum(seqNum: number): void;
+    /** `ResetOnLogon` */
+    getResetOnLogon(): boolean;
+    setResetOnLogon(value: boolean): void;
+    /** `ResetOnLogout` */
+    getResetOnLogout(): boolean;
+    setResetOnLogout(value: boolean): void;
+    /** `ResetOnDisconnect` */
+    getResetOnDisconnect(): boolean;
+    setResetOnDisconnect(value: boolean): void;
+    /** `RefreshOnLogon` */
+    getRefreshOnLogon(): boolean;
+    setRefreshOnLogon(value: boolean): void;
+    /** `CheckCompID` */
+    getCheckCompId(): boolean;
+    setCheckCompId(value: boolean): void;
+    /** `CheckLatency` */
+    getCheckLatency(): boolean;
+    setCheckLatency(value: boolean): void;
+    /** `PersistMessages` */
+    getPersistMessages(): boolean;
+    setPersistMessages(value: boolean): void;
+    /** `SendRedundantResendRequests` */
+    getSendRedundantResendRequests(): boolean;
+    setSendRedundantResendRequests(value: boolean): void;
+    /** `ValidateLengthAndChecksum` */
+    getValidateLengthAndChecksum(): boolean;
+    setValidateLengthAndChecksum(value: boolean): void;
+    /** `SendNextExpectedMsgSeqNum` */
+    getSendNextExpectedMsgSeqNum(): boolean;
+    setSendNextExpectedMsgSeqNum(value: boolean): void;
+    /** `NonStopSession` */
+    getIsNonStopSession(): boolean;
+    setIsNonStopSession(value: boolean): void;
+    /** `LogonTimeout`, in seconds. */
+    getLogonTimeout(): number;
+    /** @throws {RangeError} if `seconds` is not an integer in the int32 range. */
+    setLogonTimeout(seconds: number): void;
+    /** `LogoutTimeout`, in seconds. */
+    getLogoutTimeout(): number;
+    /** @throws {RangeError} if `seconds` is not an integer in the int32 range. */
+    setLogoutTimeout(seconds: number): void;
+    /** `MaxLatency`, in seconds. */
+    getMaxLatency(): number;
+    /** @throws {RangeError} if `seconds` is not an integer in the int32 range. */
+    setMaxLatency(seconds: number): void;
+    /** `TimestampPrecision` (number of sub-second digits, `0..9`). */
+    getTimestampPrecision(): number;
+    /** @throws `RangeError` unless `precision` is an integer in `0..9`. */
+    setTimestampPrecision(precision: number): void;
+    /**
+     * Enable the session. An initiator session reconnects and logs on at its
+     * next `ReconnectInterval`; an acceptor session accepts the next inbound
+     * Logon. Takes effect immediately ({@link Session.isEnabled} is `true` on
+     * return); observe the handshake through the engine's `'logon'` event.
+     */
+    logon(): void;
+    /**
+     * Disable the session and initiate a graceful Logout (sent with `reason` as
+     * tag 58 on the next engine tick). The session stays disabled — it will not
+     * reconnect — until {@link Session.logon}. Takes effect immediately
+     * ({@link Session.isEnabled} is `false` on return); observe completion
+     * through the engine's `'logout'` event.
+     */
+    logout(reason?: string): void;
+    /**
+     * Re-read the session state (sequence numbers etc.) from the message store.
+     *
+     * @throws {QuickFixError} `IOException` if the store cannot be read.
+     */
+    refresh(): void;
+}
+/**
+ * Look up a live session by id, across every engine in this process.
+ *
+ * @returns The {@link Session}, or `undefined` if no session with that id
+ *   exists (never created, or its engine has been stopped).
+ *
+ * @example
+ * ```ts
+ * const session = lookupSession(new SessionID('FIX.4.4', 'CLIENT', 'BROKER'));
+ * console.log(session?.isLoggedOn());
+ * ```
+ */
+export declare function lookupSession(sessionID: SessionID): Session | undefined;
+/** Whether a session with this id exists in this process. */
+export declare function doesSessionExist(sessionID: SessionID): boolean;
+/** The ids of every session in this process, across all engines. */
+export declare function getSessions(): SessionID[];
+/** The number of sessions in this process, across all engines. */
+export declare function numSessions(): number;

package/dist/esm/session.js

@@ -0,0 +1,329 @@
+/**
+ * Ergonomic wrapper around a live native `FIX::Session`.
+ */
+import { native } from './native.js';
+import { SessionID, toNativeSessionID } from './session-id.js';
+/**
+ * A handle on one live FIX session (wraps `FIX::Session`).
+ *
+ * Obtain one with {@link lookupSession} (any session in the process) or
+ * {@link Engine.getSession} (a session of a particular engine); sessions
+ * cannot be constructed directly.
+ *
+ * **Lifetime.** The underlying `FIX::Session` is owned by its engine. This
+ * handle stores only the {@link SessionID} and the identity of the engine it
+ * was obtained from, and re-resolves the session on every call, so it never
+ * dangles: once that engine has been stopped (which destroys its sessions)
+ * every method throws a {@link QuickFixError} whose `fixErrorName` is
+ * `'SessionNotFound'` -- also after a new engine has been created with the
+ * same id. A handle never crosses over to another engine's session; obtain a
+ * new one from the new engine.
+ *
+ * **Everything is synchronous.** State queries, sequence-number access, the
+ * runtime option getters/setters, {@link Session.logon}, {@link Session.logout}
+ * and {@link Session.refresh} never take the mutex QuickFIX holds while running
+ * your application handlers, so they cannot deadlock the main thread, and calls
+ * made in program order take effect in program order. ({@link Session.logon} /
+ * {@link Session.logout} flip a plain flag the engine's network thread reads
+ * without a lock, exactly as QuickFIX's own `Initiator::stop()` does; the
+ * engine picks the change up on its next pass.) QuickFIX's
+ * `Session::disconnect()` / `reset()` are deliberately not exposed: they are
+ * only safe on the engine's own network thread (see ARCHITECTURE.md §5). Use
+ * {@link Session.logout} to bring a session down, and the sequence-number
+ * setters to reset its numbering -- on a quiet session; see
+ * {@link Session.setNextSenderMsgSeqNum}.
+ *
+ * @example
+ * ```ts
+ * const session = initiator.getSession(sessionID)!;
+ * if (session.isLoggedOn()) {
+ *   console.log('next outbound seq', session.getExpectedSenderNum());
+ *   session.logout('maintenance');
+ * }
+ * ```
+ */
+export class Session {
+    /** @internal Underlying native handle. */
+    #native;
+    /** @internal Use {@link lookupSession} / {@link Engine.getSession}. */
+    constructor(handle) {
+        this.#native = handle;
+    }
+    /** @internal Wrap an existing native session handle. */
+    static fromNative(handle) {
+        return new Session(handle);
+    }
+    /** @internal The native handle backing this session. */
+    get nativeHandle() {
+        return this.#native;
+    }
+    /** The id this handle refers to. Always available, even after the session is gone. */
+    get sessionID() {
+        return SessionID.fromNative(this.#native.getSessionID());
+    }
+    // --- state -----------------------------------------------------------------
+    /** `true` once a Logon has been both sent and received. */
+    isLoggedOn() {
+        return this.#native.isLoggedOn();
+    }
+    /**
+     * Whether the session is enabled. `false` after {@link Session.logout} until
+     * {@link Session.logon}; a disabled initiator session is not reconnected.
+     */
+    isEnabled() {
+        return this.#native.isEnabled();
+    }
+    /** Whether this side has sent a Logon on the current connection. */
+    sentLogon() {
+        return this.#native.sentLogon();
+    }
+    /** Whether this side has sent a Logout on the current connection. */
+    sentLogout() {
+        return this.#native.sentLogout();
+    }
+    /** Whether a Logon has been received on the current connection. */
+    receivedLogon() {
+        return this.#native.receivedLogon();
+    }
+    /** `true` for a session owned by an {@link Initiator}. */
+    isInitiator() {
+        return this.#native.isInitiator();
+    }
+    /** `true` for a session owned by an {@link Acceptor}. */
+    isAcceptor() {
+        return this.#native.isAcceptor();
+    }
+    /**
+     * Whether `now` (default: the current time) falls inside the session's
+     * configured `StartTime`/`EndTime` window. Throws `RangeError` for an
+     * invalid `Date`.
+     */
+    isSessionTime(now) {
+        return this.#native.isSessionTime(now?.getTime());
+    }
+    /**
+     * Whether `now` (default: the current time) falls inside the session's
+     * configured `LogonTime`/`LogoutTime` window. Throws `RangeError` for an
+     * invalid `Date`.
+     */
+    isLogonTime(now) {
+        return this.#native.isLogonTime(now?.getTime());
+    }
+    // --- sequence numbers --------------------------------------------------------
+    /** The MsgSeqNum (tag 34) the next outbound message will carry. */
+    getExpectedSenderNum() {
+        return this.#native.getExpectedSenderNum();
+    }
+    /** The MsgSeqNum (tag 34) expected on the next inbound message. */
+    getExpectedTargetNum() {
+        return this.#native.getExpectedTargetNum();
+    }
+    /**
+     * Set the MsgSeqNum the next outbound message will carry (writes to the
+     * message store; a file store may throw `IOException`).
+     *
+     * **Call it on a quiet session.** The setter is not serialised against a
+     * message the engine is sending or receiving on this session at the same
+     * time: QuickFIX reads the next number into the outbound header, runs your
+     * `toApp`/`toAdmin` handler, then increments from the store, all under a
+     * lock this call does not (and must not) take. A value set inside that
+     * window -- from a handler, or while a {@link sendToTarget} promise or a
+     * heartbeat is in flight on this session -- is overwritten by the increment,
+     * and the session ends up one off from its counterparty (a Resend Request or
+     * a "MsgSeqNum too low" Logout). Set it before {@link Engine.start}, from a
+     * `'logout'` event, or when you know nothing is in flight; never from a
+     * handler.
+     *
+     * @throws `RangeError` if `seqNum` is not a positive safe integer (MsgSeqNum is
+     * 1-based).
+     */
+    setNextSenderMsgSeqNum(seqNum) {
+        this.#native.setNextSenderMsgSeqNum(seqNum);
+    }
+    /**
+     * Set the MsgSeqNum expected on the next inbound message (writes to the
+     * message store; a file store may throw `IOException`).
+     *
+     * **Call it on a quiet session.** Like {@link Session.setNextSenderMsgSeqNum},
+     * it is not serialised against a message the engine is processing on this
+     * session: QuickFIX checks the inbound number, runs your `fromApp`/`fromAdmin`
+     * handler, then increments the expected number from the store under a lock
+     * this call does not take, so a value set meanwhile is overwritten. Set it
+     * before {@link Engine.start}, from a `'logout'` event, or when you know
+     * nothing is in flight; never from a handler.
+     *
+     * @throws `RangeError` if `seqNum` is not a positive safe integer (MsgSeqNum is
+     * 1-based).
+     */
+    setNextTargetMsgSeqNum(seqNum) {
+        this.#native.setNextTargetMsgSeqNum(seqNum);
+    }
+    // --- runtime options -----------------------------------------------------------
+    // Each pair mirrors a QuickFIX session setting; the setter changes the LIVE
+    // session only (the SessionSettings it was created from are not updated).
+    /** `ResetOnLogon` */
+    getResetOnLogon() {
+        return this.#native.getResetOnLogon();
+    }
+    setResetOnLogon(value) {
+        this.#native.setResetOnLogon(value);
+    }
+    /** `ResetOnLogout` */
+    getResetOnLogout() {
+        return this.#native.getResetOnLogout();
+    }
+    setResetOnLogout(value) {
+        this.#native.setResetOnLogout(value);
+    }
+    /** `ResetOnDisconnect` */
+    getResetOnDisconnect() {
+        return this.#native.getResetOnDisconnect();
+    }
+    setResetOnDisconnect(value) {
+        this.#native.setResetOnDisconnect(value);
+    }
+    /** `RefreshOnLogon` */
+    getRefreshOnLogon() {
+        return this.#native.getRefreshOnLogon();
+    }
+    setRefreshOnLogon(value) {
+        this.#native.setRefreshOnLogon(value);
+    }
+    /** `CheckCompID` */
+    getCheckCompId() {
+        return this.#native.getCheckCompId();
+    }
+    setCheckCompId(value) {
+        this.#native.setCheckCompId(value);
+    }
+    /** `CheckLatency` */
+    getCheckLatency() {
+        return this.#native.getCheckLatency();
+    }
+    setCheckLatency(value) {
+        this.#native.setCheckLatency(value);
+    }
+    /** `PersistMessages` */
+    getPersistMessages() {
+        return this.#native.getPersistMessages();
+    }
+    setPersistMessages(value) {
+        this.#native.setPersistMessages(value);
+    }
+    /** `SendRedundantResendRequests` */
+    getSendRedundantResendRequests() {
+        return this.#native.getSendRedundantResendRequests();
+    }
+    setSendRedundantResendRequests(value) {
+        this.#native.setSendRedundantResendRequests(value);
+    }
+    /** `ValidateLengthAndChecksum` */
+    getValidateLengthAndChecksum() {
+        return this.#native.getValidateLengthAndChecksum();
+    }
+    setValidateLengthAndChecksum(value) {
+        this.#native.setValidateLengthAndChecksum(value);
+    }
+    /** `SendNextExpectedMsgSeqNum` */
+    getSendNextExpectedMsgSeqNum() {
+        return this.#native.getSendNextExpectedMsgSeqNum();
+    }
+    setSendNextExpectedMsgSeqNum(value) {
+        this.#native.setSendNextExpectedMsgSeqNum(value);
+    }
+    /** `NonStopSession` */
+    getIsNonStopSession() {
+        return this.#native.getIsNonStopSession();
+    }
+    setIsNonStopSession(value) {
+        this.#native.setIsNonStopSession(value);
+    }
+    /** `LogonTimeout`, in seconds. */
+    getLogonTimeout() {
+        return this.#native.getLogonTimeout();
+    }
+    /** @throws {RangeError} if `seconds` is not an integer in the int32 range. */
+    setLogonTimeout(seconds) {
+        this.#native.setLogonTimeout(seconds);
+    }
+    /** `LogoutTimeout`, in seconds. */
+    getLogoutTimeout() {
+        return this.#native.getLogoutTimeout();
+    }
+    /** @throws {RangeError} if `seconds` is not an integer in the int32 range. */
+    setLogoutTimeout(seconds) {
+        this.#native.setLogoutTimeout(seconds);
+    }
+    /** `MaxLatency`, in seconds. */
+    getMaxLatency() {
+        return this.#native.getMaxLatency();
+    }
+    /** @throws {RangeError} if `seconds` is not an integer in the int32 range. */
+    setMaxLatency(seconds) {
+        this.#native.setMaxLatency(seconds);
+    }
+    /** `TimestampPrecision` (number of sub-second digits, `0..9`). */
+    getTimestampPrecision() {
+        return this.#native.getTimestampPrecision();
+    }
+    /** @throws `RangeError` unless `precision` is an integer in `0..9`. */
+    setTimestampPrecision(precision) {
+        this.#native.setTimestampPrecision(precision);
+    }
+    // --- control -----------------------------------------------------------------------
+    /**
+     * Enable the session. An initiator session reconnects and logs on at its
+     * next `ReconnectInterval`; an acceptor session accepts the next inbound
+     * Logon. Takes effect immediately ({@link Session.isEnabled} is `true` on
+     * return); observe the handshake through the engine's `'logon'` event.
+     */
+    logon() {
+        this.#native.logon();
+    }
+    /**
+     * Disable the session and initiate a graceful Logout (sent with `reason` as
+     * tag 58 on the next engine tick). The session stays disabled — it will not
+     * reconnect — until {@link Session.logon}. Takes effect immediately
+     * ({@link Session.isEnabled} is `false` on return); observe completion
+     * through the engine's `'logout'` event.
+     */
+    logout(reason) {
+        this.#native.logout(reason);
+    }
+    /**
+     * Re-read the session state (sequence numbers etc.) from the message store.
+     *
+     * @throws {QuickFixError} `IOException` if the store cannot be read.
+     */
+    refresh() {
+        this.#native.refresh();
+    }
+}
+/**
+ * Look up a live session by id, across every engine in this process.
+ *
+ * @returns The {@link Session}, or `undefined` if no session with that id
+ *   exists (never created, or its engine has been stopped).
+ *
+ * @example
+ * ```ts
+ * const session = lookupSession(new SessionID('FIX.4.4', 'CLIENT', 'BROKER'));
+ * console.log(session?.isLoggedOn());
+ * ```
+ */
+export function lookupSession(sessionID) {
+    const handle = native.lookupSession(toNativeSessionID(sessionID, 'sessionID'));
+    return handle ? Session.fromNative(handle) : undefined;
+}
+/** Whether a session with this id exists in this process. */
+export function doesSessionExist(sessionID) {
+    return native.doesSessionExist(toNativeSessionID(sessionID, 'sessionID'));
+}
+/** The ids of every session in this process, across all engines. */
+export function getSessions() {
+    return native.getSessions().map((h) => SessionID.fromNative(h));
+}
+/** The number of sessions in this process, across all engines. */
+export function numSessions() {
+    return native.numSessions();
+}

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>;
+}