lemon-tls 0.9.0 → 0.11.0

package/index.d.ts

@@ -7,9 +7,81 @@ 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 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;
+  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 +91,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 +180,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 +208,76 @@ 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;
+
+  /**
+   * 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;
+  /** 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;
+
+  /**
+   * 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;
 
   // TCP options, as in node:net. connect() passes them (and the rest of
   // net.connect's: localAddress, localPort, family, lookup, timeout) to
@@ -150,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;
@@ -162,6 +312,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 +341,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 +352,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 +403,22 @@ 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, 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 }]. */
+  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 +450,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 +475,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 +499,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;
@@ -305,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;
@@ -352,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;
@@ -375,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;
@@ -389,16 +628,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 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;
 
-export function createServer(
-  options: TLSSocketOptions & { key?: Buffer | string; cert?: Buffer | string },
-  connectionListener?: (socket: TLSSocket) => void
-): Server;
+/** 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[];
 
@@ -416,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. */
@@ -448,6 +725,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;
@@ -460,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 declare function createDTLSServer(options: any, connectionListener?: (socket: DTLSSocket) => void): any;
-export declare function connectDTLS(options: any, callback?: () => void): DTLSSocket;
+
+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;
+}
+
+/** 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 ========================
 
@@ -493,6 +1077,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;