push.rocks/smartproxy
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

BREAKING CHANGE(IRouteSecurity): Consolidate duplicated IRouteSecurity interfaces by unifying property names

Browse Source
This commit is contained in:
Philipp Kunz
2025-05-15 09:34:01 +00:00
parent 1067177d82
commit 35d7dfcedf
12 changed files with 206 additions and 238 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
changelog.md
View File

@ -1,5 +1,14 @@
# Changelog
## 2025-05-15 - 18.0.0 - BREAKING CHANGE(IRouteSecurity)
Consolidate duplicated IRouteSecurity interfaces by unifying property names (using 'ipAllowList' and 'ipBlockList' exclusively) and removing legacy definitions, updating security checks throughout the codebase to handle IPv6-mapped IPv4 addresses and cleaning up deprecated forwarding helpers.
- Unified duplicate IRouteSecurity definitions into a single interface with consistent property names.
- Replaced 'allowedIps' and 'blockedIps' with 'ipAllowList' and 'ipBlockList' respectively.
- Updated references in security and route managers to use the new properties.
- Ensured consistent IPv6-mapped IPv4 normalization in IP security checks.
- Removed deprecated helpers and legacy code affecting port forwarding and route migration.
## 2025-05-15 - 17.0.0 - BREAKING CHANGE(smartproxy)
Remove legacy migration utilities and deprecated forwarding helpers; consolidate route utilities, streamline interface definitions, and normalize IPv6-mapped IPv4 addresses

303
readme.plan.md
View File

