js/net/tls

hostname?: string

Hostname used for SNI and peer certificate checks.

await TlsSocket.connect(addr, { hostname: 'example.com' });

servername?: string

Alias for hostname, matching other TLS option surfaces.

If both names are provided they must be identical.

await TlsSocket.connect(addr, { servername: 'example.com' });

ca?: string

Path to a PEM CA bundle or file loaded with OpenSSL verify locations.

await TlsSocket.connect(addr, { hostname: 'internal.test', ca: '/etc/ssl/internal-ca.pem' });

cert?: string

Path to the PEM client certificate chain presented when requested.

Must be paired with key; partial certificate configuration throws before the TCP connection is opened.

await TlsSocket.connect(addr, { cert: './client.pem', key: './client.key' });

key?: string

Path to the PEM private key matching cert.

await TlsSocket.connect(addr, { cert: './client.pem', key: './client.key' });

rejectUnauthorized?: boolean

Whether to verify the peer certificate; defaults to true.

await TlsSocket.connect(addr, { rejectUnauthorized: false });

alpn?: string[]

ALPN protocol list offered by the client in preference order.

await TlsSocket.connect(addr, { hostname: 'example.com', alpn: ['h2', 'http/1.1'] });

cert: string

PEM certificate chain presented by the server.

key: string

PEM private key matching cert.

ca?: string

PEM CA bundle used to verify client certificates.

clientAuth?: TlsClientAuth

Client certificate policy. Defaults to 'none'.

rejectUnauthorized?: boolean

Whether verification failures abort the handshake. Defaults to true.

alpn?: readonly string[]

ALPN protocols offered by the server.

code: number

OpenSSL verification code. 0 means success.

reason: string | null

Human-readable OpenSSL reason, or null when verification succeeded.

peerCertificate: Uint8Array | null

Leaf peer certificate in DER form, or null when none was presented.

verify: TlsVerifyResult

Verification status from OpenSSL.

authorized: boolean

True when OpenSSL verification succeeded.

constructor(ssl: object, fd: number, onClose: () => void | Promise<void>)

Wrap OpenSSL state and a non-blocking fd as a TLS reader.

The reader does not own the SSL pointer by itself; the close callback coordinates cleanup with the paired TlsWriter.

const reader = new TlsReader(ssl, fd, onClose);

get fd(): number

Underlying socket file descriptor.

console.log(reader.fd);

override async close(): Promise<void>

constructor(ssl: object, fd: number, onClose: () => void | Promise<void>)

Wrap OpenSSL state and a non-blocking fd as a TLS writer.

The writer shares SSL ownership with a TlsReader; cleanup runs through the supplied close callback.

const writer = new TlsWriter(ssl, fd, onClose);

get fd(): number

Underlying socket file descriptor.

console.log(writer.fd);

constructor(fd: number, remoteAddr: Address | null, ssl: object, sslCtx: object | null)

Wrap an established TLS session.

The constructor takes ownership of ssl and, when non-null, sslCtx. Prefer connect(), upgrade(), or accept() so handshakes and cleanup are coordinated.

const tls = new TlsSocket(fd, remoteAddr, ssl, sslCtx);

get negotiatedProtocol(): string | null

The ALPN protocol negotiated during the TLS handshake, or null if none.

if (tls.negotiatedProtocol === 'h2') console.log('HTTP/2');

getPeerCertificate(): Uint8Array | null

Return the peer leaf certificate as DER bytes, or null.

This is raw certificate material. Treat it as authenticated identity only when getPeerInfo().authorized is true.

const cert = tls.getPeerCertificate();
if (cert) console.log(cert.byteLength);

getVerifyResult(): TlsVerifyResult

Return OpenSSL's peer verification result for this session.

Code 0 means verification succeeded. When verification was disabled, OpenSSL may still report the peer certificate's validation state, but the result must not be treated as application authentication by itself.

const verify = tls.getVerifyResult();
console.log(verify.code, verify.reason);

getPeerInfo(): TlsPeerInfo

Return peer certificate and verification metadata together.

const info = tls.getPeerInfo();
if (info.authorized) console.log(info.peerCertificate?.byteLength);

split(): [TlsReader, TlsWriter]

Split into a [TlsReader, TlsWriter pair. SSL cleanup and fd close happen automatically when both halves have been closed.

Note: TLS does not support half-close (no SHUT_RD/SHUT_WR per half). Both sides must close before SSL_shutdown is issued.

const [reader, writer] = tls.split();
await writer.close();
await reader.close();

close()

Close both directions immediately. Performs SSL teardown, then delegates fd cleanup to Socket.close(). Idempotent.

tls.close();

static async connect(addr: Address, opts: TlsConnectOptions = {}): Promise<TlsSocket>

Connect to a remote address over TLS. Uses connectTcp() for the TCP layer (same helper as Socket.connect()), then performs the TLS handshake.

Throws when OpenSSL is unavailable, TCP connection fails, certificate verification fails, or the TLS handshake fails.

const tls = await TlsSocket.connect(addr, { hostname: 'example.com' });

static async upgrade(socket: Socket, opts: TlsConnectOptions = {}): Promise<TlsSocket>

Upgrade an existing connected Socket to TLS (client side). The original Socket should not be used after this call.

On failure, the original socket fd remains caller-owned. This allows the caller to decide whether to close or recover it.

const raw = await Socket.connect(addr);
const tls = await TlsSocket.upgrade(raw, { hostname: 'example.com' });

static async accept(fd: number, sslCtx: object): Promise<TlsSocket>

Accept a TLS connection (server side) on an already-accepted TCP fd.

sslCtx is borrowed from the server and is not freed by the returned socket. On handshake failure, the SSL object is freed and the fd remains caller-owned.

const tls = await TlsSocket.accept(fd, sslCtx);