@push.rocks/smartproxy 27.22.0 → 28.1.0

package/readme.md

@@ -103,7 +103,7 @@ SmartProxy uses a powerful **match/action** pattern that makes routing predictab
 
 Every route consists of:
 - **Match** — What traffic to capture (ports, domains, paths, transport, protocol, IPs, headers)
-- **Action** — What to do with it (`forward` or `socket-handler`)
+- **Action** — What to do with it (`forward`, `socket-handler` or `respond`)
 - **Security** (optional) — IP allow/block lists, rate limits, authentication
 - **Headers** (optional) — Request/response header manipulation with template variables
 - **Name/Priority** (optional) — For identification and ordering
@@ -137,6 +137,40 @@ const proxy = new SmartProxy({
 });
 ```
 
+### 🚧 Fixed Response (Maintenance / Stopped Service)
+
+A `respond` route answers every HTTP request itself, without an upstream. Keep a stopped service's hostname routed and tell clients when to retry instead of failing with 502 or a TLS error:
+
+```typescript
+const proxy = new SmartProxy({
+  routes: [{
+    name: 'app-stopped',
+    match: { ports: 443, domains: 'app.example.com' },
+    action: {
+      type: 'respond',
+      tls: { mode: 'terminate', certificate: 'auto' },
+      response: {
+        status: 503,
+        headers: {
+          'Retry-After': '30',
+          'Cache-Control': 'no-store',
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({ error: 'service stopped' })
+      }
+    }
+  }]
+});
+```
+
+- `status` is 200–599. `headers` must not set `connection`, `keep-alive`, `transfer-encoding`, `upgrade`, `te`, `trailer`, `proxy-connection` or `content-length` (SmartProxy computes it).
+- `body` is UTF-8 text of at most 64 KiB and needs an explicit `content-type` header; 204 and 304 carry no body.
+- TLS is optional; when set it must be `mode: 'terminate'` (static certificate or `'auto'`). Responses go out over HTTP/1.1 and h2. Route `security`, rate limits, challenges and `maxConnections` apply before the response.
+- Respond routes are HTTP over TCP only: `action.udp`, `match.transport: 'udp' | 'all'` and HTTP/3 are rejected in this version. `targets`, socket handlers and nftables forwarding are rejected too.
+- Switch a hostname between `forward` and `respond` with `updateRoutes()`.
+
+**Migrating from `advanced.testResponse`:** SmartProxy 28 removes `action.advanced.testResponse`. Move its `status`, `headers` and `body` to `action.response`, set `action.type: 'respond'`, drop the `targets`, and add a `content-type` header when the body is not empty.
+
 ### ⚖️ Load Balancer
 
 For equivalent backends, put the backend hosts into one target's `host` array and choose a target-level load-balancing algorithm. Multiple `targets` are for sub-routing with `target.match` and `priority`.
@@ -891,6 +925,7 @@ type TPortRange = number | Array<number | { from: number; to: number }>;
 |------|-------------|
 | `forward` | Proxy to one or more backend targets (with optional TLS, WebSocket, load balancing, UDP/QUIC) |
 | `socket-handler` | Custom socket/datagram handling function in TypeScript |
+| `respond` | Answer every HTTP request with the fixed `action.response` (status, headers, body); no upstream, TCP only |
 
 `targets` are evaluated as route-internal sub-routes by `target.match` and `target.priority`. For load balancing across equivalent upstreams, use a single target with `host: ['a', 'b', 'c']` and target-level `loadBalancing`.
 
@@ -1044,7 +1079,15 @@ import {
   findBestMatchingRoute,           // Find best matching route
   cloneRoute,                      // Deep-clone a route
   generateRouteId,                 // Generate deterministic route ID
-  RouteValidator,                  // Validate route configurations
+  RouteValidator,                  // Validate route configurations (validateRoutes, getRouteLabels)
+  RouteValidationError,            // Thrown when SmartProxy refuses a route set; carries the per-route reasons
+  MAX_FIXED_RESPONSE_BODY_BYTES,   // Largest `respond` route body in UTF-8 bytes (65536)
+} from '@push.rocks/smartproxy';
+
+import type {
+  IRouteConfig,                    // A route: match + action
+  IRouteFixedResponse,             // Fixed response of a `respond` route (status, headers, body)
+  IRouteValidationErrorEntry,      // One rejected route in RouteValidationError.errors (index, route, messages)
 } from '@push.rocks/smartproxy';
 ```
 
@@ -1056,14 +1099,14 @@ All routes are configured as plain `IRouteConfig` objects with `match` and `acti
 
 ```typescript
 class SmartProxy extends EventEmitter {
-  constructor(options: ISmartProxyOptions);
+  constructor(options: ISmartProxyOptions); // Throws RouteValidationError for invalid routes
 
   // Lifecycle
   start(): Promise<void>;
   stop(): Promise<void>;
 
   // Route Management (atomic, mutex-locked)
-  updateRoutes(routes: IRouteConfig[]): Promise<void>;
+  updateRoutes(routes: IRouteConfig[]): Promise<void>; // Rejects with RouteValidationError for invalid routes
   updateSecurityPolicy(policy: ISmartProxySecurityPolicy): Promise<void>;
   registerChallengeProvider(providerId: string, provider: IChallengeProvider): void;
 
@@ -1262,6 +1305,31 @@ The percentile methods are part of the public metrics shape. In the current Rust
 
 ## 🐛 Troubleshooting
 
+### Route Validation Errors
+
+SmartProxy validates every route set before it applies it, first in TypeScript and then in the Rust engine. When either refuses one, the constructor, `start()` or `updateRoutes()` throws a `RouteValidationError` and the running routes stay unchanged. `assertValidRoute()` throws the same error for a single route:
+
+```typescript
+import { RouteValidationError } from '@push.rocks/smartproxy';
+
+try {
+  await proxy.updateRoutes(newRoutes);
+} catch (error) {
+  if (error instanceof RouteValidationError) {
+    // A configuration problem, e.g. answer an admin API call with 422
+    for (const { index, route, messages } of error.errors) {
+      console.error(`#${index} ${route}: ${messages.join('; ')}`);
+    }
+  }
+  throw error;
+}
+```
+
+- `error.name` is `'RouteValidationError'`.
+- `error.errors` lists every rejected route with all its reasons, for example `response.body requires an explicit content-type header`. `index` is the route's position in the list you passed. `route` is its label from `RouteValidator.getRouteLabels()`: the name, else the id, else `route[<index>]`; a name or id that several routes share gets `[<index>]` appended, so no route's reasons hide another's.
+- `error.message` names the first 10 routes with up to 5 reasons each, shortens long names and reasons to 200 characters and counts the rest, so it stays bounded for large route sets. Read `error.errors` for the complete list.
+- Checks that only the Rust engine makes, such as duplicate route ids or an `inboundProxyProtocol` policy without route-level or global `trustedProxyIPs`, arrive the same way; their message starts with `Route validation failed`.
+
 ### Certificate Issues
 - ✅ Ensure domain DNS points to your server
 - ✅ Port 80 must be accessible for ACME HTTP-01 challenges
@@ -1285,6 +1353,8 @@ SmartProxy searches for the Rust binary in this order:
 5. Local dev build (`./rust/target/release/rustproxy`)
 6. System PATH (`rustproxy`)
 
+`rustBinaryPath` is an explicit choice, not a first guess: when it is set, SmartProxy uses only that file. If it is missing or not executable, `start()` rejects with a `RustBinaryLocatorError` naming the path and does not fall back to the other locations.
+
 ### QUIC / HTTP3 Caveats
 - **GREASE frames are disabled.** The underlying h3 crate sends [GREASE frames](https://www.rfc-editor.org/rfc/rfc9114.html#frame-reserved) by default to test protocol extensibility. However, some HTTP/3 clients and servers don't properly ignore unknown frame types, causing 400/500 errors or stream hangs ([h3#206](https://github.com/hyperium/h3/issues/206)). SmartProxy disables GREASE on both the server side (for incoming H3 requests) and the client side (for H3 backend connections) to maximize compatibility.
 - **HTTP/3 is pre-release.** The h3 ecosystem (h3 0.0.8, h3-quinn 0.0.10, quinn 0.11) is still pre-1.0. Expect rough edges.

package/ts/00_commitinfo_data.ts

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

package/ts/index.ts

@@ -7,7 +7,7 @@ export { SmartProxy } from './proxies/smart-proxy/index.js';
 export { SharedRouteManager as RouteManager } from './core/routing/route-manager.js';
 
 // Export smart-proxy models
-export type { ISmartProxyOptions, ISmartProxySecurityPolicy, ISmartProxyChallengeOptions, IConnectionRecord, IRouteConfig, IRouteMatch, IRouteAction, IRouteTls, IRouteContext, TDatagramHandler, IDatagramInfo, IActiveConnectionSnapshot, IActiveConnectionSnapshotOptions, IActiveConnectionSnapshotPage } from './proxies/smart-proxy/models/index.js';
+export type { ISmartProxyOptions, ISmartProxySecurityPolicy, ISmartProxyChallengeOptions, IConnectionRecord, IRouteConfig, IRouteMatch, IRouteAction, IRouteFixedResponse, IRouteTls, IRouteContext, TDatagramHandler, IDatagramInfo, IActiveConnectionSnapshot, IActiveConnectionSnapshotOptions, IActiveConnectionSnapshotPage } from './proxies/smart-proxy/models/index.js';
 export type { TSmartProxyCertProvisionObject, ICertProvisionEventComms, ICertificateIssuedEvent, ICertificateFailedEvent } from './proxies/smart-proxy/models/interfaces.js';
 export * from './proxies/smart-proxy/utils/index.js';
 

package/ts/proxies/smart-proxy/models/interfaces.ts

@@ -289,8 +289,10 @@ export interface ISmartProxyOptions {
   certStore?: ISmartProxyCertStore;
 
   /**
-   * Path to the RustProxy binary. If not set, the binary is located
-   * automatically via env var, platform package, local build, or PATH.
+   * Path to the RustProxy binary. When set, it is the only candidate: `start()` rejects
+   * with a `RustBinaryLocatorError` if it is missing or not executable, without falling
+   * back to discovery. If not set, the binary is located automatically via env var,
+   * platform package, local build, or PATH.
    */
   rustBinaryPath?: string;
 }

package/ts/proxies/smart-proxy/models/route-types.ts

@@ -7,7 +7,7 @@ export type { IRouteContext };
 /**
  * Supported action types for route configurations
  */
-export type TRouteActionType = 'forward' | 'socket-handler';
+export type TRouteActionType = 'forward' | 'socket-handler' | 'respond';
 
 /**
  * Socket handler function type
@@ -227,12 +227,18 @@ export interface IRouteStaticFiles {
 }
 
 /**
- * Test route response configuration
+ * Fixed response answered by a `respond` route without contacting any upstream.
+ *
+ * - `status` must be an integer from 200 to 599.
+ * - `headers` must not contain hop-by-hop or computed headers (`connection`, `keep-alive`,
+ *   `transfer-encoding`, `upgrade`, `te`, `trailer`, `proxy-connection`, `content-length`).
+ * - A non-empty `body` requires an explicit `content-type` header; 204 and 304 carry no body.
+ * - `body` is UTF-8 text of at most 65536 bytes.
  */
-export interface IRouteTestResponse {
+export interface IRouteFixedResponse {
   status: number;
-  headers: Record<string, string>;
-  body: string;
+  headers?: Record<string, string>;
+  body?: string;
 }
 
 /**
@@ -253,7 +259,6 @@ export interface IRouteAdvanced {
   headers?: Record<string, string>;
   keepAlive?: boolean;
   staticFiles?: IRouteStaticFiles;
-  testResponse?: IRouteTestResponse;
   urlRewrite?: IRouteUrlRewrite; // URL rewriting configuration
   // Additional advanced options would go here
 }
@@ -322,6 +327,9 @@ export interface IRouteAction {
   // NFTables-specific options
   nftables?: INfTablesOptions;
 
+  // Fixed response (required when type is 'respond')
+  response?: IRouteFixedResponse;
+
   // Socket handler function (when type is 'socket-handler')
   socketHandler?: TSocketHandler;
 

package/ts/proxies/smart-proxy/models/rust-types.ts

@@ -44,6 +44,26 @@ export interface IRustRouteConfig extends Omit<IRouteConfig, 'match' | 'action'>
   action: IRustRouteAction;
 }
 
+/** `errorCode` of a Rust `start` or `updateRoutes` response that refused its routes in validation. */
+export const RUST_ROUTE_VALIDATION_ERROR_CODE = 'ROUTE_VALIDATION';
+
+/** One rejected route in the `errorData` of a `ROUTE_VALIDATION` response. */
+export interface IRustRouteValidationIssue {
+  /** The route's position in the sent route list. */
+  index: number;
+  /**
+   * The engine's label of the route as it received it. The preprocessor names unnamed routes
+   * `route_<index>`, so TypeScript relabels issues by `index` and does not surface this label.
+   */
+  route: string;
+  messages: string[];
+}
+
+/** `errorData` of a `ROUTE_VALIDATION` response. */
+export interface IRustRouteValidationErrorData {
+  routes: IRustRouteValidationIssue[];
+}
+
 export interface IRustAcmeOptions extends Omit<IAcmeOptions, 'routeForwards'> {}
 
 export interface IRustChallengeOptions extends Required<Pick<

package/ts/proxies/smart-proxy/rust-proxy-bridge.ts

@@ -1,14 +1,17 @@
 import * as plugins from '../../plugins.js';
 import { logger } from '../../core/utils/logger.js';
-import type {
-  IRustCertificateStatus,
-  IRustChallengeOptions,
-  IRustMetricsSnapshot,
-  IRustProxyOptions,
-  IRustMetricsHistory,
-  IRustRouteConfig,
-  IRustStatistics,
+import {
+  RUST_ROUTE_VALIDATION_ERROR_CODE,
+  type IRustCertificateStatus,
+  type IRustChallengeOptions,
+  type IRustMetricsSnapshot,
+  type IRustProxyOptions,
+  type IRustMetricsHistory,
+  type IRustRouteConfig,
+  type IRustRouteValidationErrorData,
+  type IRustStatistics,
 } from './models/rust-types.js';
+import { RouteValidationError } from './utils/route-validation-error.js';
 import type { IActiveConnectionSnapshot, IActiveConnectionSnapshotOptions, IActiveConnectionSnapshotPage, ISmartProxySecurityPolicy } from './models/interfaces.js';
 
 const MAXIMUM_RUST_CONNECTION_ID = 18_446_744_073_709_551_615n;
@@ -26,6 +29,69 @@ function validateActiveConnectionSnapshotOptions(options: IActiveConnectionSnaps
   }
 }
 
+function isRustRouteValidationErrorData(
+  data: unknown,
+  sentRouteCount: number,
+): data is IRustRouteValidationErrorData {
+  if (
+    typeof data !== 'object'
+    || data === null
+    || !('routes' in data)
+    || !Array.isArray(data.routes)
+    || data.routes.length === 0
+  ) {
+    return false;
+  }
+  return data.routes.every((issue: unknown) =>
+    typeof issue === 'object'
+    && issue !== null
+    && 'index' in issue
+    && typeof issue.index === 'number'
+    && Number.isSafeInteger(issue.index)
+    && issue.index >= 0
+    && issue.index < sentRouteCount
+    && 'route' in issue
+    && typeof issue.route === 'string'
+    && 'messages' in issue
+    && Array.isArray(issue.messages)
+    && issue.messages.every((message: unknown) => typeof message === 'string'),
+  );
+}
+
+/**
+ * Turn a Rust `ROUTE_VALIDATION` refusal into a `RouteValidationError` carrying the
+ * per-route reasons from its `errorData`. Any other error is returned unchanged.
+ *
+ * `routeLabels` holds `RouteValidator.getRouteLabels()` of the caller's routes, one per sent
+ * route. Entries are relabelled by index: the preprocessor names unnamed routes for Rust, so
+ * the engine's own labels can differ from the ones the caller sees.
+ */
+export function toRouteValidationError(error: unknown, routeLabels: string[]): unknown {
+  if (
+    !(error instanceof plugins.smartrust.RustBridgeRequestError)
+    || error.responseErrorCode !== RUST_ROUTE_VALIDATION_ERROR_CODE
+  ) {
+    return error;
+  }
+  if (!isRustRouteValidationErrorData(error.responseErrorData, routeLabels.length)) {
+    return new Error(`RustProxy sent a route validation refusal with malformed errorData: ${error.message}`, {
+      cause: error,
+    });
+  }
+  return new RouteValidationError(
+    'Route validation failed',
+    error.responseErrorData.routes.map(({ index, messages }) => ({ index, route: routeLabels[index], messages })),
+  );
+}
+
+function assertOneLabelPerRoute(routes: IRustRouteConfig[], routeLabels: string[]): void {
+  if (routes.length !== routeLabels.length) {
+    throw new Error(
+      `RustProxyBridge got ${routeLabels.length} route label(s) for ${routes.length} route(s); they must match one to one`,
+    );
+  }
+}
+
 /**
  * Type-safe command definitions for the Rust proxy IPC protocol.
  */
@@ -97,6 +163,14 @@ function buildLocalPaths(): string[] {
   return paths;
 }
 
+export interface IRustProxyBridgeOptions {
+  /**
+   * Explicit path to the RustProxy binary. When set, it is the only candidate:
+   * `spawn()` rejects with a `RustBinaryLocatorError` if it is missing or not executable.
+   */
+  binaryPath?: string;
+}
+
 /**
  * Bridge between TypeScript SmartProxy and the Rust binary.
  * Wraps @push.rocks/smartrust's RustBridge with type-safe command definitions.
@@ -104,11 +178,12 @@ function buildLocalPaths(): string[] {
 export class RustProxyBridge extends plugins.EventEmitter {
   private bridge: plugins.smartrust.RustBridge<TSmartProxyCommands>;
 
-  constructor() {
+  constructor(options: IRustProxyBridgeOptions = {}) {
     super();
 
     this.bridge = new plugins.smartrust.RustBridge<TSmartProxyCommands>({
       binaryName: 'rustproxy',
+      binaryPath: options.binaryPath,
       envVarName: 'SMARTPROXY_RUST_BINARY',
       platformPackagePrefix: '@push.rocks/smartproxy',
       localPaths: buildLocalPaths(),
@@ -155,16 +230,34 @@ export class RustProxyBridge extends plugins.EventEmitter {
 
   // --- Convenience methods for each management command ---
 
-  public async startProxy(config: IRustProxyOptions): Promise<void> {
-    await this.bridge.sendCommand('start', { config });
+  /**
+   * @param routeLabels `RouteValidator.getRouteLabels()` of the routes before preprocessing,
+   *   used to label a route validation refusal.
+   */
+  public async startProxy(config: IRustProxyOptions, routeLabels: string[]): Promise<void> {
+    assertOneLabelPerRoute(config.routes, routeLabels);
+    try {
+      await this.bridge.sendCommand('start', { config });
+    } catch (error) {
+      throw toRouteValidationError(error, routeLabels);
+    }
   }
 
   public async stopProxy(): Promise<void> {
     await this.bridge.sendCommand('stop', {} as Record<string, never>);
   }
 
-  public async updateRoutes(routes: IRustRouteConfig[]): Promise<void> {
-    await this.bridge.sendCommand('updateRoutes', { routes });
+  /**
+   * @param routeLabels `RouteValidator.getRouteLabels()` of the routes before preprocessing,
+   *   used to label a route validation refusal.
+   */
+  public async updateRoutes(routes: IRustRouteConfig[], routeLabels: string[]): Promise<void> {
+    assertOneLabelPerRoute(routes, routeLabels);
+    try {
+      await this.bridge.sendCommand('updateRoutes', { routes });
+    } catch (error) {
+      throw toRouteValidationError(error, routeLabels);
+    }
   }
 
   public async setSecurityPolicy(policy: ISmartProxySecurityPolicy): Promise<void> {

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

@@ -12,6 +12,7 @@ import { RustMetricsAdapter } from './rust-metrics-adapter.js';
 // Route management
 import { SharedRouteManager as RouteManager } from '../../core/routing/route-manager.js';
 import { RouteValidator } from './utils/route-validator.js';
+import { RouteValidationError, type IRouteValidationErrorEntry } from './utils/route-validation-error.js';
 import { buildRustProxyOptions } from './utils/rust-config.js';
 import { generateDefaultCertificate } from './utils/default-cert-generator.js';
 import { Mutex } from './utils/mutex.js';
@@ -107,7 +108,7 @@ export class SmartProxy extends plugins.EventEmitter {
       const validation = RouteValidator.validateRoutes(this.settings.routes);
       if (!validation.valid) {
         RouteValidator.logValidationErrors(validation.errors);
-        throw new Error(`Initial route validation failed: ${validation.errors.size} route(s) have errors`);
+        throw new RouteValidationError('Initial route validation failed', validation.entries);
       }
     }
 
@@ -126,7 +127,7 @@ export class SmartProxy extends plugins.EventEmitter {
       routes: this.settings.routes,
     });
 
-    this.bridge = new RustProxyBridge();
+    this.bridge = new RustProxyBridge({ binaryPath: this.settings.rustBinaryPath });
     this.preprocessor = new RoutePreprocessor();
     this.metricsAdapter = new RustMetricsAdapter(
       this.bridge,
@@ -216,7 +217,7 @@ export class SmartProxy extends plugins.EventEmitter {
       const config = this.buildRustConfig(rustRoutes, acmeForRust);
 
       // Start the Rust proxy
-      await this.bridge.startProxy(config);
+      await this.bridge.startProxy(config, RouteValidator.getRouteLabels(this.settings.routes));
 
       // Now that Rust proxy is running, configure socket handler relay
       if (this.socketHandlerServer) {
@@ -370,7 +371,7 @@ export class SmartProxy extends plugins.EventEmitter {
       const validation = RouteValidator.validateRoutes(newRoutes);
       if (!validation.valid) {
         RouteValidator.logValidationErrors(validation.errors);
-        throw new Error(`Route validation failed: ${validation.errors.size} route(s) have errors`);
+        throw new RouteValidationError('Route validation failed', validation.entries);
       }
 
       const hasChallengeRoutes = this.hasChallengeRoutes(newRoutes);
@@ -389,7 +390,7 @@ export class SmartProxy extends plugins.EventEmitter {
         }
 
         // Send to Rust
-        await this.bridge.updateRoutes(rustRoutes);
+        await this.bridge.updateRoutes(rustRoutes, RouteValidator.getRouteLabels(newRoutes));
       } catch (err) {
         if (hasChallengeRoutes && !challengeRelayWasStarted && this.challengeProviderRelayServer) {
           await this.bridge.setChallengeProviderRelay('').catch(() => undefined);
@@ -580,7 +581,7 @@ export class SmartProxy extends plugins.EventEmitter {
     for (const route of this.settings.routes || []) {
       if (!route.match.domains) continue;
       if (
-        route.action.type !== 'forward' ||
+        (route.action.type !== 'forward' && route.action.type !== 'respond') ||
         !route.action.tls ||
         route.action.tls.mode === 'passthrough' ||
         route.action.tls.certificate !== 'auto'
@@ -729,10 +730,11 @@ export class SmartProxy extends plugins.EventEmitter {
 
   private async validateChallengeRoutes(routes: IRouteConfig[]): Promise<void> {
     const manifestCache = new Map<string, plugins.smartchallenge.IChallengeProviderManifest>();
-    const errors: string[] = [];
+    const labels = RouteValidator.getRouteLabels(routes);
+    const entries: IRouteValidationErrorEntry[] = [];
 
-    for (const route of routes) {
-      const routeName = route.name || route.id || 'unnamed route';
+    for (const [index, route] of routes.entries()) {
+      const errors: string[] = [];
       const challengeEntries: Array<{
         path: string;
         challenge: plugins.smartchallenge.IRouteChallengeConfig;
@@ -758,50 +760,50 @@ export class SmartProxy extends plugins.EventEmitter {
       if (challengeEntries.length === 0) continue;
 
       if (!route.name && !route.id) {
-        errors.push(`${routeName}: challenge routes must set a stable route name or id`);
+        errors.push('challenge routes must set a stable route name or id');
       }
       if (route.action.type !== 'forward') {
-        errors.push(`${routeName}: challenge routes must use forward actions`);
+        errors.push('challenge routes must use forward actions');
       }
       if (route.action.forwardingEngine === 'nftables') {
-        errors.push(`${routeName}: challenge routes cannot use nftables forwarding`);
+        errors.push('challenge routes cannot use nftables forwarding');
       }
       if (route.action.tls?.mode === 'passthrough') {
-        errors.push(`${routeName}: challenge routes cannot use TLS passthrough`);
+        errors.push('challenge routes cannot use TLS passthrough');
       }
       for (const target of route.action.targets || []) {
         if (typeof target.host === 'function' || typeof target.port === 'function') {
-          errors.push(`${routeName}: challenge routes cannot use dynamic target host or port functions`);
+          errors.push('challenge routes cannot use dynamic target host or port functions');
         }
         if (target.tls?.mode === 'passthrough') {
-          errors.push(`${routeName}: challenge routes cannot use target TLS passthrough`);
+          errors.push('challenge routes cannot use target TLS passthrough');
         }
       }
       const hasHttp3Transport = route.match.transport === 'all'
         && route.action.udp?.quic?.enableHttp3 === true;
       if (route.match.transport === 'udp') {
-        errors.push(`${routeName}: challenge routes cannot use pure UDP transport`);
+        errors.push('challenge routes cannot use pure UDP transport');
       }
       if (route.match.transport === 'all' && !hasHttp3Transport) {
-        errors.push(`${routeName}: challenge routes using transport 'all' must enable HTTP/3 with action.udp.quic.enableHttp3`);
+        errors.push(`challenge routes using transport 'all' must enable HTTP/3 with action.udp.quic.enableHttp3`);
       }
       if (route.match.protocol !== 'http') {
-        errors.push(`${routeName}: challenge routes must set match.protocol to 'http'`);
+        errors.push(`challenge routes must set match.protocol to 'http'`);
       }
 
       for (const { path, challenge } of challengeEntries) {
         if (!challenge.providerId || typeof challenge.providerId !== 'string') {
-          errors.push(`${routeName}: ${path}.providerId must be a non-empty string`);
+          errors.push(`${path}.providerId must be a non-empty string`);
         }
         if (!challenge.challengeType || typeof challenge.challengeType !== 'string') {
-          errors.push(`${routeName}: ${path}.challengeType must be a non-empty string`);
+          errors.push(`${path}.challengeType must be a non-empty string`);
         }
-        this.validateChallengeIntentShape(challenge, errors, routeName, path);
-        this.collectForbiddenChallengeKeys(challenge, path, errors, routeName);
+        this.validateChallengeIntentShape(challenge, errors, path);
+        this.collectForbiddenChallengeKeys(challenge, path, errors);
 
         const provider = this.challengeProviders.get(challenge.providerId);
         if (!provider) {
-          errors.push(`${routeName}: challenge provider '${challenge.providerId}' is not registered`);
+          errors.push(`challenge provider '${challenge.providerId}' is not registered`);
           continue;
         }
         let manifest = manifestCache.get(challenge.providerId);
@@ -810,24 +812,27 @@ export class SmartProxy extends plugins.EventEmitter {
           manifestCache.set(challenge.providerId, manifest);
         }
         if (!manifest.challengeTypes.some((type) => type.challengeType === challenge.challengeType)) {
-          errors.push(`${routeName}: challenge provider '${challenge.providerId}' does not support type '${challenge.challengeType}'`);
+          errors.push(`challenge provider '${challenge.providerId}' does not support type '${challenge.challengeType}'`);
         }
       }
+
+      if (errors.length > 0) {
+        entries.push({ index, route: labels[index], messages: errors });
+      }
     }
 
-    if (errors.length > 0) {
-      throw new Error(`Challenge route validation failed:\n${errors.map((error) => `- ${error}`).join('\n')}`);
+    if (entries.length > 0) {
+      throw new RouteValidationError('Challenge route validation failed', entries);
     }
   }
 
   private validateChallengeIntentShape(
     challengeArg: unknown,
     errors: string[],
-    routeName: string,
     challengePath = 'security.challenge',
   ): void {
     if (!this.isPlainRecord(challengeArg)) {
-      errors.push(`${routeName}: ${challengePath} must be an object`);
+      errors.push(`${challengePath} must be an object`);
       return;
     }
 
@@ -836,25 +841,23 @@ export class SmartProxy extends plugins.EventEmitter {
       challengePath,
       new Set(['providerId', 'challengeType', 'policyRef', 'settings', 'applyTo', 'clearance']),
       errors,
-      routeName,
     );
 
     const settings = challengeArg.settings;
     if (settings !== undefined && !this.isPlainRecord(settings)) {
-      errors.push(`${routeName}: ${challengePath}.settings must be an object when set`);
+      errors.push(`${challengePath}.settings must be an object when set`);
     }
 
     const applyTo = challengeArg.applyTo;
     if (applyTo !== undefined) {
       if (!this.isPlainRecord(applyTo)) {
-        errors.push(`${routeName}: ${challengePath}.applyTo must be an object when set`);
+        errors.push(`${challengePath}.applyTo must be an object when set`);
       } else {
         this.validateAllowedChallengeKeys(
           applyTo,
           `${challengePath}.applyTo`,
           new Set(['methods', 'browserNavigationsOnly', 'includePaths', 'excludePaths']),
           errors,
-          routeName,
         );
       }
     }
@@ -862,14 +865,13 @@ export class SmartProxy extends plugins.EventEmitter {
     const clearance = challengeArg.clearance;
     if (clearance !== undefined) {
       if (!this.isPlainRecord(clearance)) {
-        errors.push(`${routeName}: ${challengePath}.clearance must be an object when set`);
+        errors.push(`${challengePath}.clearance must be an object when set`);
       } else {
         this.validateAllowedChallengeKeys(
           clearance,
           `${challengePath}.clearance`,
           new Set(['ttlSeconds', 'bindToHost', 'bindToRoute', 'bindToIp']),
           errors,
-          routeName,
         );
       }
     }
@@ -880,11 +882,10 @@ export class SmartProxy extends plugins.EventEmitter {
     pathArg: string,
     allowedKeysArg: Set<string>,
     errors: string[],
-    routeName: string,
   ): void {
     for (const key of Object.keys(valueArg)) {
       if (!allowedKeysArg.has(key)) {
-        errors.push(`${routeName}: ${pathArg}.${key} is not part of the persisted challenge intent shape`);
+        errors.push(`${pathArg}.${key} is not part of the persisted challenge intent shape`);
       }
     }
   }
@@ -895,19 +896,19 @@ export class SmartProxy extends plugins.EventEmitter {
       && !Array.isArray(valueArg);
   }
 
-  private collectForbiddenChallengeKeys(value: unknown, path: string, errors: string[], routeName: string): void {
+  private collectForbiddenChallengeKeys(value: unknown, path: string, errors: string[]): void {
     if (!value || typeof value !== 'object') return;
     const forbiddenKeyPattern = /(endpoint|url|uri|host|hostname|address|ipAddress|port|secret|token|password|credential|apiKey|apikey|accessKey|privateKey|keyfile|certfile|deployment|container|socketPath)/i;
     for (const [key, nestedValue] of Object.entries(value as Record<string, unknown>)) {
       const childPath = `${path}.${key}`;
       if (forbiddenKeyPattern.test(key) && !['providerId', 'challengeType', 'policyRef', 'bindToHost', 'bindToIp', 'includePaths', 'excludePaths'].includes(key)) {
-        errors.push(`${routeName}: ${childPath} looks like runtime wiring or secret material and must not be stored in route config`);
+        errors.push(`${childPath} looks like runtime wiring or secret material and must not be stored in route config`);
       }
       if (typeof nestedValue === 'string' && this.looksLikeRuntimeChallengeValue(nestedValue) && !['includePaths', 'excludePaths'].includes(key)) {
-        errors.push(`${routeName}: ${childPath} contains endpoint/IP-style runtime wiring and must not be stored in route config`);
+        errors.push(`${childPath} contains endpoint/IP-style runtime wiring and must not be stored in route config`);
       }
       if (nestedValue && typeof nestedValue === 'object') {
-        this.collectForbiddenChallengeKeys(nestedValue, childPath, errors, routeName);
+        this.collectForbiddenChallengeKeys(nestedValue, childPath, errors);
       }
     }
   }