@ -1,201 +1,146 @@
# SmartProxy Codebase Cleanup Plan
# SmartProxy Interface Consolidation Plan
## Overview
This document outlines a comprehensive plan to clean up the SmartProxy codebase by removing deprecated and unused code, consolidating functionality, and reducing complexity. The goal is to make the codebase more maintainable, easier to understand, and better positioned for future enhancements.
This document outlines a plan to consolidate duplicate and inconsistent interfaces in the SmartProxy codebase, specifically the `IRouteSecurity` interface which is defined twice with different properties. This inconsistency caused issues with security checks for port forwarding. The goal is to unify these interfaces, use consistent property naming, and improve code maintainability.
## Phase 1: Remove Deprecated Code
## Problem Description
### 1.1 Delete Legacy Migration Utilities ✅
We currently have two separate `IRouteSecurity` interfaces defined in `ts/proxies/smart-proxy/models/route-types.ts`:
The route migration utilities were created to assist in transitioning from the legacy domain-based configuration to the new route-based configuration system. As this migration is now complete, these utilities can be safely removed.
1. **First definition** (lines 116-122) - Used in IRouteAction:
```typescript
export interface IRouteSecurity {
allowedIps?: string[];
blockedIps?: string[];
maxConnections?: number;
authentication?: IRouteAuthentication;
}
```
- **Action:** ✅ Remove `/ts/proxies/smart-proxy/utils/route-migration-utils.ts`
- **Impact:** Low - This file is explicitly marked as temporary and for migration purposes only
- **Dependencies:** ✅ Update any imports of these utilities (check forwarding-types.ts)
2. **Second definition** (lines 253-272) - Used directly in IRouteConfig:
```typescript
export interface IRouteSecurity {
rateLimit?: IRouteRateLimit;
basicAuth?: {...};
jwtAuth?: {...};
ipAllowList?: string[];
ipBlockList?: string[];
}
```
### 1.2 Clean Up References to Deleted Files ✅
This duplication with inconsistent naming (`allowedIps` vs `ipAllowList` and `blockedIps` vs `ipBlockList`) caused routing issues when IP security checks were used, as we had to implement a workaround to check both property names.
Several files are marked for deletion in the git status but are still referenced in the codebase.
## Implementation Plan
- **Action:** ✅ Remove references to deleted route-helpers files:
- ✅ Update `/ts/proxies/smart-proxy/utils/index.ts` to remove `export * from './route-helpers.js';`
- ✅ Update `/ts/forwarding/config/forwarding-types.ts` to remove imports and re-exports of route helper functions
- **Impact:** Medium - May break code that still relies on these helpers
- **Dependencies:** ✅ Ensure route-patterns.js provides equivalent functionality (moved helper functions from route-helpers.js to route-patterns.ts)
### Phase 1: Interface Consolidation
### 1.3 Remove Deprecated Forwarding Types and Helpers ✅
1. **Create a unified interface definition:**
- Create one comprehensive `IRouteSecurity` interface that includes all properties
- Use consistent property naming (standardize on `ipAllowList` and `ipBlockList`)
- Add proper documentation for each property
- Remove the duplicate interface definition
2. **Update references to use the unified interface:**
- Update all code that references the old interface properties
- Update all configurations to use the new property names
- Ensure implementation in `route-manager.ts` uses the correct property names
Legacy forwarding types and helper functions in forwarding-types.ts are marked as deprecated.
### Phase 2: Code and Documentation Updates
- **Action:** ✅
- ✅ Clean up `/ts/forwarding/config/forwarding-types.ts`
- ✅ Remove deprecated helper functions: `httpOnly`, `tlsTerminateToHttp`, `tlsTerminateToHttps`, `httpsPassthrough`
- ✅ Remove deprecated interfaces: `IDeprecatedForwardConfig`
- **Impact:** Medium - May break code that still uses these helpers
- **Dependencies:** ✅ Ensure route patterns provide equivalent functionality
1. **Update type usages and documentation:**
- Update all code that creates or uses security configurations
- Update documentation to reflect the new interface structure
- Add examples of the correct property usage
- Document the breaking change in changelog.md
## Phase 2: Consolidate and Simplify Code
2. **Add tests:**
- Update existing tests to use the new property names
- Add test cases for all security configuration scenarios
- Verify that port range configurations with security settings work correctly
### 2.1 Streamline Interface Definitions ✅
There are several redundant interfaces that could be simplified.
- **Action:** ✅
- ✅ Remove legacy type checking functions (`isLegacyOptions`, `isRoutedOptions`) in `/ts/proxies/smart-proxy/models/interfaces.ts`
- ✅ Update `ISmartProxyOptions` interface to remove obsolete properties
- ✅ Remove backward compatibility aliases like `IRoutedSmartProxyOptions`
- **Impact:** Medium - May break code that relies on these interfaces
- **Dependencies:** ✅ Update any code that references these interfaces
### 2.2 Consolidate Route Utilities
The route utilities are spread across multiple files with some overlapping functionality.
- **Action:**
- Consolidate route utilities into a single coherent structure
- Move common functions from route-utils.ts, route-patterns.ts into a single location
- Ensure consistent naming conventions for route utility functions
- **Impact:** Medium - Requires careful refactoring
- **Dependencies:** Update all references to these utilities
### 2.3 Clean Up Legacy Connection Handling ✅
The route-connection-handler.ts file contains legacy code and parameters kept for backward compatibility.
- **Action:** ✅
- ✅ Remove unused parameters and legacy comments from `setupDirectConnection` method
- ✅ Simplify connection handling logic by removing special cases for legacy configurations
- **Impact:** Medium - Requires careful testing to ensure no regressions
- **Dependencies:** ✅ Test with all current route configurations
## Phase 3: Code Modernization
### 3.1 Standardize on 'preserve' Port Handling ✅
Previously implemented changes to use `port: 'preserve'` instead of `preservePort: true` should be consistently applied.
- **Action:** ✅
- ✅ Ensure all code paths handle the 'preserve' value for port
- ✅ Remove any remaining references to preservePort in code and documentation
- **Impact:** Low - Already implemented in most places
- **Dependencies:** None
### 3.2 Normalize IPv6-Mapped IPv4 Addresses ✅
Implement consistent handling of IPv6-mapped IPv4 addresses throughout the codebase.
- **Action:** ✅
- ✅ Ensure any IP address comparisons consistently handle IPv6-mapped IPv4 addresses
- ✅ Standardize on a single approach to IP normalization
- **Impact:** Low - Already partially implemented
- **Dependencies:** None
### 3.3 Improve Type Safety ✅
Enhance type safety throughout the codebase to catch errors at compile time.
- **Action:** ✅
- ✅ Add stronger types where appropriate
- ✅ Remove any `any` types that could be replaced with more specific types
- ✅ Add explicit return types to functions
- **Impact:** Medium - May uncover existing issues
- **Dependencies:** None
## Phase 4: Documentation and Tests
### 4.1 Update API Documentation ✅
Ensure documentation is current and accurately reflects the cleaned-up API.
- **Action:** ✅
- ✅ Update comments and JSDoc throughout the codebase
- ✅ Ensure porthandling.md and other documentation reflect current implementation
- ✅ Remove references to deprecated functionality
- **Impact:** Low
- **Dependencies:** None
### 4.2 Add or Update Tests ✅
Ensure test coverage for the cleaned-up codebase.
- **Action:** ✅
- ✅ Update existing tests to remove references to deprecated functionality
- ✅ Add tests for edge cases in IP normalization
- ✅ Add tests for the updated route utility functions
- **Impact:** Medium
- **Dependencies:** None
## Implementation Sequence ✅
The changes were implemented in this order:
1. ✅ **Phase 1.1**: Remove Legacy Migration Utilities
2. ✅ **Phase 1.2**: Clean Up References to Deleted Files
3. ✅ **Phase 1.3**: Remove Deprecated Forwarding Types and Helpers
4. ✅ **Phase 2.1**: Streamline Interface Definitions
5. ✅ **Phase 3.1**: Standardize on 'preserve' Port Handling
6. ✅ **Phase 3.2**: Normalize IPv6-Mapped IPv4 Addresses
7. ⏸️ **Phase 2.2**: Consolidate Route Utilities (Postponed - Low priority)
8. ✅ **Phase 2.3**: Clean Up Legacy Connection Handling
9. ✅ **Phase 3.3**: Improve Type Safety
10. ✅ **Phase 4.1**: Update API Documentation
11. ✅ **Phase 4.2**: Add or Update Tests
## Detailed Implementation Steps
### 1. Remove Legacy Migration Utilities
```bash
# Delete the file
git rm ts/proxies/smart-proxy/utils/route-migration-utils.ts
# Remove the export from the index file
# Edit ts/proxies/smart-proxy/utils/index.ts to remove the export line
```
### 2. Clean Up References to Deleted Files
```bash
# Update forwarding-types.ts to remove imports from route-helpers.js
# Edit ts/forwarding/config/forwarding-types.ts
# Remove or update imports in index.ts
# Edit ts/proxies/smart-proxy/utils/index.ts
```
### 3. Remove Deprecated Forwarding Types
```bash
# Edit ts/forwarding/config/forwarding-types.ts to remove deprecated helpers and interfaces
```
### 4. Streamline Interface Definitions
```bash
# Edit ts/proxies/smart-proxy/models/interfaces.ts to remove legacy functions and aliases
```
### 5. Normalize IPv6-Mapped IPv4 Addresses
Ensure all IP matching functions consistently handle IPv6-mapped IPv4 addresses:
## Implementation Steps
```typescript
// In all IP matching functions:
const normalizeIp = (ip: string): string => {
return ip.startsWith('::ffff:') ? ip.substring(7) : ip;
};
// Step 1: Define the unified interface
export interface IRouteSecurity {
// Access control lists
ipAllowList?: string[]; // IP addresses that are allowed to connect
ipBlockList?: string[]; // IP addresses that are blocked from connecting
// Connection limits
maxConnections?: number; // Maximum concurrent connections
// Authentication
authentication?: IRouteAuthentication;
// Rate limiting
rateLimit?: IRouteRateLimit;
// Authentication methods
basicAuth?: {
enabled: boolean;
users: Array<{ username: string; password: string }>;
realm?: string;
excludePaths?: string[];
};
jwtAuth?: {
enabled: boolean;
secret: string;
algorithm?: string;
issuer?: string;
audience?: string;
expiresIn?: number;
excludePaths?: string[];
};
}
```
## Implementation Results ✅
Update `isClientIpAllowed` method to use only the new property names:
The cleanup implementation was successful, resulting in:
```typescript
private isClientIpAllowed(route: IRouteConfig, clientIp: string): boolean {
const security = route.action.security;
if (!security) {
return true; // No security settings means allowed
}
// Check blocked IPs first
if (security.ipBlockList && security.ipBlockList.length > 0) {
for (const pattern of security.ipBlockList) {
if (this.matchIpPattern(pattern, clientIp)) {
return false; // IP is blocked
}
}
}
// If there are allowed IPs, check them
if (security.ipAllowList && security.ipAllowList.length > 0) {
for (const pattern of security.ipAllowList) {
if (this.matchIpPattern(pattern, clientIp)) {
return true; // IP is allowed
}
}
return false; // IP not in allowed list
}
// No allowed IPs specified, so IP is allowed
return true;
}
```
- **Reduced Codebase Size**: Successfully removed multiple deprecated files and functions
- **Improved Maintainability**: Cleaner, more focused code without legacy compatibility layers
- **Reduced Complexity**: Eliminated special cases for legacy config formats
- **Better Developer Experience**: Standardized on consistent patterns for port handling
- **Future-Proofing**: Removed deprecated code that would complicate future upgrades
- **Type Safety**: Fixed multiple TypeScript errors and improved type checking
## Expected Benefits
All changes successfully compile and the build process passes with no errors. The codebase is now simpler, more maintainable, and better positioned for future enhancements.
- **Improved Consistency**: Single, unified interface with consistent property naming
- **Better Type Safety**: Eliminating confusing duplicate interface definitions
- **Reduced Errors**: Prevent misunderstandings about which property names to use
- **Forward Compatibility**: Clearer path for future security enhancements
- **Better Developer Experience**: Simplified interface with comprehensive documentation
## Testing Plan
1. Test with existing configurations using both old and new property names
2. Create specific test cases for port ranges with different security configurations
3. Verify that port forwarding with IP allow lists works correctly with the unified interface

