@push.rocks/smartproxy 10.2.0 → 12.0.0

package/dist_ts/smartproxy/types/forwarding.types.d.ts

@@ -0,0 +1,104 @@
+import type * as plugins from '../../plugins.js';
+/**
+ * The primary forwarding types supported by SmartProxy
+ */
+export type ForwardingType = 'http-only' | 'https-passthrough' | 'https-terminate-to-http' | 'https-terminate-to-https';
+/**
+ * Target configuration for forwarding
+ */
+export interface ITargetConfig {
+    host: string | string[];
+    port: number;
+}
+/**
+ * HTTP-specific options for forwarding
+ */
+export interface IHttpOptions {
+    enabled?: boolean;
+    redirectToHttps?: boolean;
+    headers?: Record<string, string>;
+}
+/**
+ * HTTPS-specific options for forwarding
+ */
+export interface IHttpsOptions {
+    customCert?: {
+        key: string;
+        cert: string;
+    };
+    forwardSni?: boolean;
+}
+/**
+ * ACME certificate handling options
+ */
+export interface IAcmeForwardingOptions {
+    enabled?: boolean;
+    maintenance?: boolean;
+    production?: boolean;
+    forwardChallenges?: {
+        host: string;
+        port: number;
+        useTls?: boolean;
+    };
+}
+/**
+ * Security options for forwarding
+ */
+export interface ISecurityOptions {
+    allowedIps?: string[];
+    blockedIps?: string[];
+    maxConnections?: number;
+}
+/**
+ * Advanced options for forwarding
+ */
+export interface IAdvancedOptions {
+    portRanges?: Array<{
+        from: number;
+        to: number;
+    }>;
+    networkProxyPort?: number;
+    keepAlive?: boolean;
+    timeout?: number;
+    headers?: Record<string, string>;
+}
+/**
+ * Unified forwarding configuration interface
+ */
+export interface IForwardConfig {
+    type: ForwardingType;
+    target: ITargetConfig;
+    http?: IHttpOptions;
+    https?: IHttpsOptions;
+    acme?: IAcmeForwardingOptions;
+    security?: ISecurityOptions;
+    advanced?: IAdvancedOptions;
+}
+/**
+ * Event types emitted by forwarding handlers
+ */
+export declare enum ForwardingHandlerEvents {
+    CONNECTED = "connected",
+    DISCONNECTED = "disconnected",
+    ERROR = "error",
+    DATA_FORWARDED = "data-forwarded",
+    HTTP_REQUEST = "http-request",
+    HTTP_RESPONSE = "http-response",
+    CERTIFICATE_NEEDED = "certificate-needed",
+    CERTIFICATE_LOADED = "certificate-loaded"
+}
+/**
+ * Base interface for forwarding handlers
+ */
+export interface IForwardingHandler extends plugins.EventEmitter {
+    initialize(): Promise<void>;
+    handleConnection(socket: plugins.net.Socket): void;
+    handleHttpRequest(req: plugins.http.IncomingMessage, res: plugins.http.ServerResponse): void;
+}
+/**
+ * Helper function types for common forwarding patterns
+ */
+export declare const httpOnly: (partialConfig: Partial<IForwardConfig> & Pick<IForwardConfig, "target">) => IForwardConfig;
+export declare const tlsTerminateToHttp: (partialConfig: Partial<IForwardConfig> & Pick<IForwardConfig, "target">) => IForwardConfig;
+export declare const tlsTerminateToHttps: (partialConfig: Partial<IForwardConfig> & Pick<IForwardConfig, "target">) => IForwardConfig;
+export declare const httpsPassthrough: (partialConfig: Partial<IForwardConfig> & Pick<IForwardConfig, "target">) => IForwardConfig;

package/dist_ts/smartproxy/types/forwarding.types.js

