lemon-tls 0.7.0 → 0.10.0

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;
@@ -31,16 +81,39 @@ export interface PeerCertificate {
 }
 
 export interface EphemeralKeyInfo {
-  type: 'X25519' | 'ECDH' | 'DH';
+  /** 'TLSGroup' for a group that is not a plain curve, as Node reports it —
+   *  X25519MLKEM768 among them (no size). Client side only; {} on a server. */
+  type: 'X25519' | 'ECDH' | 'DH' | 'TLSGroup';
   name?: string;
-  size: number;
+  size?: number;
 }
 
-export interface JA3Result {
+/** A TLS fingerprint: `hash` is the fingerprint, `raw` what was hashed. */
+export interface FingerprintResult {
   hash: string;
   raw: string;
 }
 
+export interface FingerprintOptions {
+  /** Transport character, for a caller driving the session from a transport
+   *  it cannot see: 't' TCP (default), 'q' QUIC, 'd' DTLS. */
+  protocol?: 't' | 'q' | 'd';
+}
+
+/**
+ * Server: this connection's session ticket, from the first connection on.
+ * `data` is what the ticketData option put in the ticket — the one this
+ * connection resumed with, or, on a full handshake, the one made for the
+ * ticket issued to it (null until the server's Finished is sent).
+ * `offered && !resumed`: the client presented a ticket that was turned away
+ * (expired, issued before a restart, no compatible cipher).
+ */
+export interface TicketInfo {
+  data: any;
+  resumed: boolean;
+  offered: boolean;
+}
+
 export interface NegotiationResult {
   version: number | null;
   versionName: string | null;
@@ -84,21 +157,96 @@ 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
+   * connection as ticketData(resumed) — `resumed` is the data of the ticket
+   * this connection resumed with, null on a full handshake. The return value
+   * (JSON-safe, at most 256 bytes serialized) rides in the ticket, encrypted
+   * with ticketKeys; read it back with getTicketInfo().
+   */
+  ticketData?: (resumed: any) => any;
   /**
    * 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;
+  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
+  // net.connect; createServer() applies noDelay/keepAlive to every
+  // connection it accepts. Defaults as in Node: off.
+  /** Disable Nagle's algorithm (TCP_NODELAY). Default: false. */
+  noDelay?: boolean;
+  /** Enable TCP keep-alive. Default: false. */
+  keepAlive?: boolean;
+  /** Milliseconds before the first keep-alive probe. Default: 0. */
+  keepAliveInitialDelay?: number;
+  localAddress?: string;
+  localPort?: number;
+  family?: number;
+  timeout?: number;
 
   // LemonTLS-only options
   noTickets?: boolean;
@@ -116,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 {
@@ -124,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+). */
@@ -134,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). */
@@ -179,7 +355,29 @@ export class TLSSocket extends Duplex {
   /** Returns the underlying TLSSession for low-level access. */
   session: TLSSession;
   readonly handshakeDuration: number | null;
-  getJA3(): JA3Result | 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;
+  /** JA5 of the ClientHello (ntop's draft): as JA4 without the extensions that
+   *  vary per connection, plus supported_groups — the same for a client
+   *  whether it resumed or not. */
+  getJA5(opts?: FingerprintOptions): FingerprintResult | null;
+  /** JA4S of the ServerHello. */
+  getJA4S(opts?: FingerprintOptions): FingerprintResult | null;
+  /** Server: this connection's session ticket — see TicketInfo. */
+  getTicketInfo(): TicketInfo;
   getSharedSecret(): Buffer | null;
   getNegotiationResult(): NegotiationResult | null;
   rekeySend(): void;
@@ -200,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;
@@ -218,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). */
@@ -231,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;
@@ -246,6 +467,8 @@ export interface TLSSessionOptions {
   ALPNProtocols?: string[];
   SNICallback?: (servername: string, cb: (err: Error | null, ctx: SecureContext | null) => void) => void;
   ticketKeys?: Buffer;
+  /** See TLSSocketOptions.ticketData. */
+  ticketData?: (resumed: any) => any;
   session?: Buffer | Uint8Array | SessionTicketData;
   psk?: any;
   rejectUnauthorized?: boolean;
@@ -295,6 +518,8 @@ export class TLSSession extends EventEmitter {
   getCipher(): number | null;
   getALPN(): string | null;
   getPeerCertificate(): Array<{ cert: Buffer }> | null;
+  /** Our own certificate chain — the one this connection presents. */
+  getCertificate(): Array<{ cert: Buffer }> | null;
   getTrafficSecrets(): TrafficSecrets;
   getHandshakeSecrets(): HandshakeSecrets;
   exportKeyingMaterial(length: number, label: string, context: Uint8Array): Uint8Array;
@@ -302,7 +527,11 @@ export class TLSSession extends EventEmitter {
   getPeerFinished(): Buffer | null;
   getSharedSecret(): Buffer | null;
   getNegotiationResult(): NegotiationResult;
-  getJA3(): JA3Result | null;
+  getJA4(opts?: FingerprintOptions): FingerprintResult | null;
+  getJA5(opts?: FingerprintOptions): FingerprintResult | null;
+  getJA4S(opts?: FingerprintOptions): FingerprintResult | null;
+  /** Server: this connection's session ticket — see TicketInfo. */
+  getTicketInfo(): TicketInfo;
   requestKeyUpdate(requestPeer?: boolean): void;
 
   // Events
@@ -325,19 +554,57 @@ 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[];
 
+/** Node-compat: the shipped CA bundle (PEM strings) — tls.rootCertificates. */
+export const rootCertificates: readonly string[];
+/**
+ * Node-compat: tls.getCACertificates([type]). 'default' and 'bundled' return
+ * the CA set clients verify against when given no `ca` (the shipped bundle,
+ * or what setDefaultCACertificates put in its place); 'extra' and 'system'
+ * are not sourced here and return [].
+ */
+export function getCACertificates(type?: 'default' | 'bundled' | 'extra' | 'system'): string[];
+/** Node-compat: tls.setDefaultCACertificates(certs) — replaces that set for
+ *  every later connection that passes no `ca`. Throws if not an array. */
+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.
@@ -363,6 +630,24 @@ export declare const crypto: {
   hkdf_expand: (hash: string, prk: Uint8Array, info: Uint8Array, length: number) => Uint8Array;
   hkdf_expand_label: (hash: string, secret: Uint8Array, label: string, context: Uint8Array, length: number) => Uint8Array;
   hmac: (hash: string, key: Uint8Array, data: Uint8Array) => Uint8Array;
+  /** TLS 1.2 PRF (RFC 5246 §5). */
+  tls12_prf: (secret: Uint8Array, label: string, seed: Uint8Array, length: number, hash: string) => Uint8Array;
+  /** RFC 5705 exporter over a TLS 1.2 master secret. */
+  tls12_exporter: (hash: string, masterSecret: Uint8Array, label: string, clientRandom: Uint8Array,
+                   serverRandom: Uint8Array, context: Uint8Array | null, length: number) => Uint8Array;
+  /** 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;
@@ -398,6 +683,9 @@ declare const _default: {
   createServer: typeof createServer;
   getCiphers: typeof getCiphers;
   checkServerIdentity: typeof checkServerIdentity;
+  getCACertificates: typeof getCACertificates;
+  setDefaultCACertificates: typeof setDefaultCACertificates;
+  rootCertificates: typeof rootCertificates;
   DEFAULT_MIN_VERSION: string;
   DEFAULT_MAX_VERSION: string;
   DEFAULT_CIPHERS: string;
@@ -405,10 +693,22 @@ 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;
   connectDTLS: typeof connectDTLS;
 };
 
-export default _default;
+export default _default;

package/index.js

@@ -21,11 +21,74 @@ import {
   Server,
   getCiphers,
   checkServerIdentity,
+  getCACertificates,
+  setDefaultCACertificates,
   DEFAULT_MIN_VERSION,
   DEFAULT_MAX_VERSION,
   DEFAULT_CIPHERS,
   DEFAULT_ECDH_CURVE,
 } from './src/compat.js';
+import { parseCiphers, parseEcdhCurve, parseSigalgs, parseTlsVersion } from './src/node_options.js';
+import { certificateObject } from './src/utils.js';
+import { parse_cert_compression, precompress_certificate_body, supported_cert_compression } from './src/session/cert_compression.js';
+import { build_tls_message } from './src/session/message.js';
+import { client_session_info } from './src/session/ticket.js';
+
+/** A saved session ('session' event's Buffer) described without its secrets:
+ *  { version, servername, alpn, created, expiresAt, earlyData }, or null. */
+function sessionInfo(blob) { return client_session_info(blob); }
+import { SERVER_DEFAULT_GROUPS } from './src/session/ecdh.js';
+import { default_signature_schemes } from './src/session/signing.js';
+
+/** The signature schemes offered by default (signature_algorithms), in
+ *  order, as code points: the modern ones, ML-DSA where this Node.js has it,
+ *  then the legacy ones (accepted on certificates, never used in a TLS 1.3
+ *  CertificateVerify). A copy. */
+const DEFAULT_SIGNATURE_SCHEMES = Object.freeze(default_signature_schemes());
+
+/** The key-exchange groups a server offers by default, in its preference:
+ *  every post-quantum group this Node.js has (the hybrids, then ML-KEM
+ *  alone), then X25519, P-256, P-384 — as code points. A copy. */
+const DEFAULT_SERVER_GROUPS = Object.freeze(SERVER_DEFAULT_GROUPS.slice());
+
+/** certificateCompression (RFC 8879): ['brotli', 'zlib', 'zstd'] in order,
+ *  true (all this build has) or false (none) → algorithm codes; null when
+ *  unset (the default). Throws on a name it does not know, so a server can
+ *  check the option when it is made rather than at the first handshake. */
+function parseCertificateCompression(value) { return parse_cert_compression(value); }
+
+/** A server's certificate chain compressed now (RFC 8879), in the
+ *  background, for each algorithm it may be sent in — `algorithms` as the
+ *  certificateCompression option takes them (unset: all this build has) —
+ *  so the first TLS 1.3 handshake to send it does not compress it while
+ *  its client waits. `secureContext`: from createSecureContext(). Optional:
+ *  without it the first handshake compresses, and caches, as before.
+ *  callback() when done. */
+function precompressCertificate(secureContext, algorithms, callback) {
+  if (typeof algorithms === 'function') { callback = algorithms; algorithms = undefined; }
+  const algs = parse_cert_compression(algorithms) || supported_cert_compression();
+  // Its chain, and those of its other key/certificate pairs (key/cert arrays).
+  const chains = secureContext ? [secureContext.certificateChain].concat((secureContext.alternates || []).map((a) => a.certificateChain)) : [];
+  let left = 1;
+  const done = () => { if (--left === 0 && callback) callback(); };
+  for (const chain of chains) {
+    if (!Array.isArray(chain) || chain.length === 0 || algs.length === 0) continue;
+    // The Certificate message's body as a TLS 1.3 server sends it: an empty
+    // request context, each entry without extensions (an OCSP response
+    // stapled to the leaf makes another body, compressed when it is sent).
+    const body = build_tls_message({ type: 'certificate', version: 0x0304, entries: chain, certificate_request_context: new Uint8Array(0) }).subarray(4);
+    left++;
+    precompress_certificate_body(body, algs, done);
+  }
+  process.nextTick(done);
+}
+import { generate_ech_key, prepare_ech_server } from './src/session/ech.js';
+import { hpke_suite, setup_sender, setup_recipient, hpke_seal, hpke_open,
+         hpke_generate_key_pair, hpke_derive_key_pair } from './src/session/hpke.js';
+import nodeTls from 'node:tls';
+
+/** Node-compat: the shipped CA bundle, same array Node exposes. */
+const rootCertificates = nodeTls.rootCertificates;
 
 // DTLS
 import DTLSSession from './src/dtls_session.js';
@@ -53,8 +116,40 @@ var crypto = {
   tls12_prf,
   tls12_exporter,
   tls13_exporter,
+  // HPKE (RFC 9180) — what ECH encrypts with; also the base of Oblivious
+  // HTTP and MLS.
+  hpke: {
+    suite: hpke_suite,
+    setupSender: setup_sender,
+    setupRecipient: setup_recipient,
+    seal: hpke_seal,
+    open: hpke_open,
+    generateKeyPair: hpke_generate_key_pair,
+    deriveKeyPair: hpke_derive_key_pair,
+  },
 };
 
+/**
+ * A new Encrypted Client Hello key (RFC 9849) for a server:
+ * { config, privateKey, configList, configListBase64 }.
+ * Pass { keys: [{ config, privateKey }] } as the server's `ech` option and
+ * publish configListBase64 as `ech=` in the domain's HTTPS record.
+ */
+function generateEchKey(options) {
+  return generate_ech_key(options);
+}
+
+/**
+ * Check a server's `ech` option — { keys: [{ config, privateKey, retry }] }
+ * — and throw, saying what is wrong, if it would not work: a config that
+ * does not parse, a private key that is not its config's. For a server
+ * built on TLSSession directly, which would otherwise learn of it on the
+ * first connection. createServer checks by itself.
+ */
+function checkEchKeys(ech) {
+  prepare_ech_server(ech);
+}
+
 export {
   TLSSocket,
   TLSSession,
@@ -64,6 +159,9 @@ export {
   Server,
   getCiphers,
   checkServerIdentity,
+  getCACertificates,
+  setDefaultCACertificates,
+  rootCertificates,
   DEFAULT_MIN_VERSION,
   DEFAULT_MAX_VERSION,
   DEFAULT_CIPHERS,
@@ -71,6 +169,19 @@ export {
   crypto,
   wire,
   record,
+  // node:tls option strings → code lists (node_options.js)
+  parseCiphers,
+  parseEcdhCurve,
+  parseSigalgs,
+  parseTlsVersion,
+  parseCertificateCompression,
+  precompressCertificate,
+  DEFAULT_SERVER_GROUPS,
+  DEFAULT_SIGNATURE_SCHEMES,
+  sessionInfo,
+  certificateObject,
+  generateEchKey,
+  checkEchKeys,
 
   // DTLS
   DTLSSession,
@@ -91,6 +202,9 @@ export default {
   Server,
   getCiphers,
   checkServerIdentity,
+  getCACertificates,
+  setDefaultCACertificates,
+  rootCertificates,
   DEFAULT_MIN_VERSION,
   DEFAULT_MAX_VERSION,
   DEFAULT_CIPHERS,
@@ -98,6 +212,18 @@ export default {
   crypto,
   wire,
   record,
+  parseCiphers,
+  parseEcdhCurve,
+  parseSigalgs,
+  parseTlsVersion,
+  parseCertificateCompression,
+  precompressCertificate,
+  DEFAULT_SERVER_GROUPS,
+  DEFAULT_SIGNATURE_SCHEMES,
+  sessionInfo,
+  certificateObject,
+  generateEchKey,
+  checkEchKeys,
 
   // DTLS
   DTLSSession,