JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 144
  • Score
    100M100P100Q69183F
  • License Apache-2.0

Zero-dependency TLS 1.3/1.2 implementation for Node.js - full control over cryptographic keys, record layer, and handshake. Drop-in replacement for node:tls with advanced options impossible in OpenSSL.

Package Exports

  • lemon-tls
  • lemon-tls/crypto
  • lemon-tls/record
  • lemon-tls/session
  • lemon-tls/wire

Readme

LemonTLS

LemonTLS

๐Ÿ‹ Pure JavaScript implementation of TLS for Node.js, exposing cryptographic keys and record-layer control for implementing advanced protocols.

npm status license


โš ๏ธ Project status: Active development.
APIs may change without notice until we reach v1.0.
Use at your own risk and please report issues!

โœจ Features

  • ๐Ÿ”’ Pure JavaScript โ€“ no OpenSSL, no native bindings. Zero dependencies.
  • โšก TLS 1.3 (RFC 8446) + TLS 1.2 โ€“ both server and client.
  • ๐Ÿ”‘ Key Access โ€“ read handshake secrets, traffic keys, ECDHE shared secret, and resumption data at any point.
  • ๐Ÿ” Session Resumption โ€“ session tickets + PSK with binder validation.
  • ๐Ÿ”„ Key Update โ€“ refresh traffic keys on long-lived TLS 1.3 connections.
  • ๐Ÿ”ƒ HelloRetryRequest โ€“ automatic group negotiation fallback.
  • ๐Ÿ“œ Client Certificate Auth โ€“ mutual TLS (mTLS) with requestCert / cert / key options.
  • ๐Ÿ›ก Designed for extensibility โ€“ exposes cryptographic keys and record-layer primitives for QUIC, DTLS, or custom transports.
  • ๐Ÿงฉ Two API levels โ€“ high-level TLSSocket (drop-in Node.js Duplex stream) and low-level TLSSession (state machine only, you handle the transport).
  • ๐Ÿ”ง Beyond Node.js โ€“ per-connection cipher/sigalg/group selection, JA3 fingerprinting, certificate pinning, and more options that are impossible or require openssl.cnf hacks in Node.js.

๐Ÿ“ฆ Installation

npm i lemon-tls

๐Ÿš€ Quick Start

Drop-in Node.js Replacement

import tls from 'lemon-tls';  // not 'node:tls' โ€” same API
import fs from 'node:fs';
 
// Server
const server = tls.createServer({
  key: fs.readFileSync('server.key'),
  cert: fs.readFileSync('server.crt'),
}, (socket) => {
  console.log('Protocol:', socket.getProtocol());
  console.log('Cipher:', socket.getCipher().name);
  socket.write('Hello from LemonTLS!\n');
});
server.listen(8443);
 
// Client
const socket = tls.connect(8443, 'localhost', { rejectUnauthorized: false }, () => {
  socket.write('Hello from client!\n');
});
socket.on('data', (d) => console.log(d.toString()));

Low-Level: TLSSocket with TCP

import net from 'node:net';
import { TLSSocket, createSecureContext } from 'lemon-tls';
 
const server = net.createServer((tcp) => {
  const socket = new TLSSocket(tcp, {
    isServer: true,
    SNICallback: (servername, cb) => {
      cb(null, createSecureContext({
        key: fs.readFileSync('server.key'),
        cert: fs.readFileSync('server.crt'),
      }));
    }
  });
  socket.on('secureConnect', () => socket.write('hi\n'));
  socket.on('data', (d) => console.log('Got:', d.toString()));
});
server.listen(8443);

Session Resumption (PSK)

let savedSession = null;
 
// First connection โ€” save the ticket
socket.on('session', (ticketData) => { savedSession = ticketData; });
 
// Second connection โ€” resume (no certificate exchange, faster)
const socket2 = tls.connect(8443, 'localhost', { session: savedSession }, () => {
  console.log('Resumed:', socket2.isResumed);  // true
});

Mutual TLS (Client Certificate)

// Server: request client certificate
const server = tls.createServer({
  key: serverKey, cert: serverCert,
  requestCert: true,
});
 
// Client: provide certificate
const socket = tls.connect(8443, 'localhost', {
  cert: fs.readFileSync('client.crt'),
  key: fs.readFileSync('client.key'),
});

๐Ÿ“š API

Module-Level Functions

import tls from 'lemon-tls';
 
