@serve.zone/dcrouter 13.19.1 → 13.20.2

package/ts/readme.md

@@ -1,8 +1,6 @@
 # @serve.zone/dcrouter
 
-The core DcRouter package — a unified datacenter gateway orchestrator. 🚀
-
-This is the main entry point for DcRouter. It provides the `DcRouter` class that wires together SmartProxy, smartmta, SmartDNS, SmartRadius, RemoteIngress, and the OpsServer dashboard into a single cohesive service.
+The `ts/` directory is the main dcrouter runtime package. It exposes the `DcRouter` orchestrator, `IDcRouterOptions`, `runCli()`, and the server-side exports that matter when you want to boot the full router stack from code.
 
 ## Issue Reporting and Security
 
@@ -14,7 +12,19 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 pnpm add @serve.zone/dcrouter
 ```
 
-## Usage
+## Core Exports
+
+| Export | Purpose |
+| --- | --- |
+| `DcRouter` | Main orchestrator for proxying, DNS, email, VPN, RADIUS, remote ingress, DB, and OpsServer |
+| `IDcRouterOptions` | Top-level configuration shape |
+| `runCli()` | Bootstrap helper; uses OCI env-driven config when `DCROUTER_MODE=OCI_CONTAINER` |
+| `UnifiedEmailServer` and smartmta types | Re-exported email server primitives |
+| `RadiusServer` and related types | RADIUS server runtime exports |
+| `RemoteIngressManager` and `TunnelManager` | Remote ingress orchestration exports |
+| `IHttp3Config` | HTTP/3 configuration for qualifying HTTPS routes |
+
+## Quick Start
 
 ```typescript
 import { DcRouter } from '@serve.zone/dcrouter';
@@ -23,120 +33,53 @@ const router = new DcRouter({
   smartProxyConfig: {
     routes: [
       {
-        name: 'web-app',
-        match: { domains: ['example.com'], ports: [443] },
+        name: 'local-app',
+        match: {
+          domains: ['localhost'],
+          ports: [18080],
+        },
         action: {
           type: 'forward',
-          targets: [{ host: '192.168.1.10', port: 8080 }],
-          tls: { mode: 'terminate', certificate: 'auto' }
-        }
-      }
+          targets: [{ host: '127.0.0.1', port: 3001 }],
+        },
+      },
     ],
-    acme: { email: 'admin@example.com', enabled: true, useProduction: true }
-  }
+  },
+  opsServerPort: 3000,
 });
 
 await router.start();