@@ -0,0 +1,50 @@
+/**
+ * Event types emitted by forwarding handlers
+ */
+export var ForwardingHandlerEvents;
+(function (ForwardingHandlerEvents) {
+    ForwardingHandlerEvents["CONNECTED"] = "connected";
+    ForwardingHandlerEvents["DISCONNECTED"] = "disconnected";
+    ForwardingHandlerEvents["ERROR"] = "error";
+    ForwardingHandlerEvents["DATA_FORWARDED"] = "data-forwarded";
+    ForwardingHandlerEvents["HTTP_REQUEST"] = "http-request";
+    ForwardingHandlerEvents["HTTP_RESPONSE"] = "http-response";
+    ForwardingHandlerEvents["CERTIFICATE_NEEDED"] = "certificate-needed";
+    ForwardingHandlerEvents["CERTIFICATE_LOADED"] = "certificate-loaded";
+})(ForwardingHandlerEvents || (ForwardingHandlerEvents = {}));
+/**
+ * Helper function types for common forwarding patterns
+ */
+export const httpOnly = (partialConfig) => ({
+    type: 'http-only',
+    target: partialConfig.target,
+    http: { enabled: true, ...(partialConfig.http || {}) },
+    ...(partialConfig.security ? { security: partialConfig.security } : {}),
+    ...(partialConfig.advanced ? { advanced: partialConfig.advanced } : {})
+});
+export const tlsTerminateToHttp = (partialConfig) => ({
+    type: 'https-terminate-to-http',
+    target: partialConfig.target,
+    https: { ...(partialConfig.https || {}) },
+    acme: { enabled: true, maintenance: true, ...(partialConfig.acme || {}) },
+    http: { enabled: true, redirectToHttps: true, ...(partialConfig.http || {}) },
+    ...(partialConfig.security ? { security: partialConfig.security } : {}),
+    ...(partialConfig.advanced ? { advanced: partialConfig.advanced } : {})
+});
+export const tlsTerminateToHttps = (partialConfig) => ({
+    type: 'https-terminate-to-https',
+    target: partialConfig.target,
+    https: { ...(partialConfig.https || {}) },
+    acme: { enabled: true, maintenance: true, ...(partialConfig.acme || {}) },
+    http: { enabled: true, redirectToHttps: true, ...(partialConfig.http || {}) },
+    ...(partialConfig.security ? { security: partialConfig.security } : {}),
+    ...(partialConfig.advanced ? { advanced: partialConfig.advanced } : {})
+});
+export const httpsPassthrough = (partialConfig) => ({
+    type: 'https-passthrough',
+    target: partialConfig.target,
+    https: { forwardSni: true, ...(partialConfig.https || {}) },
+    ...(partialConfig.security ? { security: partialConfig.security } : {}),
+    ...(partialConfig.advanced ? { advanced: partialConfig.advanced } : {})
+});
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZm9yd2FyZGluZy50eXBlcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3RzL3NtYXJ0cHJveHkvdHlwZXMvZm9yd2FyZGluZy50eXBlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUE2RkE7O0dBRUc7QUFDSCxNQUFNLENBQU4sSUFBWSx1QkFTWDtBQVRELFdBQVksdUJBQXVCO0lBQ2pDLGtEQUF1QixDQUFBO0lBQ3ZCLHdEQUE2QixDQUFBO0lBQzdCLDBDQUFlLENBQUE7SUFDZiw0REFBaUMsQ0FBQTtJQUNqQyx3REFBNkIsQ0FBQTtJQUM3QiwwREFBK0IsQ0FBQTtJQUMvQixvRUFBeUMsQ0FBQTtJQUN6QyxvRUFBeUMsQ0FBQTtBQUMzQyxDQUFDLEVBVFcsdUJBQXVCLEtBQXZCLHVCQUF1QixRQVNsQztBQVdEOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sUUFBUSxHQUFHLENBQ3RCLGFBQXVFLEVBQ3ZELEVBQUUsQ0FBQyxDQUFDO0lBQ3BCLElBQUksRUFBRSxXQUFXO0lBQ2pCLE1BQU0sRUFBRSxhQUFhLENBQUMsTUFBTTtJQUM1QixJQUFJLEVBQUUsRUFBRSxPQUFPLEVBQUUsSUFBSSxFQUFFLEdBQUcsQ0FBQyxhQUFhLENBQUMsSUFBSSxJQUFJLEVBQUUsQ0FBQyxFQUFFO0lBQ3RELEdBQUcsQ0FBQyxhQUFhLENBQUMsUUFBUSxDQUFDLENBQUMsQ0FBQyxFQUFFLFFBQVEsRUFBRSxhQUFhLENBQUMsUUFBUSxFQUFFLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQztJQUN2RSxHQUFHLENBQUMsYUFBYSxDQUFDLFFBQVEsQ0FBQyxDQUFDLENBQUMsRUFBRSxRQUFRLEVBQUUsYUFBYSxDQUFDLFFBQVEsRUFBRSxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUM7Q0FDeEUsQ0FBQyxDQUFDO0FBRUgsTUFBTSxDQUFDLE1BQU0sa0JBQWtCLEdBQUcsQ0FDaEMsYUFBdUUsRUFDdkQsRUFBRSxDQUFDLENBQUM7SUFDcEIsSUFBSSxFQUFFLHlCQUF5QjtJQUMvQixNQUFNLEVBQUUsYUFBYSxDQUFDLE1BQU07SUFDNUIsS0FBSyxFQUFFLEVBQUUsR0FBRyxDQUFDLGFBQWEsQ0FBQyxLQUFLLElBQUksRUFBRSxDQUFDLEVBQUU7SUFDekMsSUFBSSxFQUFFLEVBQUUsT0FBTyxFQUFFLElBQUksRUFBRSxXQUFXLEVBQUUsSUFBSSxFQUFFLEdBQUcsQ0FBQyxhQUFhLENBQUMsSUFBSSxJQUFJLEVBQUUsQ0FBQyxFQUFFO0lBQ3pFLElBQUksRUFBRSxFQUFFLE9BQU8sRUFBRSxJQUFJLEVBQUUsZUFBZSxFQUFFLElBQUksRUFBRSxHQUFHLENBQUMsYUFBYSxDQUFDLElBQUksSUFBSSxFQUFFLENBQUMsRUFBRTtJQUM3RSxHQUFHLENBQUMsYUFBYSxDQUFDLFFBQVEsQ0FBQyxDQUFDLENBQUMsRUFBRSxRQUFRLEVBQUUsYUFBYSxDQUFDLFFBQVEsRUFBRSxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUM7SUFDdkUsR0FBRyxDQUFDLGFBQWEsQ0FBQyxRQUFRLENBQUMsQ0FBQyxDQUFDLEVBQUUsUUFBUSxFQUFFLGFBQWEsQ0FBQyxRQUFRLEVBQUUsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDO0NBQ3hFLENBQUMsQ0FBQztBQUVILE1BQU0sQ0FBQyxNQUFNLG1CQUFtQixHQUFHLENBQ2pDLGFBQXVFLEVBQ3ZELEVBQUUsQ0FBQyxDQUFDO0lBQ3BCLElBQUksRUFBRSwwQkFBMEI7SUFDaEMsTUFBTSxFQUFFLGFBQWEsQ0FBQyxNQUFNO0lBQzVCLEtBQUssRUFBRSxFQUFFLEdBQUcsQ0FBQyxhQUFhLENBQUMsS0FBSyxJQUFJLEVBQUUsQ0FBQyxFQUFFO0lBQ3pDLElBQUksRUFBRSxFQUFFLE9BQU8sRUFBRSxJQUFJLEVBQUUsV0FBVyxFQUFFLElBQUksRUFBRSxHQUFHLENBQUMsYUFBYSxDQUFDLElBQUksSUFBSSxFQUFFLENBQUMsRUFBRTtJQUN6RSxJQUFJLEVBQUUsRUFBRSxPQUFPLEVBQUUsSUFBSSxFQUFFLGVBQWUsRUFBRSxJQUFJLEVBQUUsR0FBRyxDQUFDLGFBQWEsQ0FBQyxJQUFJLElBQUksRUFBRSxDQUFDLEVBQUU7SUFDN0UsR0FBRyxDQUFDLGFBQWEsQ0FBQyxRQUFRLENBQUMsQ0FBQyxDQUFDLEVBQUUsUUFBUSxFQUFFLGFBQWEsQ0FBQyxRQUFRLEVBQUUsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDO0lBQ3ZFLEdBQUcsQ0FBQyxhQUFhLENBQUMsUUFBUSxDQUFDLENBQUMsQ0FBQyxFQUFFLFFBQVEsRUFBRSxhQUFhLENBQUMsUUFBUSxFQUFFLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQztDQUN4RSxDQUFDLENBQUM7QUFFSCxNQUFNLENBQUMsTUFBTSxnQkFBZ0IsR0FBRyxDQUM5QixhQUF1RSxFQUN2RCxFQUFFLENBQUMsQ0FBQztJQUNwQixJQUFJLEVBQUUsbUJBQW1CO0lBQ3pCLE1BQU0sRUFBRSxhQUFhLENBQUMsTUFBTTtJQUM1QixLQUFLLEVBQUUsRUFBRSxVQUFVLEVBQUUsSUFBSSxFQUFFLEdBQUcsQ0FBQyxhQUFhLENBQUMsS0FBSyxJQUFJLEVBQUUsQ0FBQyxFQUFFO0lBQzNELEdBQUcsQ0FBQyxhQUFhLENBQUMsUUFBUSxDQUFDLENBQUMsQ0FBQyxFQUFFLFFBQVEsRUFBRSxhQUFhLENBQUMsUUFBUSxFQUFFLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQztJQUN2RSxHQUFHLENBQUMsYUFBYSxDQUFDLFFBQVEsQ0FBQyxDQUFDLENBQUMsRUFBRSxRQUFRLEVBQUUsYUFBYSxDQUFDLFFBQVEsRUFBRSxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUM7Q0FDeEUsQ0FBQyxDQUFDIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartproxy",
-  "version": "10.2.0",
+  "version": "12.0.0",
   "private": false,
   "description": "A powerful proxy package that effectively handles high traffic, with features such as SSL/TLS support, port proxying, WebSocket handling, dynamic routing with authentication options, and automatic ACME certificate management.",
   "main": "dist_ts/index.js",
