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

⚠️ Project status: Active development.
APIs may change without notice until we reach v1.0.
Use at your own risk and please report issues!

• 🔒 Pure JavaScript – no OpenSSL, no native bindings.
• ⚡ TLS 1.3 (RFC 8446) + TLS 1.2 support.
• 🔑 Key Schedule – full HKDF-based derivation, AEAD, transcript hashing.
• 📜 X.509 Certificates – parsing and basic validation included.
• 🛡 Designed for extensibility – exposes cryptographic keys and record-layer primitives, making it possible to implement protocols such as QUIC, DTLS, or custom transports that depend on TLS. This level of flexibility is not possible when using OpenSSL directly.
• 🌐 Currently server-only – LemonTLS supports acting as a TLS server today.
  TLS client support is planned and under design.

npm i lemon-tls

import net from 'node:net';
import fs from 'node:fs';
import tls from 'lemon-tls';

// Example: TLS server over TCP
var server = net.createServer(function(tcp){
  
  var socket = new tls.TLSSocket(tcp, { 
    isServer: true, 
    minVersion: 'TLSv1.2',
    maxVersion: 'TLSv1.3',
    ALPNProtocols: ['http/1.1'],
    SNICallback: function (servername, cb) {
      console.log('get cert for: '+servername);
      cb(null, tls.createSecureContext({
        key: fs.readFileSync('YOUR_CERT_PEM_FILE_PATH'),
        cert: fs.readFileSync('YOUR_KEY_PEM_FILE_PATH')
      }));
    }
  });

  socket.on('secureConnect', function(){
    console.log('[SRV] secure handshake established');
    
    socket.write(new TextEncoder().encode('hi'));
  });

  socket.on('data', function(c){
    // echo
    socket.write(c);
  });

  socket.on('error', function(e){ console.error('[SRV TLS ERROR]', e); });
  socket.on('close', function(){ console.log('[SRV] closed'); });
});

server.listen(8443, function(){ console.log('[SRV] listening 8443'); });

TLSSession is the core state machine for a TLS connection. its exposes low-level cryptographic material:

• Handshake secrets and application traffic keys.
• Record-layer primitives for encrypting/decrypting TLS records.
• Hooks for ALPN, SNI, and extensions.

TLSSocket is a high-level wrapper designed to be API-compatible with Node.js tls.TLSSocket.
The main difference is that it uses a TLSSession from LemonTLS under the hood. This allows you to:

• Use familiar methods and events (secureConnect, data, end, etc.).
• Integrate seamlessly with existing Node.js applications.
• Gain access to LemonTLS’s advanced features by working directly with the underlying TLSSession if needed.

The following roadmap reflects the current and planned status of the LemonTLS project.
✅ = Completed 🔄 = In progress ⏳ = Planned ❌ = Not planned

Note: LemonTLS is an active work-in-progress project aiming to provide a fully auditable, pure JavaScript TLS implementation for Node.js and beyond.

Please ⭐ star the repo to follow progress!

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

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.

• RFC 8446 – TLS 1.3
• RFC 5246 – TLS 1.2

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.