tls.connect(port, host, options, callback)   // Node.js compatible
tls.createServer(options, callback)          // Node.js compatible
tls.createSecureContext({ key, cert })       // PEM โ†’ { certificateChain, privateKey }
tls.getCiphers()                             // ['tls_aes_128_gcm_sha256', ...]
tls.DEFAULT_MIN_VERSION                      // 'TLSv1.2'
tls.DEFAULT_MAX_VERSION                      // 'TLSv1.3'

TLSSocket

High-level wrapper extending stream.Duplex, API-compatible with Node.js tls.TLSSocket.

Constructor Options

Standard (Node.js compatible):

Option Type Description
isServer boolean Server or client mode
servername string SNI hostname (client)
SNICallback function (servername, cb) => cb(null, secureContext) (server)
minVersion string 'TLSv1.2' or 'TLSv1.3'
maxVersion string 'TLSv1.2' or 'TLSv1.3'
ALPNProtocols string[] Offered ALPN protocols
rejectUnauthorized boolean Validate peer certificate (default: true)
ca Buffer/string CA certificate(s) for validation
ticketKeys Buffer 48-byte key for session ticket encryption (server)
session object Saved ticket data from 'session' event (client resumption)
requestCert boolean Request client certificate (server)
cert Buffer/string Client certificate PEM (for mTLS)
key Buffer/string Client private key PEM (for mTLS)

LemonTLS-only (not available in Node.js):

Option Type Description
noTickets boolean Disable session tickets (in Node.js requires openssl.cnf)
signatureAlgorithms number[] Per-connection sigalg list, e.g. [0x0804] for RSA-PSS only
groups number[] Per-connection curves, e.g. [0x001d] for X25519 only
prioritizeChaCha boolean Move ChaCha20-Poly1305 before AES in cipher preference
maxRecordSize number Max plaintext per TLS record (default: 16384)
allowedCipherSuites number[] Whitelist โ€” only these ciphers are offered
pins string[] Certificate pinning: ['sha256/AAAA...']
handshakeTimeout number Abort handshake after N ms
maxHandshakeSize number Max handshake bytes โ€” DoS protection
certificateCallback function Dynamic cert selection: (info, cb) => cb(null, ctx)

Events

Event Callback Description
secureConnect () Handshake complete, data can flow
data (Buffer) Decrypted application data received
session (ticketData) New session ticket available for resumption
keyUpdate (direction) Traffic keys refreshed: 'send' or 'receive'
keylog (Buffer) SSLKEYLOGFILE-format line (for Wireshark)
clienthello (raw, parsed) Raw ClientHello received (server, for JA3)
handshakeMessage (type, raw, parsed) Every handshake message (debugging)
certificateRequest (msg) Server requested a client certificate
error (Error) TLS or transport error
close () Connection closed

Properties & Methods

Node.js compatible:

socket.getProtocol() 'TLSv1.3' or 'TLSv1.2'
socket.getCipher() { name, standardName, version }
socket.getPeerCertificate() { subject, issuer, valid_from, fingerprint256, raw, ... }
socket.isResumed true if PSK resumption was used
socket.isSessionReused() Same as isResumed (Node.js compat)
socket.authorized true if peer certificate is valid
socket.authorizationError Error string or null
socket.alpnProtocol Negotiated ALPN protocol or false
socket.encrypted Always true
socket.getFinished() Local Finished verify_data (Buffer)
socket.getPeerFinished() Peer Finished verify_data (Buffer)
socket.exportKeyingMaterial(len, label, ctx) RFC 5705 keying material
socket.getEphemeralKeyInfo() { type: 'X25519', size: 253 }
socket.write(data) Send encrypted application data
socket.end() Send close_notify alert and close

LemonTLS-only:

socket.getSession() Access the underlying TLSSession
socket.handshakeDuration Handshake time in ms
socket.getJA3() { hash, raw } โ€” JA3 fingerprint (server-side)
socket.getSharedSecret() ECDHE shared secret (Buffer)
socket.getNegotiationResult() { version, cipher, group, sni, alpn, resumed, helloRetried, ... }
socket.rekeySend() Refresh outgoing encryption keys (TLS 1.3)
socket.rekeyBoth() Refresh keys for both directions (TLS 1.3)

TLSSession

The core state machine for a TLS connection. Performs handshake, key derivation, and state management โ€” but does no I/O. You provide the transport.

This is the API to use for QUIC, DTLS, or any custom transport.

import { TLSSession } from 'lemon-tls';
 
const session = new TLSSession({ isServer: true });
 
// Feed incoming handshake bytes from your transport:
session.message(handshakeBytes);
 