-// OpsServer dashboard at http://localhost:3000 (configurable via opsServerPort)
-
-// Graceful shutdown
-await router.stop();
-```
-
-## Module Structure
-
-```
-ts/
-├── index.ts                        # Main exports (DcRouter, re-exported smartmta types)
-├── classes.dcrouter.ts             # DcRouter orchestrator class + IDcRouterOptions
-├── classes.cert-provision-scheduler.ts  # Per-domain cert backoff scheduler
-├── classes.storage-cert-manager.ts # SmartAcme cert manager backed by StorageManager
-├── logger.ts                       # Structured logging utility
-├── paths.ts                        # Centralized data directory paths
-├── plugins.ts                      # All dependency imports
-├── cache/                          # Cache database (smartdata + LocalTsmDb)
-│   ├── classes.cachedb.ts          # CacheDb singleton
-│   ├── classes.cachecleaner.ts     # TTL-based cleanup
-│   └── documents/                  # Cached document models
-├── config/                         # Configuration utilities
-├── errors/                         # Error classes and retry logic
-├── http3/                          # HTTP/3 (QUIC) route augmentation
-│   ├── index.ts                    # Barrel export
-│   └── http3-route-augmentation.ts # Pure utility: augmentRoutesWithHttp3(), IHttp3Config
-├── monitoring/                     # MetricsManager (SmartMetrics integration)
-├── opsserver/                      # OpsServer dashboard + API handlers
-│   ├── classes.opsserver.ts        # HTTP server + TypedRouter setup
-│   └── handlers/                   # TypedRequest handlers by domain
-│       ├── admin.handler.ts        # Auth (login/logout/verify)
-│       ├── stats.handler.ts        # Statistics + health
-│       ├── config.handler.ts       # Configuration (read-only)
-│       ├── logs.handler.ts         # Log retrieval
-│       ├── email.handler.ts        # Email operations
-│       ├── certificate.handler.ts  # Certificate management
-│       ├── radius.handler.ts       # RADIUS management
-│       ├── remoteingress.handler.ts # Remote ingress edge + token management
-│       ├── route-management.handler.ts # Programmatic route CRUD
-│       ├── api-token.handler.ts    # API token management
-│       └── security.handler.ts     # Security metrics + connections
-├── radius/                         # RADIUS server integration
-├── remoteingress/                  # Remote ingress hub integration
-│   ├── classes.remoteingress-manager.ts  # Edge CRUD + port derivation
-│   └── classes.tunnel-manager.ts   # Rust hub lifecycle + status tracking
-├── security/                       # Security utilities
-├── sms/                            # SMS integration
-└── storage/                        # StorageManager (filesystem/custom/memory)
-```
-
-## Exports
-
-```typescript
-// Main class
-export { DcRouter, IDcRouterOptions } from './classes.dcrouter.js';
-
-// Re-exported from smartmta
-export { UnifiedEmailServer } from '@push.rocks/smartmta';
-export type { IUnifiedEmailServerOptions, IEmailRoute, IEmailDomainConfig } from '@push.rocks/smartmta';
-
-// RADIUS
-export { RadiusServer, IRadiusServerConfig } from './radius/index.js';
-
-// Remote Ingress
-export { RemoteIngressManager, TunnelManager } from './remoteingress/index.js';
-
-// HTTP/3
-export type { IHttp3Config } from './http3/index.js';
 ```
 
-## Key Classes
-
-### `DcRouter`
-
-The central orchestrator. Accepts `IDcRouterOptions` and manages the lifecycle of all sub-services:
+## What `DcRouter` Manages
 
-| Config Section | Service Started | Package |
-|----------------|----------------|---------|
-| `smartProxyConfig` | SmartProxy (HTTP/HTTPS/TCP/SNI) | `@push.rocks/smartproxy` |
-| `emailConfig` | UnifiedEmailServer (SMTP) | `@push.rocks/smartmta` |
-| `dnsNsDomains` + `dnsScopes` | DnsServer (UDP + DoH) | `@push.rocks/smartdns` |
-| `radiusConfig` | RadiusServer (auth + accounting) | `@push.rocks/smartradius` |
-| `remoteIngressConfig` | RemoteIngressManager + TunnelManager | `@serve.zone/remoteingress` |
-| `tls` + `dnsChallenge` | SmartAcme (ACME cert provisioning) | `@push.rocks/smartacme` |
-| `http3` | HTTP/3 route augmentation (enabled by default) | built-in |
-| `cacheConfig` | CacheDb (embedded MongoDB) | `@push.rocks/smartdata` |
-| *(always)* | OpsServer (dashboard + API) | `@api.global/typedserver` |
-| *(always)* | MetricsManager | `@push.rocks/smartmetrics` |
+- SmartProxy for HTTP/HTTPS/TCP routes
+- `UnifiedEmailServer` for SMTP ingress and delivery when `emailConfig` is present
+- DB-backed managers for routes, API tokens, target profiles, domains, records, ACME config, and email domains when the DB is enabled
+- embedded authoritative DNS and DoH route generation from `dnsNsDomains` and `dnsScopes`
+- VPN, RADIUS, and remote ingress services when their config blocks are enabled
+- OpsServer and the dashboard, which start on every boot
 
-### `RemoteIngressManager`
+## Important Runtime Behavior
 
-Manages CRUD for remote ingress edge registrations. Persists edges via StorageManager. Provides port derivation from routes tagged with `remoteIngress.enabled`.
+- The DB is enabled by default and uses an embedded local database when no external MongoDB URL is provided.
+- System routes from config, email, and DNS are persisted with stable ownership and are toggle-only.
+- API-created routes are the only routes intended for full CRUD from the dashboard or client SDK.
+- Qualifying HTTPS forward routes on port `443` get HTTP/3 augmentation by default.
+- `runCli()` is the supported code-level bootstrap entrypoint; the package does not expose a separate npm `bin` command.
 
-### `TunnelManager`
+## Use Another Module When...
 
-Manages the Rust-based RemoteIngressHub lifecycle. Syncs allowed edges, tracks connection status, and exposes edge statuses (connected, publicIp, activeTunnels, lastHeartbeat).
+| Need | Module |
+| --- | --- |
+| A higher-level client SDK for a running router | `@serve.zone/dcrouter-apiclient` or `@serve.zone/dcrouter/apiclient` |
+| Raw TypedRequest request/data contracts | `@serve.zone/dcrouter-interfaces` or `@serve.zone/dcrouter/interfaces` |
+| The standalone migration runner | `@serve.zone/dcrouter-migrations` |
+| The browser dashboard module boundary | `@serve.zone/dcrouter-web` |
 
 ## License and Legal Information
 
-This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](../license) file.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](../license) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
@@ -148,7 +91,7 @@ Use of these trademarks must comply with Task Venture Capital GmbH's Trademark G
 
 ### Company Information
 
-Task Venture Capital GmbH
+Task Venture Capital GmbH  
 Registered at District Court Bremen HRB 35230 HB, Germany
 
 For any legal inquiries or further information, please contact us via email at hello@task.vc.

package/ts/vpn/classes.vpn-manager.ts

@@ -112,14 +112,11 @@ export class VpnManager {
     const subnet = this.getSubnet();
     const wgListenPort = this.config.wgListenPort ?? 51820;
 
-    // Auto-detect hybrid mode: if any persisted client uses host IP and mode is
-    // 'socket' (or unset), upgrade to 'hybrid' so the daemon can handle both
-    let configuredMode = this.forwardingModeOverride ?? this.config.forwardingMode ?? 'socket';
-    if (anyClientUsesHostIp && configuredMode === 'socket') {
-      configuredMode = 'hybrid';
+    const desiredForwardingMode = this.getDesiredForwardingMode(anyClientUsesHostIp);
+    if (anyClientUsesHostIp && desiredForwardingMode === 'hybrid') {
       logger.log('info', 'VPN: Auto-upgrading forwarding mode to hybrid (client with useHostIp detected)');
     }
-    const forwardingMode = configuredMode === 'hybrid' ? 'hybrid' : configuredMode;
+    const forwardingMode = desiredForwardingMode;
     const isBridge = forwardingMode === 'bridge';
     this.resolvedForwardingMode = forwardingMode;
     this.forwardingModeOverride = undefined;
@@ -218,7 +215,7 @@ export class VpnManager {
       throw new Error('VPN server not running');
     }
 
-    await this.ensureForwardingModeForHostIpClient(opts.useHostIp === true);
+    await this.ensureForwardingModeForNextClient(opts.useHostIp === true);
 
     const doc = new VpnClientDoc();
     doc.clientId = opts.clientId;
@@ -298,6 +295,7 @@ export class VpnManager {
     if (doc) {
       await doc.delete();
     }
+    await this.reconcileForwardingMode();
     this.config.onClientChanged?.();
   }
 
@@ -368,8 +366,10 @@ export class VpnManager {
     await this.persistClient(client);
 
     if (this.vpnServer) {
-      await this.ensureForwardingModeForHostIpClient(client.useHostIp === true);
-      await this.vpnServer.updateClient(clientId, this.buildClientRuntimeUpdate(client));
+      const restarted = await this.reconcileForwardingMode();
+      if (!restarted) {
+        await this.vpnServer.updateClient(clientId, this.buildClientRuntimeUpdate(client));
+      }
     }
 
     this.config.onClientChanged?.();
@@ -563,6 +563,28 @@ export class VpnManager {
       ?? 'socket';
   }
 
+  private hasHostIpClients(extraHostIpClient = false): boolean {
+    if (extraHostIpClient) {
+      return true;
+    }
+
+    for (const client of this.clients.values()) {
+      if (client.useHostIp) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  private getDesiredForwardingMode(hasHostIpClients = this.hasHostIpClients()): 'socket' | 'bridge' | 'hybrid' {
+    const configuredMode = this.forwardingModeOverride ?? this.config.forwardingMode ?? 'socket';
+    if (configuredMode !== 'socket') {
+      return configuredMode;
+    }
+    return hasHostIpClients ? 'hybrid' : 'socket';
+  }
+
   private getDefaultDestinationPolicy(
     forwardingMode: 'socket' | 'bridge' | 'hybrid',
     useHostIp = false,
@@ -633,16 +655,45 @@ export class VpnManager {
     };
   }
 
-  private async ensureForwardingModeForHostIpClient(useHostIp: boolean): Promise<void> {
-    if (!useHostIp || !this.vpnServer) return;
-    if (this.getResolvedForwardingMode() !== 'socket') return;
-
-    logger.log('info', 'VPN: Restarting server in hybrid mode to support a host-IP client');
-    this.forwardingModeOverride = 'hybrid';
+  private async restartWithForwardingMode(
+    forwardingMode: 'socket' | 'bridge' | 'hybrid',
+    reason: string,
+  ): Promise<void> {
+    logger.log('info', `VPN: Restarting server in ${forwardingMode} mode ${reason}`);
+    this.forwardingModeOverride = forwardingMode;
     await this.stop();
     await this.start();
   }
 
+  private async ensureForwardingModeForNextClient(useHostIp: boolean): Promise<void> {
+    if (!this.vpnServer) return;
+
+    const desiredForwardingMode = this.getDesiredForwardingMode(this.hasHostIpClients(useHostIp));
+    if (desiredForwardingMode === this.getResolvedForwardingMode()) {
+      return;
+    }
+
+    await this.restartWithForwardingMode(desiredForwardingMode, 'to support a host-IP client');
+  }
+
+  private async reconcileForwardingMode(): Promise<boolean> {
+    if (!this.vpnServer) {
+      return false;
+    }
+
+    const desiredForwardingMode = this.getDesiredForwardingMode();
+    const currentForwardingMode = this.getResolvedForwardingMode();
+    if (desiredForwardingMode === currentForwardingMode) {
+      return false;
+    }
+
+    const reason = desiredForwardingMode === 'socket'
+      ? 'because no host-IP clients remain'
+      : 'to support host-IP clients';
+    await this.restartWithForwardingMode(desiredForwardingMode, reason);
+    return true;
+  }
+
   private async persistClient(client: VpnClientDoc): Promise<void> {
     await client.save();
   }

package/ts_apiclient/readme.md

@@ -1,8 +1,6 @@
 # @serve.zone/dcrouter-apiclient
 
-Typed, object-oriented API client for operating a running dcrouter instance. 🔧
-
-Use this package when you want a clean TypeScript client instead of manually firing TypedRequest calls. It wraps the OpsServer API in resource managers and resource classes such as routes, certificates, tokens, edges, emails, stats, logs, config, and RADIUS.
+Typed, object-oriented client for operating a running dcrouter instance. It wraps the OpsServer `/typedrequest` API in managers and resource classes so your scripts can work with routes, certificates, tokens, remote ingress edges, emails, stats, config, logs, and RADIUS without hand-rolling requests.
 
 ## Issue Reporting and Security
 
@@ -14,7 +12,7 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 pnpm add @serve.zone/dcrouter-apiclient
 ```
 