@@ -74,7 +74,7 @@
   },
   "scripts": {
     "test": "(tstest test/)",
-    "build": "(tsbuild --web --allowimplicitany)",
+    "build": "(tsbuild tsfolders --allowimplicitany)",
     "format": "(gitzone format)",
     "buildDocs": "tsdoc"
   }

package/readme.md

@@ -6,6 +6,7 @@ A high-performance proxy toolkit for Node.js, offering:
 - Low-level port forwarding via nftables
 - HTTP-to-HTTPS and custom URL redirects
 - Advanced TCP/SNI-based proxying with IP filtering and rules
+- Unified forwarding configuration system for all proxy types
 
 ## Exports
 The following classes and interfaces are provided:
@@ -23,11 +24,14 @@ The following classes and interfaces are provided:
   TCP/SNI-based proxy with dynamic routing, IP filtering, and unified certificates.
 - **SniHandler** (ts/smartproxy/classes.pp.snihandler.ts)
   Static utilities to extract SNI hostnames from TLS handshakes.
+- **Forwarding Handlers** (ts/smartproxy/forwarding/*.ts)
+  Unified forwarding handlers for different connection types (HTTP, HTTPS passthrough, TLS termination).
 - **Interfaces**
   - IPortProxySettings, IDomainConfig (ts/smartproxy/classes.pp.interfaces.ts)
   - INetworkProxyOptions (ts/networkproxy/classes.np.types.ts)
-  - IAcmeOptions, IDomainOptions, IForwardConfig (ts/common/types.ts)
+  - IAcmeOptions, IDomainOptions (ts/common/types.ts)
   - INfTableProxySettings (ts/nfttablesproxy/classes.nftablesproxy.ts)
+  - IForwardConfig, ForwardingType (ts/smartproxy/types/forwarding.types.ts)
 
 ## Installation
 Install via npm:
@@ -134,16 +138,37 @@ await nft.stop();
 ### 5. TCP/SNI Proxy (SmartProxy)
 ```typescript
 import { SmartProxy } from '@push.rocks/smartproxy';
+import { createDomainConfig, httpOnly, tlsTerminateToHttp, httpsPassthrough } from '@push.rocks/smartproxy';
 
 const smart = new SmartProxy({
   fromPort: 443,
   toPort: 8443,
   domainConfigs: [
-    {
-      domains: ['example.com', '*.example.com'],
-      allowedIPs: ['*'],
-      targetIPs: ['127.0.0.1'],
-    }
+    // HTTPS passthrough example
+    createDomainConfig(['example.com', '*.example.com'],
+      httpsPassthrough({
+        target: {
+          host: '127.0.0.1',
+          port: 443
+        },
+        security: {
+          allowedIps: ['*']
+        }
+      })
+    ),
+    // HTTPS termination example
+    createDomainConfig('secure.example.com',
+      tlsTerminateToHttp({
+        target: {
+          host: 'localhost',
+          port: 3000
+        },
+        acme: {
+          enabled: true,
+          production: true
+        }
+      })
+    )
   ],
   sniEnabled: true
 });
@@ -386,6 +411,126 @@ Listen for certificate events via EventEmitter:
 
 Provide a `certProvisionFunction(domain)` in SmartProxy settings to supply static certs or return `'http01'`.
 
+## Unified Forwarding System
+
+The SmartProxy Unified Forwarding System provides a clean, use-case driven approach to configuring different types of traffic forwarding. It replaces disparate configuration mechanisms with a unified interface.
+
+### Forwarding Types
+
+The system supports four primary forwarding types:
+
+1. **HTTP-only (`http-only`)**: Forwards HTTP traffic to a backend server.
+2. **HTTPS Passthrough (`https-passthrough`)**: Passes through raw TLS traffic without termination (SNI forwarding).
+3. **HTTPS Termination to HTTP (`https-terminate-to-http`)**: Terminates TLS and forwards the decrypted traffic to an HTTP backend.
+4. **HTTPS Termination to HTTPS (`https-terminate-to-https`)**: Terminates TLS and creates a new TLS connection to an HTTPS backend.
+
+### Basic Configuration
+
+Each domain is configured with a forwarding type and target:
+
+```typescript
+{
+  domains: ['example.com'],
+  forwarding: {
+    type: 'http-only',
+    target: {
+      host: 'localhost',
+      port: 3000
+    }
+  }
+}
+```
+
+### Helper Functions
+
+Helper functions are provided for common configurations:
+
+```typescript
+import { createDomainConfig, httpOnly, tlsTerminateToHttp,
+         tlsTerminateToHttps, httpsPassthrough } from '@push.rocks/smartproxy';
+
+// HTTP-only
+await domainManager.addDomainConfig(
+  createDomainConfig('example.com', httpOnly({
+    target: { host: 'localhost', port: 3000 }
+  }))
+);
+
+// HTTPS termination to HTTP
+await domainManager.addDomainConfig(
+  createDomainConfig('secure.example.com', tlsTerminateToHttp({
+    target: { host: 'localhost', port: 3000 },
+    acme: { production: true }
+  }))
+);
+
+// HTTPS termination to HTTPS
+await domainManager.addDomainConfig(
+  createDomainConfig('api.example.com', tlsTerminateToHttps({
+    target: { host: 'internal-api', port: 8443 },
+    http: { redirectToHttps: true }
+  }))
+);
+
+// HTTPS passthrough (SNI)
+await domainManager.addDomainConfig(
+  createDomainConfig('passthrough.example.com', httpsPassthrough({
+    target: { host: '10.0.0.5', port: 443 }
+  }))
+);
+```
+
+### Advanced Configuration
+
+For more complex scenarios, additional options can be specified:
+
+```typescript
+{
+  domains: ['api.example.com'],
+  forwarding: {
+    type: 'https-terminate-to-https',
+    target: {
+      host: ['10.0.0.10', '10.0.0.11'], // Round-robin load balancing
+      port: 8443
+    },
+    http: {
+      enabled: true,
+      redirectToHttps: true
+    },
+    https: {
+      // Custom certificate instead of ACME-provisioned
+      customCert: {
+        key: '-----BEGIN PRIVATE KEY-----\n...',
+        cert: '-----BEGIN CERTIFICATE-----\n...'
+      }
+    },
+    security: {
+      allowedIps: ['10.0.0.*', '192.168.1.*'],
+      blockedIps: ['1.2.3.4'],
+      maxConnections: 100
+    },
+    advanced: {
+      timeout: 30000,
+      headers: {
+        'X-Forwarded-For': '{clientIp}',
+        'X-Original-Host': '{sni}'
+      }
+    }
+  }
+}
+```
+
+### Extended Configuration Options
+
+#### IForwardConfig
+- `type`: 'http-only' | 'https-passthrough' | 'https-terminate-to-http' | 'https-terminate-to-https'
+- `target`: { host: string | string[], port: number }
+- `http?`: { enabled?: boolean, redirectToHttps?: boolean, headers?: Record<string, string> }
+- `https?`: { customCert?: { key: string, cert: string }, forwardSni?: boolean }
+- `acme?`: { enabled?: boolean, maintenance?: boolean, production?: boolean, forwardChallenges?: { host: string, port: number, useTls?: boolean } }
+- `security?`: { allowedIps?: string[], blockedIps?: string[], maxConnections?: number }
+- `advanced?`: { portRanges?: Array<{ from: number, to: number }>, networkProxyPort?: number, keepAlive?: boolean, timeout?: number, headers?: Record<string, string> }
+
 ## Configuration Options
 
 ### NetworkProxy (INetworkProxyOptions)
@@ -425,12 +570,14 @@ Provide a `certProvisionFunction(domain)` in SmartProxy settings to supply stati
 
 ### SmartProxy (IPortProxySettings)
 - `fromPort`, `toPort` (number)
-- `domainConfigs` (IDomainConfig[])
-- `sniEnabled`, `defaultAllowedIPs`, `preserveSourceIP` (booleans)
+- `domainConfigs` (IDomainConfig[]) - Using unified forwarding configuration
+- `sniEnabled`, `preserveSourceIP` (booleans)
+- `defaultAllowedIPs`, `defaultBlockedIPs` (string[]) - Default IP allowlists/blocklists
 - Timeouts: `initialDataTimeout`, `socketTimeout`, `inactivityTimeout`, etc.
 - Socket opts: `noDelay`, `keepAlive`, `enableKeepAliveProbes`
 - `acme` (IAcmeOptions), `certProvisionFunction` (callback)
 - `useNetworkProxy` (number[]), `networkProxyPort` (number)
+- `globalPortRanges` (Array<{ from: number; to: number }>)
 
 ## Troubleshooting
 
@@ -455,6 +602,9 @@ Provide a `certProvisionFunction(domain)` in SmartProxy settings to supply stati
 - Increase `initialDataTimeout`/`maxPendingDataSize` for large ClientHello
 - Enable `enableTlsDebugLogging` to trace handshake
 - Ensure `allowSessionTicket` and fragmentation support for resumption
+- Double-check forwarding configuration to ensure correct `type` for your use case
+- Use helper functions like `httpOnly()`, `httpsPassthrough()`, etc. to create correct configurations
+- For IP filtering issues, check the `security.allowedIps` and `security.blockedIps` settings
 
 ## License and Legal Information