@push.rocks/smartproxy 29.1.0 → 30.0.0

package/ts/proxies/smart-proxy/utils/index.ts

@@ -9,7 +9,7 @@
 export * from './route-validator.js';
 
 // Export the error SmartProxy throws when it refuses a route set
-export { RouteValidationError } from './route-validation-error.js';
+export { RouteValidationError, SettingsValidationError } from './route-validation-error.js';
 export type { IRouteValidationErrorEntry } from './route-validation-error.js';
 
 // Export route utilities for route operations

package/ts/proxies/smart-proxy/utils/ip-entry-validation.ts

@@ -0,0 +1,201 @@
+import * as plugins from '../../../plugins.js';
+
+/**
+ * Validation of configured IP entries, one rule per Rust parser that reads them.
+ *
+ * Every check accepts exactly what its Rust reader can match and answers why it refuses anything
+ * else, so a configuration that validates never carries an entry the engine silently ignores:
+ *
+ * - Security lists (`security.ipAllowList`, `security.ipBlockList`, `defaults.security`,
+ *   `securityPolicy.blockedIps`/`blockedCidrs`) are read by `rustproxy-security` `IpPattern::parse`:
+ *   `*`, an address or an `ipnet` prefix, compared as parsed addresses with the client converted
+ *   from IPv4-mapped IPv6 to IPv4. Anything else becomes `0.0.0.0` and never matches.
+ * - Source matches (`match.clientIp`, `trustedProxyIPs` of a route policy or the settings) are read
+ *   by `rustproxy-routing` `matchers::ip_matches`: `*`, an `ipnet` prefix, a four-part IPv4 wildcard,
+ *   or an exact address compared as text against the client's Rust `Display` form, after a leading
+ *   `::ffff:` is stripped from both sides.
+ * - VPN assigned addresses (`security.vpn.allowedAssignedIps`) are compared as text against the
+ *   address the VPN metadata carries.
+ *
+ * A check answers `null` for an entry it accepts, else the reason it refuses it.
+ */
+
+const ipv4MappedPrefixLength = 96;
+
+/** An address without a zone index, in any textual form `node:net` and Rust both read. */
+const ipFamilyOf = (value: string): 0 | 4 | 6 => {
+  if (value.includes('%')) return 0;
+  return plugins.net.isIP(value) as 0 | 4 | 6;
+};
+
+/** The eight 16-bit segments of an IPv6 address `node:net` already accepted. */
+const ipv6SegmentsOf = (address: string): number[] => {
+  const toSegments = (text: string): number[] => {
+    if (text === '') return [];
+    const segments: number[] = [];
+    for (const part of text.split(':')) {
+      if (part.includes('.')) {
+        const [a, b, c, d] = part.split('.').map(Number);
+        segments.push((a << 8) | b, (c << 8) | d);
+      } else {
+        segments.push(parseInt(part, 16));
+      }
+    }
+    return segments;
+  };
+  const compressionAt = address.indexOf('::');
+  if (compressionAt === -1) {
+    return toSegments(address);
+  }
+  const head = toSegments(address.slice(0, compressionAt));
+  const tail = toSegments(address.slice(compressionAt + 2));
+  return [...head, ...new Array<number>(8 - head.length - tail.length).fill(0), ...tail];
+};
+
+/** The IPv4 address an IPv4-mapped IPv6 address (`::ffff:a.b.c.d`) carries, else `null`. */
+const ipv4MappedOf = (segments: number[]): string | null => {
+  if (segments.slice(0, 5).some((segment) => segment !== 0) || segments[5] !== 0xffff) {
+    return null;
+  }
+  return [segments[6] >> 8, segments[6] & 0xff, segments[7] >> 8, segments[7] & 0xff].join('.');
+};
+
+/**
+ * The address as Rust's `Display` writes it: IPv4 unchanged (`node:net` admits only plain decimal
+ * octets), IPv4-mapped IPv6 as `::ffff:a.b.c.d`, any other IPv6 in lowercase hex without leading
+ * zeros and with the first longest run of two or more zero segments written as `::`.
+ */
+export const formatIpAddress = (address: string): string => {
+  if (ipFamilyOf(address) !== 6) {
+    return address;
+  }
+  const segments = ipv6SegmentsOf(address);
+  const mapped = ipv4MappedOf(segments);
+  if (mapped !== null) {
+    return `::ffff:${mapped}`;
+  }
+  let longestStart = 0;
+  let longestLength = 0;
+  let currentStart = 0;
+  let currentLength = 0;
+  segments.forEach((segment, index) => {
+    if (segment === 0) {
+      if (currentLength === 0) currentStart = index;
+      currentLength += 1;
+      if (currentLength > longestLength) {
+        longestStart = currentStart;
+        longestLength = currentLength;
+      }
+    } else {
+      currentLength = 0;
+    }
+  });
+  const hex = (part: number[]) => part.map((segment) => segment.toString(16)).join(':');
+  if (longestLength > 1) {
+    return `${hex(segments.slice(0, longestStart))}::${hex(segments.slice(longestStart + longestLength))}`;
+  }
+  return hex(segments);
+};
+
+interface IParsedPrefix {
+  address: string;
+  family: 4 | 6;
+  length: number;
+}
+
+/**
+ * An address, `/` and a prefix length as `ipnet` parses it: up to two digits and at most 32 for
+ * IPv4, up to three digits and at most 128 for IPv6. Host bits may be set.
+ */
+const parsePrefix = (value: string): IParsedPrefix | null => {
+  const parts = value.split('/');
+  if (parts.length !== 2) return null;
+  const [address, lengthText] = parts;
+  const family = ipFamilyOf(address);
+  if (family === 4 && /^\d{1,2}$/.test(lengthText) && Number(lengthText) <= 32) {
+    return { address, family, length: Number(lengthText) };
+  }
+  if (family === 6 && /^\d{1,3}$/.test(lengthText) && Number(lengthText) <= 128) {
+    return { address, family, length: Number(lengthText) };
+  }
+  return null;
+};
+
+/** The IPv4 prefix an IPv4-mapped IPv6 prefix of at least 96 bits covers, else `null`. */
+const ipv4PrefixOfMapped = (prefix: IParsedPrefix): string | null => {
+  if (prefix.family !== 6 || prefix.length < ipv4MappedPrefixLength) return null;
+  const mapped = ipv4MappedOf(ipv6SegmentsOf(prefix.address));
+  return mapped === null ? null : `${mapped}/${prefix.length - ipv4MappedPrefixLength}`;
+};
+
+/** A four-part IPv4 wildcard with plain decimal octets first and only `*` parts after them. */
+const isIpv4TrailingWildcard = (value: string): boolean => {
+  const parts = value.split('.');
+  if (parts.length !== 4) return false;
+  const firstWildcard = parts.indexOf('*');
+  if (firstWildcard === -1) return false;
+  return parts.slice(0, firstWildcard).every((part) => /^(0|[1-9]\d{0,2})$/.test(part) && Number(part) <= 255)
+    && parts.slice(firstWildcard).every((part) => part === '*');
+};
+
+const zoneIndexReason = 'a zone index (%…) is not supported';
+
+/** Checks an entry of a security list: `ipAllowList`, `ipBlockList` or a global block list. */
+export const checkSecurityIpEntry = (entry: unknown): string | null => {
+  if (typeof entry !== 'string') return 'must be a string';
+  if (entry === '*') return null;
+  if (entry.includes('%')) return zoneIndexReason;
+  const family = ipFamilyOf(entry);
+  if (family !== 0) {
+    const mapped = family === 6 ? ipv4MappedOf(ipv6SegmentsOf(entry)) : null;
+    return mapped === null
+      ? null
+      : `an IPv4-mapped address never matches, because clients are compared as IPv4; write ${mapped}`;
+  }
+  const prefix = parsePrefix(entry);
+  if (prefix) {
+    const ipv4Prefix = ipv4PrefixOfMapped(prefix);
+    return ipv4Prefix === null
+      ? null
+      : `an IPv4-mapped prefix never matches, because clients are compared as IPv4; write ${ipv4Prefix}`;
+  }
+  return "must be '*', an IPv4 or IPv6 address, or an address prefix such as 192.0.2.0/24";
+};
+
+/** Checks a source-match entry: `match.clientIp` or a `trustedProxyIPs` entry. */
+export const checkSourceMatchIpEntry = (entry: unknown): string | null => {
+  if (typeof entry !== 'string') return 'must be a string';
+  if (entry === '*') return null;
+  if (entry.includes('%')) return zoneIndexReason;
+  if (ipFamilyOf(entry) !== 0) {
+    const canonical = formatIpAddress(entry);
+    return canonical === entry
+      ? null
+      : `an exact address is compared as text with the client address; write ${canonical}`;
+  }
+  const prefix = parsePrefix(entry);
+  if (prefix) {
+    const ipv4Prefix = ipv4PrefixOfMapped(prefix);
+    return ipv4Prefix === null
+      ? null
+      : `an IPv4-mapped prefix never matches, because clients are compared as IPv4; write ${ipv4Prefix}`;
+  }
+  if (isIpv4TrailingWildcard(entry)) return null;
+  return "must be '*', an IPv4 or IPv6 address, an address prefix such as 192.0.2.0/24, "
+    + 'or a four-part IPv4 wildcard such as 192.0.2.*';
+};
+
+/** Checks a `security.vpn.allowedAssignedIps` entry. */
+export const checkAssignedIpEntry = (entry: unknown): string | null => {
+  if (typeof entry !== 'string') return 'must be a string';
+  if (entry.includes('%')) return zoneIndexReason;
+  if (ipFamilyOf(entry) === 0) return 'must be one IPv4 or IPv6 address';
+  const canonical = formatIpAddress(entry);
+  return canonical === entry
+    ? null
+    : `an assigned address is compared as text with the VPN client's address; write ${canonical}`;
+};
+
+/** Formats one refused entry for a validation message. */
+export const describeRefusedIpEntry = (labelArg: string, entryArg: unknown, reasonArg: string): string =>
+  `${labelArg}: ${String(entryArg)} (${reasonArg})`;

