@trex-tls/tls

A TLS 1.2/1.3 client implementation in TypeScript. It runs in the browser (no polyfills), Node, Bun, JavascriptCore, and other JavaScript environments. Cryptography is provided by either WebCrypto or a pure-JS implementation, depending on what is available.

Install

npm i @trex-tls/tls

Quick start

Set the crypto implementation once before use:

Recommended: WebCrypto (browser / Node / Bun)

import { setCryptoImplementation } from '@trex-tls/tls'
import { webcryptoCrypto } from '@trex-tls/tls/webcrypto'

setCryptoImplementation(webcryptoCrypto)

When WebCrypto is not available: pure-JS implementation

import { setCryptoImplementation } from '@trex-tls/tls'
import { pureJsCrypto } from '@trex-tls/tls/purejs-crypto'

setCryptoImplementation(pureJsCrypto)

Then create a TLS client and connect:

import { Socket } from 'net'
import { makeTLSClient, uint8ArrayToBinaryStr } from '@trex-tls/tls'

const socket = new Socket()
const host = 'www.google.com'
const port = 443

const tls = makeTLSClient({
  host,
  verifyServerCertificate: true,
  async write({ header, content }) {
    socket.write(header)
    socket.write(content)
  },
  onHandshake() {
    tls.write(Buffer.from(`GET / HTTP/1.1\r\nHost: ${host}\r\n\r\n`))
  },
  onApplicationData(plaintext) {
    console.log('received:', uint8ArrayToBinaryStr(plaintext))
  },
  onTlsEnd(error) {
    if (error) console.error('TLS ended:', error)
  },
})

socket.on('data', tls.handleReceivedBytes)
socket.on('connect', () => tls.startHandshake())
socket.connect({ host, port })

API

makeTLSClient(options)

Creates a TLS client instance. Required options:

| Option | Description | |--------|-------------| | host | Target hostname (used for SNI and certificate verification) | | write({ header, content }) | Sends TLS records to the underlying transport (e.g. TCP socket) |

Common optional options:

| Option | Default | Description | |--------|---------|-------------| | verifyServerCertificate | true | Whether to verify the server certificate; set to false for self-signed or debugging only | | cipherSuites | All supported | List of cipher suites to use | | onHandshake() | — | Callback when the handshake completes | | onApplicationData(plaintext) | — | Callback when application data is received | | onTlsEnd(error?) | — | Callback when the connection ends (close or error) |

Instance methods

• tls.startHandshake(opts?)
  Start the handshake. Use opts.psk for session resumption; use opts.random to supply a custom client random.

• tls.handleReceivedBytes(data: Uint8Array)
  Feed bytes from the underlying transport into the TLS layer (typically bound to the socket’s data event).

• tls.write(data: Uint8Array)
  Send encrypted application data after the handshake has completed.

• tls.getPskFromTicket(ticket)
  Derive a PSK from a session ticket for use with startHandshake({ psk }) on reconnect.

• tls.updateTrafficKeys(requestUpdateFromServer?)
  (TLS 1.3 only) Send KeyUpdate to rotate traffic keys for forward secrecy.

• tls.end(error?)
  End the connection and trigger onTlsEnd.

Session resumption and certificate callbacks

Session ticket and PSK resumption:

makeTLSClient({
  // ...
  onSessionTicket(ticket) {
    const psk = tls.getPskFromTicket(ticket)
    // On reconnect: tls.startHandshake({ psk })
  },
})

Receiving server certificates:

makeTLSClient({
  // ...
  onRecvCertificates({ certificates }) {
    // Read or log certificates here
  },
})

Supported protocols and algorithms

• Protocols: TLS 1.2, TLS 1.3
• Curves: P-256, P-384; X25519 (Node only)
• TLS 1.3 cipher suites: AES-128-GCM-SHA256, AES-256-GCM-SHA384, CHACHA20-POLY1305-SHA256
• TLS 1.2: ECDHE with AES-GCM, ChaCha20-Poly1305, AES-128-CBC, etc.
• Certificates: Built-in Mozilla CA roots; AIA fetching for intermediates with chain verification

ChaCha20-Poly1305 is provided by @stablelib/chacha20-poly1305; X.509 handling uses @peculiar/x509.

Development and scripts

# Install dependencies
npm i

# Run tests (choose one)
npm run test:webcrypto
npm run test:pure-js

# Run a handshake against a host
npm run handshake -- --host www.google.com

# Update built-in root CA store
npm run update:root-ca

For JavascriptCore compatibility, install the jsc binary and run npm run build:jsc before the relevant tests.