-Or import through the main package:
+You can also import the same client through the main package subpath:
 
 ```typescript
 import { DcRouterApiClient } from '@serve.zone/dcrouter/apiclient';
@@ -29,24 +27,40 @@ const client = new DcRouterApiClient({
   baseUrl: 'https://dcrouter.example.com',
 });
 
-await client.login('admin', 'password');
+await client.login('admin', 'admin');
 
-const { routes } = await client.routes.list();
-console.log(routes.map((route) => `${route.origin}:${route.name}`));
+const { routes, warnings } = await client.routes.list();
+console.log('route count', routes.length, 'warnings', warnings.length);
 
-await client.routes.build()
+const route = await client.routes.build()
   .setName('api-gateway')
   .setMatch({ ports: 443, domains: ['api.example.com'] })
   .setAction({ type: 'forward', targets: [{ host: '127.0.0.1', port: 8080 }] })
   .save();
+
+await route.toggle(false);
 ```
 
+## What the Client Gives You
+
+| Manager | Purpose |
+| --- | --- |
+| `client.routes` | List merged routes, create API routes, toggle routes |
+| `client.certificates` | Inspect certificates and run certificate operations |
+| `client.apiTokens` | Create, list, toggle, roll, and revoke API tokens |
+| `client.remoteIngress` | Manage edge registrations, statuses, and connection tokens |
+| `client.emails` | Inspect email items and trigger resend flows |
+| `client.stats` | Health, statistics, and operational summaries |
+| `client.config` | Read the current configuration view |
+| `client.logs` | Read recent logs and log-related data |
+| `client.radius` | Manage RADIUS clients, VLANs, and sessions |
+
 ## Authentication Modes
 
 | Mode | How it works |
 | --- | --- |
