smartproxy/readme.plan.md

# 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.