bare-tls
Transport Layer Security (TLS) streams for JavaScript
v4.0.0bare-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-tlsUpgrading from 3.x. Version 4.0.0 aligns the events with Node.js. Check these when you upgrade.
- A
TLSSocketemits'secureConnect'instead of'connect'when the TLS handshake completes. Theonconnectcallback ofcreateConnection()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 theTLSNetSocketonce the handshake of a connection completes, and'tlsClientError'when the connection fails before that. Itsonconnectioncallback becameonsecureconnection, and its'connection'event now fires when a TCP connection is accepted, before the handshake, with the plainbare-netsocket. createServer()no longer takeseagerOpen.- A socket whose underlying connection closes before the handshake completes fails with a
TLSErrorthat has the codeECONNRESET, available aserrors.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
| Parameter | Type | Default | Description |
|---|---|---|---|
msg | string | — | — |
errors.from(err: Error): TLSError
Create a TLSError from err, copying its message and code.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
err | Error | — | The error to convert. |
TLSSocket
new TLSSocket(socket: Duplex, opts?: TLSSocketOptions)
Wrap the duplex stream socket with TLS.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
socket | Duplex | — | 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—hostis missing for a client socket whilerejectUnauthorizedistrue.RangeError— an ALPN protocol name is empty or longer than 255 bytes.TypeError—hostis set for a client socket, ends in a numeric label, and is not a canonical dotted-decimal IPv4 address, such as127.1or0x7f.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): TLSNetServerCreates 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
| Parameter | Type | Default | Description |
|---|---|---|---|
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): TLSNetSocketCreates 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
| Parameter | Type | Default | Description |
|---|---|---|---|
opts | TLSSocketOptions & { 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
| Parameter | Type | Default | Description |
|---|---|---|---|
msg | string | — | — |
TLSError.from(err: Error): TLSError
Create a TLSError from err, copying its message and code.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
err | Error | — | The error to convert. |
See also
- Builds on
bare-netandbare-stream. - Without a
caoption, peer certificates are verified against the Mozilla root certificates built into the addon, taken from curl's CA bundle:cacert-2026-11-05.pemas of v3.2.1, andcacert-2026-10-20.pemin v3.2.0. - Bare modules — the full
bare-*catalog. - Bare runtime API — the runtime these modules extend.
Last updated on