lemon-tls 0.2.2 → 0.3.0

package/index.d.ts

@@ -3,6 +3,7 @@
 import { Duplex } from 'node:stream';
 import { EventEmitter } from 'node:events';
 import type { Server as NetServer } from 'node:net';
+import type { X509Certificate } from 'node:crypto';
 
 // ======================== Types ========================
 
@@ -18,8 +19,8 @@ export interface CipherInfo {
 }
 
 export interface PeerCertificate {
-  subject: string;
-  issuer: string;
+  subject: any;
+  issuer: any;
   subjectaltname?: string;
   valid_from: string;
   valid_to: string;
@@ -55,6 +56,10 @@ export interface NegotiationResult {
   handshakeDuration: number | null;
 }
 
+/**
+ * Payload of the 'session' event on TLSSession (raw internal form).
+ * The TLSSocket-level 'session' event emits an opaque Buffer (Node-compatible).
+ */
 export interface SessionTicketData {
   ticket: Buffer;
   ticket_nonce: Buffer;
@@ -86,13 +91,19 @@ export interface TLSSocketOptions {
   rejectUnauthorized?: boolean;
   ca?: Buffer | string;
   ticketKeys?: Buffer;
-  session?: SessionTicketData;
+  /**
+   * Opaque serialized session from a previous 'session' event.
+   * Pass this back to resume a TLS 1.2/1.3 session.
+   */
+  session?: Buffer | Uint8Array;
   requestCert?: boolean;
   cert?: Buffer | string;
   key?: Buffer | string;
 
   // LemonTLS-only options
   noTickets?: boolean;
+  sessionTickets?: boolean;
+  ticketLifetime?: number;
   signatureAlgorithms?: number[];
   groups?: number[];
   prioritizeChaCha?: boolean;
@@ -110,10 +121,16 @@ export interface TLSSocketOptions {
 export class TLSSocket extends Duplex {
   constructor(transport: Duplex | null, options: TLSSocketOptions);
 
-  // Node.js compatible
+  // ------- Node.js tls.TLSSocket compatible API -------
   getProtocol(): string | null;
   getCipher(): CipherInfo | null;
   getPeerCertificate(): 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+). */
+  getPeerX509Certificate(): X509Certificate | undefined;
+  /** Returns our LOCAL cert as a native crypto.X509Certificate object. */
+  getX509Certificate(): X509Certificate | undefined;
   isSessionReused(): boolean;
   getFinished(): Buffer | null;
   getPeerFinished(): Buffer | null;
@@ -121,16 +138,46 @@ export class TLSSocket extends Duplex {
   getEphemeralKeyInfo(): EphemeralKeyInfo;
   disableRenegotiation(): void;
   setServername(name: string): void;
+  /** 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). */
+  getTLSTicket(): Buffer | undefined;
+  /** Returns signature algorithm names shared between client and server (server side). */
+  getSharedSigalgs(): string[];
+  /** Caps outgoing plaintext fragment size. Must be in [512, 16384]. */
+  setMaxSendFragment(size: number): boolean;
+  /** Node-compat no-op (we don't wrap OpenSSL). Use 'keylog' / 'handshakeMessage' for insight. */
+  enableTrace(): void;
   setSocket(transport: Duplex): void;
 
-  readonly isResumed: boolean;
   readonly authorized: boolean;
   readonly authorizationError: string | null;
+  /** The negotiated ALPN protocol string (e.g. 'h2'), or false. */
   readonly alpnProtocol: string | false;
+  /** Always true for TLSSocket. */
   readonly encrypted: boolean;
-
-  // LemonTLS-only
-  getSession(): TLSSession;
+  /** SNI value — on server, the name the client sent; on client, the name we sent. */
+  readonly servername: string | false;
+
+  // net.Socket compat (delegated to underlying transport)
+  readonly remoteAddress: string | undefined;
+  readonly remotePort: number | undefined;
+  readonly remoteFamily: string | undefined;
+  readonly localAddress: string | undefined;
+  readonly localPort: number | undefined;
+  readonly localFamily: string | undefined;
+  readonly bytesRead: number;
+  readonly bytesWritten: number;
+  setNoDelay(noDelay?: boolean): this;
+  setKeepAlive(enable?: boolean, initialDelay?: number): this;
+  setTimeout(timeout: number, callback?: () => void): this;
+  ref(): this;
+  unref(): this;
+
+  // ------- LemonTLS-only extensions -------
+  readonly isResumed: boolean;
+  /** Returns the underlying TLSSession for low-level access. */
+  session: TLSSession;
   readonly handshakeDuration: number | null;
   getJA3(): JA3Result | null;
   getSharedSecret(): Buffer | null;
@@ -138,15 +185,54 @@ export class TLSSocket extends Duplex {
   rekeySend(): void;
   rekeyBoth(): void;
 
-  // Events
+  // ------- Events -------
   on(event: 'secureConnect', listener: () => void): this;
   on(event: 'data', listener: (data: Buffer) => void): this;
-  on(event: 'session', listener: (data: SessionTicketData) => void): this;
-  on(event: 'keyUpdate', listener: (direction: 'send' | 'receive') => void): this;
+  /**
+   * Emits an opaque Buffer (Node-compatible). Pass it back into tls.connect({ session })
+   * to resume. The Buffer is our internal encoded session blob.
+   */
+  on(event: 'session', listener: (data: Buffer) => void): this;
   on(event: 'keylog', listener: (line: Buffer) => void): this;
+  on(event: 'keyUpdate', listener: (direction: 'send' | 'receive') => void): this;
   on(event: 'clienthello', listener: (raw: Buffer, parsed: any) => void): this;
   on(event: 'handshakeMessage', listener: (type: string, raw: Buffer, parsed: any) => void): this;
   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;
+  on(event: 'error', listener: (err: Error) => void): this;
+  on(event: 'close', listener: () => void): this;
+  on(event: string, listener: (...args: any[]) => void): this;
+}
+
+// ======================== Server ========================
+
+/**
+ * Node.js tls.Server compatible server. Returned by createServer().
+ * Extends EventEmitter and wraps a net.Server internally.
+ */
+export class Server extends EventEmitter {
+  listen(port: number, host?: string, callback?: () => void): this;
+  listen(port: number, callback?: () => void): this;
+  listen(options: { port?: number; host?: string }, callback?: () => void): this;
+  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;
+  /** Returns the 48-byte TLS session ticket encryption keys. */
+  getTicketKeys(): Buffer;
+  /** Sets the 48-byte TLS session ticket encryption keys (for clustered deployments). */
+  setTicketKeys(keys: Buffer): void;
+
+  readonly listening: boolean;
+
+  // Events
+  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;
+  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;
   on(event: 'close', listener: () => void): this;
   on(event: string, listener: (...args: any[]) => void): this;
@@ -160,11 +246,12 @@ export interface TLSSessionOptions {
   ALPNProtocols?: string[];
   SNICallback?: (servername: string, cb: (err: Error | null, ctx: SecureContext | null) => void) => void;
   ticketKeys?: Buffer;
-  session?: SessionTicketData;
+  session?: Buffer | Uint8Array | SessionTicketData;
   psk?: any;
   rejectUnauthorized?: boolean;
   ca?: Buffer | string;
   noTickets?: boolean;
+  sessionTickets?: boolean;
   maxHandshakeSize?: number;
   customExtensions?: Array<{ type: number; data: Uint8Array }>;
   requestCert?: boolean;
@@ -222,12 +309,16 @@ export class TLSSession extends EventEmitter {
   on(event: 'message', listener: (epoch: number, seq: number, type: string, data: Uint8Array) => void): this;
   on(event: 'hello', listener: () => void): this;
   on(event: 'secureConnect', listener: () => void): this;
-  on(event: 'session', listener: (data: SessionTicketData) => void): this;
+  /** Emits the raw internal session blob (Buffer/Uint8Array — encoded session state). */
+  on(event: 'session', listener: (data: Buffer) => void): this;
   on(event: 'psk', listener: (identity: Buffer, callback: (result: { psk: Buffer; cipher: number } | null) => void) => void): this;
   on(event: 'keyUpdate', listener: (info: { direction: 'send' | 'receive'; secret: Uint8Array }) => void): this;
+  on(event: 'keylog', listener: (line: Buffer) => void): this;
   on(event: 'clienthello', listener: (raw: Buffer, parsed: any) => void): this;
   on(event: 'handshakeMessage', listener: (type: string, raw: Buffer, parsed: any) => void): this;
   on(event: 'certificateRequest', listener: (msg: any) => void): this;
+  on(event: 'newSession', listener: (id: Uint8Array, data: Uint8Array, cb: () => void) => void): this;
+  on(event: 'resumeSession', listener: (id: Uint8Array, cb: (err: Error | null, data: Uint8Array | null) => void) => void): this;
   on(event: 'error', listener: (err: Error) => void): this;
   on(event: string, listener: (...args: any[]) => void): this;
 }
@@ -235,13 +326,32 @@ export class TLSSession extends EventEmitter {
 // ======================== Module Functions ========================
 
 export function createSecureContext(options: { key: Buffer | string; cert: Buffer | string }): SecureContext;
+
 export function connect(port: number, host: string, options?: TLSSocketOptions, 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): NetServer;
+
+export function createServer(
+  options: TLSSocketOptions & { key?: Buffer | string; cert?: Buffer | string },
+  connectionListener?: (socket: TLSSocket) => void
+): Server;
+
 export function getCiphers(): string[];
 
+/**
+ * Validates that the peer certificate matches the hostname (RFC 6125).
+ * Returns undefined on success, or an Error on mismatch.
+ * This is the default check used when rejectUnauthorized is true; apps can
+ * override it via the checkServerIdentity option in tls.connect.
+ */
+export function checkServerIdentity(hostname: string, cert: PeerCertificate): Error | undefined;
+
 export const DEFAULT_MIN_VERSION: string;
 export const DEFAULT_MAX_VERSION: string;
+/** Node-compat: default colon-separated cipher string. */
+export const DEFAULT_CIPHERS: string;
+/** Node-compat: default ECDH curve selection policy ('auto'). */
+export const DEFAULT_ECDH_CURVE: string;
 
 // ======================== Submodules ========================
 
@@ -264,20 +374,41 @@ export declare const record: {
   decryptRecord: (ciphertext: Uint8Array, key: Uint8Array, nonce: Uint8Array, algo: string) => Uint8Array;
 };
 
+// ======================== DTLS ========================
+// DTLS bindings are exported from the package but typed loosely here —
+// use the JS source directly for exact signatures.
+
+export declare class DTLSSession extends EventEmitter {
+  constructor(options: any);
+}
+export declare class DTLSSocket extends EventEmitter {
+  constructor(options: any);
+}
+export declare function createDTLSServer(options: any, connectionListener?: (socket: DTLSSocket) => void): any;
+export declare function connectDTLS(options: any, callback?: () => void): DTLSSocket;
+
 // ======================== Default Export ========================
 
 declare const _default: {
   TLSSocket: typeof TLSSocket;
   TLSSession: typeof TLSSession;
+  Server: typeof Server;
   createSecureContext: typeof createSecureContext;
   connect: typeof connect;
   createServer: typeof createServer;
   getCiphers: typeof getCiphers;
+  checkServerIdentity: typeof checkServerIdentity;
   DEFAULT_MIN_VERSION: string;
   DEFAULT_MAX_VERSION: string;
+  DEFAULT_CIPHERS: string;
+  DEFAULT_ECDH_CURVE: string;
   crypto: typeof crypto;
   wire: typeof wire;
   record: typeof record;
+  DTLSSession: typeof DTLSSession;
+  DTLSSocket: typeof DTLSSocket;
+  createDTLSServer: typeof createDTLSServer;
+  connectDTLS: typeof connectDTLS;
 };
 
 export default _default;

package/index.js

@@ -15,9 +15,13 @@ import * as record from './src/record.js';
 import {
   connect,
   createServer,
+  Server,
   getCiphers,
+  checkServerIdentity,
   DEFAULT_MIN_VERSION,
   DEFAULT_MAX_VERSION,
+  DEFAULT_CIPHERS,
+  DEFAULT_ECDH_CURVE,
 } from './src/compat.js';
 
 // DTLS
@@ -47,9 +51,13 @@ export {
   createSecureContext,
   connect,
   createServer,
+  Server,
   getCiphers,
+  checkServerIdentity,
   DEFAULT_MIN_VERSION,
   DEFAULT_MAX_VERSION,
+  DEFAULT_CIPHERS,
+  DEFAULT_ECDH_CURVE,
   crypto,
   wire,
   record,
@@ -70,9 +78,13 @@ export default {
   createSecureContext,
   connect,
   createServer,
+  Server,
   getCiphers,
+  checkServerIdentity,
   DEFAULT_MIN_VERSION,
   DEFAULT_MAX_VERSION,
+  DEFAULT_CIPHERS,
+  DEFAULT_ECDH_CURVE,
   crypto,
   wire,
   record,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lemon-tls",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "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.",
   "main": "index.js",
   "type": "module",