package/ts/proxies/smart-proxy/utils/route-validation-error.ts

@@ -58,3 +58,23 @@ export class RouteValidationError extends Error {
     this.errors = errorsArg;
   }
 }
+
+/**
+ * Thrown when SmartProxy refuses settings outside its routes because they failed validation.
+ *
+ * `messages` lists every reason. The message names the first reasons only.
+ */
+export class SettingsValidationError extends Error {
+  public readonly messages: string[];
+
+  constructor(summaryArg: string, messagesArg: string[]) {
+    const shownMessages = messagesArg.slice(0, MAX_MESSAGES_PER_ROUTE_IN_MESSAGE).map(truncateText);
+    const hiddenMessageCount = messagesArg.length - shownMessages.length;
+    if (hiddenMessageCount > 0) {
+      shownMessages.push(`and ${hiddenMessageCount} more`);
+    }
+    super(`${summaryArg}: ${shownMessages.join('; ')}`);
+    this.name = 'SettingsValidationError';
+    this.messages = messagesArg;
+  }
+}

package/ts/proxies/smart-proxy/utils/route-validator.ts

@@ -1,5 +1,12 @@
 import { logger } from '../../../core/utils/logger.js';
+import {
+  checkAssignedIpEntry,
+  checkSecurityIpEntry,
+  checkSourceMatchIpEntry,
+  describeRefusedIpEntry,
+} from './ip-entry-validation.js';
 import type { IInboundProxyProtocolPolicy, IRouteConfig, IRouteMatch, IRouteAction, TPortRange, TTransportProtocol } from '../models/route-types.js';