// Session tells you what to send:
session.on('message', (epoch, seq, type, data) => {
  // epoch: 0=cleartext, 1=handshake-encrypted, 2=app-encrypted
  myTransport.send(data);
});
 
session.on('hello', () => {
  session.set_context({
    local_supported_versions: [0x0304],
    local_supported_cipher_suites: [0x1301, 0x1302, 0x1303],
    local_cert_chain: myCerts,
    cert_private_key: myKey,
  });
});
 
session.on('secureConnect', () => {
  const secrets = session.getTrafficSecrets();
  const result = session.getNegotiationResult();
  console.log(session.handshakeDuration, 'ms');
});
 
// Key Update
session.requestKeyUpdate(true); // true = request peer to update too
session.on('keyUpdate', ({ direction, secret }) => { /* ... */ });
 
// PSK callback โ€” full control over ticket validation (server)
session.on('psk', (identity, callback) => {
  const psk = myTicketStore.lookup(identity);
  callback(psk ? { psk, cipher: 0x1301 } : null);
});
 
// JA3 fingerprinting (server)
session.on('clienthello', (raw, parsed) => {
  console.log(session.getJA3()); // { hash: 'abc...', raw: '769,47-53,...' }
});

Record Layer Module

Shared encrypt/decrypt primitives for QUIC, DTLS, and custom transport consumers:

import { deriveKeys, encryptRecord, decryptRecord, getNonce, getAeadAlgo }
  from 'lemon-tls/record';
 
const { key, iv } = deriveKeys(trafficSecret, cipherSuite);
const nonce = getNonce(iv, sequenceNumber);
const algo = getAeadAlgo(cipherSuite);  // 'aes-128-gcm' | 'chacha20-poly1305'
const encrypted = encryptRecord(contentType, plaintext, key, nonce, algo);

๐Ÿ”ง Advanced Options (Not Available in Node.js)

LemonTLS gives you control that Node.js doesn't expose โ€” without openssl.cnf hacks:

import tls from 'lemon-tls';
 
// Per-connection cipher/group/sigalg selection (impossible in Node.js)
const socket = tls.connect(443, 'api.example.com', {
  groups: [0x001d],                  // X25519 only (Node: ecdhCurve is global)
  signatureAlgorithms: [0x0804],     // RSA-PSS-SHA256 only (Node: no control)
  prioritizeChaCha: true,            // ChaCha20 before AES (Node: no control)
  allowedCipherSuites: [0x1301, 0x1303], // whitelist (Node: string-based, error-prone)
});
 
// Disable session tickets (in Node.js requires openssl.cnf)
tls.createServer({ key, cert, noTickets: true });
 
// Certificate pinning
tls.connect(443, 'bank.example.com', {
  pins: ['sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg='],
});
 
// Handshake timeout โ€” DoS protection
tls.connect(443, 'host', { handshakeTimeout: 5000 });
 
// Max handshake size โ€” prevents oversized certificate chains
tls.createServer({ key, cert, maxHandshakeSize: 65536 });
 
// Dynamic certificate selection (beyond SNI โ€” based on cipher, version, extensions)
tls.createServer({
  certificateCallback: (info, cb) => {
    // info = { servername, version, ciphers, sigalgs, groups, alpns }
    const ctx = pickCertFor(info);
    cb(null, ctx);
  }
});
 
// Wireshark debugging
socket.on('keylog', (line) => fs.appendFileSync('keys.log', line));
// Wireshark: Edit โ†’ Preferences โ†’ TLS โ†’ Pre-Master-Secret log filename โ†’ keys.log
 
// JA3 fingerprinting (server-side bot detection)
server.on('secureConnection', (socket) => {
  const ja3 = socket.getJA3();
  console.log(ja3.hash); // 'e7d705a3286e19ea42f587b344ee6865'
});
 
// Full negotiation result
socket.on('secureConnect', () => {
  console.log(socket.getNegotiationResult());
  // { version: 0x0304, versionName: 'TLSv1.3', cipher: 0x1301,
  //   cipherName: 'TLS_AES_128_GCM_SHA256', group: 0x001d, groupName: 'X25519',
  //   sni: 'example.com', alpn: 'h2', resumed: false, helloRetried: false,
  //   handshakeDuration: 23 }
});
 
// ECDHE shared secret access (for research)
console.log(socket.getSharedSecret()); // Buffer<...>

๐Ÿ›ฃ Roadmap

โœ… = Completed ๐Ÿ”„ = Implemented, needs testing โณ = Planned

โœ… Completed

