lemon-tls

LemonTLS

🍋 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!

✨ Features

• 🔒 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.

📦 Installation

npm i lemon-tls

🚀 Example

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'); });

📚 API

TLSSession

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

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.

🛣 Roadmap

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

✅ Completed

Status	Item
✅	TLS 1.3 - Server mode
✅	X.509 certificate parsing (basic)

🔄 In Progress

Status	Item	Notes
🔄	TLS 1.3 - Client mode
🔄	TLS 1.2 - Server mode
🔄	TLS 1.2 - Client mode
🔄	Session tickets & resumption
🔄	ALPN & SNI extensions	API design ongoing
🔄	API alignment with Node.js tls.TLSSocket	Migration tests in progress
🔄	Modularization of key schedule & record layer	For reuse in QUIC/DTLS

⏳ Planned

Status	Item	Notes
⏳	DTLS support	Datagram TLS 1.2/1.3
⏳	Full certificate chain validation	Including revocation checks
⏳	Browser compatibility	Via WebCrypto integration
⏳	End-to-end interoperability tests	Against OpenSSL, rustls
⏳	Benchmarks & performance tuning	Resource usage, throughput
⏳	Fuzz testing & robustness checks	To improve security
⏳	Developer documentation & API reference	For easier onboarding
⏳	TypeScript typings	Type safety and IDE integration

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!

🤝 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.

📚 Documentation

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

📜 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.