lemon-tls 0.9.0 → 0.10.0

package/README.md

@@ -530,6 +530,11 @@ Everything above has a DTLS twin. Same TLS state machine underneath, same
 methods, plus datagram-specific plumbing (retransmission flights, epoch
 handling, cookie exchange):
 
+Retransmission under loss: in DTLS 1.3 an ACK that covers only part of a
+flight retires only those records — the rest are resent when the timer
+fires (RFC 9147 §7.1) — and a client keeps resending its final flight until
+the peer ACKs it or sends protected data (§5.8.3).
+
 ```js
 import { DTLSSession, DTLSSocket, createDTLSServer, connectDTLS } from 'lemon-tls';
 ```

package/index.cjs

@@ -1,12 +1,14 @@
 /**
  * CJS wrapper for lemon-tls.
- * 
- * On Node 22+, require('lemon-tls') works natively with the ESM module.
- * On Node 16-21, this wrapper provides require() support via dynamic import.
  *
- * Usage:
- *   const tls = require('lemon-tls');           // sync on Node 22+
- *   const tls = await require('lemon-tls');     // async on Node 16-21
+ * lemon-tls needs Node 24+ (package.json "engines"), where require() of an
+ * ES module is built in: require('lemon-tls') returns the module itself,
+ * synchronously.
+ *
+ *   const tls = require('lemon-tls');
+ *
+ * The fallback below — a Promise of the module — is for a runtime or bundler
+ * whose require() cannot load ES modules; there, `await require('lemon-tls')`.
  */
 
 let cached = null;
