lemon-tls 0.10.0 → 0.11.0

package/index.d.ts

@@ -37,6 +37,29 @@ export interface SecureContext {
   alternates?: Array<{ certificateChain: Array<{ cert: Buffer }>; privateKey: any }>;
 }
 
+/**
+ * An external PSK (RFC 8446 §2.2): a key both sides hold from elsewhere.
+ * TLS 1.3 and DTLS 1.3, psk_dhe_ke (a fresh ECDHE secret is mixed in). The
+ * peer that proves it is authenticated by it — no certificate is needed or
+ * sent; if the server does not take it, the handshake goes on with its
+ * certificate, checked as usual.
+ */
+export interface ExternalPsk {
+  /** Its identity: a string (UTF-8) or bytes, 1 to 65535 long. */
+  identity: string | Uint8Array;
+  psk: Uint8Array;
+  /** The hash it is used with (RFC 8446 §4.2.11). Default 'sha256'. */
+  hash?: 'sha256' | 'sha384';
+}
+/** A server's answer for an identity: the key (SHA-256), the key and its hash, or none. */
+export type ExternalPskAnswer = Uint8Array | { psk: Uint8Array; hash?: 'sha256' | 'sha384' } | null | undefined;
+
+/** The record size limits in force (RFC 8449), in plaintext bytes: what we may send, what we take. */
+export interface RecordSizeLimit {
+  send: number;
+  receive: number;
+}
+
 /** An Encrypted Client Hello key (RFC 9849), from generateEchKey(). */
 export interface EchKey {
   config: Uint8Array;
@@ -214,6 +237,25 @@ export interface TLSSocketOptions {
   /** RFC 8879: ['brotli', 'zlib', 'zstd'] in order, true (all this build has) or false (none). */
   certificateCompression?: Array<'brotli' | 'zlib' | 'zstd'> | boolean;
 
+  /**
+   * RFC 8449: the largest record we take — 64 to 16385 (TLS 1.3 counts the
+   * content-type byte). A client sends it; a server answers a client's with
+   * this or the protocol's maximum. false: never sent or answered. Records
+   * we send are cut to the peer's limit.
+   */
+  recordSizeLimit?: number | false;
+
+  // ---- External PSK (TLS 1.3) ----
+  /**
+   * node:tls's. Client: (hint) → { psk, identity } or null — asked once,
+   * hint is null (TLS 1.3 has no identity hint). Server: (socket, identity)
+   * → the key or { psk, hash }, or null for an identity it does not know
+   * (then session tickets are tried, then a full handshake).
+   */
+  pskCallback?: ((hint: null) => (ExternalPsk | null)) | ((socket: TLSSocket, identity: string) => ExternalPskAnswer);
+  /** Client: the external PSK, without a callback. */
+  psk?: ExternalPsk;
+
   // ---- 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;
@@ -228,7 +270,11 @@ export interface TLSSocketOptions {
   grease?: boolean;
   permuteExtensions?: boolean;
 
-  /** Client: trust the bundled CAs when no `ca` is given (default: true). */
+  /**
+   * Trust the bundled CAs when no `ca` is given (default: true) — a client
+   * for the server's chain, a server (requestCert) for the client's. false
+   * with no `ca`: no peer is authorized.
+   */
   useDefaultCA?: boolean;
   allowHalfOpen?: boolean;
   highWaterMark?: number;
@@ -252,10 +298,12 @@ export interface TLSSocketOptions {
   noTickets?: boolean;
   sessionTickets?: boolean;
   ticketLifetime?: number;
+  /** Signature schemes, in preference order. No SHA-1 (0x0201, 0x0203: RFC 9155) — a list naming one throws. */
   signatureAlgorithms?: number[];
   groups?: number[];
   prioritizeChaCha?: boolean;
   maxRecordSize?: number;
+  /** Code points to narrow the suites to; a list with none this library carries throws ("no cipher match"). */
   allowedCipherSuites?: number[];
   pins?: string[];
   handshakeTimeout?: number;
@@ -362,6 +410,10 @@ export class TLSSocket extends Duplex {
   /** Encrypted Client Hello: what happened to it on this connection. */
   readonly echStatus: string | null;
   readonly echAccepted: boolean;
+  /** Server, ECH split mode: ECH accepted by the client-facing server in front of this one; echStatus is 'accepted' either way. */
+  readonly echBackend: boolean;
+  /** External PSK: the identity this connection was authenticated with (or resumed from one that was), or null. */
+  getPskIdentity(): Buffer | null;
   /** 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 }]. */
@@ -470,7 +522,14 @@ export interface TLSSessionOptions {
   /** See TLSSocketOptions.ticketData. */
   ticketData?: (resumed: any) => any;
   session?: Buffer | Uint8Array | SessionTicketData;
-  psk?: any;
+  /** Client: an external PSK (or, older, a resumption PSK already decoded). */
+  psk?: ExternalPsk | any;
+  /** Server: the external PSK for an identity — tried before 'psk' and the session tickets. */
+  pskCallback?: (identity: Uint8Array) => ExternalPskAnswer;
+  /** See TLSSocketOptions.recordSizeLimit. */
+  recordSizeLimit?: number | false;
+  /** DTLS: the CID to ask for (DTLSSession turns DTLSCommonOptions.connectionId into it). */
+  connectionId?: Uint8Array;
   rejectUnauthorized?: boolean;
   ca?: Buffer | string;
   noTickets?: boolean;
@@ -517,9 +576,21 @@ export class TLSSession extends EventEmitter {
   getVersion(): number | null;
   getCipher(): number | null;
   getALPN(): string | null;
+  /** Encrypted Client Hello: null, 'grease' (client), 'accepted', 'rejected'. */
+  getEchStatus(): 'grease' | 'accepted' | 'rejected' | null;
+  /** Server, ECH split mode: accepted by the client-facing server in front of this one (BoringSSL's SSL_ech_accepted is false here). */
+  isEchBackend(): boolean;
   getPeerCertificate(): Array<{ cert: Buffer }> | null;
   /** Our own certificate chain — the one this connection presents. */
   getCertificate(): Array<{ cert: Buffer }> | null;
+  /** External PSK: the identity this connection was authenticated with, or null. */
+  getPskIdentity(): Uint8Array | null;
+  /** RFC 8449: the limits once both sides sent record_size_limit, else null. */
+  getRecordSizeLimit(): RecordSizeLimit | null;
+  /** The largest handshake message taken: 128 KB, or maxHandshakeSize when smaller. */
+  handshakeMessageLimit(): number;
+  /** The most content a record we send may carry: the peer's record_size_limit, or 2^14. */
+  recordSendLimit(): number;
   getTrafficSecrets(): TrafficSecrets;
   getHandshakeSecrets(): HandshakeSecrets;
   exportKeyingMaterial(length: number, label: string, context: Uint8Array): Uint8Array;
@@ -540,7 +611,10 @@ export class TLSSession extends EventEmitter {
   on(event: 'secureConnect', listener: () => 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;
+  /** Server: a PSK identity offered; answer with a resumption PSK, or not at all (the session's own tickets are tried). External PSKs: pskCallback. */
+  on(event: 'psk', listener: (info: { identity: Uint8Array; obfuscatedAge: number }, callback: (result: { psk: Uint8Array; cipher: number } | null) => void) => void): this;
+  /** DTLS: the Connection IDs were agreed (the record layer's cue). */
+  on(event: 'connectionId', listener: (ids: ConnectionIds) => 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;
@@ -606,13 +680,26 @@ export function getCACertificates(type?: 'default' | 'bundled' | 'extra' | 'syst
 export function setDefaultCACertificates(certs: string[]): void;
 
 /**
- * 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.
+ * Validates that the peer certificate matches the hostname — the check the
+ * handshake itself makes (RFC 9525): the subjectAltName alone (DNS names,
+ * whole-label wildcards; IP addresses for an IP), no fallback to the CN.
+ * Needs cert.raw, as getPeerCertificate() gives it. Returns undefined on a
+ * match, or an Error with code ERR_TLS_CERT_ALTNAME_INVALID, reason, host
+ * and cert (Node's shape). The checkServerIdentity option replaces it.
  */
 export function checkServerIdentity(hostname: string, cert: PeerCertificate): Error | undefined;
 
+/**
+ * The errors a connection fails with when an alert ends it: ours —
+ * code 'ERR_SSL_<ALERT NAME>' (e.g. ERR_SSL_HANDSHAKE_FAILURE) — or the
+ * peer's — 'ERR_TLS_ALERT_RECEIVED'; `alert` is the alert's code (RFC 8446
+ * §6), the same in TLS and DTLS.
+ */
+export interface TLSAlertError extends Error {
+  code: string;
+  alert: number;
+}
+
 export const DEFAULT_MIN_VERSION: string;
 export const DEFAULT_MAX_VERSION: string;
 /** Node-compat: default colon-separated cipher string. */
@@ -660,17 +747,314 @@ export declare const record: {
 };
 
 // ======================== 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);
+/**
+ * DTLS Connection IDs (RFC 9146; RFC 9147 §9). local: the CID the peer puts
+ * in the records we receive (the one we asked for); peer: the one we put in
+ * ours. Empty: the side asked for none.
+ */
+export interface ConnectionIds {
+  local: Uint8Array;
+  peer: Uint8Array;
 }
-export declare class DTLSSocket extends EventEmitter {
-  constructor(options: any);
+
+/** DTLS options shared by DTLSSession, DTLSSocket, connectDTLS and createDTLSServer. */
+export interface DTLSCommonOptions {
+  /** As createSecureContext: arrays for several certificates, the one the peer can verify chosen per handshake. */
+  cert?: SecureContextOptions['cert'];
+  key?: SecureContextOptions['key'];
+  ca?: PemInput | PemInput[];
+  minVersion?: 'DTLSv1.2' | 'DTLSv1.3';
+  maxVersion?: 'DTLSv1.2' | 'DTLSv1.3';
+  rejectUnauthorized?: boolean;
+  checkServerIdentity?: (hostname: string, cert: PeerCertificate) => Error | undefined;
+  /** Server: ask the client for a certificate (WebRTC: always). */
+  requestCert?: boolean;
+  servername?: string;
+  /** Also spelled ALPNProtocols, as in TLS. */
+  alpnProtocols?: string[];
+  /** Key-exchange groups, code points (e.g. [29, 23]). Default: a client X25519, P-256, P-384; a server those, X448 and P-521. */
+  groups?: number[];
+  /** See TLSSocketOptions.recordSizeLimit. A send larger than the peer's limit is refused (RangeError, code ERR_DTLS_RECORD_TOO_LARGE). */
+  recordSizeLimit?: number | false;
+  /**
+   * Connection ID (RFC 9146, RFC 9147 §9): the records survive the peer's
+   * address changing (a NAT rebinding). Each side asks for the CID it wants
+   * in what it receives. true — a client asks for an empty one (it needs
+   * none: the server does not move), a server for 8 random bytes; or the
+   * CID itself (up to 255 bytes; not on createDTLSServer, which gives each
+   * connection its own). Off by default.
+   */
+  connectionId?: boolean | Uint8Array;
+  /** Client, DTLS 1.3: an external PSK (see ExternalPsk). */
+  psk?: ExternalPsk;
+  /**
+   * External PSK, DTLS 1.3. DTLSSession (as TLSSession): server,
+   * (identity bytes) → the key. DTLSSocket / createDTLSServer / connectDTLS
+   * take node:tls's form, as TLSSocket does: see TLSSocketOptions.pskCallback.
+   */
+  pskCallback?: ((identity: Uint8Array) => ExternalPskAnswer) | ((hint: null) => (ExternalPsk | null)) | ((socket: DTLSSocket, identity: string) => ExternalPskAnswer);
+  /** DTLS-SRTP protection profiles to offer / accept (RFC 5764), code points. */
+  srtpProfiles?: number[];
+  /**
+   * The path MTU: the largest datagram written (every record is one
+   * datagram). Integer in [128, 65507]; default 1200. RangeError otherwise.
+   */
+  mtu?: number;
+  /**
+   * Milliseconds each flight's retransmission timer starts at, doubling on
+   * every timeout, to 60 s. Given, it is a fixed schedule: no measured round
+   * trip changes it. Not given, the timer starts at 1000 ms until a round
+   * trip has been measured, then follows it (RFC 6298: SRTT + 4·RTTVAR, at
+   * least 100 ms; Karn's rule). A flight is given up after six retransmissions AND 60 s since it
+   * began, so a short timer does not give up early on a lossy path.
+   * Integer in [10, 60000]; default 1000 (RFC 9147 §5.8.2). RangeError
+   * otherwise.
+   */
+  initialRetransmitTimeout?: number;
+  /**
+   * Client: a 'session' Buffer from an earlier connection, to resume —
+   * a DTLS 1.3 PSK ticket, or a DTLS 1.2 RFC 5077 ticket / session id.
+   * A DTLS 1.2 ticket offered with DTLS 1.3 as well goes with no session_id
+   * (RFC 9147 §5.3 leaves such a ClientHello none to carry it); whether the
+   * server took it, the message after its ServerHello says (RFC 5077 §3.4).
+   */
+  session?: Buffer | Uint8Array;
+  /** Issue (server) / ask for (client, DTLS 1.2) session tickets. Default true. */
+  sessionTickets?: boolean;
+  /** Older spelling of sessionTickets: false. */
+  noTickets?: boolean;
+}
+
+export interface DTLSSessionOptions extends DTLSCommonOptions {
+  isServer?: boolean;
+  SNICallback?: (servername: string, cb: (err: Error | null, ctx?: SecureContext | null) => void) => void;
+  /** 48 bytes. A server that resumes across connections shares one (createDTLSServer does). */
+  ticketKeys?: Buffer | Uint8Array;
+  /** Server, DTLS 1.2: HelloVerifyRequest cookie exchange (RFC 6347 §4.2.1). */
+  useCookies?: boolean;
+  /**
+   * Code points; default per version. Suites this library does not carry
+   * are skipped; a list with none it carries throws ("no cipher match").
+   */
+  cipherSuites?: number[];
+  /** Largest reassembled handshake message accepted: at most the TLS limit (128 KB, or maxHandshakeSize). */
+  maxHandshakeMessageSize?: number;
+  /**
+   * Without `ca`: the platform trust store? Default false for DTLS — WebRTC
+   * peers are self-signed, checked by SDP fingerprint; with neither, no peer
+   * is authorized, so such a caller sets rejectUnauthorized: false.
+   */
+  useDefaultCA?: boolean;
 }
-export declare function createDTLSServer(options: any, connectionListener?: (socket: DTLSSocket) => void): any;
-export declare function connectDTLS(options: any, callback?: () => void): DTLSSocket;
+
+/** The DTLS state machine without a transport: you move the datagrams. */
+export declare class DTLSSession {
+  constructor(options: DTLSSessionOptions);
+
+  /**
+   * Hand in one received UDP datagram. Never throws: a malformed one is
+   * dropped or ends the session. True when it held a record that
+   * authenticated and is the newest yet — the condition (RFC 9146 §6) for
+   * taking a new peer address with Connection IDs.
+   */
+  feedDatagram(datagram: Uint8Array | Buffer): boolean;
+  /** Application data; before 'connect' it is refused ('error'). */
+  send(data: Uint8Array | Buffer | string): void;
+  /** close_notify, then 'close'. */
+  close(): void;
+
+  readonly state: 'idle' | 'handshaking' | 'connected' | 'closed';
+  readonly connected: boolean;
+  /** 0xFEFD (DTLS 1.2) or 0xFEFC (DTLS 1.3) once negotiated, else null. */
+  readonly version: number | null;
+  /** The TLSSession underneath. */
+  readonly tls: TLSSession;
+
+  isSessionReused(): boolean;
+  /** The last 'session' Buffer, or undefined — as TLSSocket#getSession. */
+  getSession(): Buffer | undefined;
+  /** Change the path MTU; for messages fragmented from now on. RangeError outside [128, 65507]. */
+  setMTU(mtu: number): void;
+  getMTU(): number;
+  /** Where every flight's timer starts from now on — a fixed schedule, as the option given. RangeError outside [10, 60000] ms. */
+  setInitialRetransmitTimeout(ms: number): void;
+
+  /** DTLS 1.3 KeyUpdate (RFC 9147 §8); requestPeer asks the peer to update too. */
+  requestKeyUpdate(requestPeer?: boolean): void;
+  getWriteEpoch(): number | null;
+  getReadEpoch(): number | null;
+
+  /** RFC 5705 / RFC 8446 §7.5. DTLS-SRTP: exportKeyingMaterial(60, 'EXTRACTOR-dtls_srtp'), no context. */
+  exportKeyingMaterial(length: number, label: string, context?: Uint8Array | Buffer): Uint8Array | null;
+  /** The negotiated DTLS-SRTP profile, or null. */
+  getSelectedSrtpProfile(): number | null;
+  getRemoteExtensions(): Array<{ type: number; name: string | null; data: Uint8Array; value: any }>;
+  getRemoteExtension(type: number): { type: number; name: string | null; data: Uint8Array; value: any } | null;
+  getNegotiationResult(): NegotiationResult;
+  getALPN(): string | null;
+  /** Encrypted Client Hello: null, 'grease' (client), 'accepted', 'rejected'. */
+  getEchStatus(): 'grease' | 'accepted' | 'rejected' | null;
+  /** Server, ECH split mode: accepted by the client-facing server in front of this one (BoringSSL's SSL_ech_accepted is false here). */
+  isEchBackend(): boolean;
+  /** External PSK: the identity this connection was authenticated with, or null. */
+  getPskIdentity(): Uint8Array | null;
+  /** Connection IDs as they are now (NewConnectionId may have changed the peer's), or null. */
+  getConnectionIds(): ConnectionIds | null;
+  getPeerCertificate(): Array<{ cert: Buffer }> | null;
+  setKeyCert(context: SecureContext | SecureContextOptions): void;
+  getFinished(): Buffer | null;
+  getPeerFinished(): Buffer | null;
+  getJA4(opts?: FingerprintOptions): FingerprintResult | null;
+  getJA5(opts?: FingerprintOptions): FingerprintResult | null;
+  getJA4S(opts?: FingerprintOptions): FingerprintResult | null;
+  set_context(options: Record<string, any>): void;
+
+  /** A datagram to send. */
+  on(event: 'packet', listener: (datagram: Uint8Array) => void): void;
+  /** DTLS 1.3: a KeyUpdate took effect in this direction. */
+  on(event: 'keyUpdate', listener: (info: { direction: 'send' | 'receive'; epoch: number }) => void): void;
+  on(event: 'connect', listener: () => void): void;
+  /** Decrypted application data: a Buffer (a view of the record, not a copy), as node:tls gives. */
+  on(event: 'data', listener: (data: Buffer) => void): void;
+  on(event: 'error', listener: (err: Error) => void): void;
+  on(event: 'close', listener: () => void): void;
+  on(event: 'session', listener: (session: Buffer) => void): void;
+  on(event: 'clienthello', listener: (raw: Uint8Array, parsed: any) => void): void;
+  /** An alert from the peer (its warnings too). */
+  on(event: 'alert', listener: (alert: { level: number; description: number }) => void): void;
+  /** Connection IDs agreed, or the peer's moved (NewConnectionId). */
+  on(event: 'connectionId', listener: (ids: ConnectionIds) => void): void;
+  on(event: string, listener: (...args: any[]) => void): void;
+  off(event: string, listener: (...args: any[]) => void): void;
+}
+
+export interface DTLSSocketOptions extends DTLSCommonOptions {
+  isServer?: boolean;
+  /** The peer (a client's server; filled from the first datagram on a server). */
+  remoteAddress?: string;
+  remotePort?: number;
+  SNICallback?: DTLSSessionOptions['SNICallback'];
+  ticketKeys?: Buffer | Uint8Array;
+  useCookies?: boolean;
+}
+
+/** One DTLS connection over a UDP socket. */
+export declare class DTLSSocket {
+  constructor(udpSocket: import('node:dgram').Socket, options: DTLSSocketOptions);
+
+  send(data: Uint8Array | Buffer | string): void;
+  close(): void;
+  /** Server side: what DTLSServer calls for this peer's datagrams. */
+  feedDatagram(datagram: Uint8Array | Buffer, rinfo?: { address: string; port: number }): void;
+  /**
+   * Send to another address from now on. With Connection IDs, for a peer
+   * reported at a new one ('remoteAddressChange'): not taken by itself —
+   * RFC 9146 §6 asks for a way of knowing the peer is there first.
+   */
+  setRemoteAddress(address: string, port: number): void;
+
+  readonly state: DTLSSession['state'];
+  readonly connected: boolean;
+  readonly version: number | null;
+  readonly remoteAddress: string | null;
+  readonly remotePort: number | null;
+  /** The DTLSSession underneath. */
+  readonly session: DTLSSession;
+
+  isSessionReused(): boolean;
+  getSession(): Buffer | undefined;
+  setMTU(mtu: number): void;
+  getMTU(): number;
+  setInitialRetransmitTimeout(ms: number): void;
+
+  exportKeyingMaterial(length: number, label: string, context?: Uint8Array | Buffer): Uint8Array | null;
+  getSelectedSrtpProfile(): number | null;
+  getRemoteExtensions(): ReturnType<DTLSSession['getRemoteExtensions']>;
+  getRemoteExtension(type: number): ReturnType<DTLSSession['getRemoteExtension']>;
+  getNegotiationResult(): NegotiationResult;
+  getALPN(): string | null;
+  /** Encrypted Client Hello: null, 'grease' (client), 'accepted', 'rejected'. */
+  getEchStatus(): 'grease' | 'accepted' | 'rejected' | null;
+  /** Server, ECH split mode: accepted by the client-facing server in front of this one (BoringSSL's SSL_ech_accepted is false here). */
+  isEchBackend(): boolean;
+  /** External PSK: the identity (a Buffer, as TLSSocket's), or null. */
+  getPskIdentity(): Buffer | null;
+  getConnectionIds(): ConnectionIds | null;
+  getPeerCertificate(): Array<{ cert: Buffer }> | null;
+  setKeyCert(context: SecureContext | SecureContextOptions): void;
+  /** undefined (not null) when not available. */
+  getFinished(): Buffer | undefined;
+  getPeerFinished(): Buffer | undefined;
+  getJA4(opts?: FingerprintOptions): FingerprintResult | null;
+  getJA5(opts?: FingerprintOptions): FingerprintResult | null;
+  getJA4S(opts?: FingerprintOptions): FingerprintResult | null;
+  set_context(options: Record<string, any>): void;
+
+  /** Also emitted as 'secureConnect', right after 'connect'. */
+  on(event: 'connect' | 'secureConnect', listener: () => void): void;
+  /** Decrypted application data: a Buffer (a view of the record, not a copy), as node:tls gives. */
+  on(event: 'data', listener: (data: Buffer) => void): void;
+  on(event: 'error', listener: (err: Error) => void): void;
+  on(event: 'close', listener: () => void): void;
+  on(event: 'session', listener: (session: Buffer) => void): void;
+  on(event: 'clienthello', listener: (raw: Uint8Array, parsed: any) => void): void;
+  on(event: 'alert', listener: (alert: { level: number; description: number }) => void): void;
+  on(event: 'connectionId', listener: (ids: ConnectionIds) => void): void;
+  /** Connection IDs: a datagram of this connection, the newest authenticated yet, from another address. */
+  on(event: 'remoteAddressChange', listener: (to: { address: string; port: number }) => void): void;
+  on(event: string, listener: (...args: any[]) => void): void;
+  off(event: string, listener: (...args: any[]) => void): void;
+}
+
+/** Every DTLSSession option, for each connection (ca, requestCert, cipherSuites, ...). */
+export interface DTLSServerOptions extends Omit<DTLSSessionOptions, 'isServer' | 'connectionId'> {
+  /** 48 bytes; one for every connection of this server (random if not given). */
+  ticketKeys?: Buffer | Uint8Array;
+  /** Connection IDs: each connection its own 8 random bytes — and found by it when its peer moves. */
+  connectionId?: boolean;
+  /** The UDP socket's receive/send buffers, bytes: 4 MB by default; 0 or false, the OS default. The kernel caps it at net.core.rmem_max. */
+  socketBufferSize?: number | false;
+}
+
+/** createDTLSServer()'s: one UDP port, a DTLSSocket per peer address. */
+export interface DTLSServer {
+  /**
+   * An IPv6 `address`, an IPv6 socket; an IPv4 one, IPv4. None: '::',
+   * dual-stack — IPv4 peers too, as '::ffff:a.b.c.d' — or 0.0.0.0 on a host
+   * without IPv6 (as node:net).
+   */
+  listen(port: number, address?: string, callback?: () => void): void;
+  listen(port: number, callback?: () => void): void;
+  /** close_notify to every connection, then the socket, once they have gone. */
+  close(callback?: () => void): void;
+  address(): { port: number; family: string; address: string } | null;
+  /** A peer's handshake completed (also the connectionListener). */
+  on(event: 'connection', listener: (socket: DTLSSocket) => void): void;
+  /** A peer's connection failed. */
+  on(event: 'clientError', listener: (err: Error, socket: DTLSSocket) => void): void;
+  on(event: 'listening', listener: () => void): void;
+  /** The UDP socket's error. */
+  on(event: 'error', listener: (err: Error) => void): void;
+  on(event: string, listener: (...args: any[]) => void): void;
+  off(event: string, listener: (...args: any[]) => void): void;
+}
+
+/** Every DTLSSession option a client takes (cipherSuites, useDefaultCA, ...). */
+export interface ConnectDTLSOptions extends Omit<DTLSSessionOptions, 'isServer' | 'ticketKeys' | 'useCookies' | 'SNICallback'> {
+  /** A name (resolved once — IPv4 or IPv6, whichever it has first) or an IP. Default '127.0.0.1'. */
+  host?: string;
+  hostname?: string;
+  /** Default 4433. */
+  port?: number;
+  /** The UDP socket's receive/send buffers, bytes: 4 MB by default; 0 or false, the OS default. */
+  socketBufferSize?: number | false;
+}
+
+export declare function createDTLSServer(options: DTLSServerOptions, connectionListener?: (socket: DTLSSocket) => void): DTLSServer;
+export declare function createDTLSServer(connectionListener?: (socket: DTLSSocket) => void): DTLSServer;
+/** A UDP socket of its own, closed with the connection. */
+export declare function connectDTLS(options: ConnectDTLSOptions, callback?: () => void): DTLSSocket;
 
 // ======================== Default Export ========================
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lemon-tls",
-  "version": "0.10.0",
+  "version": "0.11.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",
@@ -58,6 +58,12 @@
   "engines": {
     "node": ">=24.0.0"
   },
+  "dependencies": {
+    "cryptographic-formats": "^0.1.0"
+  },
+  "scripts": {
+    "test": "node tests/test_all.js && node tests/test_x509_chain.js && node tests/test_keys_groups.js"
+  },
   "keywords": [
     "tls",
     "dtls",
@@ -110,7 +116,6 @@
     "http3",
     "record-layer",
     "pure-javascript",
-    "zero-dependencies",
     "no-openssl",
     "security",
     "network",

package/src/ca_store.js

@@ -0,0 +1,31 @@
+// ============================================================
+//  The default trust anchors: Node's CA bundle (Mozilla's)
+// ============================================================
+//
+// One store for every session that is given no `ca` — client or server,
+// TLS over TCP, QUIC (a TLSSession used directly) — and the one
+// tls.setDefaultCACertificates() replaces. It lived in compat.js, and only
+// connect() handed it on: a server (createServer, requestCert) and a session
+// built directly had no anchors at all, and "no anchors" authorized every
+// certificate.
+//
+// Parsing all ~144 certificates costs a few tens of milliseconds, so it is
+// done once, lazily, and only if something actually needs it.
+import nodeTls from 'node:tls';
+
+let _rootPems = null;
+function getRootCertificates() {
+  if (_rootPems === null) {
+    try { _rootPems = nodeTls.rootCertificates.slice(); }
+    catch (e) { _rootPems = []; }   // a build without the bundle
+  }
+  return _rootPems;
+}
+
+/** tls.setDefaultCACertificates(certs): the store, for every later session. */
+function setRootCertificates(certs) {
+  if (!Array.isArray(certs)) throw new TypeError('certs must be an array');
+  _rootPems = certs.slice();
+}
+
+export { getRootCertificates, setRootCertificates };