Status Item
โœ… TLS 1.3 โ€” Server + Client
โœ… TLS 1.2 โ€” Server + Client
โœ… AES-128-GCM, AES-256-GCM, ChaCha20-Poly1305
โœ… X25519 / P-256 key exchange
โœ… RSA-PSS / ECDSA signatures
โœ… SNI, ALPN extensions
โœ… Session tickets + PSK resumption (TLS 1.3)
โœ… Extended Master Secret (RFC 7627, TLS 1.2)
โœ… Certificate validation (dates, hostname, CA chain)
โœ… Alert handling (close_notify, fatal alerts)
โœ… TLSSocket โ€” Node.js compatible Duplex stream
โœ… TLSSession โ€” raw state machine for QUIC/DTLS
โœ… record.js โ€” shared AEAD module for custom transports
โœ… Node.js tls compat โ€” connect(), createServer(), getCiphers()
โœ… 27 Node.js API compatibility methods verified
โœ… Zero dependencies โ€” node:crypto only
โœ… 45 automated tests

๐Ÿ”„ Implemented (Needs Testing)

Status Item Notes
๐Ÿ”„ HelloRetryRequest Group negotiation fallback, transcript message_hash
๐Ÿ”„ Key Update (TLS 1.3) rekeySend() / rekeyBoth() for long-lived connections
๐Ÿ”„ Client Certificate Auth mTLS with requestCert / cert / key options

โณ Planned

Status Item Notes
โณ DTLS 1.2/1.3 Datagram TLS over UDP
โณ 0-RTT Early Data Risky (replay attacks), low priority
โณ Full certificate chain validation Including revocation checks
โณ TypeScript typings Type safety and IDE integration
โณ Benchmarks & performance tuning Throughput, memory
โณ Fuzz testing Security hardening

๐Ÿงช Testing

npm test                     # 11 tests โ€” core TLS interop (OpenSSL)
node tests/test_https.js     # 7 tests โ€” HTTPS server (browser + curl)
node tests/test_compat.js    # 27 tests โ€” Node.js API compatibility

Core Tests (npm test)

Server tests (LemonTLS server โ†” openssl s_client):
  โœ… TLS 1.3 โ€” handshake + bidirectional data
  โœ… TLS 1.2 โ€” handshake + bidirectional data
  โœ… ChaCha20-Poly1305 โ€” cipher negotiation
  โœ… Session ticket โ€” sent to client
 
Client tests (Node.js tls server โ†” LemonTLS client):
  โœ… TLS 1.3 โ€” handshake + bidirectional data
  โœ… TLS 1.2 โ€” handshake + bidirectional data
 
Resumption (LemonTLS โ†” LemonTLS):
  โœ… PSK โ€” full handshake โ†’ ticket โ†’ resumed connection
 
Node.js compat API:
  โœ… tls.connect() / tls.createServer() / getCiphers()
  โœ… isSessionReused / getFinished / exportKeyingMaterial / ...

HTTPS Integration Test

node tests/test_https.js

Starts a real HTTPS server powered by LemonTLS. After tests pass, open in your browser:

https://localhost:19600/

Requires: Node.js โ‰ฅ 16, OpenSSL in PATH.

๐Ÿ“ Project Structure

index.js                 โ€” exports: TLSSocket, TLSSession, connect, createServer, crypto, wire, record
src/
  tls_session.js         โ€” TLS state machine (reactive set_context pattern)
  tls_socket.js          โ€” Duplex stream wrapper, Node.js compatible API
  record.js              โ€” shared AEAD encrypt/decrypt, key derivation
  wire.js                โ€” binary encode/decode of all TLS messages + constants
  crypto.js              โ€” key schedule (HKDF, PRF, resumption primitives)
  compat.js              โ€” Node.js tls API wrappers (connect, createServer, etc.)
  secure_context.js      โ€” PEM/DER cert/key loading
  utils.js               โ€” array helpers
  session/
    signing.js           โ€” signature scheme selection + signing
    ecdh.js              โ€” X25519/P-256 key exchange
    message.js           โ€” high-level message build/parse
tests/
  test_all.js            โ€” automated suite (npm test)
  test_https.js          โ€” HTTPS integration (stays running for browser)
  test_compat.js         โ€” Node.js API compatibility

๐Ÿค Contributing

Pull requests are welcome!
Please open an issue before submitting major changes.

๐Ÿ’– Sponsors

This project is part of the colocohen Node.js infrastructure stack (QUIC, WebRTC, DNSSEC, TLS, and more).
You can support ongoing development via GitHub Sponsors.

๐Ÿ“š References

๐Ÿ“œ License

Apache License 2.0

Copyright ยฉ 2025 colocohen

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.