Bare Docs

bare-tls

Transport Layer Security (TLS) streams for JavaScript

Documented against v4.0.0
stable

bare-tls — Transport Layer Security (TLS) streams for JavaScript. It is a native addon and requires Bare >=1.7.0.

Mirrors the Node.js tls module.

npm i bare-tls

Upgrading from 3.x. Version 4.0.0 aligns the events with Node.js. Check these when you upgrade.

  • A TLSSocket emits 'secureConnect' instead of 'connect' when the TLS handshake completes. The onconnect callback of createConnection() still runs at that point.
  • A socket from createConnection() emits 'connect' when its TCP connection opens, before the handshake.
  • A server from createServer() emits 'secureConnection' with the TLSNetSocket once the handshake of a connection completes, and 'tlsClientError' when the connection fails before that. Its onconnection callback became onsecureconnection, and its 'connection' event now fires when a TCP connection is accepted, before the handshake, with the plain bare-net socket.
  • createServer() no longer takes eagerOpen.
  • A socket whose underlying connection closes before the handshake completes fails with a TLSError that has the code ECONNRESET, available as errors.CONNECTION_RESET().

Usage

const tls = require('bare-tls')
const fs = require('bare-fs')

const server = tls.createServer(
  {
    cert: fs.readFileSync('cert.pem'),
    key: fs.readFileSync('key.pem')
  },
  (socket) => {
    socket.on('data', (data) => socket.end('pong')).on('close', () => server.close())
  }
)

server.listen(8443)

const client = tls.connect({ port: 8443, host: 'localhost' })

client.on('data', (data) => console.log(data)).end('ping')

API

errors

errors.code: string

errors.CONNECTION_RESET(msg: string): TLSError

The underlying socket disconnected before the TLS handshake completed.

Parameters

ParameterTypeDefaultDescription
msgstring——

errors.from(err: Error): TLSError

Create a TLSError from err, copying its message and code.

Parameters

ParameterTypeDefaultDescription
errError—The error to convert.

TLSSocket

new TLSSocket(socket: Duplex, opts?: TLSSocketOptions)

Wrap the duplex stream socket with TLS.

Parameters

ParameterTypeDefaultDescription
socketDuplex—The duplex stream to wrap; it handles transport while the TLS socket handles encryption and decryption.
opts?TLSSocketOptions—Options; rejectUnauthorized, eagerOpen, and allowHalfOpen default to true, and readBufferSize to 65536.

Throws

  • TypeError — host is missing for a client socket while rejectUnauthorized is true.
  • RangeError — an ALPN protocol name is empty or longer than 255 bytes.
  • TypeError — host is set for a client socket, ends in a numeric label, and is not a canonical dotted-decimal IPv4 address, such as 127.1 or 0x7f.0.0.1. Added in v3.2.0.

alpnProtocol: string | null

The negotiated ALPN protocol as a string, or null if no protocol was negotiated.

encrypted: true

Always true.

socket: Duplex

The underlying duplex stream.

Functions

createServer

createServer(opts?: Omit<TLSSocketOptions, 'eagerOpen'>, onsecureconnection?: (socket: TLSNetSocket) => void): TLSNetServer

Creates a TLS server that listens for TCP connections and wraps them with TLS. Incoming connections are emitted as 'secureConnection' events with a tls.Socket instance once the handshake completes. Options are the same as tls.Socket, plus any options supported by <https://github.com/holepunchto/bare-net>.

Parameters

ParameterTypeDefaultDescription
opts?Omit<TLSSocketOptions, 'eagerOpen'>—Options applied to each incoming socket; the same as TLSSocket, plus any options supported by bare-net.
onsecureconnection?(socket: TLSNetSocket) => void—Called on each 'secureConnection' event.

createConnection

createConnection(opts: TLSSocketOptions & { port: number; host?: string }, onconnect?: () => void): TLSNetSocket

