@serve.zone/dcrouter 11.14.0 → 11.15.0

package/dist_ts/classes.dcrouter.d.ts

@@ -0,0 +1,392 @@
+import * as plugins from './plugins.js';
+import * as paths from './paths.js';
+import { UnifiedEmailServer, type IUnifiedEmailServerOptions, type IEmailRoute } from '@push.rocks/smartmta';
+import { StorageManager, type IStorageConfig } from './storage/index.js';
+import { CertProvisionScheduler } from './classes.cert-provision-scheduler.js';
+import { CacheDb, CacheCleaner } from './cache/index.js';
+import { OpsServer } from './opsserver/index.js';
+import { MetricsManager } from './monitoring/index.js';
+import { RadiusServer, type IRadiusServerConfig } from './radius/index.js';
+import { RemoteIngressManager, TunnelManager } from './remoteingress/index.js';
+import { VpnManager } from './vpn/index.js';
+import { RouteConfigManager, ApiTokenManager } from './config/index.js';
+import { type IHttp3Config } from './http3/index.js';
+export interface IDcRouterOptions {
+    /** Base directory for all dcrouter data. Defaults to ~/.serve.zone/dcrouter */
+    baseDir?: string;
+    /**
+     * Direct SmartProxy configuration - gives full control over HTTP/HTTPS and TCP/SNI traffic
+     * This is the preferred way to configure HTTP/HTTPS and general TCP/SNI traffic
+     */
+    smartProxyConfig?: plugins.smartproxy.ISmartProxyOptions;
+    /**
+     * Email server configuration
+     * This enables all email handling with pattern-based routing
+     */
+    emailConfig?: IUnifiedEmailServerOptions;
+    /**
+     * Custom email port configuration
+     * Allows configuring specific ports for email handling
+     * This overrides the default port mapping in the emailConfig
+     */
+    emailPortConfig?: {
+        /** External to internal port mapping */
+        portMapping?: Record<number, number>;
+        /** Custom port configuration for specific ports */
+        portSettings?: Record<number, any>;
+        /** Path to store received emails */
+        receivedEmailsPath?: string;
+    };
+    /** TLS/certificate configuration */
+    tls?: {
+        /** Contact email for ACME certificates */
+        contactEmail: string;
+        /** Domain for main certificate */
+        domain?: string;
+        /** Path to certificate file (if not using auto-provisioning) */
+        certPath?: string;
+        /** Path to key file (if not using auto-provisioning) */
+        keyPath?: string;
+        /** Path to CA certificate file (for custom CAs) */
+        caPath?: string;
+    };
+    /**
+     * The nameserver domains (e.g., ['ns1.example.com', 'ns2.example.com'])
+     * These will automatically get A records pointing to publicIp or proxyIps[0]
+     * These are what go in the NS records for ALL domains in dnsScopes
+     */
+    dnsNsDomains?: string[];
+    /**
+     * Domains this DNS server is authoritative for (e.g., ['example.com', 'mail.example.org'])
+     * NS records will be auto-generated for these domains
+     * Any DNS record outside these scopes will trigger a warning
+     * Email domains with `internal-dns` mode must be included here
+     */
+    dnsScopes?: string[];
+    /**
+     * IPs of proxies that forward traffic to your server (optional)
+     * When defined AND useIngressProxy is true, A records with server IP are replaced with proxy IPs
+     * If not defined or empty, all A records use the real server IP
+     * Helps hide real server IP for security/privacy
+     */
+    proxyIps?: string[];
+    /**
+     * Public IP address for nameserver A records (required if proxyIps not set)
+     * This is the IP that will be used for the nameserver domains (dnsNsDomains)
+     * If proxyIps is set, the first proxy IP will be used instead
+     */
+    publicIp?: string;
+    /**
+     * DNS records to register
+     * Must be within the defined dnsScopes (or receive warning)
+     * Only need A, CNAME, TXT, MX records (NS records auto-generated, SOA handled by smartdns)
+     * Can use `useIngressProxy: false` to expose real server IP (defaults to true)
+     */
+    dnsRecords?: Array<{
+        name: string;
+        type: 'A' | 'AAAA' | 'CNAME' | 'MX' | 'TXT' | 'NS' | 'SOA';
+        value: string;
+        ttl?: number;
+        useIngressProxy?: boolean;
+    }>;
+    /** DNS challenge configuration for ACME (optional) */
+    dnsChallenge?: {
+        /** Cloudflare API key for DNS challenges */
+        cloudflareApiKey?: string;
+    };
+    /** Storage configuration */
+    storage?: IStorageConfig;
+    /**
+     * Cache database configuration using smartdata and LocalTsmDb
+     * Provides persistent caching for emails, IP reputation, bounces, etc.
+     */
+    cacheConfig?: {
+        /** Enable cache database (default: true) */
+        enabled?: boolean;
+        /** Storage path for TsmDB data (default: ~/.serve.zone/dcrouter/tsmdb) */
+        storagePath?: string;
+        /** Database name (default: dcrouter) */
+        dbName?: string;
+        /** Default TTL in days for cached items (default: 30) */
+        defaultTTLDays?: number;
+        /** Cleanup interval in hours (default: 1) */
+        cleanupIntervalHours?: number;
+        /** TTL configuration per data type (in days) */
+        ttlConfig?: {
+            /** Email cache TTL (default: 30 days) */
+            emails?: number;
+            /** IP reputation cache TTL (default: 1 day) */
+            ipReputation?: number;
+            /** Bounce records TTL (default: 30 days) */
+            bounces?: number;
+            /** DKIM keys TTL (default: 90 days) */
+            dkimKeys?: number;
+            /** Suppression list TTL (default: 30 days, can be permanent) */
+            suppression?: number;
+        };
+    };
+    /**
+     * RADIUS server configuration for network authentication
+     * Enables MAC Authentication Bypass (MAB) and VLAN assignment
+     */
+    radiusConfig?: IRadiusServerConfig;
+    /**
+     * Remote Ingress configuration for edge tunnel nodes
+     * Enables edge nodes to accept incoming connections and tunnel them to this DcRouter
+     */
+    /**
+     * HTTP/3 (QUIC) configuration for HTTPS routes.
+     * Enabled by default — qualifying HTTPS routes on port 443 are automatically
+     * augmented with QUIC/H3 fields. Set { enabled: false } to disable globally.
+     * Individual routes can opt out via action.options.http3 = false.
+     */
+    http3?: IHttp3Config;
+    /** Port for the OpsServer web UI (default: 3000) */
+    opsServerPort?: number;
+    remoteIngressConfig?: {
+        /** Enable remote ingress hub (default: false) */
+        enabled?: boolean;
+        /** Port for tunnel connections from edge nodes (default: 8443) */
+        tunnelPort?: number;
+        /** External hostname of this hub, embedded in connection tokens */
+        hubDomain?: string;
+        /** TLS configuration for the tunnel server */
+        tls?: {
+            certPath?: string;
+            keyPath?: string;
+        };
+    };
+    /**
+     * VPN server configuration.
+     * Enables VPN-based access control: routes with vpn.required are only
+     * accessible from VPN clients. Supports WireGuard + native (WS/QUIC) transports.
+     */
+    vpnConfig?: {
+        /** Enable VPN server (default: false) */
+        enabled?: boolean;
+        /** VPN subnet CIDR (default: '10.8.0.0/24') */
+        subnet?: string;
+        /** WireGuard UDP listen port (default: 51820) */
+        wgListenPort?: number;
+        /** DNS servers pushed to VPN clients */
+        dns?: string[];
+        /** Server endpoint hostname for client configs (e.g. 'vpn.example.com') */
+        serverEndpoint?: string;
+        /** Override forwarding mode. Default: auto-detect (tun if root, socket otherwise) */
+        forwardingMode?: 'tun' | 'socket';
+        /** Pre-defined VPN clients created on startup */
+        clients?: Array<{
+            clientId: string;
+            serverDefinedClientTags?: string[];
+            description?: string;
+        }>;
+    };
+}
+/**
+ * DcRouter can be run on ingress and egress to and from a datacenter site.
+ */
+/**
+ * Context passed to HTTP routing rules
+ */
+/**
+ * Context passed to port proxy (SmartProxy) routing rules
+ */
+export interface PortProxyRuleContext {
+    proxy: plugins.smartproxy.SmartProxy;
+    routes: plugins.smartproxy.IRouteConfig[];
+}
+export declare class DcRouter {
+    options: IDcRouterOptions;
+    resolvedPaths: ReturnType<typeof paths.resolvePaths>;
+    smartProxy?: plugins.smartproxy.SmartProxy;
+    smartAcme?: plugins.smartacme.SmartAcme;
+    dnsServer?: plugins.smartdns.dnsServerMod.DnsServer;
+    emailServer?: UnifiedEmailServer;
+    radiusServer?: RadiusServer;
+    storageManager: StorageManager;
+    opsServer: OpsServer;
+    metricsManager?: MetricsManager;
+    cacheDb?: CacheDb;
+    cacheCleaner?: CacheCleaner;
+    remoteIngressManager?: RemoteIngressManager;
+    tunnelManager?: TunnelManager;
+    vpnManager?: VpnManager;
+    routeConfigManager?: RouteConfigManager;
+    apiTokenManager?: ApiTokenManager;
+    detectedPublicIp: string | null;
+    private dnsLogWindowSecond;
+    private dnsLogWindowCount;
+    private dnsBatchCount;
+    private dnsBatchTimer;
+    certificateStatusMap: Map<string, {
+        status: "valid" | "failed";
+        routeNames: string[];
+        expiryDate?: string;
+        issuedAt?: string;
+        source?: string;
+        error?: string;
+    }>;
+    certProvisionScheduler?: CertProvisionScheduler;
+    serviceManager: plugins.taskbuffer.ServiceManager;
+    private serviceSubjectSubscription?;
+    smartAcmeReady: boolean;
+    typedrouter: plugins.typedrequest.TypedRouter<import("@api.global/typedrequest-interfaces").ITypedRequest>;
+    private constructorRoutes;
+    private qenv;
+    constructor(optionsArg: IDcRouterOptions);
+    /**
+     * Register all dcrouter services with the ServiceManager.
+     * Services are started in dependency order, with failure isolation for optional services.
+     */
+    private registerServices;
+    start(): Promise<void>;
+    /**
+     * Detect OS-level resource limits and warn if they are too low for production use.
+     * This is detection only — no attempts to raise limits.
+     */
+    private checkSystemLimits;
+    /**
+     * Log comprehensive startup summary
+     */
+    private logStartupSummary;
+    /**
+     * Set up the cache database (smartdata + LocalTsmDb)
+     */
+    private setupCacheDb;
+    /**
+     * Set up SmartProxy with direct configuration and automatic email routes
+     */
+    private setupSmartProxy;
+    /**
+     * Generate SmartProxy routes for email configuration
+     */
+    private generateEmailRoutes;
+    /**
+     * Generate SmartProxy routes for DNS configuration
+     */
+    private generateDnsRoutes;
+    /**
+     * Check if a domain matches a pattern (including wildcard support)
+     * @param domain The domain to check
+     * @param pattern The pattern to match against (e.g., "*.example.com")
+     * @returns Whether the domain matches the pattern
+     */
+    private isDomainMatch;
+    /**
+     * Find ALL route names that match a given domain
+     */
+    findRouteNamesForDomain(domain: string): string[];
+    /**
+     * Get the routes derived from constructor config (smartProxy + email + DNS).
+     * Used by RouteConfigManager as the "hardcoded" base.
+     */
+    getConstructorRoutes(): plugins.smartproxy.IRouteConfig[];
+    stop(): Promise<void>;
+    /**
+     * Update SmartProxy configuration
+     * @param config New SmartProxy configuration
+     */
+    updateSmartProxyConfig(config: plugins.smartproxy.ISmartProxyOptions): Promise<void>;
+    /**
+     * Set up unified email handling with pattern-based routing
+     * This implements the consolidated emailConfig approach
+     */
+    private setupUnifiedEmailHandling;
+    /**
+     * Update the unified email configuration
+     * @param config New email configuration
+     */
+    updateEmailConfig(config: IUnifiedEmailServerOptions): Promise<void>;
+    /**
+     * Stop all unified email components
+     */
+    private stopUnifiedEmailComponents;
+    /**
+     * Update domain rules for email routing
+     * @param rules New domain rules to apply
+     */
+    updateEmailRoutes(routes: IEmailRoute[]): Promise<void>;
+    /**
+     * Get statistics from all components
+     */
+    getStats(): any;
+    /**
+     * Register DNS records with the DNS server
+     * @param records Array of DNS records to register
+     */
+    private registerDnsRecords;
+    /**
+     * Parse DNS record data based on record type
+     * @param type DNS record type
+     * @param value DNS record value
+     * @returns Parsed data for the DNS response
+     */
+    private parseDnsRecordData;
+    /**
+     * Set up DNS server with socket handler for DoH
+     */
+    private setupDnsWithSocketHandler;
+    /**
+     * Create DNS socket handler for DoH
+     */
+    private createDnsSocketHandler;
+    /**
+     * Validate DNS configuration
+     */
+    private validateDnsConfiguration;
+    /**
+     * Generate email DNS records for domains with internal-dns mode
+     */
+    private generateEmailDnsRecords;
+    /**
+     * Load DKIM records from JSON files
+     * Reads all *.dkimrecord.json files from the DNS records directory
+     */
+    private loadDkimRecords;
+    /**
+     * Initialize DKIM keys for all configured email domains
+     * This ensures DKIM records are available immediately at startup
+     */
+    private initializeDkimForEmailDomains;
+    /**
+     * Generate authoritative DNS records (NS only) for all domains in dnsScopes
+     * SOA records are now automatically generated by smartdns with primaryNameserver setting
+     */
+    private generateAuthoritativeRecords;
+    /**
+     * Extract the base domain from a DNS record name
+     */
+    private extractDomain;
+    /**
+     * Apply proxy IP replacement logic to DNS records
+     */
+    private applyProxyIpReplacement;
+    /**
+     * Detect the server's public IP address
+     */
+    private detectServerPublicIp;
+    /**
+     * Set up Remote Ingress hub for edge tunnel connections
+     */
+    private setupRemoteIngress;
+    /**
+     * Set up VPN server for VPN-based route access control.
+     */
+    private setupVpnServer;
+    /**
+     * Inject VPN security into routes that have vpn.required === true.
+     * Adds the VPN subnet to security.ipAllowList so only VPN clients can access them.
+     */
+    private injectVpnSecurity;
+    /**
+     * Set up RADIUS server for network authentication
+     */
+    private setupRadiusServer;
+    /**
+     * Update RADIUS configuration at runtime
+     */
+    updateRadiusConfig(config: IRadiusServerConfig): Promise<void>;
+}
+export type { IUnifiedEmailServerOptions };
+export type { IRadiusServerConfig };
+export default DcRouter;