@push.rocks/smartproxy 16.0.2 → 16.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartproxy",
-  "version": "16.0.2",
+  "version": "16.0.4",
   "private": false,
   "description": "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.",
   "main": "dist_ts/index.js",

package/readme.md

@@ -7,6 +7,7 @@ A unified high-performance proxy toolkit for Node.js, with **SmartProxy** as the
 - **Flexible Matching Patterns**: Route by port, domain, path, client IP, and TLS version
 - **Advanced SNI Handling**: Smart TCP/SNI-based forwarding with IP filtering
 - **Multiple Action Types**: Forward (with TLS modes), redirect, or block traffic
+- **Dynamic Port Management**: Add or remove listening ports at runtime without restart
 - **Security Features**: IP allowlists, connection limits, timeouts, and more
 
 ## Project Architecture Overview
@@ -211,12 +212,18 @@ proxy.on('certificate', evt => {
 await proxy.start();
 
 // Dynamically add new routes later
-await proxy.addRoutes([
+await proxy.updateRoutes([
+  ...proxy.settings.routes,
   createHttpsTerminateRoute('new-domain.com', { host: 'localhost', port: 9000 }, {
     certificate: 'auto'
   })
 ]);
 
+// Dynamically add or remove port listeners
+await proxy.addListeningPort(8081);
+await proxy.removeListeningPort(8081);
+console.log('Currently listening on ports:', proxy.getListeningPorts());
+
 // Later, gracefully shut down
 await proxy.stop();
 ```
@@ -557,12 +564,37 @@ Available helper functions:
    })
    ```
 
+8. **Dynamic Port Management**
+   ```typescript
+   // Start the proxy with initial configuration
+   const proxy = new SmartProxy({
+     routes: [
+       createHttpRoute('example.com', { host: 'localhost', port: 8080 })
+     ]
+   });
+   await proxy.start();
+
+   // Dynamically add a new port listener
+   await proxy.addListeningPort(8081);
+
+   // Add a route for the new port
+   const currentRoutes = proxy.settings.routes;
+   const newRoute = createHttpRoute('api.example.com', { host: 'api-server', port: 3000 });
+   newRoute.match.ports = 8081;  // Override the default port
+
+   // Update routes - will automatically sync port listeners
+   await proxy.updateRoutes([...currentRoutes, newRoute]);
+
+   // Later, remove a port listener when needed
+   await proxy.removeListeningPort(8081);
+   ```
+
 ## Other Components
 
 While SmartProxy provides a unified API for most needs, you can also use individual components:
 
 ### NetworkProxy
-For HTTP/HTTPS reverse proxy with TLS termination and WebSocket support:
+For HTTP/HTTPS reverse proxy with TLS termination and WebSocket support. Now with native route-based configuration support:
 
 ```typescript
 import { NetworkProxy } from '@push.rocks/smartproxy';
@@ -570,9 +602,49 @@ import * as fs from 'fs';
 
 const proxy = new NetworkProxy({ port: 443 });
 await proxy.start();
+
+// Modern route-based configuration (recommended)
+await proxy.updateRouteConfigs([
+  {
+    match: {
+      ports: 443,
+      domains: 'example.com'
+    },
+    action: {
+      type: 'forward',
+      target: {
+        host: '127.0.0.1',
+        port: 3000
+      },
+      tls: {
+        mode: 'terminate',
+        certificate: {
+          cert: fs.readFileSync('cert.pem', 'utf8'),
+          key: fs.readFileSync('key.pem', 'utf8')
+        }
+      },
+      advanced: {
+        headers: {
+          'X-Forwarded-By': 'NetworkProxy'
+        },
+        urlRewrite: {
+          pattern: '^/old/(.*)$',
+          target: '/new/$1',
+          flags: 'g'
+        }
+      },
+      websocket: {
+        enabled: true,
+        pingInterval: 30000
+      }
+    }
+  }
+]);
+
+// Legacy configuration (for backward compatibility)
 await proxy.updateProxyConfigs([
   {
-    hostName: 'example.com',
+    hostName: 'legacy.example.com',
     destinationIps: ['127.0.0.1'],
     destinationPorts: [3000],
     publicKey: fs.readFileSync('cert.pem', 'utf8'),
@@ -1084,18 +1156,34 @@ createRedirectRoute({
 - Socket opts: `noDelay`, `keepAlive`, `enableKeepAliveProbes`
 - `certProvisionFunction` (callback) - Custom certificate provisioning
 
+#### SmartProxy Dynamic Port Management Methods
+- `async addListeningPort(port: number)` - Add a new port listener without changing routes
+- `async removeListeningPort(port: number)` - Remove a port listener without changing routes
+- `getListeningPorts()` - Get all ports currently being listened on
+- `async updateRoutes(routes: IRouteConfig[])` - Update routes and automatically adjust port listeners
+
 ### NetworkProxy (INetworkProxyOptions)
-- `port` (number, required)
-- `backendProtocol` ('http1'|'http2', default 'http1')
-- `maxConnections` (number, default 10000)
-- `keepAliveTimeout` (ms, default 120000)
-- `headersTimeout` (ms, default 60000)
-- `cors` (object)
-- `connectionPoolSize` (number, default 50)
-- `logLevel` ('error'|'warn'|'info'|'debug')
-- `acme` (IAcmeOptions)
-- `useExternalPort80Handler` (boolean)
-- `portProxyIntegration` (boolean)
+- `port` (number, required) - Main port to listen on
+- `backendProtocol` ('http1'|'http2', default 'http1') - Protocol to use with backend servers
+- `maxConnections` (number, default 10000) - Maximum concurrent connections
+- `keepAliveTimeout` (ms, default 120000) - Connection keep-alive timeout
+- `headersTimeout` (ms, default 60000) - Timeout for receiving complete headers
+- `cors` (object) - Cross-Origin Resource Sharing configuration
+- `connectionPoolSize` (number, default 50) - Size of the connection pool for backend servers
+- `logLevel` ('error'|'warn'|'info'|'debug') - Logging verbosity level
+- `acme` (IAcmeOptions) - ACME certificate configuration
+- `useExternalPort80Handler` (boolean) - Use external port 80 handler for ACME challenges
+- `portProxyIntegration` (boolean) - Integration with other proxies
+
+#### NetworkProxy Enhanced Features
+NetworkProxy now supports full route-based configuration including:
+- Advanced request and response header manipulation
+- URL rewriting with RegExp pattern matching
+- Template variable resolution for dynamic values (e.g. `{domain}`, `{clientIp}`)
+- Function-based dynamic target resolution
+- Security features (IP filtering, rate limiting, authentication)
+- WebSocket configuration with path rewriting, custom headers, ping control, and size limits
+- Context-aware CORS configuration
 
 ### Port80Handler (IAcmeOptions)
 - `enabled` (boolean, default true)

package/readme.plan.md

@@ -1,168 +1,103 @@
-# SmartProxy Complete Route-Based Implementation Plan
-
-## Project Goal
-Complete the refactoring of SmartProxy to a pure route-based configuration approach by:
-1. Removing all remaining domain-based configuration code with no backward compatibility
-2. Updating internal components to work directly and exclusively with route configurations
-3. Eliminating all conversion functions and domain-based interfaces
-4. Cleaning up deprecated methods and interfaces completely
-5. Focusing entirely on route-based helper functions for the best developer experience
-
-## Current Status
-The major refactoring to route-based configuration has been successfully completed:
-- SmartProxy now works exclusively with route-based configurations in its public API
-- All test files have been updated to use route-based configurations
-- Documentation has been updated to explain the route-based approach
-- Helper functions have been implemented for creating route configurations
-- All features are working correctly with the new approach
-
-### Completed Phases:
-1. ✅ **Phase 1:** CertProvisioner has been fully refactored to work natively with routes
-2. ✅ **Phase 2:** NetworkProxyBridge now works directly with route configurations
-3. ✅ **Phase 3:** Legacy domain configuration code has been removed
-4. ✅ **Phase 4:** Route helpers and configuration experience have been enhanced
-5. ✅ **Phase 5:** Tests and validation have been completed
-
-### Project Status:
-✅ COMPLETED (May 10, 2025): SmartProxy has been fully refactored to a pure route-based configuration approach with no backward compatibility for domain-based configurations.
-
-## Implementation Checklist
-
-### Phase 1: Refactor CertProvisioner for Native Route Support ✅
-- [x] 1.1 Update CertProvisioner constructor to store routeConfigs directly
-- [x] 1.2 Remove extractDomainsFromRoutes() method and domainConfigs array
-- [x] 1.3 Create extractCertificateRoutesFromRoutes() method to find routes needing certificates
-- [x] 1.4 Update provisionAllDomains() to work with route configurations
-- [x] 1.5 Update provisionDomain() to handle route configs
-- [x] 1.6 Modify renewal tracking to use routes instead of domains
-- [x] 1.7 Update renewals scheduling to use route-based approach
-- [x] 1.8 Refactor requestCertificate() method to use routes
-- [x] 1.9 Update ICertificateData interface to include route references
-- [x] 1.10 Update certificate event handling to include route information
-- [x] 1.11 Add unit tests for route-based certificate provisioning
-- [x] 1.12 Add tests for wildcard domain handling with routes
-- [x] 1.13 Test certificate renewal with route configurations
-- [x] 1.14 Update certificate-types.ts to remove domain-based types
-
-### Phase 2: Refactor NetworkProxyBridge for Direct Route Processing ✅
-- [x] 2.1 Update NetworkProxyBridge constructor to work directly with routes
-- [x] 2.2 Refactor syncRoutesToNetworkProxy() to eliminate domain conversion
-- [x] 2.3 Rename convertRoutesToNetworkProxyConfigs() to mapRoutesToNetworkProxyConfigs()
-- [x] 2.4 Maintain syncDomainConfigsToNetworkProxy() as deprecated wrapper
-- [x] 2.5 Implement direct mapping from routes to NetworkProxy configs
-- [x] 2.6 Update handleCertificateEvent() to work with routes
-- [x] 2.7 Update applyExternalCertificate() to use route information
-- [x] 2.8 Update registerDomainsWithPort80Handler() to extract domains from routes
-- [x] 2.9 Update certificate request flow to track route references
-- [x] 2.10 Test NetworkProxyBridge with pure route configurations
-- [x] 2.11 Successfully build and run all tests
-
-### Phase 3: Remove Legacy Domain Configuration Code
-- [x] 3.1 Identify all imports of domain-config.ts and update them
-- [x] 3.2 Create route-based alternatives for any remaining domain-config usage
-- [x] 3.3 Delete domain-config.ts
-- [x] 3.4 Identify all imports of domain-manager.ts and update them
-- [x] 3.5 Delete domain-manager.ts
-- [x] 3.6 Update forwarding-types.ts (route-based only)
-- [x] 3.7 Add route-based domain support to Port80Handler
-- [x] 3.8 Create IPort80RouteOptions and extractPort80RoutesFromRoutes utility
-- [x] 3.9 Update SmartProxy.ts to use route-based domain management
-- [x] 3.10 Provide compatibility layer for domain-based interfaces
-- [x] 3.11 Update IDomainForwardConfig to IRouteForwardConfig
-- [x] 3.12 Update JSDoc comments to reference routes instead of domains
-- [x] 3.13 Run build to find any remaining type errors
-- [x] 3.14 Fix all type errors to ensure successful build
-- [x] 3.15 Update tests to use route-based approach instead of domain-based
-- [x] 3.16 Fix all failing tests
-- [x] 3.17 Verify build and test suite pass successfully
-
-### Phase 4: Enhance Route Helpers and Configuration Experience ✅
-- [x] 4.1 Create route-validators.ts with validation functions
-- [x] 4.2 Add validateRouteConfig() function for configuration validation
-- [x] 4.3 Add mergeRouteConfigs() utility function
-- [x] 4.4 Add findMatchingRoutes() helper function
-- [x] 4.5 Expand createStaticFileRoute() with more options
-- [x] 4.6 Add createApiRoute() helper for API gateway patterns
-- [x] 4.7 Add createAuthRoute() for authentication configurations
-- [x] 4.8 Add createWebSocketRoute() helper for WebSocket support
-- [x] 4.9 Create routePatterns.ts with common route patterns
-- [x] 4.10 Update utils/index.ts to export all helpers
-- [x] 4.11 Add schema validation for route configurations
-- [x] 4.12 Create utils for route pattern testing
-- [x] 4.13 Update docs with pure route-based examples
-- [x] 4.14 Remove any legacy code examples from documentation
-
-### Phase 5: Testing and Validation ✅
-- [x] 5.1 Update all tests to use pure route-based components
-- [x] 5.2 Create test cases for potential edge cases
-- [x] 5.3 Create a test for domain wildcard handling
-- [x] 5.4 Test all helper functions
-- [x] 5.5 Test certificate provisioning with routes
-- [x] 5.6 Test NetworkProxy integration with routes
-- [x] 5.7 Benchmark route matching performance
-- [x] 5.8 Compare memory usage before and after changes
-- [x] 5.9 Optimize route operations for large configurations
-- [x] 5.10 Verify public API matches documentation
-- [x] 5.11 Check for any backward compatibility issues
-- [x] 5.12 Ensure all examples in README work correctly
-- [x] 5.13 Run full test suite with new implementation
-- [x] 5.14 Create a final PR with all changes
-
-## Clean Break Approach
-
-To keep our codebase as clean as possible, we are taking a clean break approach with NO migration or compatibility support for domain-based configuration. We will:
-
-1. Completely remove all domain-based code
-2. Not provide any migration utilities in the codebase
-3. Focus solely on the route-based approach
-4. Document the route-based API as the only supported method
-
-This approach prioritizes codebase clarity over backward compatibility, which is appropriate since we've already made a clean break in the public API with v14.0.0.
-
-## File Changes
-
-### Files to Delete (Remove Completely)
-- [x] `/ts/forwarding/config/domain-config.ts` - Deleted with no replacement
-- [x] `/ts/forwarding/config/domain-manager.ts` - Deleted with no replacement
-- [x] `/ts/forwarding/config/forwarding-types.ts` - Updated with pure route-based types
-- [x] Any domain-config related tests have been updated to use route-based approach
-
-### Files to Modify (Remove All Domain References)
-- [x] `/ts/certificate/providers/cert-provisioner.ts` - Complete rewrite to use routes only ✅
-- [x] `/ts/proxies/smart-proxy/network-proxy-bridge.ts` - Direct route processing implementation ✅
-- [x] `/ts/certificate/models/certificate-types.ts` - Updated with route-based interfaces ✅
-- [x] `/ts/certificate/index.ts` - Cleaned up domain-related types and exports
-- [x] `/ts/http/port80/port80-handler.ts` - Updated to work exclusively with routes
-- [x] `/ts/proxies/smart-proxy/smart-proxy.ts` - Removed domain references
-- [x] `test/test.forwarding.ts` - Updated to use route-based approach
-- [x] `test/test.forwarding.unit.ts` - Updated to use route-based approach
-
-### New Files to Create (Route-Focused)
-- [x] `/ts/proxies/smart-proxy/utils/route-helpers.ts` - Created with helper functions for common route configurations
-- [x] `/ts/proxies/smart-proxy/utils/route-migration-utils.ts` - Added migration utilities from domains to routes
-- [x] `/ts/proxies/smart-proxy/utils/route-validators.ts` - Validation utilities for route configurations
-- [x] `/ts/proxies/smart-proxy/utils/route-utils.ts` - Additional route utility functions
-- [x] `/ts/proxies/smart-proxy/utils/route-patterns.ts` - Common route patterns for easy configuration
-- [x] `/ts/proxies/smart-proxy/utils/index.ts` - Central export point for all route utilities
-
-## Benefits of Complete Refactoring
-
-1. **Codebase Simplicity**:
-   - No dual implementation or conversion logic
-   - Simplified mental model for developers
-   - Easier to maintain and extend
-
-2. **Performance Improvements**:
-   - Remove conversion overhead
-   - More efficient route matching
-   - Reduced memory footprint
-
-3. **Better Developer Experience**:
-   - Consistent API throughout
-   - Cleaner documentation
-   - More intuitive configuration patterns
-
-4. **Future-Proof Design**:
-   - Clear foundation for new features
-   - Easier to implement advanced routing capabilities
-   - Better integration with modern web patterns
+# SmartProxy Configuration Troubleshooting
+
+## IPv6/IPv4 Mapping Issue
+
+### Problem Identified
+The SmartProxy is failing to match connections for wildcard domains (like `*.lossless.digital`) when IP restrictions are in place. After extensive debugging, the root cause has been identified:
+
+When a connection comes in from an IPv4 address (e.g., `212.95.99.130`), the Node.js server receives it as an IPv6-mapped IPv4 address with the format `::ffff:212.95.99.130`. However, the route configuration is expecting the exact string `212.95.99.130`, causing a mismatch.
+
+From the debug logs:
+```
+[DEBUG] Route rejected: clientIp mismatch. Request: ::ffff:212.95.99.130, Route patterns: ["212.95.99.130"]
+```
+
+### Solution
+
+To fix this issue, update the route configurations to include both formats of the IP address. Here's how to modify the affected route:
+
+```typescript
+// Wildcard domain route for *.lossless.digital
+{
+  match: {
+    ports: 443,
+    domains: ['*.lossless.digital'],
+    clientIp: ['212.95.99.130', '::ffff:212.95.99.130'],  // Include both formats
+  },
+  action: {
+    type: 'forward',
+    target: {
+      host: '212.95.99.130',
+      port: 443
+    },
+    tls: {
+      mode: 'passthrough'
+    },
+    security: {
+      allowedIps: ['212.95.99.130', '::ffff:212.95.99.130']  // Include both formats
+    }
+  },
+  name: 'Wildcard lossless.digital route (IP restricted)'
+}
+```
+
+### Alternative Long-Term Fix
+
+A more robust solution would be to modify the SmartProxy codebase to automatically handle IPv6-mapped IPv4 addresses by normalizing them before comparison. This would involve:
+
+1. Modifying the `matchIpPattern` function in `route-manager.ts` to normalize IPv6-mapped IPv4 addresses:
+
+```typescript
+private matchIpPattern(pattern: string, ip: string): boolean {
+  // Normalize IPv6-mapped IPv4 addresses
+  const normalizedIp = ip.startsWith('::ffff:') ? ip.substring(7) : ip;
+  const normalizedPattern = pattern.startsWith('::ffff:') ? pattern.substring(7) : pattern;
+  
+  // Handle exact match with normalized addresses
+  if (normalizedPattern === normalizedIp) {
+    return true;
+  }
+  
+  // Rest of the existing function...
+}
+```
+
+2. Making similar modifications to other IP-related functions in the codebase.
+
+## Wild Card Domain Matching Issue
+
+### Explanation
+
+The wildcard domain matching in SmartProxy works as follows:
+
+1. When a pattern like `*.lossless.digital` is specified, it's converted to a regex: `/^.*\.lossless\.digital$/i`
+2. This correctly matches any subdomain like `my.lossless.digital`, `api.lossless.digital`, etc.
+3. However, it does NOT match the apex domain `lossless.digital` (without a subdomain)
+
+If you need to match both the apex domain and subdomains, use a list:
+```typescript
+domains: ['lossless.digital', '*.lossless.digital']
+```
+
+## Debugging SmartProxy
+
+To debug routing issues in SmartProxy:
+
+1. Add detailed logging to the `route-manager.js` file in the `dist_ts` directory:
+   - `findMatchingRoute` method - to see what criteria are being checked
+   - `matchRouteDomain` method - to see domain matching logic
+   - `matchDomain` method - to see pattern matching
+   - `matchIpPattern` method - to see IP matching logic
+
+2. Run the proxy with debugging enabled:
+   ```
+   pnpm run startNew
+   ```
+
+3. Monitor the logs for detailed information about the routing process and identify where matches are failing.
+
+## Priority and Route Order
+
+Remember that routes are evaluated in priority order (higher priority first). If multiple routes could match the same request, ensure that the more specific routes have higher priority.
+
+When routes have the same priority (or none specified), they're evaluated in the order they're defined in the configuration.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartproxy',
-  version: '16.0.2',
+  version: '16.0.4',
   description: '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.'
 }

package/ts/core/models/index.ts

@@ -3,3 +3,5 @@
  */
 
 export * from './common-types.js';
+export * from './socket-augmentation.js';
+export * from './route-context.js';

package/ts/core/models/route-context.ts

@@ -0,0 +1,113 @@
+import * as plugins from '../../plugins.js';
+
+/**
+ * Shared Route Context Interface
+ * 
+ * This interface defines the route context object that is used by both
+ * SmartProxy and NetworkProxy, ensuring consistent context throughout the system.
+ */
+
+/**
+ * Route context for route matching and function-based target resolution
+ */
+export interface IRouteContext {
+  // Connection basics
+  port: number;          // The matched incoming port
+  domain?: string;       // The domain from SNI or Host header
+  clientIp: string;      // The client's IP address
+  serverIp: string;      // The server's IP address
+  
+  // HTTP specifics (NetworkProxy only)
+  path?: string;         // URL path (for HTTP connections)
+  query?: string;        // Query string (for HTTP connections) 
+  headers?: Record<string, string>; // HTTP headers (for HTTP connections)
+  
+  // TLS information
+  isTls: boolean;        // Whether the connection is TLS
+  tlsVersion?: string;   // TLS version if applicable
+  
+  // Routing information
+  routeName?: string;    // The name of the matched route
+  routeId?: string;      // The ID of the matched route
+  
+  // Resolved values
+  targetHost?: string | string[]; // The resolved target host
+  targetPort?: number;   // The resolved target port
+  
+  // Request metadata
+  timestamp: number;     // The request timestamp
+  connectionId: string;  // Unique connection identifier
+}
+
+/**
+ * Extended context interface with HTTP-specific objects
+ * Used only in NetworkProxy for HTTP request handling
+ */
+export interface IHttpRouteContext extends IRouteContext {
+  req?: plugins.http.IncomingMessage;
+  res?: plugins.http.ServerResponse;
+  method?: string; // HTTP method (GET, POST, etc.)
+}
+
+/**
+ * Extended context interface with HTTP/2-specific objects
+ * Used only in NetworkProxy for HTTP/2 request handling
+ */
+export interface IHttp2RouteContext extends IHttpRouteContext {
+  stream?: plugins.http2.ServerHttp2Stream;
+  headers?: Record<string, string>; // HTTP/2 pseudo-headers like :method, :path
+}
+
+/**
+ * Create a basic route context from connection information
+ */
+export function createBaseRouteContext(options: {
+  port: number;
+  clientIp: string;
+  serverIp: string;
+  domain?: string;
+  isTls: boolean;
+  tlsVersion?: string;
+  connectionId: string;
+}): IRouteContext {
+  return {
+    ...options,
+    timestamp: Date.now(),
+  };
+}
+
+/**
+ * Convert IHttpRouteContext to IRouteContext
+ * This is used to ensure type compatibility when passing HTTP-specific context 
+ * to methods that require the base IRouteContext type
+ */
+export function toBaseContext(httpContext: IHttpRouteContext): IRouteContext {
+  // Create a new object with only the properties from IRouteContext
+  const baseContext: IRouteContext = {
+    port: httpContext.port,
+    domain: httpContext.domain,
+    clientIp: httpContext.clientIp,
+    serverIp: httpContext.serverIp,
+    path: httpContext.path,
+    query: httpContext.query,
+    headers: httpContext.headers,
+    isTls: httpContext.isTls,
+    tlsVersion: httpContext.tlsVersion,
+    routeName: httpContext.routeName,
+    routeId: httpContext.routeId,
+    timestamp: httpContext.timestamp,
+    connectionId: httpContext.connectionId
+  };
+  
+  // Only copy targetHost if it's a string
+  if (httpContext.targetHost) {
+    baseContext.targetHost = httpContext.targetHost;
+  }
+  
+  // Copy targetPort if it exists
+  if (httpContext.targetPort) {
+    baseContext.targetPort = httpContext.targetPort;
+  }
+  
+  return baseContext;
+}

package/ts/core/models/socket-augmentation.ts

@@ -0,0 +1,33 @@
+import * as plugins from '../../plugins.js';
+
+// Augment the Node.js Socket type to include TLS-related properties
+// This helps TypeScript understand properties that are dynamically added by Node.js
+declare module 'net' {
+  interface Socket {
+    // TLS-related properties
+    encrypted?: boolean;    // Indicates if the socket is encrypted (TLS/SSL)
+    authorizationError?: Error; // Authentication error if TLS handshake failed
+    
+    // TLS-related methods
+    getTLSVersion?(): string;  // Returns the TLS version (e.g., 'TLSv1.2', 'TLSv1.3')
+    getPeerCertificate?(detailed?: boolean): any;  // Returns the peer's certificate
+    getSession?(): Buffer;   // Returns the TLS session data
+  }
+}
+
+// Export a utility function to check if a socket is a TLS socket
+export function isTLSSocket(socket: plugins.net.Socket): boolean {
+  return 'encrypted' in socket && !!socket.encrypted;
+}
+
+// Export a utility function to safely get the TLS version
+export function getTLSVersion(socket: plugins.net.Socket): string | null {
+  if (socket.getTLSVersion) {
+    try {
+      return socket.getTLSVersion();
+    } catch (e) {
+      return null;
+    }
+  }
+  return null;
+}