Creates a TCP connection and wraps it with TLS. opts are passed to both the underlying TCP socket and TLSSocket. At minimum, port must be specified.

Parameters

ParameterTypeDefaultDescription
optsTLSSocketOptions & { port: number; host?: string }—Options passed to both the underlying TCP socket and TLSSocket; port is required and host defaults to 'localhost'.
onconnect?() => void—Called once the TLS handshake has completed (the socket's 'secureConnect' event). Before v3.2.0, it was called when the TCP connection opened, before the handshake.

Constants and variables

constants

constants: {
  state: {
    CONNECTED: number
    ATTACHED: number
  }
}

Internal state flags used by TLSSocket, such as state.CONNECTED.

Types

TLSSocketEvents

interface TLSSocketEvents {
  secureConnect: []
  data: [data: unknown]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
  drain: []
  finish: []
  pipe: [src: Readable]
}

Events emitted by a TLSSocket.

TLSSocketOptions

interface TLSSocketOptions {
  isServer?: boolean
  cert?: ArrayBufferView
  key?: ArrayBufferView
  host?: string
  rejectUnauthorized?: boolean
  ca?: ArrayBufferView
  alpnProtocols?: string[]
  eagerOpen?: boolean
  allowHalfOpen?: boolean
  readBufferSize?: number
}

Options for a TLSSocket.

TLSNetSocketEvents

interface TLSNetSocketEvents {
  connect: []
  timeout: []
  secureConnect: []
  data: [data: unknown]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
  drain: []
  finish: []
  pipe: [src: Readable]
}

Events emitted by a TLSNetSocket.

TLSNetSocket

interface TLSNetSocket {
  setKeepAlive(enable?: boolean, initialDelay?: number): this
  setNoDelay(noDelay?: boolean): this
  setTimeout(ms: number, ontimeout?: () => void): this
  ref(): void
  unref(): void
  readonly socket: Duplex
  readonly encrypted: true
  readonly alpnProtocol: string | null
}

A TLSSocket over a bare-net socket, as returned by createConnection(). ref() and unref() pass through to the underlying socket. Added in v3.2.0: setKeepAlive(), setNoDelay(), and setTimeout() also pass through and return the TLS socket, and the TLS socket emits timeout when the underlying socket does. setTimeout(ms, ontimeout) adds ontimeout as a one-time timeout listener, or removes it when ms is 0.

TLSNetServerEvents

interface TLSNetServerEvents {
  listening: []
  connection: [socket: NetSocket]
  secureConnection: [socket: TLSNetSocket]
  tlsClientError: [err: Error, socket: TLSNetSocket]
  error: [err: Error]
  close: []
}

Events emitted by a TLS server.

TLSNetServer

interface TLSNetServer extends EventEmitter<TLSNetServerEvents> {
  readonly listening: boolean
}

A TLS server over TCP; incoming connections are wrapped with TLS and emitted as 'secureConnection' events once the handshake completes.

bare-tls/constants

Constants and variables

constants.constants

constants: {
  state: {
    CONNECTED: number
    ATTACHED: number
  }
}

Internal state flags used by TLSSocket, such as state.CONNECTED.

bare-tls/errors

TLSError

TLSError.code: string

TLSError.CONNECTION_RESET(msg: string): TLSError

The underlying socket disconnected before the TLS handshake completed.

Parameters

ParameterTypeDefaultDescription
msgstring——

TLSError.from(err: Error): TLSError

Create a TLSError from err, copying its message and code.

Parameters

ParameterTypeDefaultDescription
errError—The error to convert.

See also

  • Builds on bare-net and bare-stream.
  • Without a ca option, peer certificates are verified against the Mozilla root certificates built into the addon, taken from curl's CA bundle: cacert-2026-11-05.pem as of v3.2.1, and cacert-2026-10-20.pem in v3.2.0.
  • Bare modules — the full bare-* catalog.
  • Bare runtime API — the runtime these modules extend.

Last updated on

Was this helpful?

On this page