-| Admin login | Call `login(username, password)` and the client stores the returned identity for later requests |
-| API token | Pass `apiToken` into the constructor for token-based automation |
+| Admin login | Call `login(username, password)` and the returned identity is stored on the client |
+| API token | Pass `apiToken` in the constructor and it is injected into requests automatically |
 
 ```typescript
 const client = new DcRouterApiClient({
@@ -55,52 +69,19 @@ const client = new DcRouterApiClient({
 });
 ```
 
-## Main Managers
-
-| Manager | Purpose |
-| --- | --- |
-| `client.routes` | List routes and create API-managed routes |
-| `client.certificates` | Inspect and operate on certificate records |
-| `client.apiTokens` | Create, list, toggle, roll, revoke API tokens |
-| `client.remoteIngress` | Manage registered remote ingress edges |
-| `client.stats` | Read operational metrics and health data |
-| `client.config` | Read current configuration view |
-| `client.logs` | Read recent logs or stream them |
-| `client.emails` | List emails and trigger resend flows |
-| `client.radius` | Operate on RADIUS clients, VLANs, sessions, and accounting |
-
-## Route Behavior
-
-Routes are returned as `Route` instances with:
-
-- `id`
-- `name`
-- `enabled`
-- `origin`
-
 Important behavior:
 
