@ac-kit/node 0.1.0 → 0.2.0

package/dist/net/tls-socket.js

@@ -1,146 +1,296 @@
 import * as tls from "node:tls";
-import { isObject } from "@ac-kit/core";
-import { StreamSocket } from "./stream-socket.js";
-export class TlsSocket extends StreamSocket {
+import { nullIfEmpty } from "@ac-kit/core";
+import { ConnectionClosedError } from "./connection-closed-error.js";
+import { InetSocket } from "./inet-socket.js";
+/**
+ * TLS socket for establishing encrypted connections to TLS servers.
+ *
+ * Unlike {@link TcpSocket}, a TLS connection cannot be established on an
+ * existing instance: Node.js creates the socket as part of the handshake. The
+ * connection therefore starts from the static {@link TlsSocket.connect}, which
+ * resolves only once the handshake completed and the peer certificate has been
+ * verified.
+ *
+ * ```ts
+ * const socket = await TlsSocket.connect(443, { host: "example.com" });
+ * ```
+ *
+ * The same method upgrades an already-connected plaintext stream, which is what
+ * `STARTTLS`-style protocols need. The plaintext transport is destroyed if the
+ * handshake fails, so a failed upgrade can never fall back to cleartext.
+ *
+ * ```ts
+ * const plain = TcpSocket.from();
+ * await plain.connect(587, { host: "mail.example.com" });
+ * // ... negotiate STARTTLS over the plaintext connection ...
+ * const secure = await TlsSocket.connect(plain.stream, {
+ * 	servername: "mail.example.com",
+ * });
+ * ```
+ *
+ * Accessors that report handshake results ({@link TlsSocket.authorized},
+ * {@link TlsSocket.getPeerCertificate}, {@link TlsSocket.getCipher}, …) are
+ * only meaningful once the handshake completed.
+ */
+export class TlsSocket extends InetSocket {
+    /**
+     * Wraps an existing stream in a TLS socket without waiting for the handshake.
+     *
+     * The handshake starts immediately and its outcome is reported through the
+     * {@link TlsSocketEvents.secureConnect} and {@link StreamSocketEvents.error}
+     * events. Prefer {@link TlsSocket.connect}, which reports both through the
+     * returned promise; use this method only to drive the handshake manually.
+     *
+     * @param stream The plaintext stream to encrypt.
+     * @param options Options for the underlying Node.js TLS socket.
+     * @returns A new `TlsSocket` instance whose handshake is in progress.
+     */
     static from(stream, options) {
         return new TlsSocket(new tls.TLSSocket(stream, options));
     }
-    static connect(port, options) {
-        return new Promise((resolve, reject) => {
-            const { signal, ...connectOptions } = options ?? {};
-            signal?.throwIfAborted();
-            const tlsSocket = new TlsSocket(tls.connect({ ...connectOptions, port }));
-            const handleError = (error) => {
-                tlsSocket.unsubscribe("secureConnect", handleSecureConnect);
-                signal?.removeEventListener("abort", handleAbort);
-                reject(error);
-            };
-            tlsSocket.subscribe("error", handleError, { once: true });
-            const handleSecureConnect = () => {
-                tlsSocket.unsubscribe("error", handleError);
-                signal?.removeEventListener("abort", handleAbort);
-                resolve(tlsSocket);
-            };
-            tlsSocket.subscribe("secureConnect", handleSecureConnect, { once: true });
-            const handleAbort = () => {
-                tlsSocket.unsubscribe("error", handleError);
-                tlsSocket.unsubscribe("secureConnect", handleSecureConnect);
-                tlsSocket.destroy();
-                reject(signal?.reason);
-            };
-            signal?.addEventListener("abort", handleAbort, { once: true });
-        });
+    static async connect(target, options) {
+        let connectTarget;
+        if (typeof target === "number") {
+            connectTarget = { port: target };
+        }
+        else if (typeof target === "string") {
+            connectTarget = { path: target };
+        }
+        else {
+            connectTarget = { socket: target };
+        }
+        const { signal, ...connectOptions } = { ...options, ...connectTarget };
+        signal?.throwIfAborted();
+        const socket = new TlsSocket(tls.connect(connectOptions));
+        try {
+            await socket.awaitReady("secureConnect", { signal });
+        }
+        catch (error) {
+            // Leaving the transport open after a failed upgrade would expose the
+            // session to a cleartext downgrade.
+            socket.destroy();
+            throw error;
+        }
+        return socket;
     }
+    /** Always `true`; distinguishes a TLS socket from a plaintext one. */
     get encrypted() {
-        return this.sock.encrypted;
+        return this.socket.encrypted;
     }
+    /** Whether the peer certificate was signed by one of the configured CAs. */
     get authorized() {
-        return this.sock.authorized;
+        return this.socket.authorized;
     }
+    /**
+     * Reason why the peer certificate was rejected, or `null` when the peer is
+     * authorized or the handshake has not completed yet.
+     */
     get authorizationError() {
-        return this.sock.authorizationError ?? null;
+        return this.socket.authorizationError ?? null;
     }
+    /**
+     * Protocol selected through ALPN, or `null` before the handshake completed
+     * and when no protocol was negotiated.
+     */
     get alpnProtocol() {
-        const value = this.sock.alpnProtocol;
+        const value = this.socket.alpnProtocol;
+        return value === false ? null : value;
+    }
+    /**
+     * Server name requested through SNI, or `null` when the peer sent none.
+     *
+     * Only set on sockets accepted by a server.
+     */
+    get servername() {
+        const value = this.socket.servername;
         return value === false ? null : value;
     }
+    /**
+     * Returns the local certificate, or `null` when none was presented.
+     *
+     * @returns The local certificate or `null`.
+     */
     getCertificate() {
-        const cert = this.sock.getCertificate();
-        // Connection established but no certificate presented
-        if (isObject(cert) && Object.keys(cert).length === 0) {
-            return null;
-        }
-        if (cert === null) {
-            return null;
-        }
-        return cert;
+        // Node.js widens the result to `object` for the empty "no certificate" case.
+        return nullIfEmpty(this.socket.getCertificate());
+    }
+    getPeerCertificate(detailed) {
+        return nullIfEmpty(this.socket.getPeerCertificate(detailed));
+    }
+    /**
+     * Returns the peer certificate as an `X509Certificate`, or `null` when the
+     * peer presented none.
+     *
+     * @returns The peer certificate or `null`.
+     */
+    getPeerX509Certificate() {
+        return this.socket.getPeerX509Certificate() ?? null;
     }
+    /**
+     * Returns the local certificate as an `X509Certificate`, or `null` when none
+     * was presented.
+     *
+     * @returns The local certificate or `null`.
+     */
+    getX509Certificate() {
+        return this.socket.getX509Certificate() ?? null;
+    }
+    /**
+     * Returns the negotiated cipher suite.
+     *
+     * @returns The cipher name, standard name and protocol version.
+     */
     getCipher() {
-        return this.sock.getCipher();
+        return this.socket.getCipher();
     }
+    /**
+     * Returns the type, name and size of the ephemeral key exchange, or `null`
+     * when the key exchange was not ephemeral.
+     *
+     * @returns The ephemeral key information or `null`.
+     */
     getEphemeralKeyInfo() {
-        return this.sock.getEphemeralKeyInfo();
+        return nullIfEmpty(this.socket.getEphemeralKeyInfo());
     }
+    /**
+     * Returns the latest `Finished` message sent to the peer, or `null` when no
+     * handshake completed.
+     *
+     * @returns The message or `null`.
+     */
     getFinished() {
-        const value = this.sock.getFinished();
-        return value ?? null;
-    }
-    getPeerCertificate(detailed) {
-        return this.sock.getPeerCertificate(detailed);
+        return this.socket.getFinished() ?? null;
     }
+    /**
+     * Returns the latest `Finished` message received from the peer, or `null`
+     * when no handshake completed.
+     *
+     * @returns The message or `null`.
+     */
     getPeerFinished() {
-        const value = this.sock.getPeerFinished();
-        return value ?? null;
+        return this.socket.getPeerFinished() ?? null;
     }
+    /**
+     * Returns the negotiated protocol version, or `null` before the handshake
+     * completed.
+     *
+     * @returns The protocol version such as `TLSv1.3`, or `null`.
+     */
     getProtocol() {
-        return this.sock.getProtocol();
+        return this.socket.getProtocol();
     }
+    /**
+     * Returns the negotiated session, which can be passed back as the `session`
+     * connect option to resume it.
+     *
+     * @returns The session or `null`.
+     */
     getSession() {
-        const value = this.sock.getSession();
-        return value ?? null;
+        return this.socket.getSession() ?? null;
     }
-    getSharedSigalgs() {
-        return this.sock.getSharedSigalgs();
+    /**
+     * Returns the session ticket, or `null` when the peer issued none.
+     *
+     * @returns The session ticket or `null`.
+     */
+    getTLSTicket() {
+        return this.socket.getTLSTicket() ?? null;
     }
-    getTicket() {
-        const value = this.sock.getTLSTicket();
-        return value ?? null;
+    /**
+     * Returns the signature algorithms shared between client and server, in
+     * descending order of preference.
+     *
+     * @returns The shared signature algorithms.
+     */
+    getSharedSigalgs() {
+        return this.socket.getSharedSigalgs();
     }
+    /**
+     * Indicates whether the session was resumed rather than renegotiated.
+     *
+     * @returns `true` when the session was reused.
+     */
     isSessionReused() {
-        return this.sock.isSessionReused();
+        return this.socket.isSessionReused();
+    }
+    /**
+     * Keying material for the connection, as defined by RFC 5705.
+     *
+     * @param length Number of bytes to derive.
+     * @param label Application-specific label.
+     * @param context Optional application-specific context.
+     * @returns The derived keying material.
+     */
+    exportKeyingMaterial(length, label, context) {
+        // Node.js accepts an omitted context; @types/node declares it required.
+        return this.socket.exportKeyingMaterial(length, label, context);
     }
-    async renegotiate(options) {
-        // renegotiate callback is never called if socket is destroyed
-        if (this.sock.destroyed) {
-            throw new Error("Socket is destroyed");
+    /**
+     * Renegotiates the TLS session and resolves once the new handshake completed.
+     *
+     * @param options Renegotiation options.
+     * @returns A promise that resolves once renegotiation completed.
+     * @throws {ConnectionClosedError} When the socket is already destroyed, since
+     *   Node.js would never invoke the completion callback.
+     */
+    renegotiate(options) {
+        if (this.socket.destroyed) {
+            throw new ConnectionClosedError("Cannot renegotiate on a destroyed socket");
         }
         return new Promise((resolve, reject) => {
-            const callback = (err) => {
-                if (err) {
-                    reject(err);
-                }
-                else {
-                    resolve();
+            this.socket.renegotiate(options ?? {}, (error) => {
+                if (error) {
+                    reject(error);
+                    return;
                 }
-            };
-            this.sock.renegotiate(options, callback);
+                resolve();
+            });
         });
     }
+    /**
+     * Sets the private key and certificate to use for this socket, overriding the
+     * ones inherited from the secure context.
+     *
+     * @param context The secure context or the options to build one from.
+     */
     setKeyCert(context) {
-        this.sock.setKeyCert(context);
+        this.socket.setKeyCert(context);
     }
+    /**
+     * Sets the maximum TLS fragment size.
+     *
+     * @param size The maximum fragment size, between 512 and 16384.
+     * @returns `true` when the limit was set.
+     */
     setMaxSendFragment(size) {
-        return this.sock.setMaxSendFragment(size);
+        return this.socket.setMaxSendFragment(size);
     }
+    /**
+     * Disables renegotiation. Any further renegotiation attempt by the peer emits
+     * an error instead.
+     */
     disableRenegotiation() {
-        this.sock.disableRenegotiation();
+        this.socket.disableRenegotiation();
     }
+    /** Enables OpenSSL trace output on standard error, for debugging. */
     enableTrace() {
-        this.sock.enableTrace();
-    }
-    getPeerX509Certificate() {
-        const cert = this.sock.getPeerX509Certificate();
-        return cert ?? null;
-    }
-    getX509Certificate() {
-        const cert = this.sock.getX509Certificate();
-        return cert ?? null;
-    }
-    exportKeyingMaterial(length, label, context) {
-        return this.sock.exportKeyingMaterial(length, label, context);
+        this.socket.enableTrace();
     }
     setupEventForwarding() {
         super.setupEventForwarding();
-        this.sock.on("secureConnect", () => {
+        this.socket.on("secureConnect", () => {
             this.dispatch("secureConnect", []);
         });
-        this.sock.on("OCSPResponse", (response) => {
-            this.dispatch("ocspResponse", [response]);
+        this.socket.on("secure", () => {
+            this.dispatch("secure", []);
+        });
+        this.socket.on("OCSPResponse", (response) => {
+            this.dispatch("ocspResponse", [response ?? null]);
         });
-        this.sock.on("keylog", (line) => {
+        this.socket.on("keylog", (line) => {
             this.dispatch("keylog", [line]);
         });
-        this.sock.on("session", (session) => {
+        this.socket.on("session", (session) => {
             this.dispatch("session", [session]);
         });
     }

package/dist/net/tls-socket.js.map

@@ -1 +1 @@
-{"version":3,"file":"tls-socket.js","sourceRoot":"","sources":["../../src/net/tls-socket.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tls-socket.js","sourceRoot":"","sources":["../../src/net/tls-socket.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ac-kit/node",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Node.js extensions and zero-dependency wrappers over node: built-ins — promise-based TCP, TLS, IPC and UDP sockets, file I/O helpers and process utilities.",
   "keywords": [
     "fs",
@@ -39,15 +39,15 @@
     "prepack": "yarn build"
   },
   "dependencies": {
-    "@ac-kit/async": "^0.1.0",
-    "@ac-kit/core": "^0.1.0",
+    "@ac-kit/async": "^0.1.1",
+    "@ac-kit/core": "^0.2.0",
     "@types/node": "^26.5.1",
     "type-fest": "^5.8.0"
   },
   "devDependencies": {
     "@ac-kit/tsconfig": "0.1.0",
     "@ac-kit/typedoc-config": "0.1.0",
-    "@ac-kit/vitest-config": "0.1.0",
+    "@ac-kit/vitest-config": "0.1.1",
     "@typescript/native": "typescript@7.0.2",
     "rimraf": "6.1.3",
     "tsx": "4.23.12",

package/dist/shell/escape-command-arg.d.ts

@@ -1,9 +0,0 @@
-/**
- * Escape a string to be safely used as a shell argument, using the rules of the
- * current platform.
- *
- * @param expr The string to escape
- * @returns The escaped string
- */
-export declare const escapeCommandArg: (expr: string) => string;
-//# sourceMappingURL=escape-command-arg.d.ts.map

package/dist/shell/escape-command-arg.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"escape-command-arg.d.ts","sourceRoot":"","sources":["../../src/shell/escape-command-arg.ts"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAGtB,CAAC"}

package/dist/shell/escape-command-arg.js

@@ -1,13 +0,0 @@
-import { platform as processPlatform } from "node:process";
-import { escapePosixShCommandArg, escapeWin32CmdCommandArg, } from "@ac-kit/core";
-/**
- * Escape a string to be safely used as a shell argument, using the rules of the
- * current platform.
- *
- * @param expr The string to escape
- * @returns The escaped string
- */
-export const escapeCommandArg = processPlatform === "win32"
-    ? escapeWin32CmdCommandArg
-    : escapePosixShCommandArg;
-//# sourceMappingURL=escape-command-arg.js.map

package/dist/shell/escape-command-arg.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"escape-command-arg.js","sourceRoot":"","sources":["../../src/shell/escape-command-arg.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,eAAe,EAAE,MAAM,cAAc,CAAC;AAE3D,OAAO,EACN,uBAAuB,EACvB,wBAAwB,GACxB,MAAM,cAAc,CAAC;AAEtB;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAC5B,eAAe,KAAK,OAAO;IAC1B,CAAC,CAAC,wBAAwB;IAC1B,CAAC,CAAC,uBAAuB,CAAC"}

package/dist/shell/escape-command.d.ts

@@ -1,10 +0,0 @@
-/**
- * Escapes any characters in a string that might be used to trick a shell
- * command into executing arbitrary commands, using the rules of the current
- * platform.
- *
- * @param cmd The command to escape
- * @returns The escaped command
- */
-export declare const escapeCommand: (cmd: string) => string;
-//# sourceMappingURL=escape-command.d.ts.map

package/dist/shell/escape-command.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"escape-command.d.ts","sourceRoot":"","sources":["../../src/shell/escape-command.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAC8B,CAAC"}

package/dist/shell/escape-command.js

@@ -1,12 +0,0 @@
-import { platform as processPlatform } from "node:process";
-import { escapePosixShCommand, escapeWin32CmdCommand } from "@ac-kit/core";
-/**
- * Escapes any characters in a string that might be used to trick a shell
- * command into executing arbitrary commands, using the rules of the current
- * platform.
- *
- * @param cmd The command to escape
- * @returns The escaped command
- */
-export const escapeCommand = processPlatform === "win32" ? escapeWin32CmdCommand : escapePosixShCommand;
-//# sourceMappingURL=escape-command.js.map

package/dist/shell/escape-command.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"escape-command.js","sourceRoot":"","sources":["../../src/shell/escape-command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,eAAe,EAAE,MAAM,cAAc,CAAC;AAE3D,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE3E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GACzB,eAAe,KAAK,OAAO,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,oBAAoB,CAAC"}