@@ -21,7 +23,7 @@ try {
   const m = require('./index.js');
   module.exports = m.default || m;
 } catch (e) {
-  // Node 16-21: return a promise that resolves to the module
+  // require() of ES modules not available: a promise of the module.
   // Users need: const tls = await require('lemon-tls');
   module.exports = load();
   module.exports.__esModule = true;

package/index.d.ts

@@ -7,9 +7,58 @@ import type { X509Certificate } from 'node:crypto';
 
 // ======================== Types ========================
 
+/** A key or certificate: PEM or DER bytes, or a file path. */
+export type PemInput = Buffer | Uint8Array | string;
+
+/**
+ * createSecureContext()'s options. `key` and `cert` as arrays — node:tls's
+ * form — for several certificates of different kinds (an ML-DSA one for
+ * clients that ask for post-quantum authentication, an ECDSA or RSA one for
+ * the rest): each key is paired with the chain whose leaf carries its public
+ * key, the first being the default.
+ */
+export interface SecureContextOptions {
+  key?: PemInput | Array<PemInput | { pem: PemInput; passphrase?: string }>;
+  cert?: PemInput | PemInput[];
+  ca?: PemInput | PemInput[];
+  passphrase?: string;
+  pfx?: PemInput;
+  /** A stapled OCSP response (DER) for the leaf. */
+  ocsp?: PemInput;
+  ticketKeys?: Buffer | Uint8Array;
+  [option: string]: any;
+}
+
 export interface SecureContext {
   certificateChain: Array<{ cert: Buffer }>;
   privateKey: any;
+  ca?: any[];
+  /** The other key/certificate pairs (key/cert arrays). */
+  alternates?: Array<{ certificateChain: Array<{ cert: Buffer }>; privateKey: any }>;
+}
+
+/** An Encrypted Client Hello key (RFC 9849), from generateEchKey(). */
+export interface EchKey {
+  config: Uint8Array;
+  privateKey: Uint8Array;
+  configList: Uint8Array;
+  /** The value of `ech=` in the domain's HTTPS record. */
+  configListBase64: string;
+}
+
+/** A server's `ech` option. `retry: false`: still accepted, no longer offered to clients. */
+export interface EchServerOption {
+  keys: Array<{ config: Uint8Array | Buffer | string; privateKey: Uint8Array | Buffer | string; retry?: boolean }>;
+}
+
+/** A saved session ('session' event's Buffer) described without its secrets: sessionInfo(). */
+export interface SessionInfo {
+  version: 'TLSv1.3' | 'TLSv1.2' | null;
+  servername: string | null;
+  alpn: string | null;
+  created: number | null;
+  expiresAt: number | null;
+  earlyData: boolean;
 }
 
 export interface CipherInfo {
@@ -19,6 +68,7 @@ export interface CipherInfo {
 }
 
 export interface PeerCertificate {
+  /** RDN fields as node:tls has them: { C, ST, L, O, OU, CN }. */
   subject: any;
   issuer: any;
   subjectaltname?: string;
@@ -107,12 +157,19 @@ export interface CertificateCallbackInfo {
 export interface TLSSocketOptions {
   isServer?: boolean;
   servername?: string;
-  SNICallback?: (servername: string, cb: (err: Error | null, ctx: SecureContext | null) => void) => void;
+  SNICallback?: (servername: string, cb: (err: Error | null, ctx?: SecureContext | null) => void) => void;
+  /** Server, node:tls's: pick the protocol from what the client offers (exclusive with ALPNProtocols on a Server). */
+  ALPNCallback?: (info: { servername: string | null; protocols: string[] }) => string | undefined;
   minVersion?: 'TLSv1.2' | 'TLSv1.3';
   maxVersion?: 'TLSv1.2' | 'TLSv1.3';
   ALPNProtocols?: string[];
   rejectUnauthorized?: boolean;
-  ca?: Buffer | string;
+  /** Client: the identity check (node:tls's); undefined for a match, an Error otherwise. */
+  checkServerIdentity?: (hostname: string, cert: PeerCertificate) => Error | undefined;
+  ca?: PemInput | PemInput[];
+  /** A context from createSecureContext(), in place of key/cert/ca. */
+  secureContext?: SecureContext;
+  passphrase?: string;
   ticketKeys?: Buffer;
   /**
    * Server: what to carry inside each session ticket issued. Called once per
@@ -128,8 +185,53 @@ export interface TLSSocketOptions {
    */
   session?: Buffer | Uint8Array;
   requestCert?: boolean;
-  cert?: Buffer | string;
-  key?: Buffer | string;
+  cert?: PemInput;
+  key?: PemInput;
+
+  // node:tls's option strings — taken as Node takes them. lemon-tls's code
+  // lists (allowedCipherSuites, groups, signatureAlgorithms) win when given.
+  /** 'TLS_AES_128_GCM_SHA256:ECDHE-RSA-AES128-GCM-SHA256…' */
+  ciphers?: string;
+  /** 'X25519:P-256', or 'auto'. */
+  ecdhCurve?: string;
+  /** 'ecdsa_secp256r1_sha256:rsa_pss_rsae_sha256…' */
+  sigalgs?: string;
+  /** Server: the cipher suite by the server's order (default: the client's). */
+  honorCipherOrder?: boolean;
+
+  // ---- Encrypted Client Hello (RFC 9849) ----
+  /** Server: { keys }. Client: the server's ECHConfigList (bytes, or base64 — `ech=` of its HTTPS record). */
+  ech?: EchServerOption | Uint8Array | Buffer | string;
+  /** Client: GREASE ECH, without a config. */
+  echGrease?: boolean;
+
+  // ---- OCSP stapling ----
+  /** Server: asked when a client requests status; callback(null, response DER) or (null, null). */
+  ocspRequest?: (certificate: Buffer, issuer: Buffer | null, callback: (err: Error | null, response: Buffer | Uint8Array | null) => void) => void;
+  /** Client: ask the server for a stapled response ('OCSPResponse'). */
+  requestOCSP?: boolean;
+
+  /** RFC 8879: ['brotli', 'zlib', 'zstd'] in order, true (all this build has) or false (none). */
+  certificateCompression?: Array<'brotli' | 'zlib' | 'zstd'> | boolean;
+
+  // ---- 0-RTT (RFC 8446 §4.2.10) ----
+  /** Server: issue tickets that allow it, and take it. Client: with `session`, what is written before 'secureConnect' goes early. */
+  earlyData?: boolean;
+  /** Server: ms the client's ticket age may differ from ours. */
+  earlyDataMaxAge?: number;
+  /** Server: the anti-replay store — cb(null, true) when `id` is new (keep it `ttl` ms). */
+  earlyDataReplay?: (id: string, ttl: number, cb: (err: Error | null, fresh: boolean) => void) => void;
+  /** Server: bytes of early data a ticket allows (16 KB). */
+  maxEarlyData?: number;
+
+  // ---- ClientHello shaping (client) ----
+  grease?: boolean;
+  permuteExtensions?: boolean;
+
+  /** Client: trust the bundled CAs when no `ca` is given (default: true). */
+  useDefaultCA?: boolean;
+  allowHalfOpen?: boolean;
+  highWaterMark?: number;
 
   // TCP options, as in node:net. connect() passes them (and the rest of
   // net.connect's: localAddress, localPort, family, lookup, timeout) to
@@ -162,6 +264,27 @@ export interface TLSSocketOptions {
   customExtensions?: Array<{ type: number; data: Uint8Array }>;
 }
 
+/** connect()'s: the socket's options, where, and node:net's. */
+export interface ConnectOptions extends TLSSocketOptions {
+  port?: number;
+  host?: string;
+  /** STARTTLS: an existing socket to run TLS on (no net.connect). */
+  socket?: Duplex;
+  lookup?: (...args: any[]) => void;
+  [option: string]: any;
+}
+
+/** createServer()'s: the server side of TLSSocketOptions, and node:tls's server ones. */
+export interface ServerOptions extends Omit<TLSSocketOptions, 'key' | 'cert'> {
+  key?: SecureContextOptions['key'];
+  cert?: SecureContextOptions['cert'];
+  /** Seconds a session stays good — tickets and TLS 1.2 Session IDs (Node's default, 300). */
+  sessionTimeout?: number;
+  /** Sessions under one context do not resume under another. */
+  sessionIdContext?: string | Buffer;
+  pauseOnConnect?: boolean;
+}
+
 // ======================== TLSSocket ========================
 
 export class TLSSocket extends Duplex {
@@ -170,7 +293,8 @@ export class TLSSocket extends Duplex {
   // ------- Node.js tls.TLSSocket compatible API -------
   getProtocol(): string | null;
   getCipher(): CipherInfo | null;
-  getPeerCertificate(): PeerCertificate | null;
+  /** `detailed` is accepted for node:tls's signature; the leaf is described either way. */
+  getPeerCertificate(detailed?: boolean): PeerCertificate | null;
   /** Returns our LOCAL cert (what we presented). Empty object if none. */
   getCertificate(): PeerCertificate | {};
   /** Returns the peer cert as a native crypto.X509Certificate object (Node 15.9+). */
@@ -180,10 +304,16 @@ export class TLSSocket extends Duplex {
   isSessionReused(): boolean;
   getFinished(): Buffer | null;
   getPeerFinished(): Buffer | null;
-  exportKeyingMaterial(length: number, label: string, context: Buffer): Buffer;
-  getEphemeralKeyInfo(): EphemeralKeyInfo;
+  /** null before the handshake completes (Node throws). */
+  exportKeyingMaterial(length: number, label: string, context?: Buffer | Uint8Array): Buffer | null;
+  /** null on a server socket, as in Node. */
+  getEphemeralKeyInfo(): EphemeralKeyInfo | {} | null;
+  /** On sockets from connect() and createServer() (compat layer). */
   disableRenegotiation(): void;
+  /** On sockets from connect() and createServer() (compat layer). */
   setServername(name: string): void;
+  /** The transport's bound address, as node:tls's. */
+  address(): { port?: number; family?: string; address?: string };
   /** Returns the opaque serialized session Buffer, or undefined. */
   getSession(): Buffer | undefined;
   /** Returns the TLS 1.2 session ticket as a Buffer, or undefined (incl. for TLS 1.3). */
@@ -225,6 +355,18 @@ export class TLSSocket extends Duplex {
   /** Returns the underlying TLSSession for low-level access. */
   session: TLSSession;
   readonly handshakeDuration: number | null;
+  /** 0-RTT. Server: what is read now came early (it may be a replay). Client: it is sending early. */
+  readonly isEarlyData: boolean;
+  readonly earlyDataBytes: number;
+  readonly earlyDataStatus: 'offered' | 'accepted' | 'rejected' | null;
+  /** Encrypted Client Hello: what happened to it on this connection. */
+  readonly echStatus: string | null;
+  readonly echAccepted: boolean;
+  /** Server: the certificate to present, from inside ALPNCallback (a context or { key, cert }). */
+  setKeyCert(context: SecureContext | SecureContextOptions): void;
+  /** The peer's hello extensions: [{ type, name, data, value }]. */
+  getRemoteExtensions(): Array<{ type: number; name: string | null; data: Uint8Array; value: any }>;
+  getRemoteExtension(type: number): { type: number; name: string | null; data: Uint8Array; value: any } | null;
   /** JA4 of the ClientHello — the published format, what fingerprint
    *  databases match. Changes when a client resumes (pre_shared_key). */
   getJA4(opts?: FingerprintOptions): FingerprintResult | null;
@@ -256,6 +398,13 @@ export class TLSSocket extends Duplex {
   on(event: 'certificateRequest', listener: (msg: any) => void): this;
   on(event: 'newSession', listener: (id: Buffer, data: Buffer, cb: () => void) => void): this;
   on(event: 'resumeSession', listener: (id: Buffer, cb: (err: Error | null, data: Buffer | null) => void) => void): this;
+  /** Client: the server's stapled OCSP response (requestOCSP). */
+  on(event: 'OCSPResponse', listener: (response: Buffer) => void): this;
+  /** 0-RTT decided: whether the server took it. */
+  on(event: 'earlyData', listener: (accepted: boolean) => void): this;
+  on(event: 'alert', listener: (alert: { level: number; description: number }) => void): this;
+  on(event: 'secure', listener: () => void): this;
+  on(event: 'psk', listener: (identity: any, callback: (result: { psk: Buffer; cipher: number } | null) => void) => void): this;
   on(event: 'error', listener: (err: Error) => void): this;
   on(event: 'close', listener: () => void): this;
   on(event: string, listener: (...args: any[]) => void): this;
@@ -274,8 +423,19 @@ export class Server extends EventEmitter {
   close(callback?: (err?: Error) => void): this;
   address(): { port: number; family: string; address: string } | string | null;
 
-  /** Replace the server's key/cert at runtime (Let's Encrypt renewals, etc.). */
-  setSecureContext(options: { key: Buffer | string; cert: Buffer | string }): void;
+  getConnections(callback: (err: Error | null, count: number) => void): void;
+  /** Node's documented injection of a Duplex into the server ('connection'), as a method. */
+  injectConnection(stream: Duplex): this;
+  ref(): this;
+  unref(): this;
+
+  /** Replace the server's key/cert at runtime (Let's Encrypt renewals, etc.). Throws on a bad one; the old stays. */
+  setSecureContext(options: SecureContextOptions | { secureContext: SecureContext }): void;
+  /** A certificate for an SNI name or wildcard ('*.example.com': one label). The latest wins; an exact name beats a wildcard. */
+  addContext(hostname: string, context: SecureContext | SecureContextOptions): this;
+  /** Encrypted Client Hello keys, rotated without a restart. */
+  getEchKeys(): EchServerOption | null;
+  setEchKeys(ech: EchServerOption | null): void;
   /** Returns the 48-byte TLS session ticket encryption keys. */
   getTicketKeys(): Buffer;
   /** Sets the 48-byte TLS session ticket encryption keys (for clustered deployments). */
@@ -287,6 +447,11 @@ export class Server extends EventEmitter {
   on(event: 'secureConnection', listener: (socket: TLSSocket) => void): this;
   on(event: 'tlsClientError', listener: (err: Error, socket: TLSSocket | null) => void): this;
   on(event: 'keylog', listener: (line: Buffer, socket: TLSSocket) => void): this;
+  /** Before the TLS handshake: the raw socket. */
+  on(event: 'connection', listener: (socket: Duplex) => void): this;
+  on(event: 'OCSPRequest', listener: (certificate: Buffer, issuer: Buffer | null, callback: (err: Error | null, response: Buffer | Uint8Array | null) => void) => void): this;
+  on(event: 'listening', listener: () => void): this;
+  on(event: 'drop', listener: (data: any) => void): this;
   on(event: 'newSession', listener: (id: Buffer, data: Buffer, cb: () => void) => void): this;
   on(event: 'resumeSession', listener: (id: Buffer, cb: (err: Error | null, data: Buffer | null) => void) => void): this;
   on(event: 'error', listener: (err: Error) => void): this;
@@ -389,16 +554,41 @@ export class TLSSession extends EventEmitter {
 
 // ======================== Module Functions ========================
 
-export function createSecureContext(options: { key: Buffer | string; cert: Buffer | string }): SecureContext;
+export function createSecureContext(options: SecureContextOptions): SecureContext;
 
-export function connect(port: number, host: string, options?: TLSSocketOptions, callback?: () => void): TLSSocket;
+export function connect(port: number, host: string, options?: ConnectOptions, callback?: () => void): TLSSocket;
 export function connect(port: number, host: string, callback?: () => void): TLSSocket;
-export function connect(options: TLSSocketOptions & { port: number; host?: string }, callback?: () => void): TLSSocket;
-
-export function createServer(
-  options: TLSSocketOptions & { key?: Buffer | string; cert?: Buffer | string },
-  connectionListener?: (socket: TLSSocket) => void
-): Server;
+export function connect(options: ConnectOptions, callback?: () => void): TLSSocket;
+
+export function createServer(options: ServerOptions, connectionListener?: (socket: TLSSocket) => void): Server;
+export function createServer(connectionListener?: (socket: TLSSocket) => void): Server;
+
+// ---- node:tls's option strings → code lists (null when unset). They throw
+//      on a name they do not know, as Node's createServer does.
+export function parseCiphers(ciphers: string | null | undefined): number[] | null;
+export function parseEcdhCurve(ecdhCurve: string | null | undefined): number[] | null;
+export function parseSigalgs(sigalgs: string | null | undefined): number[] | null;
+export function parseTlsVersion(version: string | null | undefined, optionName?: string): number | null;
+export function parseCertificateCompression(value: Array<'brotli' | 'zlib' | 'zstd'> | boolean | null | undefined): number[] | null;
+
+/** A server's certificate chain compressed now, in the background (RFC 8879), so the first handshake does not wait for it. */
+export function precompressCertificate(secureContext: SecureContext, algorithms?: Array<'brotli' | 'zlib' | 'zstd'> | boolean, callback?: () => void): void;
+export function precompressCertificate(secureContext: SecureContext, callback?: () => void): void;
+
+/** The key-exchange groups a server offers by default, in order (code points). */
+export const DEFAULT_SERVER_GROUPS: readonly number[];
+/** The signature schemes offered by default, in order (code points). */
+export const DEFAULT_SIGNATURE_SCHEMES: readonly number[];
+
+/** A saved session described without its secrets; null if it is not one. */
+export function sessionInfo(session: Buffer | Uint8Array): SessionInfo | null;
+/** A certificate (DER) as getPeerCertificate() describes it. */
+export function certificateObject(der: Buffer | Uint8Array): PeerCertificate | { raw: Buffer | Uint8Array } | null;
+
+/** A new ECH key for a server. publicName: the name the outer hello carries (the server holds a certificate for it). */
+export function generateEchKey(options: { publicName: string; configId?: number; maxNameLength?: number; kem?: string | number }): EchKey;
+/** Throws, saying what is wrong, if a server's `ech` option would not work. */
+export function checkEchKeys(ech: EchServerOption | null | undefined): void;
 
 export function getCiphers(): string[];
 
@@ -448,6 +638,16 @@ export declare const crypto: {
   /** RFC 8446 §7.5 exporter; labelPrefix defaults to TLS 1.3's ('tls13 '). */
   tls13_exporter: (hash: string, exporterMasterSecret: Uint8Array, label: string,
                    context: Uint8Array | null, length: number, labelPrefix?: string) => Uint8Array;
+  /** HPKE (RFC 9180) — what ECH encrypts with. */
+  hpke: {
+    suite: (...args: any[]) => any;
+    setupSender: (...args: any[]) => any;
+    setupRecipient: (...args: any[]) => any;
+    seal: (...args: any[]) => any;
+    open: (...args: any[]) => any;
+    generateKeyPair: (...args: any[]) => any;
+    deriveKeyPair: (...args: any[]) => any;
+  };
 };
 
 export declare const wire: any;
@@ -493,6 +693,18 @@ declare const _default: {
   crypto: typeof crypto;
   wire: typeof wire;
   record: typeof record;
+  parseCiphers: typeof parseCiphers;
+  parseEcdhCurve: typeof parseEcdhCurve;
+  parseSigalgs: typeof parseSigalgs;
+  parseTlsVersion: typeof parseTlsVersion;
+  parseCertificateCompression: typeof parseCertificateCompression;
+  precompressCertificate: typeof precompressCertificate;
+  DEFAULT_SERVER_GROUPS: typeof DEFAULT_SERVER_GROUPS;
+  DEFAULT_SIGNATURE_SCHEMES: typeof DEFAULT_SIGNATURE_SCHEMES;
+  sessionInfo: typeof sessionInfo;
+  certificateObject: typeof certificateObject;
+  generateEchKey: typeof generateEchKey;
+  checkEchKeys: typeof checkEchKeys;
   DTLSSession: typeof DTLSSession;
   DTLSSocket: typeof DTLSSocket;
   createDTLSServer: typeof createDTLSServer;

package/package.json

@@ -1,10 +1,26 @@
 {
   "name": "lemon-tls",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "TLS 1.3/1.2 DTLS 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.",
   "main": "index.js",
   "type": "module",
   "types": "index.d.ts",
+  "typesVersions": {
+    "*": {
+      "wire": [
+        "types/wire.d.ts"
+      ],
+      "crypto": [
+        "types/crypto.d.ts"
+      ],
+      "record": [
+        "types/record.d.ts"
+      ],
+      "session": [
+        "types/session.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "types": "./index.d.ts",
@@ -12,22 +28,35 @@
       "require": "./index.cjs",
       "default": "./index.js"
     },
-    "./wire": "./src/wire.js",
-    "./crypto": "./src/crypto.js",
-    "./record": "./src/record.js",
-    "./session": "./src/tls_session.js"
+    "./wire": {
+      "types": "./types/wire.d.ts",
+      "default": "./src/wire.js"
+    },
+    "./crypto": {
+      "types": "./types/crypto.d.ts",
+      "default": "./src/crypto.js"
+    },
+    "./record": {
+      "types": "./types/record.d.ts",
+      "default": "./src/record.js"
+    },
+    "./session": {
+      "types": "./types/session.d.ts",
+      "default": "./src/tls_session.js"
+    }
   },
   "files": [
     "index.js",
     "index.cjs",
     "index.d.ts",
+    "types/",
     "src/",
     "README.md",
     "LICENSE",
     "lemontls.svg"
   ],
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=24.0.0"
   },
   "keywords": [
     "tls",
@@ -70,6 +99,10 @@
     "alpn",
     "ja3",
     "ja3-fingerprint",
+    "ja4",
+    "ja4-fingerprint",
+    "ja5",
+    "ja5-fingerprint",
     "fingerprint",
     "keylog",
     "wireshark",

package/src/compat.js

@@ -603,6 +603,12 @@ function Server(options, connectionListener) {
     return self._tcpServer.getConnections(cb);
   };
 
+  // node:net's: whether it is listening, and whether the process may exit
+  // while it does.
+  Object.defineProperty(self, 'listening', { get: function() { return self._tcpServer.listening; }, enumerable: true });
+  self.ref = function() { self._tcpServer.ref(); return self; };
+  self.unref = function() { self._tcpServer.unref(); return self; };
+
   // Ticket key management
   self.getTicketKeys = function() {
     return Buffer.from(self._ticketKeys);
@@ -631,11 +637,13 @@ function Server(options, connectionListener) {
     self._ech = ech || null;
   };
 
-  // setSecureContext — replace cert/key without restart (Node.js compat)
+  // setSecureContext — replace cert/key without restart (Node.js compat).
+  // A bad one throws, as Node's does, and the certificate in use stays: it
+  // returned quietly when key or cert was missing, and a renewal that read
+  // an empty file went unnoticed until the old certificate expired.
   self.setSecureContext = function(opts) {
-    if (!opts) return;
-    if (opts.secureContext) { defaultCtx = opts.secureContext; return; }
-    if (opts.key && opts.cert) defaultCtx = createSecureContext(opts);
+    if (!opts || typeof opts !== 'object') throw new TypeError('setSecureContext requires { key, cert } or { secureContext }');
+    defaultCtx = opts.secureContext ? opts.secureContext : createSecureContext(opts);
   };
 
   /**

package/src/dtls_session.js

@@ -291,6 +291,7 @@ function DTLSSession(options) {
     // the ACK arrives.
     pendingWriteEpoch: null,
     keyUpdateFlight: null,     // { payload, epoch, timer, attempts, timeout }
+    finalFlightPending: false, // DTLS 1.3 client: final flight not yet confirmed (see secureConnect)
 
     retransmitTimer: null,
     retransmitCount: 0,
@@ -750,9 +751,10 @@ function DTLSSession(options) {
     }
 
     for (let i = 0; i < frags.length; i++) {
-      let record = buildRecord(dtlsEpoch, CT.HANDSHAKE, frags[i]);
       // The flight captures the fragment, not the record — see currentFlight.
-      ctx.currentFlight.push({ epoch: dtlsEpoch, contentType: CT.HANDSHAKE, payload: frags[i] });
+      let entry = { epoch: dtlsEpoch, contentType: CT.HANDSHAKE, payload: frags[i] };
+      let record = buildFlightRecord(entry);
+      ctx.currentFlight.push(entry);
       if (record) {
         _ldbgTx(record, 'L543'); ev.emit('packet', record);
       } else {
@@ -1074,6 +1076,9 @@ function DTLSSession(options) {
       processHandshakeRecord(record.content, record.epoch, record.encrypted);
     } else if (record.type === CT.APPLICATION_DATA) {
       if (ctx.state === 'connected') {
+        // Protected data from the peer means it completed the handshake,
+        // so it has our Finished.
+        if (ctx.finalFlightPending) finalFlightDone();
         ev.emit('data', record.content);
       }
     } else if (record.type === CT.CHANGE_CIPHER_SPEC) {
@@ -1574,17 +1579,31 @@ function DTLSSession(options) {
     // payload never came from the application at all.
     // RFC 9147 §5.8: retransmission is bounded by the handshake; after
     // it, ACKs are the mechanism, not a timer.
-    if (ctx.state === 'connected' || ctx.state === 'closed') {
+    if (ctx.state === 'closed' || (ctx.state === 'connected' && !ctx.finalFlightPending)) {
       cancelRetransmit();
       return;
     }
     for (let i = 0; i < ctx.currentFlight.length; i++) {
       let f = ctx.currentFlight[i];
-      let record = buildRecord(f.epoch, f.contentType, f.payload);
+      // DTLS 1.3 (RFC 9147 §7.1): records the peer has ACKed are not resent.
+      if (f.acked) continue;
+      let record = buildFlightRecord(f);
       if (record) { _ldbgTx(record, 'L1280'); ev.emit('packet', record); }
     }
   }
 
+  /**
+   * Build the record for a flight entry and remember its record number
+   * (epoch, sequence) — every transmission gets a fresh one, and a DTLS 1.3
+   * ACK names the records it covers by those numbers.
+   */
+  function buildFlightRecord(f) {
+    let seq = (f.epoch in ctx.writeSeq) ? ctx.writeSeq[f.epoch] : 0;
+    let record = buildRecord(f.epoch, f.contentType, f.payload);
+    if (record) (f.sent || (f.sent = [])).push(f.epoch * 0x1000000000000 + seq);
+    return record;
+  }
+
   function startRetransmitTimer() {
     cancelRetransmit();
     // ONE GATE, AT THE SOURCE. Four call sites arm this timer and only
@@ -1593,8 +1612,13 @@ function DTLSSession(options) {
     // flight into the application-data epoch. Refusing to arm once
     // connected (or closed) covers every caller, including any added
     // later, without each having to remember the rule.
-    if (ctx.state === 'connected' || ctx.state === 'closed') return;
+    if (ctx.state === 'closed' || (ctx.state === 'connected' && !ctx.finalFlightPending)) return;
     ctx.retransmitTimer = setTimeout(function() {
+      if (ctx.finalFlightPending && ctx.retransmitCount >= ctx.maxRetransmits) {
+        // The connection is up on our side; stop resending without failing it.
+        finalFlightDone();
+        return;
+      }
       if (ctx.retransmitCount >= ctx.maxRetransmits) {
         ev.emit('error', new Error('DTLS handshake timeout — max retransmits exceeded'));
         ctx.state = 'closed';
@@ -1613,6 +1637,13 @@ function DTLSSession(options) {
     if (ctx.retransmitTimer.unref) ctx.retransmitTimer.unref();
   }
 
+  // The client's final flight is known to have arrived: stop resending it.
+  function finalFlightDone() {
+    ctx.finalFlightPending = false;
+    cancelRetransmit();
+    startNewFlight();
+  }
+
   function cancelRetransmit() {
     if (ctx.retransmitTimer !== null) {
       clearTimeout(ctx.retransmitTimer);
@@ -1646,10 +1677,37 @@ function DTLSSession(options) {
       return;
     }
 
-    // Everything else keeps the original behaviour verbatim. In particular the
-    // ACK for the client's final flight (which RFC 9147 §7.1 requires the peer
-    // to send explicitly, and which arrives at the application epoch) must
-    // still cancel that flight's retransmit timer.
+    // During the handshake an ACK may cover only PART of our flight (RFC 9147
+    // §7.1): the peer lists the records it received. Those are done; the
+    // rest stay under the retransmit timer and are what the next
+    // retransmission resends. Treating any ACK as acknowledging the whole
+    // flight cancelled the timer while a record was still missing — the
+    // peer, waiting for it, ACKed again and again, and the handshake hung
+    // (≈ half of all handshakes at 5% loss, when the lost record was inside
+    // the server's flight).
+    if ((ctx.state !== 'connected' || ctx.finalFlightPending) && ctx.currentFlight.length > 0) {
+      let got = new Set();
+      for (let i = 0; i < acks.length; i++) got.add(acks[i].epoch * 0x1000000000000 + acks[i].seq);
+      let remaining = 0;
+      for (let i = 0; i < ctx.currentFlight.length; i++) {
+        let f = ctx.currentFlight[i];
+        if (!f.acked && f.sent) {
+          for (let k = 0; k < f.sent.length; k++) {
+            if (got.has(f.sent[k])) { f.acked = true; break; }
+          }
+        }
+        // Plaintext epoch-0 records (ServerHello, CCS) are never ACKed — the
+        // peer acknowledges them implicitly by answering — so they do not
+        // keep the timer alive on their own.
+        if (!f.acked && f.epoch !== 0) remaining++;
+      }
+      if (remaining > 0) return;
+    }
+
+    // The whole flight is acknowledged — or, the ACK for the client's final
+    // flight (which RFC 9147 §7.1 requires the peer to send explicitly, and
+    // which arrives at the application epoch): cancel the retransmit timer.
+    ctx.finalFlightPending = false;
     cancelRetransmit();
     startNewFlight();
   }
@@ -1700,8 +1758,18 @@ function DTLSSession(options) {
     _ldbg('handshake complete — secureConnect (version=0x' +
       ((ctx.selectedVersion || tls.context.selected_version || 0).toString(16)) + ')');
     ctx.state = 'connected';
-    cancelRetransmit();
-    startNewFlight();
+    // DTLS 1.3 client (RFC 9147 §5.8.3, §7.1): our final flight (…Finished)
+    // is answered by nothing but an ACK, so it must stay under the
+    // retransmit timer until that ACK — or anything else from the peer at
+    // the application epoch — shows it arrived. Dropping it here meant one
+    // lost Finished left us "connected" and the peer waiting for good.
+    if (!isServer && ctx.selectedVersion === DTLS_VERSION.DTLS1_3 && ctx.currentFlight.length > 0) {
+      ctx.finalFlightPending = true;
+      startRetransmitTimer();
+    } else {
+      cancelRetransmit();
+      startNewFlight();
+    }
     ev.emit('connect');
   });
 

package/src/record.js

@@ -665,6 +665,21 @@ function readU48(buf, off) {
 }
 
 /** AES-ECB encrypt a single 16-byte block (for DTLS 1.3 record number encryption). */
+// One AES-ECB cipher per sn_key, reused for every record's number mask
+// (RFC 9147 §4.2.3) instead of creating one per record. ECB keeps no state
+// between blocks, so update() on 16 bytes always returns exactly that block's
+// encryption. Keyed by the key object, which lives as long as its epoch's keys.
+var _snEcbCache = new WeakMap();
+function _snKeyEcb(key) {
+  var c = _snEcbCache.get(key);
+  if (!c) {
+    c = crypto.createCipheriv(key.length === 32 ? 'aes-256-ecb' : 'aes-128-ecb', key, null);
+    c.setAutoPadding(false);
+    _snEcbCache.set(key, c);
+  }
+  return c;
+}
+
 function aesEcbEncrypt(key, block) {
   let algo = key.length === 32 ? 'aes-256-ecb' : 'aes-128-ecb';
   let cipher = crypto.createCipheriv(algo, key, null);
@@ -785,8 +800,8 @@ function decryptDtls12(fragment, key, ivSalt, epoch, seq, type) {
   // ChaCha20-Poly1305: no explicit nonce; nonce = iv(12) XOR (epoch||seq).
   if (ivSalt.length === 12) {
     if (fragment.length < 16) throw new Error('DTLS 1.2 ChaCha fragment too short');
-    let ct  = fragment.slice(0, fragment.length - 16);
-    let tag = fragment.slice(fragment.length - 16);
+    let ct  = fragment.subarray(0, fragment.length - 16);   // views: only read
+    let tag = fragment.subarray(fragment.length - 16);
     let seq64 = epoch * 0x1000000000000 + seq;
     let nonce = getChachaNonce12(ivSalt, seq64);
     let aad = buildDtlsAad12(epoch, seq, type, ct.length);
@@ -802,9 +817,9 @@ function decryptDtls12(fragment, key, ivSalt, epoch, seq, type) {
 
   // AES-GCM: strip the 8-byte explicit nonce.
   if (fragment.length < 24) throw new Error('DTLS 1.2 fragment too short');
-  let explicit = fragment.slice(0, 8);
-  let tag = fragment.slice(fragment.length - 16);
-  let ct = fragment.slice(8, fragment.length - 16);
+  let explicit = fragment.subarray(0, 8);   // views: only read
+  let tag = fragment.subarray(fragment.length - 16);
+  let ct = fragment.subarray(8, fragment.length - 16);
   let nonce = getNonce12(ivSalt, explicit);
   let aad = buildDtlsAad12(epoch, seq, type, ct.length);
   let algo = key.length === 16 ? 'aes-128-gcm' : 'aes-256-gcm';
@@ -819,8 +834,38 @@ function decryptDtls12(fragment, key, ivSalt, epoch, seq, type) {
 
 /** Build complete encrypted DTLS 1.2 record (header + encrypted payload). */
 function buildEncryptedDtls12(type, epoch, seq, plaintext, keys) {
-  let encrypted = encryptDtls12(plaintext, keys.key, keys.iv, epoch, seq, type);
-  return buildDtlsPlaintext(type, epoch, seq, encrypted);
+  // Same bytes as buildDtlsPlaintext(type, epoch, seq, encryptDtls12(...)),
+  // written straight into the record instead of through two more buffers.
+  let key = keys.key, ivSalt = keys.iv;
+  let chacha = ivSalt.length === 12;
+  let explicitLen = chacha ? 0 : 8;
+  let fragLen = explicitLen + plaintext.length + 16;
+  let out = new Uint8Array(13 + fragLen);
+  let off = 0;
+  off = w_u8(out, off, type);
+  off = w_u16(out, off, 0xFEFD);
+  off = w_u16(out, off, epoch);
+  off = w_u48(out, off, seq);
+  off = w_u16(out, off, fragLen);
+  let aad = buildDtlsAad12(epoch, seq, type, plaintext.length);
+  let cipher;
+  if (chacha) {
+    let nonce = getChachaNonce12(ivSalt, epoch * 0x1000000000000 + seq);
+    cipher = crypto.createCipheriv('chacha20-poly1305', key, nonce, { authTagLength: 16 });
+    cipher.setAAD(aad, { plaintextLength: plaintext.length });
+  } else {
+    // AES-GCM: explicit nonce (= record seq) prepended.
+    let explicit = seqToBytes(seq);
+    out.set(explicit, off); off += 8;
+    cipher = crypto.createCipheriv(key.length === 16 ? 'aes-128-gcm' : 'aes-256-gcm', key, getNonce12(ivSalt, explicit));
+    cipher.setAAD(aad);
+  }
+  let ct = cipher.update(plaintext);
+  out.set(ct, off); off += ct.length;
+  let fin = cipher.final();
+  if (fin.length) { out.set(fin, off); off += fin.length; }
+  out.set(cipher.getAuthTag(), off);
+  return out;
 }
 
 
@@ -898,7 +943,7 @@ function maskRecordNumber(snKey, rnBytes, ciphertext, algo) {
     let c = crypto.createCipheriv('chacha20', snKey, iv);
     mask = new Uint8Array(c.update(Buffer.alloc(16)));
   } else {
-    mask = aesEcbEncrypt(snKey, ciphertext.subarray(0, 16));
+    mask = _snKeyEcb(snKey).update(ciphertext.subarray(0, 16));
   }
 
   let out = new Uint8Array(rnBytes.length);
@@ -926,42 +971,43 @@ function buildEncryptedDtls13(innerType, plaintext, seq, epoch, keys) {
   let info = buildUnifiedHdr(epoch, true, true, false);
 
   // Plaintext record number
-  let rn = new Uint8Array(2);
-  rn[0] = (seq >>> 8) & 0xFF;
-  rn[1] = seq & 0xFF;
-
-  // Inner plaintext: content + content_type
-  let inner = new Uint8Array(plaintext.length + 1);
-  inner.set(plaintext, 0);
-  inner[plaintext.length] = innerType;
+  let rn0 = (seq >>> 8) & 0xFF, rn1 = seq & 0xFF;
 
-  let encLen = inner.length + 16;
+  // Inner plaintext = content || content_type. Fed to the cipher in two
+  // pieces rather than first copied into one buffer.
+  let innerLen = plaintext.length + 1;
+  let encLen = innerLen + 16;
 
   // AAD = header with PLAINTEXT record number (before RN encryption)
   let aad = new Uint8Array(5);
   aad[0] = info;
-  aad[1] = rn[0];
-  aad[2] = rn[1];
+  aad[1] = rn0;
+  aad[2] = rn1;
   aad[3] = (encLen >>> 8) & 0xFF;
   aad[4] = encLen & 0xFF;
 
   // Nonce (reuse TLS 1.3 nonce construction)
   let nonce = getNonce(keys.iv, seq);
 
-  // AEAD encrypt
+  // AEAD encrypt, written straight into the record: info(1) + encrypted
+  // rn(2) + length(2) + ciphertext. (It used to pass through three buffers:
+  // inner plaintext, ciphertext+tag, then the record.)
   let cipher = crypto.createCipheriv(algo, keys.key, nonce,
     isChaCha ? { authTagLength: 16 } : undefined);
-  cipher.setAAD(aad, isChaCha ? { plaintextLength: inner.length } : undefined);
-  let ct = cipher.update(inner);
-  cipher.final();
-  let tag = cipher.getAuthTag();
-
-  let ciphertext = new Uint8Array(ct.length + tag.length);
-  ciphertext.set(new Uint8Array(ct), 0);
-  ciphertext.set(new Uint8Array(tag), ct.length);
+  cipher.setAAD(aad, isChaCha ? { plaintextLength: innerLen } : undefined);
+  let record = new Uint8Array(5 + encLen);
+  let off = 5;
+  let ct1 = cipher.update(plaintext);
+  record.set(ct1, off); off += ct1.length;
+  let ct2 = cipher.update(_contentTypeByte(innerType));
+  record.set(ct2, off); off += ct2.length;
+  let ct3 = cipher.final();
+  if (ct3.length) { record.set(ct3, off); off += ct3.length; }
+  record.set(cipher.getAuthTag(), off);
+  let ciphertext = record.subarray(5);
 
   // Encrypt record number
-  let encRn = maskRecordNumber(keys.snKey, rn, ciphertext, algo);
+  let encRn = maskRecordNumber(keys.snKey, [rn0, rn1], ciphertext, algo);
 
   // ── DIAGNOSTIC (LEMON_DEBUG=1 / WEBRTC_DEBUG=1) ──────────────────────
   // Everything a peer needs to PARSE this record, printed as we build it.
@@ -971,34 +1017,39 @@ function buildEncryptedDtls13(innerType, plaintext, seq, epoch, keys) {
   // present), the sequence number before and after masking, and the
   // declared length against the actual ciphertext size. If two records
   // are accepted and the third is not, the difference between them shows
-  // up here.
-  try {
-    if (typeof process !== 'undefined' && process.env &&
-        (process.env.LEMON_DEBUG === '1' || process.env.WEBRTC_DEBUG === '1')) {
+  // up here. (Flag read once at load: process.env is slow to read per record.)
+  if (_REC_DEBUG) {
+    try {
       var _h = function (b) { return ('0' + (b & 0xFF).toString(16)).slice(-2); };
       console.log('[lemon-rec] TX info=0x' + _h(info) +
         ' [C=' + ((info >> 4) & 1) + ' S=' + ((info >> 3) & 1) +
         ' L=' + ((info >> 2) & 1) + ' epoch=' + (info & 0x03) + ']' +
-        ' seqPlain=' + _h(rn[0]) + _h(rn[1]) +
+        ' seqPlain=' + _h(rn0) + _h(rn1) +
         ' seqMasked=' + _h(encRn[0]) + _h(encRn[1]) +
         ' declaredLen=' + ciphertext.length +
-        ' aadLen=' + (aad ? aad.length : 'null') +
+        ' aadLen=' + aad.length +
         ' snKey=' + (keys.snKey ? 'set' : 'MISSING'));
-    }
-  } catch (_e) {}
+    } catch (_e) {}
+  }
   // ─────────────────────────────────────────────────────────────────────
 
-  // Assemble: info(1) + encrypted_rn(2) + length(2) + ciphertext
-  let record = new Uint8Array(5 + ciphertext.length);
   record[0] = info;
   record[1] = encRn[0];
   record[2] = encRn[1];
   record[3] = (ciphertext.length >>> 8) & 0xFF;
   record[4] = ciphertext.length & 0xFF;
-  record.set(ciphertext, 5);
   return record;
 }
 
+var _REC_DEBUG = typeof process !== 'undefined' && process.env &&
+  (process.env.LEMON_DEBUG === '1' || process.env.WEBRTC_DEBUG === '1');
+
+// The one-byte content type appended to a DTLS 1.3 inner plaintext.
+var _CT_BYTES = [];
+function _contentTypeByte(t) {
+  return _CT_BYTES[t] || (_CT_BYTES[t] = new Uint8Array([t]));
+}
+
 /**
  * Reconstruct a full DTLS 1.3 record sequence number from its truncated wire
  * encoding (RFC 9147 §4.2.2).
@@ -1093,7 +1144,9 @@ function decryptEncryptedDtls13(data, keys, fullEpoch) {
   }
 
   if (off + ctLen > data.length) return null;
-  let ciphertext = data.slice(off, off + ctLen);
+  // A view: only read here (record-number mask, AEAD input); the plaintext
+  // comes out of the decipher as a fresh buffer.
+  let ciphertext = data.subarray(off, off + ctLen);
 
   // Resolve the AEAD before unmasking: the record-number mask is built with
   // the same primitive as the AEAD (AES-ECB vs ChaCha20), so `algo` is needed
@@ -1178,23 +1231,34 @@ function decryptEncryptedDtls13(data, keys, fullEpoch) {
     // next to maxReadSeq, because both are per-epoch receive state.
     //   replayWindow: bitmask of the 64 seqs at or below maxReadSeq that have
     //   been accepted. Bit 0 = maxReadSeq, bit k = maxReadSeq - k.
+    //   The 64-bit window is kept as two 32-bit numbers (replayLo = bits
+    //   0..31, replayHi = 32..63): same window, no BigInt allocations per
+    //   record.
     if (keys.maxReadSeq === undefined || keys.maxReadSeq < 0) {
       // First accepted record in this epoch: seed the window with this seq as
       // the high-water mark (bit 0 set), so an immediate replay of it is
       // caught below rather than sailing through an unset window.
       keys.maxReadSeq = seq;
-      keys.replayWindow = 1n;
+      keys.replayLo = 1; keys.replayHi = 0;
     } else if (seq > keys.maxReadSeq) {
       // Advance: shift the window up by the gap, then set bit 0.
-      let shift = BigInt(seq - keys.maxReadSeq);
-      keys.replayWindow = shift >= 64n ? 1n : ((keys.replayWindow << shift) | 1n) & ((1n << 64n) - 1n);
+      let shift = seq - keys.maxReadSeq;
+      let lo = keys.replayLo, hi = keys.replayHi;
+      if (shift >= 64) { lo = 0; hi = 0; }
+      else if (shift >= 32) { hi = (lo << (shift - 32)) >>> 0; lo = 0; }
+      else { hi = ((hi << shift) | (lo >>> (32 - shift))) >>> 0; lo = (lo << shift) >>> 0; }
+      keys.replayLo = (lo | 1) >>> 0; keys.replayHi = hi;
       keys.maxReadSeq = seq;
     } else {
-      let back = BigInt(keys.maxReadSeq - seq);
-      if (back >= 64n) return null;                // too old — outside window
-      let bit = 1n << back;
-      if (keys.replayWindow & bit) return null;     // already seen — replay
-      keys.replayWindow |= bit;
+      let back = keys.maxReadSeq - seq;
+      if (back >= 64) return null;                  // too old — outside window
+      if (back < 32) {
+        if ((keys.replayLo >>> back) & 1) return null;   // already seen — replay
+        keys.replayLo = (keys.replayLo | (1 << back)) >>> 0;
+      } else {
+        if ((keys.replayHi >>> (back - 32)) & 1) return null;
+        keys.replayHi = (keys.replayHi | (1 << (back - 32))) >>> 0;
+      }
     }
 
     return {
@@ -1292,19 +1356,23 @@ function parseDtlsDatagram(data, keysByEpoch) {
       let length  = readU16(data, off + 11);
       if (off + 13 + length > data.length) break;
 
-      let payload = data.slice(off + 13, off + 13 + length);
+      let payload = null;
       let encrypted = false;
 
-      // DTLS 1.2: decrypt if epoch > 0 and keys available
+      // DTLS 1.2: decrypt if epoch > 0 and keys available. The ciphertext is
+      // only read (the plaintext comes out of the decipher as a fresh
+      // buffer), so it is passed as a view; a record kept as it is — not
+      // decrypted — gets its own copy, as before.
       if (epoch > 0 && keysByEpoch && keysByEpoch[epoch]) {
         let keys = keysByEpoch[epoch];
         try {
-          payload = decryptDtls12(payload, keys.key, keys.iv, epoch, seq, type);
+          payload = decryptDtls12(data.subarray(off + 13, off + 13 + length), keys.key, keys.iv, epoch, seq, type);
           encrypted = true;
         } catch(e) {
           // Decryption failed — return raw
         }
       }
+      if (payload === null) payload = data.slice(off + 13, off + 13 + length);
 
       records.push({
         type: type,

package/src/secure_context.js

@@ -186,6 +186,20 @@ function createSecureContext(options) {
     if (!privateKey) throw new Error('createSecureContext: missing private key.');
   }
 
+  // The key must be the certificate's — node:tls throws on this too
+  // (KEY_VALUES_MISMATCH). Unchecked, a renewal that paired the new key with
+  // the old certificate went in without a word, and every handshake after it
+  // failed at the client's signature check.
+  if (keyObj && certObjs.length > 0) {
+    let fromKey = crypto.createPublicKey(keyObj).export({ type: 'spki', format: 'der' });
+    let fromCert = certObjs[0].publicKey.export({ type: 'spki', format: 'der' });
+    if (Buffer.compare(Buffer.from(fromKey), Buffer.from(fromCert)) !== 0) {
+      let e = new Error('createSecureContext: the private key does not match the certificate');
+      e.code = 'ERR_OSSL_X509_KEY_VALUES_MISMATCH';
+      throw e;
+    }
+  }
+
   // --- CA (Trust store) ---
   let ca = normalizeCA(options.ca);
 

package/src/tls_session.js

@@ -1866,10 +1866,10 @@ function TLSSession(options){
     dbg('SRV-NST', 'issuing TLS 1.3 NST — cipher:', '0x' + context.selected_cipher_suite.toString(16),
         'hash:', hashName,
         'transcript len:', concatUint8Arrays(context.transcript).length);
-    dbg('SRV-NST', 'ticket_nonce:', hexPreview(ticket_nonce, 4),
+    if (LEMON_DEBUG) dbg('SRV-NST', 'ticket_nonce:', hexPreview(ticket_nonce, 4),
         'age_add:', ticket_age_add,
         'lifetime:', ticket_lifetime);
-    dbg('SRV-NST', 'resumption_master_secret:', hexPreview(context.resumption_master_secret, 8),
+    if (LEMON_DEBUG) dbg('SRV-NST', 'resumption_master_secret:', hexPreview(context.resumption_master_secret, 8),
         'derived psk:', hexPreview(psk, 8));
 
     // Ensure ticketKeys is 48 bytes (key_name + aes_key)
@@ -2319,7 +2319,7 @@ function TLSSession(options){
         context.ticket_offered = true;
         let pskBinder = message.pre_shared_key.binders ? message.pre_shared_key.binders[0] : null;
 
-        dbg('SRV-PSK', 'received identity:', hexPreview(pskIdentity.identity, 24),
+        if (LEMON_DEBUG) dbg('SRV-PSK', 'received identity:', hexPreview(pskIdentity.identity, 24),
             'age:', (pskIdentity.age || 0) >>> 0,
             'received binder:', hexPreview(pskBinder, 16));
 
@@ -2337,7 +2337,7 @@ function TLSSession(options){
         });
         if (pskResult === undefined) pskResult = open_ticket_13(pskIdentity.identity);
 
-        dbg('SRV-PSK', 'pskResult:', pskResult ? `psk=${hexPreview(pskResult.psk, 8)} cipher=0x${pskResult.cipher?.toString(16)}` : 'null (decrypt failed)');
+        if (LEMON_DEBUG) dbg('SRV-PSK', 'pskResult:', pskResult ? `psk=${hexPreview(pskResult.psk, 8)} cipher=0x${pskResult.cipher?.toString(16)}` : 'null (decrypt failed)');
 
         if (pskResult && pskResult.psk && !same_server_name(pskResult.sni, message.sni)) {
           dbg('SRV-PSK', 'ticket for another server name — full handshake');
@@ -2361,8 +2361,8 @@ function TLSSession(options){
           dbg('SRV-PSK', 'hash:', hashName, 'hashLen:', hashLen,
               'truncatedCH len:', truncatedCH.length,
               'full CH len:', data.length);
-          dbg('SRV-PSK', 'expected binder:', hexPreview(expectedBinder, 16));
-          dbg('SRV-PSK', 'received binder:', hexPreview(pskBinder, 16));
+          if (LEMON_DEBUG) dbg('SRV-PSK', 'expected binder:', hexPreview(expectedBinder, 16));
+          if (LEMON_DEBUG) dbg('SRV-PSK', 'received binder:', hexPreview(pskBinder, 16));
 
           // Constant-time binder comparison. A byte-by-byte early-exit compare
           // would let an attacker recover a valid binder via timing, one byte at
@@ -2972,7 +2972,7 @@ function TLSSession(options){
         let sentSid  = context.local_session_id;
         let hasTicket = context.tls12_client_session.ticket && context.tls12_client_session.ticket.length > 0;
 
-        dbg('CLI-12RESUME', 'saved sid:', hexPreview(savedSid, 16),
+        if (LEMON_DEBUG) dbg('CLI-12RESUME', 'saved sid:', hexPreview(savedSid, 16),
             'sent sid:', hexPreview(sentSid, 16),
             'received sid:', hexPreview(message.session_id, 16),
             'hasTicket:', hasTicket);
@@ -3435,10 +3435,10 @@ function TLSSession(options){
           dbg('CLI-NST', 'received TLS 1.3 NST — cipher:', '0x' + context.selected_cipher_suite.toString(16),
               'hash:', hashName,
               'transcript len:', concatUint8Arrays(context.transcript).length);
-          dbg('CLI-NST', 'ticket_nonce:', hexPreview(message.ticket_nonce, 4),
+          if (LEMON_DEBUG) dbg('CLI-NST', 'ticket_nonce:', hexPreview(message.ticket_nonce, 4),
               'age_add:', message.ticket_age_add,
               'lifetime:', message.ticket_lifetime);
-          dbg('CLI-NST', 'resumption_master_secret:', hexPreview(context.resumption_master_secret, 8),
+          if (LEMON_DEBUG) dbg('CLI-NST', 'resumption_master_secret:', hexPreview(context.resumption_master_secret, 8),
               'derived psk:', hexPreview(psk, 8));
 
           // Encode opaque client-side session Buffer (JSON — user is responsible for secure storage)
@@ -6597,17 +6597,17 @@ function TLSSession(options){
         let binder_key = derive_binder_key(hashName, context.psk_offered.psk, false, label_prefix());
         let binder = compute_psk_binder(hashName, binder_key, truncatedMessage, label_prefix());
 
-        dbg('CLI-PSK', 'ticket:', hexPreview(sessionData.ticket, 24),
+        if (LEMON_DEBUG) dbg('CLI-PSK', 'ticket:', hexPreview(sessionData.ticket, 24),
             'cipher:', '0x' + sessionData.cipher.toString(16),
             'hash:', hashName);
-        dbg('CLI-PSK', 'psk:', hexPreview(sessionData.psk, 8),
+        if (LEMON_DEBUG) dbg('CLI-PSK', 'psk:', hexPreview(sessionData.psk, 8),
             'age_add:', sessionData.age_add,
             'lifetime:', sessionData.lifetime,
             'ticketAge (ms):', ticketAge,
             'obfuscatedAge:', obfuscatedAge);
         dbg('CLI-PSK', 'truncatedMessage len:', truncatedMessage.length,
             'full CH len (after real binder):', 'see next');
-        dbg('CLI-PSK', 'sent binder:', hexPreview(binder, 16));
+        if (LEMON_DEBUG) dbg('CLI-PSK', 'sent binder:', hexPreview(binder, 16));
 
         // Rebuild with real binder
         pskExt.value.binders = [binder];

package/types/crypto.d.ts

@@ -0,0 +1,40 @@
+// lemon-tls/crypto — Key schedule primitives: HKDF, the TLS 1.3 secrets, exporters, cipher-suite tables.
+// Low-level: typed loosely; see the source for each signature.
+
+export declare const DEFAULT_CIPHER_SUITES_TLS12: any;
+export declare const DEFAULT_CIPHER_SUITES_TLS13: any;
+export declare const LABEL_PREFIX_DTLS13: string;
+export declare const LABEL_PREFIX_TLS13: string;
+export declare const TLS_CIPHER_SUITES: any;
+export declare function build_cert_verify_tbs(...args: any[]): any;
+export declare function build_cert_verify_tbs_with_hash(...args: any[]): any;
+export declare function build_hkdf_label(...args: any[]): any;
+export declare function compute_psk_binder(...args: any[]): any;
+export declare function default_cipher_suites(...args: any[]): any;
+export declare function derive_app_traffic_secrets(...args: any[]): any;
+export declare function derive_app_traffic_secrets_with_hash(...args: any[]): any;
+export declare function derive_binder_key(...args: any[]): any;
+export declare function derive_client_early_traffic_secret(...args: any[]): any;
+export declare function derive_exporter_master_secret_with_hash(...args: any[]): any;
+export declare function derive_handshake_traffic_secrets(...args: any[]): any;
+export declare function derive_handshake_traffic_secrets_psk(...args: any[]): any;
+export declare function derive_handshake_traffic_secrets_psk_with_hash(...args: any[]): any;
+export declare function derive_handshake_traffic_secrets_with_hash(...args: any[]): any;
+export declare function derive_psk(...args: any[]): any;
+export declare function derive_resumption_master_secret(...args: any[]): any;
+export declare function derive_resumption_master_secret_with_hash(...args: any[]): any;
+export declare function derive_sn_key(...args: any[]): any;
+export declare function getHashFn(...args: any[]): any;
+export declare function getHashLen(...args: any[]): any;
+export declare function get_handshake_finished(...args: any[]): any;
+export declare function get_handshake_finished_with_hash(...args: any[]): any;
+export declare function hkdf_expand(...args: any[]): any;
+export declare function hkdf_expand_label(...args: any[]): any;
+export declare function hkdf_extract(...args: any[]): any;
+export declare function hmac(...args: any[]): any;
+export declare function is_usable_cipher_suite(...args: any[]): any;
+export declare function suite_matches_version(...args: any[]): any;
+export declare function tls12_exporter(...args: any[]): any;
+export declare function tls12_prf(...args: any[]): any;
+export declare function tls13_exporter(...args: any[]): any;
+export declare function tls_derive_from_master_secret_tls12(...args: any[]): any;

package/types/record.d.ts

@@ -0,0 +1,40 @@
+// lemon-tls/record — The record layer: AEAD keys and nonces, encrypt/decrypt for TLS and DTLS records.
+// Low-level: typed loosely; see the source for each signature.
+
+export declare const CT: any;
+export declare function aesEcbEncrypt(...args: any[]): any;
+export declare function buildAad12(...args: any[]): any;
+export declare function buildDtlsAad12(...args: any[]): any;
+export declare function buildDtlsAck(...args: any[]): any;
+export declare function buildDtlsPlaintext(...args: any[]): any;
+export declare function buildEncryptedDtls12(...args: any[]): any;
+export declare function buildEncryptedDtls13(...args: any[]): any;
+export declare function buildUnifiedHdr(...args: any[]): any;
+export declare function decrypt12(...args: any[]): any;
+export declare function decryptDtls12(...args: any[]): any;
+export declare function decryptEncryptedDtls13(...args: any[]): any;
+export declare function decryptRecord(...args: any[]): any;
+export declare function decryptRecordWithAadView(...args: any[]): any;
+export declare function deriveKeys(...args: any[]): any;
+export declare function deriveKeys12(...args: any[]): any;
+export declare function encrypt12(...args: any[]): any;
+export declare function encryptCompleteRecord12(...args: any[]): any;
+export declare function encryptCompleteRecord13(...args: any[]): any;
+export declare function encryptDtls12(...args: any[]): any;
+export declare function encryptRecord(...args: any[]): any;
+export declare function getAeadAlgo(...args: any[]): any;
+export declare function getChachaNonce12(...args: any[]): any;
+export declare function getNonce(...args: any[]): any;
+export declare function getNonce12(...args: any[]): any;
+export declare function getNonceInto(...args: any[]): any;
+export declare function isUnifiedHdr(...args: any[]): any;
+export declare function maskRecordNumber(...args: any[]): any;
+export declare function parseDtlsAck(...args: any[]): any;
+export declare function parseDtlsDatagram(...args: any[]): any;
+export declare function parseDtlsPlaintext(...args: any[]): any;
+export declare function parseInnerPlaintext(...args: any[]): any;
+export declare function parseUnifiedHdr(...args: any[]): any;
+export declare function reconstructDtlsSeq(...args: any[]): any;
+export declare function resolveReadEpoch(...args: any[]): any;
+export declare function seqToBytes(...args: any[]): any;
+export declare function writeRecord(...args: any[]): any;

package/types/session.d.ts

@@ -0,0 +1,3 @@
+// lemon-tls/session — the TLS state machine on its own, with no socket.
+import { TLSSession } from '../index.js';
+export default TLSSession;

package/types/wire.d.ts

@@ -0,0 +1,62 @@
+// lemon-tls/wire — TLS and DTLS messages: parse_* and build_* for each handshake message, and the codes (TLS_EXT, TLS_ALERT, …).
+// Low-level: typed loosely; see the source for each signature.
+
+export declare const DTLS_VERSION: any;
+export declare const HANDSHAKE_MESSAGE_MAX: number;
+export declare const TLS13_HRR_RANDOM: any;
+export declare const TLS_ALERT: any;
+export declare const TLS_ALERT_LEVEL: any;
+export declare const TLS_CONTENT_TYPE: any;
+export declare const TLS_EXT: any;
+export declare const TLS_MESSAGE_TYPE: any;
+export declare const TLS_VERSION: any;
+export declare function build_certificate(...args: any[]): any;
+export declare function build_certificate_request(...args: any[]): any;
+export declare function build_certificate_status(...args: any[]): any;
+export declare function build_certificate_verify(...args: any[]): any;
+export declare function build_client_key_exchange_ecdhe(...args: any[]): any;
+export declare function build_client_key_exchange_rsa(...args: any[]): any;
+export declare function build_compressed_certificate(...args: any[]): any;
+export declare function build_dtls_handshake(...args: any[]): any;
+export declare function build_extensions(...args: any[]): any;
+export declare function build_hello(...args: any[]): any;
+export declare function build_hello_retry_request(...args: any[]): any;
+export declare function build_hello_verify_request(...args: any[]): any;
+export declare function build_key_update(...args: any[]): any;
+export declare function build_message(...args: any[]): any;
+export declare function build_new_session_ticket(...args: any[]): any;
+export declare function build_new_session_ticket_tls12(...args: any[]): any;
+export declare function build_server_ecdh_params(...args: any[]): any;
+export declare function build_server_key_exchange_ecdhe(...args: any[]): any;
+export declare const exts: any;
+export declare function is_tls12_wire(...args: any[]): any;
+export declare function is_tls13_wire(...args: any[]): any;
+export declare function parse_certificate(...args: any[]): any;
+export declare function parse_certificate_request(...args: any[]): any;
+export declare function parse_certificate_status(...args: any[]): any;
+export declare function parse_certificate_verify(...args: any[]): any;
+export declare function parse_client_key_exchange_ecdhe(...args: any[]): any;
+export declare function parse_client_key_exchange_rsa(...args: any[]): any;
+export declare function parse_compressed_certificate(...args: any[]): any;
+export declare function parse_dtls_handshake(...args: any[]): any;
+export declare function parse_extension_list(...args: any[]): any;
+export declare function parse_extensions(...args: any[]): any;
+export declare function parse_hello(...args: any[]): any;
+export declare function parse_hello_verify_request(...args: any[]): any;
+export declare function parse_key_update(...args: any[]): any;
+export declare function parse_message(...args: any[]): any;
+export declare function parse_new_session_ticket(...args: any[]): any;
+export declare function parse_new_session_ticket_tls12(...args: any[]): any;
+export declare function parse_server_key_exchange(...args: any[]): any;
+export declare function r_bytes(...args: any[]): any;
+export declare function r_u16(...args: any[]): any;
+export declare function r_u24(...args: any[]): any;
+export declare function r_u8(...args: any[]): any;
+export declare function readVec(...args: any[]): any;
+export declare function veclen(...args: any[]): any;
+export declare function w_bytes(...args: any[]): any;
+export declare function w_u16(...args: any[]): any;
+export declare function w_u24(...args: any[]): any;
+export declare function w_u48(...args: any[]): any;
+export declare function w_u64(...args: any[]): any;
+export declare function w_u8(...args: any[]): any;