@serve.zone/dcrouter 16.1.1 → 16.2.0

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/dcrouter',
-  version: '16.1.1',
+  version: '16.2.0',
   description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 }

package/ts/config/classes.route-config-manager.ts

@@ -4,6 +4,7 @@ import { RouteDoc } from '../db/index.js';
 import { routePathClasses } from '../../ts_interfaces/data/route-management.js';
 import type {
   IHttpRedirectInfo,
+  ILetsEncryptHttp01ForwardConfig,
   IRoute,
   IMergedRoute,
   IRouteWarning,
@@ -18,6 +19,11 @@ import { type IHttp3Config, augmentRouteWithHttp3, routeNeedsHttpProtocol } from
 import type { ReferenceResolver } from './classes.reference-resolver.js';
 import { SourcePolicyCompiler } from './classes.source-policy-compiler.js';
 import { deriveHttpRedirects } from './helpers.http-redirects.js';
+import {
+  buildLetsEncryptHttp01Route,
+  letsEncryptHttp01ManagedRouteKind,
+  type ISpecialForwardResolvedTarget,
+} from './helpers.special-forwards.js';
 
 export type TVpnClientAllowEntry = string | { clientId: string; domains: string[] };
 
@@ -26,6 +32,12 @@ export interface IRouteMutationResult {
   message?: string;
 }
 
+interface IRouteMutationOptions {
+  trustedManagedMutation?: boolean;
+  replaceMetadata?: boolean;
+  replaceRoute?: boolean;
+}
+
 /**
  * Simple async mutex — serializes concurrent applyRoutes() calls so the Rust engine
  * never receives rapid overlapping route updates that can churn UDP/QUIC listeners.
@@ -145,7 +157,17 @@ export class RouteConfigManager {
     createdBy: string,
     enabled = true,
     metadata?: IRouteMetadata,
+    options: IRouteMutationOptions = {},
   ): Promise<string> {
+    if (!options.trustedManagedMutation && this.hasReservedManagedMetadata(metadata)) {
+      throw new Error(
+        'Managed route ownership metadata is reserved; use a specialized route endpoint',
+      );
+    }
+    metadata = options.trustedManagedMutation
+      ? metadata
+      : { ...metadata, ownerType: 'operator' };
+
     const id = plugins.uuid.v4();
     const now = Date.now();
     const sourceBindingsPayloadError = SourcePolicyCompiler.validateSourceBindingsPayload(metadata?.sourceBindings);
@@ -187,6 +209,34 @@ export class RouteConfigManager {
     return id;
   }
 
+  public async createManagedRoute(
+    route: IDcRouterRouteConfig,
+    createdBy: string,
+    enabled: boolean,
+    metadata: IRouteMetadata,
+  ): Promise<string> {
+    if (!this.isManagedMetadata(metadata)) {
+      throw new Error('Managed route metadata is required');
+    }
+    return await this.createRoute(route, createdBy, enabled, metadata, {
+      trustedManagedMutation: true,
+    });
+  }
+
+  public async createLetsEncryptHttp01Forward(
+    config: ILetsEncryptHttp01ForwardConfig,
+    createdBy: string,
+    enabled = true,
+  ): Promise<string> {
+    const compiled = this.compileLetsEncryptHttp01Forward(config);
+    return await this.createManagedRoute(
+      compiled.route,
+      createdBy,
+      enabled,
+      compiled.metadata,
+    );
+  }
+
   public async updateRoute(
     id: string,
     patch: {
@@ -194,11 +244,27 @@ export class RouteConfigManager {
       enabled?: boolean;
       metadata?: Partial<IRouteMetadata>;
     },
+    options: IRouteMutationOptions = {},
   ): Promise<IRouteMutationResult> {
     const stored = this.routes.get(id);
     if (!stored) {
       return { success: false, message: 'Route not found' };
     }
+    const isToggleOnlyPatch = patch.enabled !== undefined
+      && patch.route === undefined
+      && patch.metadata === undefined;
+    if (!options.trustedManagedMutation && this.hasReservedManagedMetadata(patch.metadata)) {
+      return {
+        success: false,
+        message: 'Managed route ownership metadata is reserved; use a specialized route endpoint',
+      };
+    }
+    if (!options.trustedManagedMutation && this.isManagedRoute(stored) && !isToggleOnlyPatch) {
+      return {
+        success: false,
+        message: 'Managed routes must be changed through their specialized endpoint',
+      };
+    }
     const sourceBindingsPayloadError = SourcePolicyCompiler.validateSourceBindingsPayload(patch.metadata?.sourceBindings);
     if (sourceBindingsPayloadError) {
       return { success: false, message: sourceBindingsPayloadError };
@@ -208,9 +274,6 @@ export class RouteConfigManager {
     const previousMetadata = structuredClone(stored.metadata);
     const previousEnabled = stored.enabled;
 
-    const isToggleOnlyPatch = patch.enabled !== undefined
-      && patch.route === undefined
-      && patch.metadata === undefined;
     if (stored.origin !== 'api' && !isToggleOnlyPatch) {
       return {
         success: false,
@@ -219,36 +282,41 @@ export class RouteConfigManager {
     }
 
     if (patch.route) {
-      const mergedAction = patch.route.action
-        ? { ...stored.route.action, ...patch.route.action }
-        : stored.route.action;
-      // Handle explicit null to remove nested action properties (e.g., tls: null)
-      if (patch.route.action) {
-        for (const [key, val] of Object.entries(patch.route.action)) {
-          if (val === null) {
-            delete (mergedAction as any)[key];
+      if (options.replaceRoute) {
+        stored.route = structuredClone(patch.route) as IDcRouterRouteConfig;
+      } else {
+        const mergedAction = patch.route.action
+          ? { ...stored.route.action, ...patch.route.action }
+          : stored.route.action;
+        // Handle explicit null to remove nested action properties (e.g., tls: null)
+        if (patch.route.action) {
+          for (const [key, val] of Object.entries(patch.route.action)) {
+            if (val === null) {
+              delete (mergedAction as any)[key];
+            }
           }
         }
-      }
-      const mergedRoute = { ...stored.route, ...patch.route, action: mergedAction } as IDcRouterRouteConfig;
+        const mergedRoute = { ...stored.route, ...patch.route, action: mergedAction } as IDcRouterRouteConfig;
 
-      // Handle explicit null to remove optional top-level route properties (e.g., remoteIngress: null)
-      for (const [key, val] of Object.entries(patch.route)) {
-        if (val === null && key !== 'action' && key !== 'match') {
-          delete (mergedRoute as any)[key];
+        // Handle explicit null to remove optional top-level route properties (e.g., remoteIngress: null)
+        for (const [key, val] of Object.entries(patch.route)) {
+          if (val === null && key !== 'action' && key !== 'match') {
+            delete (mergedRoute as any)[key];
+          }
         }
-      }
 
-      stored.route = mergedRoute;
+        stored.route = mergedRoute;
+      }
     }
     if (patch.enabled !== undefined) {
       stored.enabled = patch.enabled;
     }
     if (patch.metadata !== undefined) {
-      stored.metadata = this.normalizeRouteMetadata({
-        ...stored.metadata,
-        ...patch.metadata,
-      });
+      stored.metadata = this.normalizeRouteMetadata(
+        options.replaceMetadata
+          ? patch.metadata
+          : { ...stored.metadata, ...patch.metadata },
+      );
     }
 
     // Re-resolve if metadata refs exist and resolver is available
@@ -273,11 +341,68 @@ export class RouteConfigManager {
     return { success: true };
   }
 
-  public async deleteRoute(id: string): Promise<IRouteMutationResult> {
+  public async updateManagedRoute(
+    id: string,
+    patch: {
+      route?: Partial<IDcRouterRouteConfig>;
+      enabled?: boolean;
+      metadata?: Partial<IRouteMetadata>;
+    },
+    options: Pick<IRouteMutationOptions, 'replaceMetadata' | 'replaceRoute'> = {},
+  ): Promise<IRouteMutationResult> {
+    const stored = this.routes.get(id);
+    if (!stored || !this.isManagedRoute(stored)) {
+      return { success: false, message: 'Managed route not found' };
+    }
+    return await this.updateRoute(id, patch, {
+      trustedManagedMutation: true,
+      ...options,
+    });
+  }
+
+  public async updateLetsEncryptHttp01Forward(
+    id: string,
+    config: ILetsEncryptHttp01ForwardConfig,
+    enabled?: boolean,
+  ): Promise<IRouteMutationResult> {
+    const stored = this.routes.get(id);
+    if (
+      !stored
+      || stored.metadata?.ownerType === 'gatewayClient'
+      || stored.metadata?.managedRouteKind !== letsEncryptHttp01ManagedRouteKind
+    ) {
+      return { success: false, message: 'Let\'s Encrypt HTTP-01 forward not found' };
+    }
+
+    const compiled = this.compileLetsEncryptHttp01Forward(config);
+    return await this.updateManagedRoute(
+      id,
+      {
+        route: compiled.route,
+        metadata: compiled.metadata,
+        ...(enabled !== undefined ? { enabled } : {}),
+      },
+      {
+        replaceMetadata: true,
+        replaceRoute: true,
+      },
+    );
+  }
+
+  public async deleteRoute(
+    id: string,
+    options: IRouteMutationOptions = {},
+  ): Promise<IRouteMutationResult> {
     const stored = this.routes.get(id);
     if (!stored) {
       return { success: false, message: 'Route not found' };
     }
+    if (!options.trustedManagedMutation && this.isManagedRoute(stored)) {
+      return {
+        success: false,
+        message: 'Managed routes must be deleted through their specialized endpoint',
+      };
+    }
     if (stored.origin !== 'api') {
       return {
         success: false,
@@ -292,6 +417,26 @@ export class RouteConfigManager {
     return { success: true };
   }
 
+  public async deleteManagedRoute(id: string): Promise<IRouteMutationResult> {
+    const stored = this.routes.get(id);
+    if (!stored || !this.isManagedRoute(stored)) {
+      return { success: false, message: 'Managed route not found' };
+    }
+    return await this.deleteRoute(id, { trustedManagedMutation: true });
+  }
+
+  public async deleteLetsEncryptHttp01Forward(id: string): Promise<IRouteMutationResult> {
+    const stored = this.routes.get(id);
+    if (
+      !stored
+      || stored.metadata?.ownerType === 'gatewayClient'
+      || stored.metadata?.managedRouteKind !== letsEncryptHttp01ManagedRouteKind
+    ) {
+      return { success: false, message: 'Let\'s Encrypt HTTP-01 forward not found' };
+    }
+    return await this.deleteManagedRoute(id);
+  }
+
   public async toggleRoute(id: string, enabled: boolean): Promise<IRouteMutationResult> {
     return this.updateRoute(id, { enabled });
   }
@@ -471,6 +616,97 @@ export class RouteConfigManager {
     }
   }
 
+  private compileLetsEncryptHttp01Forward(
+    config: ILetsEncryptHttp01ForwardConfig,
+  ): { route: IDcRouterRouteConfig; metadata: IRouteMetadata } {
+    if (!this.referenceResolver) {
+      throw new Error('Reference resolver is unavailable');
+    }
+
+    const publicProfile = this.referenceResolver.listProfiles().find((profile) => {
+      return profile.name.trim().toUpperCase() === 'PUBLIC';
+    });
+    if (!publicProfile) {
+      throw new Error('The PUBLIC source profile is required for HTTP-01 forwards');
+    }
+    const publicSecurity = this.referenceResolver.resolveSourceProfileSecurity(publicProfile.id);
+    if (!publicSecurity?.ipAllowList?.includes('*')) {
+      throw new Error('The PUBLIC source profile must allow all source addresses');
+    }
+
+    const networkTargetRef = config.networkTargetRef?.trim();
+    if (networkTargetRef && config.target) {
+      throw new Error('Choose either an inline target or a Network Target, not both');
+    }
+
+    let target: ISpecialForwardResolvedTarget;
+    let networkTargetName: string | undefined;
+    if (networkTargetRef) {
+      const networkTarget = this.referenceResolver.getTarget(networkTargetRef);
+      if (!networkTarget) {
+        throw new Error(`Network Target '${networkTargetRef}' was not found`);
+      }
+      target = {
+        host: networkTarget.host,
+        port: networkTarget.port,
+      };
+      networkTargetName = networkTarget.name;
+    } else if (config.target) {
+      target = config.target;
+    } else {
+      throw new Error('An inline target or Network Target is required');
+    }
+
+    return {
+      route: buildLetsEncryptHttp01Route(config, target),
+      metadata: {
+        ownerType: 'operator',
+        managedRouteKind: letsEncryptHttp01ManagedRouteKind,
+        sourceBindings: [{
+          sourceProfileRef: publicProfile.id,
+          sourceProfileName: publicProfile.name,
+        }],
+        ...(networkTargetRef
+          ? {
+              networkTargetRef,
+              networkTargetName,
+              lastResolvedAt: Date.now(),
+            }
+          : {}),
+      },
+    };
+  }
+
+  private hasReservedManagedMetadata(metadata?: Partial<IRouteMetadata>): boolean {
+    return Boolean(
+      metadata
+      && (
+        metadata.ownerType !== undefined
+        || metadata.gatewayClientType !== undefined
+        || metadata.gatewayClientId !== undefined
+        || metadata.gatewayClientAppId !== undefined
+        || metadata.externalKey !== undefined
+        || metadata.managedRouteKind !== undefined
+      ),
+    );
+  }
+
+  private isManagedMetadata(metadata?: Partial<IRouteMetadata>): boolean {
+    return Boolean(
+      metadata
+      && (
+        metadata.ownerType === 'gatewayClient'
+        || metadata.managedRouteKind !== undefined
+        || metadata.gatewayClientId
+        || metadata.externalKey
+      ),
+    );
+  }
+
+  private isManagedRoute(storedRoute: IRoute): boolean {
+    return storedRoute.origin === 'api' && this.isManagedMetadata(storedRoute.metadata);
+  }
+
   private normalizeRouteMetadata(metadata?: Partial<IRouteMetadata>): IRouteMetadata | undefined {
     if (!metadata) {
       return undefined;
@@ -500,6 +736,9 @@ export class RouteConfigManager {
       gatewayClientId: normalizeString(metadata.gatewayClientId),
       gatewayClientAppId: normalizeString(metadata.gatewayClientAppId),
       externalKey: normalizeString(metadata.externalKey),
+      managedRouteKind: metadata.managedRouteKind === letsEncryptHttp01ManagedRouteKind
+        ? metadata.managedRouteKind
+        : undefined,
     };
 
     if (!normalized.networkTargetRef) {
@@ -515,7 +754,13 @@ export class RouteConfigManager {
       normalized.externalKey = undefined;
     }
 
-    if (Object.values(normalized).every((value) => value === undefined)) {
+    for (const [key, value] of Object.entries(normalized)) {
+      if (value === undefined) {
+        delete (normalized as Record<string, unknown>)[key];
+      }
+    }
+
+    if (Object.keys(normalized).length === 0) {
       return undefined;
     }
 
@@ -807,13 +1052,7 @@ export class RouteConfigManager {
   }
 
   private isManagedAccessRoute(storedRoute: IRoute): boolean {
-    const metadata = storedRoute.metadata;
-    if (storedRoute.origin !== 'api' || !metadata) {
-      return false;
-    }
-    return metadata.ownerType === 'gatewayClient'
-      || Boolean(metadata.gatewayClientId)
-      || Boolean(metadata.externalKey);
+    return this.isManagedRoute(storedRoute);
   }
 
   private prepareRouteForApply(

package/ts/config/helpers.http-redirects.ts

@@ -18,9 +18,9 @@ interface IRedirectCandidate {
   remoteIngress?: IRouteRemoteIngress;
 }
 
-interface IRedirectConflict {
-  routeName: string;
-  covers: boolean;
+interface IRedirectConflictAssessment {
+  status: 'covered' | 'skipped';
+  routeNames: string[];
 }
 
 export interface IHttpRedirectDerivationResult {
@@ -40,7 +40,7 @@ export function deriveHttpRedirectConfiguration(
     const conflict = findHttpConflict(candidate, httpRoutes);
     const redirectInfo: IHttpRedirectInfo = {
       id: candidate.id,
-      status: conflict ? (conflict.covers ? 'covered' : 'skipped') : 'active',
+      status: conflict?.status || 'active',
       domainPattern: candidate.domainPattern,
       pathPattern: candidate.pathPattern,
       fromTemplate: 'http://{domain}{path}',
@@ -49,12 +49,12 @@ export function deriveHttpRedirectConfiguration(
       priority: REDIRECT_PRIORITY,
       sourceRouteNames: [...candidate.sourceRouteNames].sort(),
       sourceRouteIds: [...candidate.sourceRouteIds].sort(),
-      coveredByRouteNames: conflict ? [conflict.routeName] : [],
+      coveredByRouteNames: conflict?.routeNames || [],
       remoteIngress: Boolean(candidate.remoteIngress?.enabled),
       notes: conflict
-        ? conflict.covers
+        ? conflict.status === 'covered'
           ? 'An explicit HTTP route already covers this redirect scope.'
-          : 'Skipped because an explicit HTTP route overlaps this redirect scope.'
+          : 'Skipped because one or more explicit HTTP routes overlap at equal or lower priority.'
         : undefined,
     };
 
@@ -140,19 +140,27 @@ function isExplicitHttpRoute(route: plugins.smartproxy.IRouteConfig): boolean {
 function findHttpConflict(
   candidate: IRedirectCandidate,
   httpRoutes: plugins.smartproxy.IRouteConfig[],
-): IRedirectConflict | undefined {
-  for (const route of httpRoutes) {
-    if (!httpRouteOverlapsCandidate(route, candidate)) {
-      continue;
-    }
-
+): IRedirectConflictAssessment | undefined {
+  const overlaps = httpRoutes.filter((route) => httpRouteOverlapsCandidate(route, candidate));
+  const coveringRoutes = overlaps.filter((route) => httpRouteCoversCandidate(route, candidate));
+  if (coveringRoutes.length > 0) {
     return {
-      routeName: getRouteDisplayName(route),
-      covers: httpRouteCoversCandidate(route, candidate),
+      status: 'covered',
+      routeNames: coveringRoutes.map(getRouteDisplayName).sort(),
     };
   }
 
-  return undefined;
+  const unsafeOverlaps = overlaps.filter((route) => {
+    const priority = typeof route.priority === 'number' ? route.priority : 0;
+    return !route.match.path || priority <= REDIRECT_PRIORITY;
+  });
+  if (unsafeOverlaps.length === 0) {
+    return undefined;
+  }
+  return {
+    status: 'skipped',
+    routeNames: unsafeOverlaps.map(getRouteDisplayName).sort(),
+  };
 }
 
 function httpRouteOverlapsCandidate(

package/ts/config/helpers.special-forwards.ts

@@ -0,0 +1,108 @@
+import type {
+  ILetsEncryptHttp01ForwardConfig,
+  TManagedRouteKind,
+} from '../../ts_interfaces/data/route-management.js';
+import type { IDcRouterRouteConfig } from '../../ts_interfaces/data/remoteingress.js';
+
+export const letsEncryptHttp01ManagedRouteKind: TManagedRouteKind =
+  'letsencrypt-http01-forward';
+export const letsEncryptHttp01Path = '/.well-known/acme-challenge/*';
+export const letsEncryptHttp01Priority = 1000;
+
+export interface ISpecialForwardResolvedTarget {
+  host: string | string[];
+  port: number;
+}
+
+/**
+ * Compile operator input into the immutable portion of a managed HTTP-01 route.
+ */
+export function buildLetsEncryptHttp01Route(
+  configArg: ILetsEncryptHttp01ForwardConfig,
+  targetArg: ISpecialForwardResolvedTarget,
+): IDcRouterRouteConfig {
+  const name = configArg.name.trim();
+  if (!name) {
+    throw new Error('Special Forward name is required');
+  }
+
+  const domains = normalizeLetsEncryptHttp01Domains(configArg.domains);
+  const target = normalizeTarget(targetArg);
+  const edgeFilter = configArg.remoteIngress?.edgeFilter
+    ?.map((entry) => entry.trim())
+    .filter(Boolean);
+
+  return {
+    name,
+    description: 'Managed Let\'s Encrypt HTTP-01 challenge forward',
+    priority: letsEncryptHttp01Priority,
+    tags: ['managed', 'special-forward', 'letsencrypt', 'http01'],
+    match: {
+      ports: 80,
+      domains,
+      path: letsEncryptHttp01Path,
+      protocol: 'http',
+      transport: 'tcp',
+    },
+    action: {
+      type: 'forward',
+      targets: [target],
+    },
+    ...(configArg.remoteIngress?.enabled
+      ? {
+          remoteIngress: {
+            enabled: true,
+            ...(edgeFilter?.length ? { edgeFilter } : {}),
+          },
+        }
+      : {}),
+  };
+}
+
+export function normalizeLetsEncryptHttp01Domains(domainsArg: string[]): string[] {
+  if (!Array.isArray(domainsArg)) {
+    throw new Error('At least one domain is required');
+  }
+
+  const domains = [...new Set(domainsArg.map((domain) => {
+    return domain.trim().toLowerCase().replace(/\.$/, '');
+  }).filter(Boolean))];
+
+  if (domains.length === 0) {
+    throw new Error('At least one domain is required');
+  }
+
+  for (const domain of domains) {
+    if (domain.includes('*')) {
+      throw new Error(`HTTP-01 does not support wildcard domain '${domain}'`);
+    }
+    if (!isValidPublicHostname(domain)) {
+      throw new Error(`Invalid public hostname '${domain}'`);
+    }
+  }
+
+  return domains;
+}
+
+function normalizeTarget(targetArg: ISpecialForwardResolvedTarget): ISpecialForwardResolvedTarget {
+  const hosts = (Array.isArray(targetArg.host) ? targetArg.host : [targetArg.host])
+    .map((host) => host.trim())
+    .filter(Boolean);
+  if (hosts.length === 0) {
+    throw new Error('A target host or Network Target is required');
+  }
+  if (!Number.isInteger(targetArg.port) || targetArg.port < 1 || targetArg.port > 65535) {
+    throw new Error('Target port must be between 1 and 65535');
+  }
+  return {
+    host: hosts.length === 1 ? hosts[0] : hosts,
+    port: targetArg.port,
+  };
+}
+
+function isValidPublicHostname(hostname: string): boolean {
+  if (hostname.length > 253 || !hostname.includes('.')) return false;
+  return hostname.split('.').every((label) => {
+    return /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label);
+  });
+}