@serve.zone/dcrouter 13.17.0 → 13.17.3

package/dist_ts/classes.dcrouter.d.ts

@@ -0,0 +1,401 @@
+import * as plugins from './plugins.js';
+import * as paths from './paths.js';
+import { UnifiedEmailServer, type IUnifiedEmailServerOptions, type IEmailRoute } from '@push.rocks/smartmta';
+import { CertProvisionScheduler } from './classes.cert-provision-scheduler.js';
+import { DcRouterDb, CacheCleaner } from './db/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, ReferenceResolver, TargetProfileManager } from './config/index.js';
+import { type IHttp3Config } from './http3/index.js';
+import { DnsManager } from './dns/manager.dns.js';
+import { AcmeConfigManager } from './acme/manager.acme-config.js';
+import { EmailDomainManager } from './email/classes.email-domain.manager.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;
+    }>;
+    /**
+     * Unified database configuration.
+     * All persistent data (config, certs, VPN, cache, etc.) is stored via smartdata.
+     * If mongoDbUrl is provided, connects to external MongoDB.
+     * Otherwise, starts an embedded LocalSmartDb automatically.
+     */
+    dbConfig?: {
+        /** Enable database (default: true). Set to false in tests to skip DB startup. */
+        enabled?: boolean;
+        /** External MongoDB connection URL. If absent, uses embedded LocalSmartDb. */
+        mongoDbUrl?: string;
+        /** Storage path for embedded database data (default: ~/.serve.zone/dcrouter/tsmdb) */
+        storagePath?: string;
+        /** Database name (default: dcrouter) */
+        dbName?: string;
+        /** Cache cleanup interval in hours (default: 1) */
+        cleanupIntervalHours?: number;
+        /** Seed default security profiles and network targets when DB is empty on first startup. */
+        seedOnEmpty?: boolean;
+        /** Custom seed data for profiles and targets (overrides built-in defaults). */
+        seedData?: import('./config/classes.db-seeder.js').ISeedData;
+    };
+    /**
+     * 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 vpnOnly are only
+     * accessible from VPN clients whose TargetProfile matches. 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;
+        /** Pre-defined VPN clients created on startup */
+        clients?: Array<{
+            clientId: string;
+            targetProfileIds?: string[];
+            description?: string;
+        }>;
+        /** Destination routing policy for VPN client traffic.
+         *  Default in socket mode: { default: 'forceTarget', target: '127.0.0.1' } (all traffic → SmartProxy).
+         *  Default in tun mode: not set (all traffic passes through). */
+        destinationPolicy?: {
+            default: 'forceTarget' | 'block' | 'allow';
+            target?: string;
+            allowList?: string[];
+            blockList?: string[];
+        };
+        /** Forwarding mode: 'socket' (default, userspace NAT), 'bridge' (L2 bridge to host LAN),
+         *  or 'hybrid' (socket default, bridge for clients with useHostIp=true) */
+        forwardingMode?: 'socket' | 'bridge' | 'hybrid';
+        /** LAN subnet CIDR for bridge mode (e.g., '192.168.1.0/24') */
+        bridgeLanSubnet?: string;
+        /** Physical network interface for bridge mode (auto-detected if omitted) */
+        bridgePhysicalInterface?: string;
+        /** Start of VPN client IP range in LAN subnet (host offset, default: 200) */
+        bridgeIpRangeStart?: number;
+        /** End of VPN client IP range in LAN subnet (host offset, default: 250) */
+        bridgeIpRangeEnd?: number;
+    };
+}
+/**
+ * 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;
+    opsServer: OpsServer;
+    metricsManager?: MetricsManager;
+    storageManager: any;
+    dcRouterDb?: DcRouterDb;
+    cacheCleaner?: CacheCleaner;
+    remoteIngressManager?: RemoteIngressManager;
+    tunnelManager?: TunnelManager;
+    vpnManager?: VpnManager;
+    routeConfigManager?: RouteConfigManager;
+    apiTokenManager?: ApiTokenManager;
+    referenceResolver?: ReferenceResolver;
+    targetProfileManager?: TargetProfileManager;
+    dnsManager?: DnsManager;
+    acmeConfigManager?: AcmeConfigManager;
+    emailDomainManager?: EmailDomainManager;
+    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 seedConfigRoutes;
+    private seedEmailRoutes;
+    private seedDnsRoutes;
+    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 unified database (smartdata + LocalSmartDb or external MongoDB)
+     */
+    private setupDcRouterDb;
+    /**
+     * 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[];
+    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;
+    /** Cache for DNS-resolved IPs of VPN-gated domains. TTL: 5 minutes. */
+    private vpnDomainIpCache;
+    /**
+     * Resolve a domain's A record(s) for VPN AllowedIPs, with a 5-minute cache.
+     */
+    private resolveVpnDomainIPs;
+    /**
+     * 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;