@push.rocks/smartproxy 27.12.7 → 27.13.0

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

@@ -6,6 +6,7 @@ import { RustProxyBridge } from './rust-proxy-bridge.js';
 import { RoutePreprocessor } from './route-preprocessor.js';
 import { SocketHandlerServer } from './socket-handler-server.js';
 import { DatagramHandlerServer } from './datagram-handler-server.js';
+import { ChallengeProviderRelayServer } from './challenge-provider-relay-server.js';
 import { RustMetricsAdapter } from './rust-metrics-adapter.js';
 
 // Route management
@@ -20,7 +21,9 @@ import { ConcurrencySemaphore } from './utils/concurrency-semaphore.js';
 import type { ISmartProxyOptions, ISmartProxySecurityPolicy, TSmartProxyCertProvisionObject, IAcmeOptions, ICertProvisionEventComms, ICertificateIssuedEvent, ICertificateFailedEvent, ISmartProxyCertProvisionCertificate, IActiveConnectionSnapshot, IActiveConnectionSnapshotOptions } from './models/interfaces.js';
 import type { IRouteConfig } from './models/route-types.js';
 import type { IMetrics } from './models/metrics-types.js';
-import type { IRustCertificateStatus, IRustProxyOptions, IRustStatistics } from './models/rust-types.js';
+import type { IRustCertificateStatus, IRustChallengeOptions, IRustProxyOptions, IRustStatistics } from './models/rust-types.js';
+
+type TChallengeProvider = plugins.smartchallenge.IChallengeProvider;
 
 /**
  * SmartProxy - Rust-backed proxy engine with TypeScript configuration API.
@@ -40,6 +43,9 @@ export class SmartProxy extends plugins.EventEmitter {
   private preprocessor: RoutePreprocessor;
   private socketHandlerServer: SocketHandlerServer | null = null;
   private datagramHandlerServer: DatagramHandlerServer | null = null;
+  private challengeProviderRelayServer: ChallengeProviderRelayServer | null = null;
+  private challengeProviders = new Map<string, TChallengeProvider>();
+  private challengeRuntimeOptions?: IRustChallengeOptions;
   private metricsAdapter: RustMetricsAdapter;
   private nftablesManager: InstanceType<typeof plugins.smartnftables.SmartNftables> | null = null;
   private routeUpdateLock: Mutex;
@@ -116,119 +122,153 @@ export class SmartProxy extends plugins.EventEmitter {
     this.routeUpdateLock = new Mutex();
   }
 
+  /**
+   * Register a runtime challenge provider family. Routes reference providerId + challengeType;
+   * deployment wiring and provider secrets stay outside route configs.
+   */
+  public registerChallengeProvider(providerId: string, provider: TChallengeProvider): void {
+    if (!providerId || typeof providerId !== 'string') {
+      throw new Error('Challenge providerId must be a non-empty string');
+    }
+    this.challengeProviders.set(providerId, provider);
+  }
+
   /**
    * Start the proxy.
    * Spawns the Rust binary, configures socket relay if needed, sends routes, handles cert provisioning.
    */
   public async start(): Promise<void> {
-    // Spawn Rust binary
-    const spawned = await this.bridge.spawn();
-    if (!spawned) {
-      throw new Error(
-        'RustProxy binary not found. Set SMARTPROXY_RUST_BINARY env var, install the platform package, ' +
-        'or build locally with: pnpm build'
-      );
-    }
+    await this.validateChallengeRoutes(this.settings.routes);
 
-    // Handle unexpected exit (only emits error if not intentionally stopping)
-    this.bridge.removeAllListeners('exit');
-    this.bridge.on('exit', (code: number | null, signal: string | null) => {
-      if (this.stopping) return;
-      logger.log('error', `RustProxy exited unexpectedly (code=${code}, signal=${signal})`, { component: 'smart-proxy' });
-      this.emit('error', new Error(`RustProxy exited (code=${code}, signal=${signal})`));
-    });
+    let didSpawn = false;
+    try {
+      // Spawn Rust binary
+      const spawned = await this.bridge.spawn();
+      if (!spawned) {
+        throw new Error(
+          'RustProxy binary not found. Set SMARTPROXY_RUST_BINARY env var, install the platform package, ' +
+          'or build locally with: pnpm build'
+        );
+      }
+      didSpawn = true;
 
-    // Check if any routes need TS-side handling (socket handlers, dynamic functions)
-    const hasHandlerRoutes = this.settings.routes.some(
-      (r) =>
-        (r.action.type === 'socket-handler' && r.action.socketHandler) ||
-        r.action.targets?.some((t) => typeof t.host === 'function' || typeof t.port === 'function')
-    );
+      // Handle unexpected exit (only emits error if not intentionally stopping)
+      this.bridge.removeAllListeners('exit');
+      this.bridge.on('exit', (code: number | null, signal: string | null) => {
+        if (this.stopping) return;
+        logger.log('error', `RustProxy exited unexpectedly (code=${code}, signal=${signal})`, { component: 'smart-proxy' });
+        this.emit('error', new Error(`RustProxy exited (code=${code}, signal=${signal})`));
+      });
 
-    // Start socket handler relay server (but don't tell Rust yet - proxy not started)
-    if (hasHandlerRoutes) {
-      this.socketHandlerServer = new SocketHandlerServer(this.preprocessor);
-      await this.socketHandlerServer.start();
-    }
+      const hasChallengeRoutes = this.hasChallengeRoutes(this.settings.routes);
+      if (hasChallengeRoutes) {
+        await this.ensureChallengeProviderRelay();
+      }
 
-    // Check if any routes need datagram handler relay (UDP socket-handler routes)
-    const hasDatagramHandlers = this.settings.routes.some(
-      (r) => r.action.type === 'socket-handler' && r.action.datagramHandler
-    );
-    if (hasDatagramHandlers) {
-      const dgPath = `/tmp/smartproxy-dgram-relay-${process.pid}.sock`;
-      this.datagramHandlerServer = new DatagramHandlerServer(dgPath, this.preprocessor);
-      await this.datagramHandlerServer.start();
-    }
+      // Check if any routes need TS-side handling (socket handlers, dynamic functions)
+      const hasHandlerRoutes = this.settings.routes.some(
+        (r) =>
+          (r.action.type === 'socket-handler' && r.action.socketHandler) ||
+          r.action.targets?.some((t) => typeof t.host === 'function' || typeof t.port === 'function')
+      );
 
-    // Preprocess routes (strip JS functions, convert socket-handler routes)
-    const rustRoutes = this.preprocessor.preprocessForRust(this.settings.routes);
+      // Start socket handler relay server (but don't tell Rust yet - proxy not started)
+      if (hasHandlerRoutes) {
+        this.socketHandlerServer = new SocketHandlerServer(this.preprocessor);
+        await this.socketHandlerServer.start();
+      }
 
-    // When certProvisionFunction handles cert provisioning,
-    // disable Rust's built-in ACME to prevent race condition.
-    let acmeForRust = this.settings.acme;
-    if (this.settings.certProvisionFunction && acmeForRust?.enabled) {
-      acmeForRust = { ...acmeForRust, enabled: false };
-      logger.log('info', 'Rust ACME disabled — certProvisionFunction will handle certificate provisioning', { component: 'smart-proxy' });
-    }
+      // Check if any routes need datagram handler relay (UDP socket-handler routes)
+      const hasDatagramHandlers = this.settings.routes.some(
+        (r) => r.action.type === 'socket-handler' && r.action.datagramHandler
+      );
+      if (hasDatagramHandlers) {
+        const dgPath = `/tmp/smartproxy-dgram-relay-${process.pid}.sock`;
+        this.datagramHandlerServer = new DatagramHandlerServer(dgPath, this.preprocessor);
+        await this.datagramHandlerServer.start();
+      }
 
-    // Build Rust config
-    const config = this.buildRustConfig(rustRoutes, acmeForRust);
+      // Preprocess routes (strip JS functions, convert socket-handler routes)
+      const rustRoutes = this.preprocessor.preprocessForRust(this.settings.routes);
 
-    // Start the Rust proxy
-    await this.bridge.startProxy(config);
+      // When certProvisionFunction handles cert provisioning,
+      // disable Rust's built-in ACME to prevent race condition.
+      let acmeForRust = this.settings.acme;
+      if (this.settings.certProvisionFunction && acmeForRust?.enabled) {
+        acmeForRust = { ...acmeForRust, enabled: false };
+        logger.log('info', 'Rust ACME disabled — certProvisionFunction will handle certificate provisioning', { component: 'smart-proxy' });
+      }
 
-    // Now that Rust proxy is running, configure socket handler relay
-    if (this.socketHandlerServer) {
-      await this.bridge.setSocketHandlerRelay(this.socketHandlerServer.getSocketPath());
-    }
+      // Build Rust config
+      const config = this.buildRustConfig(rustRoutes, acmeForRust);
 
-    // Configure datagram handler relay
-    if (this.datagramHandlerServer) {
-      await this.bridge.setDatagramHandlerRelay(this.datagramHandlerServer.getSocketPath());
-    }
+      // Start the Rust proxy
+      await this.bridge.startProxy(config);
 
-    // Load default self-signed fallback certificate (domain: '*')
-    if (!this.settings.disableDefaultCert) {
-      try {
-        const defaultCert = generateDefaultCertificate();
-        await this.bridge.loadCertificate('*', defaultCert.cert, defaultCert.key);
-        logger.log('info', 'Default self-signed fallback certificate loaded', { component: 'smart-proxy' });
-      } catch (err: any) {
-        logger.log('warn', `Failed to generate default certificate: ${err.message}`, { component: 'smart-proxy' });
+      // Now that Rust proxy is running, configure socket handler relay
+      if (this.socketHandlerServer) {
+        await this.bridge.setSocketHandlerRelay(this.socketHandlerServer.getSocketPath());
       }
-    }
 
-    // Load consumer-stored certificates
-    const preloadedDomains = new Set<string>();
-    if (this.settings.certStore) {
-      try {
-        const stored = await this.settings.certStore.loadAll();
-        for (const entry of stored) {
-          await this.bridge.loadCertificate(entry.domain, entry.publicKey, entry.privateKey, entry.ca);
-          preloadedDomains.add(entry.domain);
+      // Configure challenge provider relay. The path is also present in startup config,
+      // but this hot setter keeps runtime changes explicit and mirrors other relays.
+      if (this.challengeProviderRelayServer) {
+        await this.bridge.setChallengeProviderRelay(
+          this.challengeProviderRelayServer.getSocketPath(),
+          this.challengeRuntimeOptions,
+        );
+      }
+
+      // Configure datagram handler relay
+      if (this.datagramHandlerServer) {
+        await this.bridge.setDatagramHandlerRelay(this.datagramHandlerServer.getSocketPath());
+      }
+
+      // Load default self-signed fallback certificate (domain: '*')
+      if (!this.settings.disableDefaultCert) {
+        try {
+          const defaultCert = generateDefaultCertificate();
+          await this.bridge.loadCertificate('*', defaultCert.cert, defaultCert.key);
+          logger.log('info', 'Default self-signed fallback certificate loaded', { component: 'smart-proxy' });
+        } catch (err) {
+          logger.log('warn', `Failed to generate default certificate: ${(err as Error).message}`, { component: 'smart-proxy' });
+        }
+      }
+
+      // Load consumer-stored certificates
+      const preloadedDomains = new Set<string>();
+      if (this.settings.certStore) {
+        try {
+          const stored = await this.settings.certStore.loadAll();
+          for (const entry of stored) {
+            await this.bridge.loadCertificate(entry.domain, entry.publicKey, entry.privateKey, entry.ca);
+            preloadedDomains.add(entry.domain);
+          }
+          logger.log('info', `Loaded ${stored.length} certificate(s) from consumer store`, { component: 'smart-proxy' });
+        } catch (err) {
+          logger.log('warn', `Failed to load certificates from consumer store: ${(err as Error).message}`, { component: 'smart-proxy' });
         }
-        logger.log('info', `Loaded ${stored.length} certificate(s) from consumer store`, { component: 'smart-proxy' });
-      } catch (err: any) {
-        logger.log('warn', `Failed to load certificates from consumer store: ${err.message}`, { component: 'smart-proxy' });
       }
-    }
 
-    // Apply NFTables rules for routes using nftables forwarding engine
-    await this.applyNftablesRules(this.settings.routes);
+      // Apply NFTables rules for routes using nftables forwarding engine
+      await this.applyNftablesRules(this.settings.routes);
 
-    // Start metrics polling BEFORE cert provisioning — the Rust engine is already
-    // running and accepting connections, so metrics should be available immediately.
-    // Cert provisioning can hang indefinitely (e.g. DNS-01 ACME timeouts) and must
-    // not block metrics collection.
-    this.metricsAdapter.startPolling();
+      // Start metrics polling BEFORE cert provisioning — the Rust engine is already
+      // running and accepting connections, so metrics should be available immediately.
+      // Cert provisioning can hang indefinitely (e.g. DNS-01 ACME timeouts) and must
+      // not block metrics collection.
+      this.metricsAdapter.startPolling();
 
-    logger.log('info', 'SmartProxy started (Rust engine)', { component: 'smart-proxy' });
+      logger.log('info', 'SmartProxy started (Rust engine)', { component: 'smart-proxy' });
 
-    // Fire-and-forget cert provisioning — Rust engine is already running and serving traffic.
-    // Events (certificate-issued / certificate-failed) fire independently per domain.
-    this.certProvisionPromise = this.provisionCertificatesViaCallback(preloadedDomains)
-      .catch((err) => logger.log('error', `Unexpected error in cert provisioning: ${err.message}`, { component: 'smart-proxy' }));
+      // Fire-and-forget cert provisioning — Rust engine is already running and serving traffic.
+      // Events (certificate-issued / certificate-failed) fire independently per domain.
+      this.certProvisionPromise = this.provisionCertificatesViaCallback(preloadedDomains)
+        .catch((err) => logger.log('error', `Unexpected error in cert provisioning: ${err.message}`, { component: 'smart-proxy' }));
+    } catch (err) {
+      await this.cleanupRuntimeResourcesAfterStartFailure(didSpawn);
+      throw err;
+    }
   }
 
   /**
@@ -276,6 +316,13 @@ export class SmartProxy extends plugins.EventEmitter {
       this.datagramHandlerServer = null;
     }
 
+    // Stop challenge provider relay
+    if (this.challengeProviderRelayServer) {
+      await this.challengeProviderRelayServer.stop();
+      this.challengeProviderRelayServer = null;
+    }
+    this.challengeRuntimeOptions = undefined;
+
     logger.log('info', 'SmartProxy shutdown complete.', { component: 'smart-proxy' });
   }
 
@@ -284,18 +331,41 @@ export class SmartProxy extends plugins.EventEmitter {
    */
   public async updateRoutes(newRoutes: IRouteConfig[]): Promise<void> {
     await this.routeUpdateLock.runExclusive(async () => {
-      // Validate
+      await this.validateChallengeRoutes(newRoutes);
+
+      // Validate before starting relays so failed route updates do not leak runtime resources.
       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`);
       }
 
+      const hasChallengeRoutes = this.hasChallengeRoutes(newRoutes);
+      const challengeRelayWasStarted = Boolean(this.challengeProviderRelayServer);
+
       // Preprocess for Rust
       const rustRoutes = this.preprocessor.preprocessForRust(newRoutes);
 
-      // Send to Rust
-      await this.bridge.updateRoutes(rustRoutes);
+      try {
+        if (hasChallengeRoutes) {
+          await this.ensureChallengeProviderRelay();
+          await this.bridge.setChallengeProviderRelay(
+            this.challengeProviderRelayServer!.getSocketPath(),
+            this.challengeRuntimeOptions,
+          );
+        }
+
+        // Send to Rust
+        await this.bridge.updateRoutes(rustRoutes);
+      } catch (err) {
+        if (hasChallengeRoutes && !challengeRelayWasStarted && this.challengeProviderRelayServer) {
+          await this.bridge.setChallengeProviderRelay('').catch(() => undefined);
+          await this.challengeProviderRelayServer.stop();
+          this.challengeProviderRelayServer = null;
+          this.challengeRuntimeOptions = undefined;
+        }
+        throw err;
+      }
 
       // Update local route manager
       this.routeManager.updateRoutes(newRoutes);
@@ -331,6 +401,15 @@ export class SmartProxy extends plugins.EventEmitter {
         this.datagramHandlerServer = null;
       }
 
+      if (!hasChallengeRoutes && this.challengeProviderRelayServer) {
+        await this.bridge.setChallengeProviderRelay('').catch((err) => {
+          logger.log('warn', `Failed to clear challenge provider relay in Rust: ${(err as Error).message}`, { component: 'smart-proxy' });
+        });
+        await this.challengeProviderRelayServer.stop();
+        this.challengeProviderRelayServer = null;
+        this.challengeRuntimeOptions = undefined;
+      }
+
       // Update NFTables rules
       if (this.nftablesManager) {
         await this.nftablesManager.cleanup();
@@ -456,6 +535,45 @@ export class SmartProxy extends plugins.EventEmitter {
 
   // --- Private helpers ---
 
+  private async cleanupRuntimeResourcesAfterStartFailure(didSpawn: boolean): Promise<void> {
+    this.metricsAdapter.stopPolling();
+
+    if (this.nftablesManager) {
+      await this.nftablesManager.cleanup().catch((err) => {
+        logger.log('warn', `Failed to clean NFTables after start failure: ${(err as Error).message}`, { component: 'smart-proxy' });
+      });
+      this.nftablesManager = null;
+    }
+
+    if (this.socketHandlerServer) {
+      await this.socketHandlerServer.stop().catch((err) => {
+        logger.log('warn', `Failed to stop socket handler relay after start failure: ${(err as Error).message}`, { component: 'smart-proxy' });
+      });
+      this.socketHandlerServer = null;
+    }
+
+    if (this.datagramHandlerServer) {
+      await this.datagramHandlerServer.stop().catch((err) => {
+        logger.log('warn', `Failed to stop datagram handler relay after start failure: ${(err as Error).message}`, { component: 'smart-proxy' });
+      });
+      this.datagramHandlerServer = null;
+    }
+
+    if (this.challengeProviderRelayServer) {
+      await this.challengeProviderRelayServer.stop().catch((err) => {
+        logger.log('warn', `Failed to stop challenge provider relay after start failure: ${(err as Error).message}`, { component: 'smart-proxy' });
+      });
+      this.challengeProviderRelayServer = null;
+      this.challengeRuntimeOptions = undefined;
+    }
+
+    if (didSpawn) {
+      this.bridge.removeAllListeners('exit');
+      await this.bridge.stopProxy().catch(() => undefined);
+      this.bridge.kill();
+    }
+  }
+
   /**
    * Apply NFTables rules for routes using the nftables forwarding engine.
    */
@@ -505,7 +623,195 @@ export class SmartProxy extends plugins.EventEmitter {
    * Build the Rust configuration object from TS settings.
    */
   private buildRustConfig(routes: IRustProxyOptions['routes'], acmeOverride?: IAcmeOptions): IRustProxyOptions {
-    return buildRustProxyOptions(this.settings, routes, acmeOverride);
+    return buildRustProxyOptions(this.settings, routes, acmeOverride, this.challengeRuntimeOptions);
+  }
+
+  private hasChallengeRoutes(routes: IRouteConfig[]): boolean {
+    return routes.some((route) => Boolean(route.security?.challenge));
+  }
+
+  private async ensureChallengeProviderRelay(): Promise<void> {
+    const runtimeOptions = this.settings.challenge || {};
+    if (!this.challengeProviderRelayServer) {
+      this.challengeProviderRelayServer = new ChallengeProviderRelayServer(this.challengeProviders, {
+        providerTimeoutMs: runtimeOptions.relayTimeoutMs ?? 5_000,
+      });
+      await this.challengeProviderRelayServer.start();
+    }
+    if (!this.challengeRuntimeOptions) {
+      this.challengeRuntimeOptions = {
+        cookieSigningKey: runtimeOptions.cookieSigningKey || plugins.crypto.randomBytes(32).toString('base64url'),
+        pendingCookieName: runtimeOptions.pendingCookieName || '__smartproxy_challenge_pending',
+        clearanceCookieName: runtimeOptions.clearanceCookieName || '__smartproxy_clearance',
+        reservedPathPrefix: runtimeOptions.reservedPathPrefix || '/.well-known/smartproxy-challenge',
+        relaySocketPath: this.challengeProviderRelayServer.getSocketPath(),
+        relayTimeoutMs: runtimeOptions.relayTimeoutMs ?? 5_000,
+        pendingTtlSeconds: runtimeOptions.pendingTtlSeconds ?? 300,
+      };
+    } else {
+      this.challengeRuntimeOptions = {
+        ...this.challengeRuntimeOptions,
+        relaySocketPath: this.challengeProviderRelayServer.getSocketPath(),
+      };
+    }
+  }
+
+  private async validateChallengeRoutes(routes: IRouteConfig[]): Promise<void> {
+    const manifestCache = new Map<string, plugins.smartchallenge.IChallengeProviderManifest>();
+    const errors: string[] = [];
+
+    for (const route of routes) {
+      const challenge = route.security?.challenge;
+      if (!challenge) continue;
+      const routeName = route.name || route.id || 'unnamed route';
+
+      if (!challenge.providerId || typeof challenge.providerId !== 'string') {
+        errors.push(`${routeName}: challenge.providerId must be a non-empty string`);
+      }
+      if (!challenge.challengeType || typeof challenge.challengeType !== 'string') {
+        errors.push(`${routeName}: challenge.challengeType must be a non-empty string`);
+      }
+      if (!route.name && !route.id) {
+        errors.push(`${routeName}: challenge routes must set a stable route name or id`);
+      }
+      this.validateChallengeIntentShape(challenge, errors, routeName);
+      if (route.action.type !== 'forward') {
+        errors.push(`${routeName}: challenge routes must use forward actions`);
+      }
+      if (route.action.forwardingEngine === 'nftables') {
+        errors.push(`${routeName}: challenge routes cannot use nftables forwarding`);
+      }
+      if (route.action.tls?.mode === 'passthrough') {
+        errors.push(`${routeName}: 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`);
+        }
+        if (target.tls?.mode === 'passthrough') {
+          errors.push(`${routeName}: challenge routes cannot use target TLS passthrough`);
+        }
+      }
+      if (route.match.transport === 'udp' || route.match.transport === 'all') {
+        errors.push(`${routeName}: challenge routes currently require HTTP-visible TCP handling`);
+      }
+      if (route.match.protocol !== 'http') {
+        errors.push(`${routeName}: challenge routes must set match.protocol to 'http'`);
+      }
+      this.collectForbiddenChallengeKeys(challenge, `security.challenge`, errors, routeName);
+
+      const provider = this.challengeProviders.get(challenge.providerId);
+      if (!provider) {
+        errors.push(`${routeName}: challenge provider '${challenge.providerId}' is not registered`);
+        continue;
+      }
+      let manifest = manifestCache.get(challenge.providerId);
+      if (!manifest) {
+        manifest = await provider.getManifest();
+        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}'`);
+      }
+    }
+
+    if (errors.length > 0) {
+      throw new Error(`Challenge route validation failed:\n${errors.map((error) => `- ${error}`).join('\n')}`);
+    }
+  }
+
+  private validateChallengeIntentShape(challengeArg: unknown, errors: string[], routeName: string): void {
+    if (!this.isPlainRecord(challengeArg)) {
+      errors.push(`${routeName}: security.challenge must be an object`);
+      return;
+    }
+
+    this.validateAllowedChallengeKeys(
+      challengeArg,
+      'security.challenge',
+      new Set(['providerId', 'challengeType', 'policyRef', 'settings', 'applyTo', 'clearance']),
+      errors,
+      routeName,
+    );
+
+    const settings = challengeArg.settings;
+    if (settings !== undefined && !this.isPlainRecord(settings)) {
+      errors.push(`${routeName}: security.challenge.settings must be an object when set`);
+    }
+
+    const applyTo = challengeArg.applyTo;
+    if (applyTo !== undefined) {
+      if (!this.isPlainRecord(applyTo)) {
+        errors.push(`${routeName}: security.challenge.applyTo must be an object when set`);
+      } else {
+        this.validateAllowedChallengeKeys(
+          applyTo,
+          'security.challenge.applyTo',
+          new Set(['methods', 'browserNavigationsOnly', 'includePaths', 'excludePaths']),
+          errors,
+          routeName,
+        );
+      }
+    }
+
+    const clearance = challengeArg.clearance;
+    if (clearance !== undefined) {
+      if (!this.isPlainRecord(clearance)) {
+        errors.push(`${routeName}: security.challenge.clearance must be an object when set`);
+      } else {
+        this.validateAllowedChallengeKeys(
+          clearance,
+          'security.challenge.clearance',
+          new Set(['ttlSeconds', 'bindToHost', 'bindToRoute', 'bindToIp']),
+          errors,
+          routeName,
+        );
+      }
+    }
+  }
+
+  private validateAllowedChallengeKeys(
+    valueArg: Record<string, unknown>,
+    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`);
+      }
+    }
+  }
+
+  private isPlainRecord(valueArg: unknown): valueArg is Record<string, unknown> {
+    return Boolean(valueArg)
+      && typeof valueArg === 'object'
+      && !Array.isArray(valueArg);
+  }
+
+  private collectForbiddenChallengeKeys(value: unknown, path: string, errors: string[], routeName: 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`);
+      }
+      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`);
+      }
+      if (nestedValue && typeof nestedValue === 'object') {
+        this.collectForbiddenChallengeKeys(nestedValue, childPath, errors, routeName);
+      }
+    }
+  }
+
+  private looksLikeRuntimeChallengeValue(valueArg: string): boolean {
+    return /^https?:\/\//i.test(valueArg)
+      || /^wss?:\/\//i.test(valueArg)
+      || /(?:^|\b)(?:\d{1,3}\.){3}\d{1,3}(?::\d+)?(?:\b|$)/.test(valueArg)
+      || /^[a-z0-9.-]+:\d+$/i.test(valueArg);
   }
 
   /**