2
test/test.route-config.ts
View File

@ -235,7 +235,7 @@ tap.test('SmartProxy: Should create instance with route-based config', async ()
port: 8080
},
security: {
allowedIps: ['127.0.0.1', '192.168.0.*'],
ipAllowList: ['127.0.0.1', '192.168.0.*'],
maxConnections: 100
}
},

2
ts/00_commitinfo_data.ts
View File

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

4
ts/core/utils/shared-security-manager.ts
View File

@ -199,8 +199,8 @@ export class SharedSecurityManager {
}
// Check IP against route security settings
const ipAllowList = route.security.ipAllowList || route.security.allowedIps;
const ipBlockList = route.security.ipBlockList || route.security.blockedIps;
const ipAllowList = route.security.ipAllowList;
const ipBlockList = route.security.ipBlockList;
const allowed = this.isIPAuthorized(clientIp, ipAllowList, ipBlockList);

22
ts/forwarding/handlers/base-handler.ts
View File

@ -40,9 +40,10 @@ export abstract class ForwardingHandler extends plugins.EventEmitter implements
/**
* Get a target from the configuration, supporting round-robin selection
* @param incomingPort Optional incoming port for 'preserve' mode
* @returns A resolved target object with host and port
*/
protected getTargetFromConfig(): { host: string, port: number } {
protected getTargetFromConfig(incomingPort: number = 80): { host: string, port: number } {
const { target } = this.config;
// Handle round-robin host selection
@ -55,32 +56,37 @@ export abstract class ForwardingHandler extends plugins.EventEmitter implements
const randomIndex = Math.floor(Math.random() * target.host.length);
return {
host: target.host[randomIndex],
port: this.resolvePort(target.port)
port: this.resolvePort(target.port, incomingPort)
};
}
// Single host
return {
host: target.host,
port: this.resolvePort(target.port)
port: this.resolvePort(target.port, incomingPort)
};
}
/**
* Resolves a port value, handling 'preserve' and function ports
* @param port The port value to resolve
* @param incomingPort Optional incoming port to use for 'preserve' mode
*/
protected resolvePort(port: number | 'preserve' | ((ctx: any) => number)): number {
protected resolvePort(
port: number | 'preserve' | ((ctx: any) => number),
incomingPort: number = 80
): number {
if (typeof port === 'function') {
try {
// Create a minimal context for the function
const ctx = { port: 80 }; // Default port for minimal context
// Create a minimal context for the function that includes the incoming port
const ctx = { port: incomingPort };
return port(ctx);
} catch (err) {
console.error('Error resolving port function:', err);
return 80; // Default fallback port
return incomingPort; // Fall back to incoming port
}
} else if (port === 'preserve') {
return 80; // Default port for 'preserve' in base handler
return incomingPort; // Use the actual incoming port for 'preserve'
} else {
return port;
}

11
ts/forwarding/handlers/http-handler.ts
View File

@ -38,6 +38,7 @@ export class HttpForwardingHandler extends ForwardingHandler {
// For HTTP, we mainly handle parsed requests, but we can still set up
// some basic connection tracking
const remoteAddress = socket.remoteAddress || 'unknown';
const localPort = socket.localPort || 80;
socket.on('close', (hadError) => {
this.emit(ForwardingHandlerEvents.DISCONNECTED, {
@ -54,7 +55,8 @@ export class HttpForwardingHandler extends ForwardingHandler {
});
this.emit(ForwardingHandlerEvents.CONNECTED, {
remoteAddress
remoteAddress,
localPort
});
}
@ -64,8 +66,11 @@ export class HttpForwardingHandler extends ForwardingHandler {
* @param res The HTTP response
*/
public handleHttpRequest(req: plugins.http.IncomingMessage, res: plugins.http.ServerResponse): void {
// Get the target from configuration
const target = this.getTargetFromConfig();
// Get the local port from the request (for 'preserve' port handling)
const localPort = req.socket.localPort || 80;
// Get the target from configuration, passing the incoming port
const target = this.getTargetFromConfig(localPort);
// Create a custom headers object with variables for substitution
const variables = {

4
ts/proxies/smart-proxy/models/interfaces.ts
View File

@ -27,8 +27,8 @@ export interface ISmartProxyOptions {
port: number; // Default port to use when not specified in routes
};
security?: {
allowedIps?: string[]; // Default allowed IPs
blockedIps?: string[]; // Default blocked IPs
ipAllowList?: string[]; // Default allowed IPs
ipBlockList?: string[]; // Default blocked IPs
maxConnections?: number; // Default max connections
};
preserveSourceIP?: boolean; // Default source IP preservation

58
ts/proxies/smart-proxy/models/route-types.ts
View File

@ -112,13 +112,39 @@ export interface IRouteAuthentication {
}
/**
* Security options for route actions
* Security options for routes
*/
export interface IRouteSecurity {
allowedIps?: string[];
blockedIps?: string[];
maxConnections?: number;
// Access control lists
ipAllowList?: string[]; // IP addresses that are allowed to connect
ipBlockList?: string[]; // IP addresses that are blocked from connecting
// Connection limits
maxConnections?: number; // Maximum concurrent connections
// Authentication
authentication?: IRouteAuthentication;
// Rate limiting
rateLimit?: IRouteRateLimit;
// Authentication methods
basicAuth?: {
enabled: boolean;
users: Array<{ username: string; password: string }>;
realm?: string;
excludePaths?: string[];
};
jwtAuth?: {
enabled: boolean;
secret: string;
algorithm?: string;
issuer?: string;
audience?: string;
expiresIn?: number;
excludePaths?: string[];
};
}
/**
@ -247,29 +273,7 @@ export interface IRouteRateLimit {
errorMessage?: string;
}
/**
* Security features for routes
*/
export interface IRouteSecurity {
rateLimit?: IRouteRateLimit;
basicAuth?: {
enabled: boolean;
users: Array<{ username: string; password: string }>;
realm?: string;
excludePaths?: string[];
};
jwtAuth?: {
enabled: boolean;
secret: string;
algorithm?: string;
issuer?: string;
audience?: string;
expiresIn?: number;
excludePaths?: string[];
};
ipAllowList?: string[];
ipBlockList?: string[];
}
// IRouteSecurity is defined above - unified definition is used for all routes
/**
* CORS configuration for a route

6
ts/proxies/smart-proxy/route-connection-handler.ts
View File

@ -289,11 +289,11 @@ export class RouteConnectionHandler {
// Check default security settings
const defaultSecuritySettings = this.settings.defaults?.security;
if (defaultSecuritySettings) {
if (defaultSecuritySettings.allowedIps && defaultSecuritySettings.allowedIps.length > 0) {
if (defaultSecuritySettings.ipAllowList && defaultSecuritySettings.ipAllowList.length > 0) {
const isAllowed = this.securityManager.isIPAuthorized(
remoteIP,
defaultSecuritySettings.allowedIps,
defaultSecuritySettings.blockedIps || []
defaultSecuritySettings.ipAllowList,
defaultSecuritySettings.ipBlockList || []
);
if (!isAllowed) {

8
ts/proxies/smart-proxy/route-manager.ts
View File

@ -213,8 +213,8 @@ export class RouteManager extends plugins.EventEmitter {
}
// Check blocked IPs first
if (security.blockedIps && security.blockedIps.length > 0) {
for (const pattern of security.blockedIps) {
if (security.ipBlockList && security.ipBlockList.length > 0) {
for (const pattern of security.ipBlockList) {
if (this.matchIpPattern(pattern, clientIp)) {
return false; // IP is blocked
}
@ -222,8 +222,8 @@ export class RouteManager extends plugins.EventEmitter {
}
// If there are allowed IPs, check them
if (security.allowedIps && security.allowedIps.length > 0) {
for (const pattern of security.allowedIps) {
if (security.ipAllowList && security.ipAllowList.length > 0) {
for (const pattern of security.ipAllowList) {
if (this.matchIpPattern(pattern, clientIp)) {
return true; // IP is allowed
}

15
ts/proxies/smart-proxy/security-manager.ts
View File

@ -63,16 +63,15 @@ export class SecurityManager {
}
/**
* Check if an IP is authorized using forwarding security rules
* Check if an IP is authorized using security rules
*
* This method is used to determine if an IP is allowed to connect, based on security
* rules configured in the forwarding configuration. The allowed and blocked IPs are
* typically derived from domain.forwarding.security.allowedIps and blockedIps through
* DomainConfigManager.getEffectiveIPRules().
* rules configured in the route configuration. The allowed and blocked IPs are
* typically derived from route.security.ipAllowList and ipBlockList.
*
* @param ip - The IP address to check
* @param allowedIPs - Array of allowed IP patterns from forwarding.security.allowedIps
* @param blockedIPs - Array of blocked IP patterns from forwarding.security.blockedIps
* @param allowedIPs - Array of allowed IP patterns from security.ipAllowList
* @param blockedIPs - Array of blocked IP patterns from security.ipBlockList
* @returns true if IP is authorized, false if blocked
*/
public isIPAuthorized(ip: string, allowedIPs: string[], blockedIPs: string[] = []): boolean {
@ -94,10 +93,10 @@ export class SecurityManager {
* Check if the IP matches any of the glob patterns from security configuration
*
* This method checks IP addresses against glob patterns and handles IPv4/IPv6 normalization.
* It's used to implement IP filtering based on the forwarding.security configuration.
* It's used to implement IP filtering based on the route.security configuration.
*
* @param ip - The IP address to check
* @param patterns - Array of glob patterns from forwarding.security.allowedIps or blockedIps
* @param patterns - Array of glob patterns from security.ipAllowList or ipBlockList
* @returns true if IP matches any pattern, false otherwise
*/
private isGlobIPMatch(ip: string, patterns: string[]): boolean {