+import type { ISmartProxyOptions, ISmartProxySecurityPolicy } from '../models/interfaces.js';
 import { RouteValidationError, type IRouteValidationErrorEntry } from './route-validation-error.js';
 
 /**
@@ -88,8 +95,9 @@ export class RouteValidator {
         const ips = Array.isArray(route.match.clientIp) ? route.match.clientIp : [route.match.clientIp];
         
         for (const ip of ips) {
-          if (!this.isValidIPPattern(ip)) {
-            errors.push(`Invalid IP pattern: ${ip}`);
+          const reason = checkSourceMatchIpEntry(ip);
+          if (reason !== null) {
+            errors.push(describeRefusedIpEntry('Invalid IP pattern', ip, reason));
           }
         }
       }
@@ -105,8 +113,9 @@ export class RouteValidator {
             errors.push('inboundProxyProtocol.trustedProxyIPs must be a non-empty array when specified');
           } else {
             for (const ip of policy.trustedProxyIPs) {
-              if (!this.isValidIPPattern(ip)) {
-                errors.push(`Invalid trusted proxy IP pattern: ${ip}`);
+              const reason = checkSourceMatchIpEntry(ip);
+              if (reason !== null) {
+                errors.push(describeRefusedIpEntry('Invalid trusted proxy IP pattern', ip, reason));
               }
             }
           }
@@ -226,17 +235,19 @@ export class RouteValidator {
         const allowList = Array.isArray(route.security.ipAllowList) ? route.security.ipAllowList : [route.security.ipAllowList];
 
         for (const entry of allowList) {
-          if (typeof entry === 'string') {
-            if (!this.isValidIPPattern(entry)) {
-              errors.push(`Invalid IP pattern in allow list: ${entry}`);
-            }
-          } else if (entry && typeof entry === 'object') {
-            if (!this.isValidIPPattern(entry.ip)) {
-              errors.push(`Invalid IP pattern in domain-scoped allow entry: ${entry.ip}`);
+          if (entry && typeof entry === 'object') {
+            const reason = checkSecurityIpEntry(entry.ip);
+            if (reason !== null) {
+              errors.push(describeRefusedIpEntry('Invalid IP pattern in domain-scoped allow entry', entry.ip, reason));
             }
             if (!Array.isArray(entry.domains) || entry.domains.length === 0) {
               errors.push(`Domain-scoped allow entry for ${entry.ip} must have non-empty domains array`);
             }
+          } else {
+            const reason = checkSecurityIpEntry(entry);
+            if (reason !== null) {
+              errors.push(describeRefusedIpEntry('Invalid IP pattern in allow list', entry, reason));
+            }
           }
         }
       }
@@ -245,8 +256,23 @@ export class RouteValidator {
         const blockList = Array.isArray(route.security.ipBlockList) ? route.security.ipBlockList : [route.security.ipBlockList];
         
         for (const ip of blockList) {
-          if (!this.isValidIPPattern(ip)) {
-            errors.push(`Invalid IP pattern in block list: ${ip}`);
+          const reason = checkSecurityIpEntry(ip);
+          if (reason !== null) {
+            errors.push(describeRefusedIpEntry('Invalid IP pattern in block list', ip, reason));
+          }
+        }
+      }
+
+      const assignedIps = route.security.vpn?.allowedAssignedIps;
+      if (assignedIps !== undefined) {
+        if (!Array.isArray(assignedIps)) {
+          errors.push('security.vpn.allowedAssignedIps must be an array');
+        } else {
+          for (const ip of assignedIps) {
+            const reason = checkAssignedIpEntry(ip);
+            if (reason !== null) {
+              errors.push(describeRefusedIpEntry('Invalid VPN assigned IP', ip, reason));
+            }
           }
         }
       }
@@ -336,6 +362,61 @@ export class RouteValidator {
     return baseLabels.map((label, index) => (labelCounts.get(label)! > 1 ? `${label}[${index}]` : label));
   }
 
+  /**
+   * Validate the IP entries of the settings outside routes: the global `trustedProxyIPs`, the
+   * `defaults.security` lists the engine copies into routes without security, and the global
+   * `securityPolicy`. Answers every reason, empty when the settings are valid.
+   */
+  public static validateSettings(
+    settings: Pick<ISmartProxyOptions, 'trustedProxyIPs' | 'defaults' | 'securityPolicy'>,
+  ): string[] {
+    const errors: string[] = [];
+    const checkList = (
+      list: unknown,
+      field: string,
+      check: (entry: unknown) => string | null,
+    ) => {
+      if (list === undefined) return;
+      if (!Array.isArray(list)) {
+        errors.push(`${field} must be an array`);
+        return;
+      }
+      for (const entry of list) {
+        const reason = check(entry);
+        if (reason !== null) {
+          errors.push(describeRefusedIpEntry(`Invalid IP pattern in ${field}`, entry, reason));
+        }
+      }
+    };
+    checkList(settings.trustedProxyIPs, 'trustedProxyIPs', checkSourceMatchIpEntry);
+    checkList(settings.defaults?.security?.ipAllowList, 'defaults.security.ipAllowList', checkSecurityIpEntry);
+    checkList(settings.defaults?.security?.ipBlockList, 'defaults.security.ipBlockList', checkSecurityIpEntry);
+    if (settings.securityPolicy) {
+      errors.push(...this.validateSecurityPolicy(settings.securityPolicy));
+    }
+    return errors;
+  }
+
+  /** Validate the IP entries of a global ingress security policy. */
+  public static validateSecurityPolicy(policy: ISmartProxySecurityPolicy): string[] {
+    const errors: string[] = [];
+    for (const field of ['blockedIps', 'blockedCidrs'] as const) {
+      const list: unknown = policy[field];
+      if (list === undefined) continue;
+      if (!Array.isArray(list)) {
+        errors.push(`securityPolicy.${field} must be an array`);
+        continue;
+      }
+      for (const entry of list) {
+        const reason = checkSecurityIpEntry(entry);
+        if (reason !== null) {
+          errors.push(describeRefusedIpEntry(`Invalid IP pattern in securityPolicy.${field}`, entry, reason));
+        }
+      }
+    }
+    return errors;
+  }
+
   /**
    * Validate multiple route configurations.
    *
@@ -567,76 +648,6 @@ export class RouteValidator {
     return true;
   }
 
-  /**
-   * Validate IP pattern
-   */
-  private static isValidIPPattern(ip: string): boolean {
-    if (!ip || typeof ip !== 'string') return false;
-    if (ip === '*') return true;
-    
-    // Check for CIDR notation
-    if (ip.includes('/')) {
-      const [addr, prefix] = ip.split('/');
-      const prefixNum = parseInt(prefix, 10);
-      
-      if (addr.includes(':')) {
-        // IPv6 CIDR
-        return this.isValidIPv6(addr) && prefixNum >= 0 && prefixNum <= 128;
-      } else {
-        // IPv4 CIDR
-        return this.isValidIPv4(addr) && prefixNum >= 0 && prefixNum <= 32;
-      }
-    }
-    
-    // Check for range
-    if (ip.includes('-')) {
-      const [start, end] = ip.split('-');
-      return (this.isValidIPv4(start) && this.isValidIPv4(end)) ||
-             (this.isValidIPv6(start) && this.isValidIPv6(end));
-    }
-    
-    // Check for wildcards in IPv4
-    if (ip.includes('*') && !ip.includes(':')) {
-      const parts = ip.split('.');
-      // Allow 1-4 parts for wildcard patterns (e.g., '10.*', '192.168.*', '192.168.1.*')
-      if (parts.length < 1 || parts.length > 4) return false;
-      
-      for (const part of parts) {
-        if (part !== '*' && !/^\d{1,3}$/.test(part)) return false;
-        if (part !== '*' && parseInt(part, 10) > 255) return false;
-      }
-      
-      return true;
-    }
-    
-    // Regular IP address
-    return this.isValidIPv4(ip) || this.isValidIPv6(ip);
-  }
-
-  /**
-   * Validate IPv4 address
-   */
-  private static isValidIPv4(ip: string): boolean {
-    const parts = ip.split('.');
-    if (parts.length !== 4) return false;
-    
-    for (const part of parts) {
-      const num = parseInt(part, 10);
-      if (isNaN(num) || num < 0 || num > 255) return false;
-    }
-    
-    return true;
-  }
-
-  /**
-   * Validate IPv6 address
-   */
-  private static isValidIPv6(ip: string): boolean {
-    // IPv6 validation including IPv6-mapped IPv4 addresses (::ffff:x.x.x.x)
-    const ipv6Pattern = /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|::[0-9a-fA-F]{0,4}(:[0-9a-fA-F]{1,4}){0,6}|::1|::|::ffff:\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i;
-    return ipv6Pattern.test(ip);
-  }
-
   /**
    * Log validation errors
    */