@push.rocks/smartproxy
Version:
A powerful proxy package with unified route-based configuration for high traffic management. Features include SSL/TLS support, flexible routing patterns, WebSocket handling, advanced security options, and automatic ACME certificate management.
155 lines (154 loc) • 7.21 kB
TypeScript
import { Buffer } from 'buffer';
/**
* SNI (Server Name Indication) handler for TLS connections.
* Provides robust extraction of SNI values from TLS ClientHello messages
* with support for fragmented packets, TLS 1.3 resumption, Chrome-specific
* connection behaviors, and tab hibernation/reactivation scenarios.
*
* This class retains the original API but leverages the new modular implementation
* for better maintainability and testability.
*/
export declare class SniHandler {
private static readonly TLS_HANDSHAKE_RECORD_TYPE;
private static readonly TLS_APPLICATION_DATA_TYPE;
private static readonly TLS_CLIENT_HELLO_HANDSHAKE_TYPE;
private static readonly TLS_SNI_EXTENSION_TYPE;
private static readonly TLS_SESSION_TICKET_EXTENSION_TYPE;
private static readonly TLS_SNI_HOST_NAME_TYPE;
private static readonly TLS_PSK_EXTENSION_TYPE;
private static readonly TLS_PSK_KE_MODES_EXTENSION_TYPE;
private static readonly TLS_EARLY_DATA_EXTENSION_TYPE;
/**
* Checks if a buffer contains a TLS handshake message (record type 22)
* @param buffer - The buffer to check
* @returns true if the buffer starts with a TLS handshake record type
*/
static isTlsHandshake(buffer: Buffer): boolean;
/**
* Checks if a buffer contains TLS application data (record type 23)
* @param buffer - The buffer to check
* @returns true if the buffer starts with a TLS application data record type
*/
static isTlsApplicationData(buffer: Buffer): boolean;
/**
* Creates a connection ID based on source/destination information
* Used to track fragmented ClientHello messages across multiple packets
*
* @param connectionInfo - Object containing connection identifiers (IP/port)
* @returns A string ID for the connection
*/
static createConnectionId(connectionInfo: {
sourceIp?: string;
sourcePort?: number;
destIp?: string;
destPort?: number;
}): string;
/**
* Handles potential fragmented ClientHello messages by buffering and reassembling
* TLS record fragments that might span multiple TCP packets.
*
* @param buffer - The current buffer fragment
* @param connectionId - Unique identifier for the connection
* @param enableLogging - Whether to enable logging
* @returns A complete buffer if reassembly is successful, or undefined if more fragments are needed
*/
static handleFragmentedClientHello(buffer: Buffer, connectionId: string, enableLogging?: boolean): Buffer | undefined;
/**
* Checks if a buffer contains a TLS ClientHello message
* @param buffer - The buffer to check
* @returns true if the buffer appears to be a ClientHello message
*/
static isClientHello(buffer: Buffer): boolean;
/**
* Checks if a ClientHello message contains session resumption indicators
* such as session tickets or PSK (Pre-Shared Key) extensions.
*
* @param buffer - The buffer containing a ClientHello message
* @param enableLogging - Whether to enable logging
* @returns Object containing details about session resumption and SNI presence
*/
static hasSessionResumption(buffer: Buffer, enableLogging?: boolean): {
isResumption: boolean;
hasSNI: boolean;
};
/**
* Detects characteristics of a tab reactivation TLS handshake
* These often have specific patterns in Chrome and other browsers
*
* @param buffer - The buffer containing a ClientHello message
* @param enableLogging - Whether to enable logging
* @returns true if this appears to be a tab reactivation handshake
*/
static isTabReactivationHandshake(buffer: Buffer, enableLogging?: boolean): boolean;
/**
* Extracts the SNI (Server Name Indication) from a TLS ClientHello message.
* Implements robust parsing with support for session resumption edge cases.
*
* @param buffer - The buffer containing the TLS ClientHello message
* @param enableLogging - Whether to enable detailed debug logging
* @returns The extracted server name or undefined if not found
*/
static extractSNI(buffer: Buffer, enableLogging?: boolean): string | undefined;
/**
* Attempts to extract SNI from the PSK extension in a TLS 1.3 ClientHello.
*
* In TLS 1.3, when a client attempts to resume a session, it may include
* the server name in the PSK identity hint rather than in the SNI extension.
*
* @param buffer - The buffer containing the TLS ClientHello message
* @param enableLogging - Whether to enable detailed debug logging
* @returns The extracted server name or undefined if not found
*/
static extractSNIFromPSKExtension(buffer: Buffer, enableLogging?: boolean): string | undefined;
/**
* Checks if the buffer contains TLS 1.3 early data (0-RTT)
* @param buffer - The buffer to check
* @param enableLogging - Whether to enable logging
* @returns true if early data is detected
*/
static hasEarlyData(buffer: Buffer, enableLogging?: boolean): boolean;
/**
* Attempts to extract SNI from an initial ClientHello packet and handles
* session resumption edge cases more robustly than the standard extraction.
*
* This method handles:
* 1. Standard SNI extraction
* 2. TLS 1.3 PSK-based resumption (Chrome, Firefox, etc.)
* 3. Session ticket-based resumption
* 4. Fragmented ClientHello messages
* 5. TLS 1.3 Early Data (0-RTT)
* 6. Chrome's connection racing behaviors
*
* @param buffer - The buffer containing the TLS ClientHello message
* @param connectionInfo - Optional connection information for fragment handling
* @param enableLogging - Whether to enable detailed debug logging
* @returns The extracted server name or undefined if not found or more data needed
*/
static extractSNIWithResumptionSupport(buffer: Buffer, connectionInfo?: {
sourceIp?: string;
sourcePort?: number;
destIp?: string;
destPort?: number;
}, enableLogging?: boolean): string | undefined;
/**
* Main entry point for SNI extraction that handles all edge cases.
* This should be called for each TLS packet received from a client.
*
* The method uses connection tracking to handle fragmented ClientHello
* messages and various TLS 1.3 behaviors, including Chrome's connection
* racing patterns and tab reactivation behaviors.
*
* @param buffer - The buffer containing TLS data
* @param connectionInfo - Connection metadata (IPs and ports)
* @param enableLogging - Whether to enable detailed debug logging
* @param cachedSni - Optional cached SNI from previous connections (for racing detection)
* @returns The extracted server name or undefined if not found or more data needed
*/
static processTlsPacket(buffer: Buffer, connectionInfo: {
sourceIp: string;
sourcePort: number;
destIp: string;
destPort: number;
timestamp?: number;
}, enableLogging?: boolean, cachedSni?: string): string | undefined;
}