-- API routes can be created, updated, deleted, and toggled.
-- System routes can be listed and toggled, but not edited or deleted.
-- A system route is any route whose `origin !== 'api'`.
-
-```typescript
-const { routes } = await client.routes.list();
+- `baseUrl` is normalized, and the client automatically calls `${baseUrl}/typedrequest`
+- `buildRequestPayload()` injects the current identity and optional API token for you
+- system routes can be toggled, but only API routes are meant for edit and delete flows
 
-for (const route of routes) {
-  if (route.origin !== 'api') {
-    await route.toggle(false);
-  }
-}
-```
-
-## Builder Example
+## Route Builder Example
 
 ```typescript
-const route = await client.routes.build()
+const newRoute = await client.routes.build()
   .setName('internal-app')
   .setMatch({
-    ports: 80,
+    ports: 443,
     domains: ['internal.example.com'],
   })
   .setAction({
@@ -110,30 +91,47 @@ const route = await client.routes.build()
   .setEnabled(true)
   .save();
 
-await route.toggle(false);
+await newRoute.update({
+  action: {
+    type: 'forward',
+    targets: [{ host: '127.0.0.1', port: 3001 }],
+  },
+});
 ```
 
-## Example: Certificates and Stats
+## Token and Remote Ingress Example
 
 ```typescript
-const { certificates, summary } = await client.certificates.list();
-console.log(summary.valid, summary.failed);
+const token = await client.apiTokens.build()
+  .setName('ci-token')
+  .setScopes(['routes:read', 'routes:write'])
+  .setExpiresInDays(30)
+  .save();
+
+console.log('copy this once:', token.tokenValue);
+
+const edge = await client.remoteIngress.build()
+  .setName('edge-eu-1')
+  .setListenPorts([80, 443])
+  .setAutoDerivePorts(true)
+  .setTags(['production', 'eu'])
+  .save();
 
-const health = await client.stats.getHealth();
-const recentLogs = await client.logs.getRecent({ level: 'error', limit: 20 });
+const connectionToken = await edge.getConnectionToken();
+console.log(connectionToken);
 ```
 
 ## What This Package Does Not Do
 
 - It does not start dcrouter.
-- It does not embed the dashboard.
-- It does not replace the request interfaces package if you only need raw types.
+- It does not bundle the dashboard.
+- It does not replace the raw interfaces package when you want low-level TypedRequest contracts.
 
-Use `@serve.zone/dcrouter` to run the server, `@serve.zone/dcrouter-web` for the dashboard bundle/components, and `@serve.zone/dcrouter-interfaces` for raw API contracts.
+Use `@serve.zone/dcrouter` to run the server and `@serve.zone/dcrouter-interfaces` for the shared request/data types.
 
 ## License and Legal Information
 
-This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](../license) file.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](../license) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 

package/ts_web/00_commitinfo_data.ts

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