v13.20.2

changelog.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 2026-04-17 - 13.20.2 - fix(vpn)
+handle VPN forwarding mode downgrades and support runtime VPN config updates
+
+- restart the VPN server back to socket mode when host-IP clients are removed while preserving explicit hybrid mode
+- allow DcRouter to update VPN configuration at runtime and refresh route allow-list resolution without recreating the router
+- improve VPN operations UI target profile rendering and loading behavior for create and edit flows
+
+## 2026-04-17 - 13.20.1 - fix(docs)
+refresh package readmes with clearer runtime, API client, interfaces, migrations, and dashboard guidance
+
+- Reworks the main README with updated positioning, quick-start examples, route ownership guidance, configuration notes, automation examples, and OCI bootstrap details
+- Expands package-specific readmes for the runtime, API client, interfaces, migrations, and web dashboard to better describe exports, behavior, and usage
+- Standardizes documentation references such as subpath import guidance and LICENSE link casing across readmes
+
 ## 2026-04-17 - 13.20.0 - feat(routes)
 add remote ingress controls and preserve-port targeting for route configuration
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@serve.zone/dcrouter",
   "private": false,
-  "version": "13.20.0",
+  "version": "13.20.2",
   "description": "A multifaceted routing service handling mail and SMS delivery functions.",
   "type": "module",
   "exports": {

readme.md

@@ -2,33 +2,31 @@
 
 ![dcrouter banner](https://code.foss.global/serve.zone/docs/raw/branch/main/dcrouter.png)
 
-`dcrouter` is a TypeScript control plane for running a serious multi-protocol edge or datacenter gateway from one process. It orchestrates HTTP/HTTPS and TCP routing through SmartProxy, email through smartmta, authoritative DNS and DNS-over-HTTPS, RADIUS, remote ingress tunnels, VPN access control, a typed Ops API, and a web dashboard.
+`dcrouter` is a TypeScript control plane for running a serious multi-protocol edge or datacenter gateway from one process. It wires together SmartProxy for HTTP/HTTPS/TCP routing, smartmta for email, smartdns for authoritative DNS and DNS-over-HTTPS, smartradius, smartvpn, remote ingress tunnels, a TypedRequest API, and the Ops dashboard.
 
-It is built for operators who want one place to define routes, expose services, manage certificates, register domains and DNS providers, control VPN-only access, and inspect what is going on in production.
+Use it when you want one place to define routes, manage domains and certificates, protect internal services, automate changes over an API, and operate the whole stack from a browser.
 
 ## Issue Reporting and Security
 
 For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
 
-## Why dcrouter
+## Why It Works
 
-- 🌐 Run HTTP/HTTPS, TCP/SNI, email, DNS, RADIUS, VPN, and remote ingress from one orchestrated service.
+- 🌐 One runtime for HTTP/HTTPS/TCP, SMTP, authoritative DNS + DoH, RADIUS, VPN, and remote ingress.
-- 🔐 Keep certificates, routes, tokens, domains, and reusable route references in one management plane.
+- 🧠 Constructor config becomes system-managed routes, while API-created routes stay editable and clearly separated.
-- 🧠 Use system-managed routes for config-, email-, and DNS-derived traffic, plus API-managed routes for dynamic additions.
+- 🔐 Certificates, DNS providers, domains, records, API tokens, access profiles, and protected routes live in one management plane.
-- 📊 Get an Ops UI and TypedRequest API for monitoring, automation, and day-2 operations.
+- 🖥️ The OpsServer UI and TypedRequest API are first-class parts of the package, not an afterthought.
-- ⚡ Lean on Rust-backed data planes where it matters: proxying, DNS, email delivery, remote ingress, and VPN.
+- ⚡ Qualifying HTTPS forward routes on port `443` get HTTP/3 augmentation by default unless you opt out.
 
-## What It Covers
+## What You Get
 
 | Area | What dcrouter does |
 | --- | --- |
-| HTTP / HTTPS / TCP | SmartProxy-based routing, TLS termination or passthrough, path/domain matching, optional HTTP/3 augmentation |
+| HTTP / HTTPS / TCP | SmartProxy-based reverse proxying, TLS termination or passthrough, path/domain/port matching, TCP/SNI forwarding |
-| Email | smartmta-based SMTP ingress and delivery, route-based email handling, DKIM-aware domain support |
+| Email | SMTP ingress and delivery via `UnifiedEmailServer`, route-based mail actions, email-domain management, queue and resend operations |
-| DNS | Authoritative DNS, DNS-over-HTTPS bootstrap routes, provider-backed and dcrouter-hosted domains and records |
+| DNS | Authoritative zones, nameserver bootstrap records, DNS-over-HTTPS routes on `/dns-query` and `/resolve`, provider-backed domain management |
-| Certificates | ACME-aware certificate management with dashboard and API support |
+| Access and Edge | VPN-gated routes, RADIUS auth/accounting, remote ingress edge registrations and tunnel hub support |
-| Access control | Source profiles, network targets, VPN-gated routes, API tokens, admin auth |
+| Operations | Browser dashboard, TypedRequest API, route management, tokens, certificates, logs, metrics, and health views |
-| Network edge | Remote ingress hub for edge nodes tunneling traffic into the router |
-| Operations | Web dashboard, TypedRequest API, logs, metrics, health, route and token management |
 
 ## Installation
 
@@ -38,7 +36,7 @@ pnpm add @serve.zone/dcrouter
 
 ## Quick Start
 
-This is the smallest realistic setup: one HTTP route, embedded database enabled, and the Ops dashboard on port `3000`.
+This example stays on unprivileged ports so you can run it locally without root.
 
 ```typescript
 import { DcRouter } from '@serve.zone/dcrouter';
@@ -47,10 +45,10 @@ const router = new DcRouter({
   smartProxyConfig: {
     routes: [
       {
-        name: 'app',
+        name: 'local-app',
         match: {
-          domains: ['app.example.com'],
+          domains: ['localhost'],
-          ports: [80],
+          ports: [18080],
         },
         action: {
           type: 'forward',
@@ -68,114 +66,61 @@ const router = new DcRouter({
 await router.start();
 ```
 
-Once the router is running, you can:
+After startup:
 
-- open the Ops dashboard on `http://localhost:3000`
+- open the dashboard at `http://localhost:3000`
-- inspect the route in the System Routes view
+- log in with the current built-in credentials `admin` / `admin`
-- add API-managed routes through the dashboard or API client
+- send proxied traffic to `http://localhost:18080`
-- enable DNS, email, VPN, remote ingress, or RADIUS by adding the corresponding config blocks
+- stop gracefully with `await router.stop()`
 
-## Mental Model
+## Route Ownership Model
 
-`dcrouter` is not a toy reverse proxy with a few side features. It is an orchestrator that wires multiple specialized services into one management plane.
+dcrouter keeps route ownership explicit so automation does not accidentally stomp on system-generated traffic.
 
-| Layer | Responsibility |
+| Route origin | Where it comes from | What you can do |
-| --- | --- |
+| --- | --- | --- |
-| `DcRouter` | Startup order, shutdown, service wiring, configuration assembly, route hydration |
+| `config` | Constructor `smartProxyConfig.routes` and related seed config | View and toggle |
-| SmartProxy | HTTP/HTTPS, TCP/SNI, TLS, HTTP/3-capable route execution |
+| `email` | Email listener and mail-routing derived routes | View and toggle |
-| smartmta | SMTP ingress, queueing, DKIM-aware email processing and delivery |
+| `dns` | Generated DoH and DNS-related routes | View and toggle |
-| SmartDNS | Authoritative DNS and DoH request handling |
+| `api` | Created through the Ops UI or API client | Full CRUD |
-| smartradius | Network authentication, VLAN assignment, accounting |
-| remoteingress | Edge tunnel registrations and runtime forwarding into the hub |
-| smartvpn | VPN server and client access mediation for protected routes |
-| OpsServer + dashboard | Typed API and browser UI for operations |
-| smartdata-backed DB | Persistent routes, tokens, domains, records, profiles, cert metadata, caches |
-
-## Route Model
-
-Routes fall into two ownership classes:
-
-| Route kind | Origin | Ownership | What users can do |
-| --- | --- | --- | --- |
-| System routes | `config`, `email`, `dns` | Derived from config or runtime-managed subsystems | View and toggle only |
-| API routes | `api` | Created through route-management API | Create, edit, delete, toggle |
 
 Important details:
 
-- system routes are persisted with a stable `systemKey`
+- system routes are persisted with stable `systemKey` values
-- config-, email-, and DNS-derived routes show up in the System Routes view
+- DNS-over-HTTPS routes are persisted and then hydrated with live socket handlers at runtime
-- DoH routes are persisted as system-route templates and get their live socket handlers attached at apply time
+- editing and deletion are reserved for `api` routes; system routes are toggle-only by design
-- system routes are managed by the system, not edited directly by operators
 
-## Core Features
+## Configuration Cheat Sheet
 
-### Traffic Routing
+The main entrypoint is `IDcRouterOptions`.
-
-- Domain-, port-, and path-based SmartProxy routes
-- HTTP/HTTPS reverse proxying and generic TCP/SNI forwarding
-- Optional HTTP/3 augmentation for qualifying HTTPS routes
-- Reusable source profiles and network targets for route composition
-- Remote ingress aware routing for edge-delivered traffic
-
-### Email
-
-- smartmta-based inbound email handling
-- Route-based mail actions such as forward, process, deliver, reject
-- DKIM-aware domain handling and DNS record generation support
-- Email-domain management through the Ops API and UI
-- Queue, resend, failure, and delivery inspection through the dashboard and API
-
-### DNS
-
-- Authoritative scopes via `dnsScopes`
-- Bootstrap nameserver domains via `dnsNsDomains`
-- DNS-over-HTTPS endpoints for `/dns-query` and `/resolve`
-- Managed domains, managed records, and provider-backed DNS integrations
-- Internal email DNS record generation for `internal-dns` email domains
-
-### Certificates and ACME
-
-- Certificate overview and operations through OpsServer
-- Import, export, delete, and reprovision flows
-- DB-backed ACME configuration management
-- Integration with managed DNS for certificate provisioning flows
-- Routes can declare `certificate: 'auto'`, but actual automated issuance depends on ACME being configured in the management plane
-
-### VPN, RADIUS, and Remote Ingress
-
-- VPN-gated routes with target-profile-based access matching
-- WireGuard-oriented VPN management with dcrouter-side client lifecycle support
-- RADIUS MAB, VLAN assignment, and accounting
-- Remote ingress hub for edge nodes tunneling traffic into central routes
-
-### Operations Plane
-
-- Web dashboard with overview, network, routes, access, security, domains, certificates, logs, and email views
-- TypedRequest API for automation and external control
-- API tokens with scoped access
-- Metrics, health, logs, and per-feature operational views
-
-## Configuration Overview
-
-The main entry point is `IDcRouterOptions`.
 
 | Option | Purpose |
 | --- | --- |
-| `smartProxyConfig` | Main HTTP/HTTPS and TCP/SNI routing configuration |
+| `smartProxyConfig` | Main HTTP/HTTPS and TCP/SNI routing config |
-| `emailConfig` | smartmta server config and email routes |
+| `emailConfig` | Email hostname, ports, domains, and mail routing rules |
-| `emailPortConfig` | External-to-internal email port mapping and email storage path tuning |
+| `emailPortConfig` | External-to-internal email port remapping and received-email storage path |
-| `dnsNsDomains` | Nameserver hostnames used for NS bootstrap and DoH routes |
+| `tls` | ACME contact and static certificate paths |
-| `dnsScopes` | Authoritative DNS zones managed by dcrouter |
+| `dnsNsDomains` | Nameserver hostnames used for NS bootstrap and DoH route generation |
-| `dnsRecords` | Static constructor-defined records |
+| `dnsScopes` | Domains served authoritatively by the embedded DNS server |
-| `publicIp` / `proxyIps` | DNS A-record exposure strategy |
+| `dnsRecords` | Static constructor-defined DNS records |
-| `dbConfig` | Embedded or external Mongo-backed persistence and seeding |
+| `publicIp` / `proxyIps` | How A records are exposed for nameserver and service records |
-| `radiusConfig` | RADIUS authentication, VLAN, and accounting setup |
+| `dbConfig` | Embedded LocalSmartDb or external MongoDB-backed persistence |
-| `remoteIngressConfig` | Edge tunnel hub setup |
+| `radiusConfig` | RADIUS auth, VLAN assignment, and accounting |
-| `vpnConfig` | VPN server and client access configuration |
+| `remoteIngressConfig` | Remote ingress hub and edge tunnel setup |
-| `http3` | Global HTTP/3 behavior for qualifying routes |
+| `vpnConfig` | VPN server and client definitions for protected route access |
-| `opsServerPort` | Dashboard and TypedRequest API port |
+| `http3` | Global HTTP/3 behavior for qualifying HTTPS routes |
+| `opsServerPort` | Ops dashboard and TypedRequest API port |
 
-## Example: Enabling DNS, Email, and VPN
+## Important Behavior
+
+- `dbConfig.enabled` defaults to `true`. If you do not provide `mongoDbUrl`, dcrouter starts an embedded local database automatically.
+- If you disable the DB, constructor-driven traffic can still run, but DB-backed features such as persistent routes, tokens, ACME config, and managed domains do not start.
+- Qualifying HTTPS forward routes on port `443` get HTTP/3 by default unless `http3.enabled === false` or the route opts out.
+- DNS-over-HTTPS endpoints are generated on the first entry of `dnsNsDomains` at `/dns-query` and `/resolve`.
+- Email listener ports are internally remapped by default, so common external ports such as `25`, `587`, and `465` end up on internal ports like `10025`, `10587`, and `10465`.
+- Provider-backed domains can be managed in the Ops plane without being served by the embedded authoritative DNS server.
+
+## Bigger Example
 
 ```typescript
 import { DcRouter } from '@serve.zone/dcrouter';
@@ -195,6 +140,19 @@ const router = new DcRouter({
           tls: { mode: 'terminate', certificate: 'auto' },
         },
       },
+      {
+        name: 'internal-admin',
+        match: {
+          domains: ['internal.example.com'],
+          ports: [443],
+        },
+        action: {
+          type: 'forward',
+          targets: [{ host: '127.0.0.1', port: 9090 }],
+          tls: { mode: 'terminate', certificate: 'auto' },
+        },
+        vpnOnly: true,
+      },
     ],
   },
   emailConfig: {
@@ -233,93 +191,103 @@ const router = new DcRouter({
   dbConfig: {
     enabled: true,
   },
+  opsServerPort: 3000,
 });
 
 await router.start();
 ```
 
-## Operations API and Dashboard
+## Automation
 
-With the database enabled, dcrouter exposes a management plane for:
+dcrouter gives you three good integration layers:
 
-- routes and route toggles
+- the browser dashboard served by `OpsServer`
-- API tokens
+- raw TypedRequest contracts via `@serve.zone/dcrouter/interfaces`
-- source profiles and network targets
+- a higher-level OO API client via `@serve.zone/dcrouter/apiclient` or `@serve.zone/dcrouter-apiclient`
-- DNS providers, domains, and records
-- ACME configuration and certificate lifecycle
-- email domains and email operations
-- VPN clients, remote ingress edges, and RADIUS data
 
-The browser dashboard is built from the `ts_web` package and is served by OpsServer. The same backend is accessible programmatically via TypedRequest or the dedicated API client package.
+### OO API Client Example
-
-## Programmatic API Client
-
-Use the API client when you want automation or integration code instead of clicking through the dashboard.
 
 ```bash
 pnpm add @serve.zone/dcrouter-apiclient
 ```
 
 ```typescript
-import { DcRouterApiClient } from '@serve.zone/dcrouter/apiclient';
+import { DcRouterApiClient } from '@serve.zone/dcrouter-apiclient';
 
 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();
-const systemRoutes = routes.filter((route) => route.origin !== 'api');
-
-if (systemRoutes[0]) {
-  await systemRoutes[0].toggle(false);
-}
 
 await client.routes.build()
   .setName('api-gateway')
   .setMatch({ ports: 443, domains: ['api.example.com'] })
   .setAction({ type: 'forward', targets: [{ host: '127.0.0.1', port: 8081 }] })
   .save();
+
+if (routes[0] && routes[0].origin !== 'api') {
+  await routes[0].toggle(false);
+}
 ```
 
-See `./ts_apiclient/readme.md` for the dedicated API-client package docs.
+See `./ts_apiclient/readme.md` for the dedicated client package and `./ts_interfaces/readme.md` for the raw contracts.
+
+## OCI / Container Bootstrap
+
+The package also includes an environment-driven bootstrap used by `runCli()` when `DCROUTER_MODE=OCI_CONTAINER`.
+
+```typescript
+import { runCli } from '@serve.zone/dcrouter';
+
+await runCli();
+```
+
+Useful environment variables include:
+
+- `DCROUTER_CONFIG_PATH`
+- `DCROUTER_BASE_DIR`
+- `DCROUTER_TLS_EMAIL`
+- `DCROUTER_TLS_DOMAIN`
+- `DCROUTER_PUBLIC_IP`
+- `DCROUTER_PROXY_IPS`
+- `DCROUTER_DNS_NS_DOMAINS`
+- `DCROUTER_DNS_SCOPES`
+- `DCROUTER_EMAIL_HOSTNAME`
+- `DCROUTER_EMAIL_PORTS`
 
 ## Published Modules
 
-This repository publishes multiple modules from the same codebase.
+This repository ships several module boundaries from one codebase.
 
 | Module | Purpose | Docs |
 | --- | --- | --- |
-| `@serve.zone/dcrouter` | Main orchestrator and server package | `./readme.md` |
+| `@serve.zone/dcrouter` | Main runtime and orchestrator | `./readme.md` |
-| `@serve.zone/dcrouter-interfaces` | Shared TypedRequest request and data interfaces | `./ts_interfaces/readme.md` |
+| `@serve.zone/dcrouter/interfaces` | Shared request and data contracts as a subpath export | `./ts_interfaces/readme.md` |
-| `@serve.zone/dcrouter-migrations` | Startup migration runner for dcrouter data | `./ts_migrations/readme.md` |
+| `@serve.zone/dcrouter/apiclient` | OO API client as a subpath export | `./ts_apiclient/readme.md` |
-| `@serve.zone/dcrouter-web` | Web dashboard entry and UI components | `./ts_web/readme.md` |
+| `@serve.zone/dcrouter-interfaces` | Standalone interfaces package | `./ts_interfaces/readme.md` |
-| `@serve.zone/dcrouter-apiclient` | Typed OO API client | `./ts_apiclient/readme.md` |
+| `@serve.zone/dcrouter-apiclient` | Standalone OO API client package | `./ts_apiclient/readme.md` |
+| `@serve.zone/dcrouter-migrations` | Standalone migration runner package | `./ts_migrations/readme.md` |
+| `@serve.zone/dcrouter-web` | Standalone web dashboard package boundary | `./ts_web/readme.md` |
 
-## Development and Testing
+## Development
 
 ```bash
 pnpm run build
 pnpm test
 ```
 
-Target a single test file while working on one area:
+Target a single test while working on one area:
 
 ```bash
-tstest test/test.dns-runtime-routes.node.ts --verbose
+tstest test/test.apiclient.ts --verbose
 ```
 
-## Notes for Operators
-
-- Database-backed management features depend on `dbConfig.enabled !== false`.
-- If you disable the DB, constructor-configured services still run, but persistent management features are limited.
-- Nameserver domains are still required for DNS bootstrap and DoH route generation.
-- HTTP/3 is enabled by default for qualifying HTTPS routes unless disabled globally or per route.
-
 ## 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.
 

test/test.vpn-runtime.node.ts

@@ -0,0 +1,110 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import { DcRouter } from '../ts/classes.dcrouter.js';
+import { VpnManager } from '../ts/vpn/classes.vpn-manager.js';
+
+tap.test('VpnManager downgrades back to socket mode when no host-IP clients remain', async () => {
+  const manager = new VpnManager({ forwardingMode: 'socket' });
+
+  let stopCalls = 0;
+  let startCalls = 0;
+
+  (manager as any).vpnServer = { running: true };
+  (manager as any).resolvedForwardingMode = 'hybrid';
+  (manager as any).clients = new Map([
+    ['client-1', { useHostIp: false }],
+  ]);
+  (manager as any).stop = async () => {
+    stopCalls++;
+  };
+  (manager as any).start = async () => {
+    startCalls++;
+    (manager as any).resolvedForwardingMode = (manager as any).forwardingModeOverride ?? 'socket';
+    (manager as any).forwardingModeOverride = undefined;
+    (manager as any).vpnServer = { running: true };
+  };
+
+  const restarted = await (manager as any).reconcileForwardingMode();
+
+  expect(restarted).toEqual(true);
+  expect(stopCalls).toEqual(1);
+  expect(startCalls).toEqual(1);
+  expect((manager as any).resolvedForwardingMode).toEqual('socket');
+});
+
+tap.test('VpnManager keeps explicit hybrid mode even without host-IP clients', async () => {
+  const manager = new VpnManager({ forwardingMode: 'hybrid' });
+
+  let stopCalls = 0;
+  let startCalls = 0;
+
+  (manager as any).vpnServer = { running: true };
+  (manager as any).resolvedForwardingMode = 'hybrid';
+  (manager as any).clients = new Map([
+    ['client-1', { useHostIp: false }],
+  ]);
+  (manager as any).stop = async () => {
+    stopCalls++;
+  };
+  (manager as any).start = async () => {
+    startCalls++;
+  };
+
+  const restarted = await (manager as any).reconcileForwardingMode();
+
+  expect(restarted).toEqual(false);
+  expect(stopCalls).toEqual(0);
+  expect(startCalls).toEqual(0);
+  expect((manager as any).resolvedForwardingMode).toEqual('hybrid');
+});
+
+tap.test('DcRouter.updateVpnConfig swaps the runtime VPN resolver and restarts VPN services', async () => {
+  const dcRouter = new DcRouter({
+    smartProxyConfig: { routes: [] },
+    dbConfig: { enabled: false },
+    vpnConfig: { enabled: false },
+  });
+
+  let stopCalls = 0;
+  let setupCalls = 0;
+  let applyCalls = 0;
+  const resolverValues: Array<unknown> = [];
+
+  dcRouter.vpnManager = {
+    stop: async () => {
+      stopCalls++;
+    },
+  } as any;
+  (dcRouter as any).routeConfigManager = {
+    setVpnClientIpsResolver: (resolver: unknown) => {
+      resolverValues.push(resolver);
+    },
+    applyRoutes: async () => {
+      applyCalls++;
+    },
+  };
+  (dcRouter as any).setupVpnServer = async () => {
+    setupCalls++;
+    dcRouter.vpnManager = {
+      stop: async () => {
+        stopCalls++;
+      },
+    } as any;
+  };
+
+  await dcRouter.updateVpnConfig({ enabled: true, subnet: '10.9.0.0/24' });
+
+  expect(stopCalls).toEqual(1);
+  expect(setupCalls).toEqual(1);
+  expect(applyCalls).toEqual(0);
+  expect(typeof resolverValues.at(-1)).toEqual('function');
+
+  await dcRouter.updateVpnConfig({ enabled: false });
+
+  expect(stopCalls).toEqual(2);
+  expect(setupCalls).toEqual(1);
+  expect(applyCalls).toEqual(1);
+  expect(resolverValues.at(-1)).toBeUndefined();
+  expect(dcRouter.vpnManager).toBeUndefined();
+});
+
+export default tap.start()

ts/00_commitinfo_data.ts

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

ts/classes.dcrouter.ts

@@ -26,6 +26,7 @@ import { RadiusServer, type IRadiusServerConfig } from './radius/index.js';
 import { RemoteIngressManager, TunnelManager } from './remoteingress/index.js';
 import { VpnManager, type IVpnManagerConfig } from './vpn/index.js';
 import { RouteConfigManager, ApiTokenManager, ReferenceResolver, DbSeeder, TargetProfileManager } from './config/index.js';
+import type { TIpAllowEntry } from './config/classes.route-config-manager.js';
 import { SecurityLogger, ContentScanner, IPReputationChecker } from './security/index.js';
 import { type IHttp3Config, augmentRoutesWithHttp3 } from './http3/index.js';
 import { DnsManager } from './dns/manager.dns.js';
@@ -565,20 +566,7 @@ export class DcRouter {
             this.routeConfigManager = new RouteConfigManager(
               () => this.smartProxy,
               () => this.options.http3,
-              this.options.vpnConfig?.enabled
+              this.createVpnRouteAllowListResolver(),
-                ? (route: import('../ts_interfaces/data/remoteingress.js').IDcRouterRouteConfig, routeId?: string) => {
-                    if (!this.vpnManager || !this.targetProfileManager) {
-                      // VPN not ready yet — deny all until re-apply after VPN starts
-                      return [];
-                    }
-                    return this.targetProfileManager.getMatchingClientIps(
-                      route,
-                      routeId,
-                      this.vpnManager.listClients(),
-                      this.routeConfigManager?.getRoutes() || new Map(),
-                    );
-                  }
-                : undefined,
               this.referenceResolver,
               // Sync routes to RemoteIngressManager whenever routes change,
               // then push updated derived ports to the Rust hub binary
@@ -2292,6 +2280,32 @@ export class DcRouter {
   /**
    * Set up VPN server for VPN-based route access control.
    */
+  private createVpnRouteAllowListResolver(): ((
+    route: import('../ts_interfaces/data/remoteingress.js').IDcRouterRouteConfig,
+    routeId?: string,
+  ) => TIpAllowEntry[]) | undefined {
+    if (!this.options.vpnConfig?.enabled) {
+      return undefined;
+    }
+
+    return (
+      route: import('../ts_interfaces/data/remoteingress.js').IDcRouterRouteConfig,
+      routeId?: string,
+    ) => {
+      if (!this.vpnManager || !this.targetProfileManager) {
+        // VPN not ready yet — deny all until re-apply after VPN starts.
+        return [];
+      }
+
+      return this.targetProfileManager.getMatchingClientIps(
+        route,
+        routeId,
+        this.vpnManager.listClients(),
+        this.routeConfigManager?.getRoutes() || new Map(),
+      );
+    };
+  }
+
   private async setupVpnServer(): Promise<void> {
     if (!this.options.vpnConfig?.enabled) {
       return;
@@ -2441,6 +2455,29 @@ export class DcRouter {
 
     logger.log('info', 'RADIUS configuration updated');
   }
+
+  /**
+   * Update VPN configuration at runtime.
+   */
+  public async updateVpnConfig(config: IDcRouterOptions['vpnConfig']): Promise<void> {
+    if (this.vpnManager) {
+      await this.vpnManager.stop();
+      this.vpnManager = undefined;
+    }
+
+    this.options.vpnConfig = config;
+    this.vpnDomainIpCache.clear();
+    this.warnedWildcardVpnDomains.clear();
+    this.routeConfigManager?.setVpnClientIpsResolver(this.createVpnRouteAllowListResolver());
+
+    if (this.options.vpnConfig?.enabled) {
+      await this.setupVpnServer();
+    } else {
+      await this.routeConfigManager?.applyRoutes();
+    }
+
+    logger.log('info', 'VPN configuration updated');
+  }
 }
 
 // Re-export email server types for convenience

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

@@ -73,6 +73,12 @@ export class RouteConfigManager {
     return this.routes.get(id);
   }
 
+  public setVpnClientIpsResolver(
+    resolver?: (route: IDcRouterRouteConfig, routeId?: string) => TIpAllowEntry[],
+  ): void {
+    this.getVpnClientIpsForRoute = resolver;
+  }
+
   /**
    * Load persisted routes, seed serializable config/email/dns routes,
    * compute warnings, and apply the combined DB-backed + runtime route set to SmartProxy.

ts/readme.md

@@ -1,8 +1,6 @@
 # @serve.zone/dcrouter
 
-The core DcRouter package — a unified datacenter gateway orchestrator. 🚀
+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.
-
-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.
 
 ## 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',
+        name: 'local-app',
-        match: { domains: ['example.com'], ports: [443] },
+        match: {
+          domains: ['localhost'],
+          ports: [18080],
+        },
         action: {
           type: 'forward',
-          targets: [{ host: '192.168.1.10', port: 8080 }],
+          targets: [{ host: '127.0.0.1', port: 3001 }],
-          tls: { mode: 'terminate', certificate: 'auto' }
+        },
-        }
+      },
-      }
     ],
-    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
+## What `DcRouter` Manages
 
-```
+- SmartProxy for HTTP/HTTPS/TCP routes
-ts/
+- `UnifiedEmailServer` for SMTP ingress and delivery when `emailConfig` is present
-├── index.ts                        # Main exports (DcRouter, re-exported smartmta types)
+- DB-backed managers for routes, API tokens, target profiles, domains, records, ACME config, and email domains when the DB is enabled
-├── classes.dcrouter.ts             # DcRouter orchestrator class + IDcRouterOptions
+- embedded authoritative DNS and DoH route generation from `dnsNsDomains` and `dnsScopes`
-├── classes.cert-provision-scheduler.ts  # Per-domain cert backoff scheduler
+- VPN, RADIUS, and remote ingress services when their config blocks are enabled
-├── classes.storage-cert-manager.ts # SmartAcme cert manager backed by StorageManager
+- OpsServer and the dashboard, which start on every boot
-├── 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
+## Important Runtime Behavior
 
-```typescript
+- The DB is enabled by default and uses an embedded local database when no external MongoDB URL is provided.
-// Main class
+- System routes from config, email, and DNS are persisted with stable ownership and are toggle-only.
-export { DcRouter, IDcRouterOptions } from './classes.dcrouter.js';
+- 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.
 
-// Re-exported from smartmta
+## Use Another Module When...
-export { UnifiedEmailServer } from '@push.rocks/smartmta';
-export type { IUnifiedEmailServerOptions, IEmailRoute, IEmailDomainConfig } from '@push.rocks/smartmta';
 
-// RADIUS
+| Need | Module |
-export { RadiusServer, IRadiusServerConfig } from './radius/index.js';
+| --- | --- |
-
+| A higher-level client SDK for a running router | `@serve.zone/dcrouter-apiclient` or `@serve.zone/dcrouter/apiclient` |
-// Remote Ingress
+| Raw TypedRequest request/data contracts | `@serve.zone/dcrouter-interfaces` or `@serve.zone/dcrouter/interfaces` |
-export { RemoteIngressManager, TunnelManager } from './remoteingress/index.js';
+| The standalone migration runner | `@serve.zone/dcrouter-migrations` |
-
+| The browser dashboard module boundary | `@serve.zone/dcrouter-web` |
-// 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:
-
-| 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` |
-
-### `RemoteIngressManager`
-
-Manages CRUD for remote ingress edge registrations. Persists edges via StorageManager. Provides port derivation from routes tagged with `remoteIngress.enabled`.
-
-### `TunnelManager`
-
-Manages the Rust-based RemoteIngressHub lifecycle. Syncs allowed edges, tracks connection status, and exposes edge statuses (connected, publicIp, activeTunnels, lastHeartbeat).
 
 ## 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.

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
+    const desiredForwardingMode = this.getDesiredForwardingMode(anyClientUsesHostIp);
-    // 'socket' (or unset), upgrade to 'hybrid' so the daemon can handle both
+    if (anyClientUsesHostIp && desiredForwardingMode === 'hybrid') {
-    let configuredMode = this.forwardingModeOverride ?? this.config.forwardingMode ?? 'socket';
-    if (anyClientUsesHostIp && configuredMode === 'socket') {
-      configuredMode = '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);
+      const restarted = await this.reconcileForwardingMode();
-      await this.vpnServer.updateClient(clientId, this.buildClientRuntimeUpdate(client));
+      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> {
+  private async restartWithForwardingMode(
-    if (!useHostIp || !this.vpnServer) return;
+    forwardingMode: 'socket' | 'bridge' | 'hybrid',
-    if (this.getResolvedForwardingMode() !== 'socket') return;
+    reason: string,
-
+  ): Promise<void> {
-    logger.log('info', 'VPN: Restarting server in hybrid mode to support a host-IP client');
+    logger.log('info', `VPN: Restarting server in ${forwardingMode} mode ${reason}`);
-    this.forwardingModeOverride = 'hybrid';
+    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();
   }

ts_apiclient/readme.md

@@ -1,8 +1,6 @@
 # @serve.zone/dcrouter-apiclient
 
-Typed, object-oriented API client for operating a running dcrouter instance. 🔧
+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.
-
-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.
 
 ## 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();
+const { routes, warnings } = await client.routes.list();
-console.log(routes.map((route) => `${route.origin}:${route.name}`));
+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 |
+| Admin login | Call `login(username, password)` and the returned identity is stored on the client |
-| API token | Pass `apiToken` into the constructor for token-based automation |
+| 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.
+- `baseUrl` is normalized, and the client automatically calls `${baseUrl}/typedrequest`
-- System routes can be listed and toggled, but not edited or deleted.
+- `buildRequestPayload()` injects the current identity and optional API token for you
-- A system route is any route whose `origin !== 'api'`.
+- system routes can be toggled, but only API routes are meant for edit and delete flows
+
+## Route Builder Example
 
 ```typescript
-const { routes } = await client.routes.list();
+const newRoute = await client.routes.build()
-
-for (const route of routes) {
-  if (route.origin !== 'api') {
-    await route.toggle(false);
-  }
-}
-```
-
-## Builder Example
-
-```typescript
-const route = 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();
+const token = await client.apiTokens.build()
-console.log(summary.valid, summary.failed);
+  .setName('ci-token')
+  .setScopes(['routes:read', 'routes:write'])
+  .setExpiresInDays(30)
+  .save();
 
-const health = await client.stats.getHealth();
+console.log('copy this once:', token.tokenValue);
-const recentLogs = await client.logs.getRecent({ level: 'error', limit: 20 });
+
+const edge = await client.remoteIngress.build()
+  .setName('edge-eu-1')
+  .setListenPorts([80, 443])
+  .setAutoDerivePorts(true)
+  .setTags(['production', 'eu'])
+  .save();
+
+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 bundle the dashboard.
-- It does not replace the request interfaces package if you only need raw types.
+- 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.
 

ts_interfaces/readme.md

@@ -1,8 +1,6 @@
 # @serve.zone/dcrouter-interfaces
 
-Shared TypeScript request and data interfaces for dcrouter's OpsServer API. 📡
+Shared TypeScript contracts for dcrouter's TypedRequest API. Use this package when you want compile-time request/response types and shared data models without pulling in the higher-level client SDK.
-
-This package is the contract layer for typed clients, frontend code, tests, or automation that talks to a running dcrouter instance through TypedRequest.
 
 ## Issue Reporting and Security
 
@@ -14,7 +12,7 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 pnpm add @serve.zone/dcrouter-interfaces
 ```
 
-Or consume the same interfaces through the main package:
+You can also consume the same contracts through the main package subpath:
 
 ```typescript
 import { data, requests } from '@serve.zone/dcrouter/interfaces';
@@ -22,17 +20,28 @@ import { data, requests } from '@serve.zone/dcrouter/interfaces';
 
 ## What It Exports
 
-The package exposes two namespaces from `index.ts`:
-
 | Export | Purpose |
 | --- | --- |
-| `data` | Shared runtime-shaped types such as route data, auth identity, stats, domains, certificates, VPN, DNS, and email-domain data |
+| `data` | Shared runtime-shaped data such as identities, routes, stats, domains, DNS records, VPN data, remote ingress data, and email-domain data |
-| `requests` | TypedRequest request and response contracts for every OpsServer endpoint |
+| `requests` | TypedRequest request/response contracts for OpsServer endpoints |
+| `typedrequestInterfaces` | Re-exported helper types from `@api.global/typedrequest-interfaces` |
 
-## Example
+## API Surface Covered
+
+| Domain | Examples |
+| --- | --- |
+| Auth | login, logout, identity verification |
+| Routes | list merged routes, create, update, delete, toggle |
+| Access | API tokens, source profiles, target profiles, network targets, users |
+| DNS and domains | providers, domains, DNS records, ACME config |
+| Email | email operations and email-domain management |
+| Edge services | remote ingress, VPN, RADIUS |
+| Observability | stats, health, logs, configuration |
+
+## Quick Example
 
 ```typescript
-import * as typedrequest from '@api.global/typedrequest';
+import { TypedRequest } from '@api.global/typedrequest';
 import { data, requests } from '@serve.zone/dcrouter-interfaces';
 
 const identity: data.IIdentity = {
@@ -41,9 +50,10 @@ const identity: data.IIdentity = {
   name: 'Admin',
   expiresAt: Date.now() + 60_000,
   role: 'admin',
+  type: 'user',
 };
 
-const request = new typedrequest.TypedRequest<requests.IReq_GetMergedRoutes>(
+const request = new TypedRequest<requests.IReq_GetMergedRoutes>(
   'https://dcrouter.example.com/typedrequest',
   'getMergedRoutes',
 );
@@ -55,42 +65,17 @@ for (const route of response.routes) {
 }
 ```
 
-## API Domains Covered
-
-| Domain | Examples |
-| --- | --- |
-| Auth | admin login, logout, identity verification |
-| Routes | merged routes, create, update, delete, toggle |
-| Access | API tokens, source profiles, target profiles, network targets |
-| DNS and domains | providers, domains, DNS records |
-| Certificates | overview, reprovision, import, export, delete, ACME config |
-| Email | email operations, email domains |
-| Remote ingress | edge registrations, status, connection tokens |
-| VPN | clients, status, telemetry, lifecycle |
-| RADIUS | clients, VLANs, sessions, accounting |
-| Observability | stats, logs, health, configuration |
-
-## Notable Data Types
-
-| Type | Description |
-| --- | --- |
-| `data.IMergedRoute` | Route entry returned by route management, including `origin`, `enabled`, and optional `systemKey` |
-| `data.IDcRouterRouteConfig` | dcrouter-flavored route config used across the stack |
-| `data.IRouteMetadata` | Reference metadata connecting routes to source profiles or network targets |
-| `data.IIdentity` | Admin identity used for authenticated requests |
-| `data.IApiTokenInfo` | Public token metadata without the secret |
-
 ## When To Use This Package
 
-- Use it in custom dashboards or CLIs that call TypedRequest directly.
+- Use it in tests that need strong request/response typing.
-- Use it in tests that need strongly typed request payloads or response assertions.
+- Use it in custom CLIs or dashboards that call TypedRequest directly.
-- Use it when you want the API contract without pulling in the OO client.
+- Use it in shared code where both client and server need the same data shapes.
 
-If you want a higher-level client with managers and resource classes, use `@serve.zone/dcrouter-apiclient` instead.
+If you want managers, builders, and resource classes instead of raw contracts, use `@serve.zone/dcrouter-apiclient`.
 
 ## 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.
 

ts_migrations/readme.md

@@ -1,53 +1,63 @@
 # @serve.zone/dcrouter-migrations
 
-Migration runner package for dcrouter's smartdata-backed persistence layer. 🧱
+Versioned SmartMigration chain for dcrouter's persistent data. This package builds the migration runner that dcrouter executes before DB-backed managers start reading collections.
-
-This package provides the startup migration chain that upgrades dcrouter data across releases before the application reads from the database.
 
 ## Issue Reporting and Security
 
 For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
 
+## Installation
+
+```bash
+pnpm add @serve.zone/dcrouter-migrations
+```
+
 ## What It Exports
 
 | Export | Purpose |
 | --- | --- |
-| `createMigrationRunner(db, targetVersion)` | Builds the dcrouter SmartMigration runner for the current application version |
+| `createMigrationRunner(db, targetVersion)` | Builds the dcrouter migration runner for the target application version |
-| `IMigrationRunner` | Small interface describing the runner's `run()` method |
+| `IMigrationRunner` | Small interface for the returned runner |
-| `IMigrationRunResult` | Logged result shape used after execution |
+| `IMigrationRunResult` | Result shape logged after a run |
+
+## When To Use It
+
+- You are embedding dcrouter's storage layer outside the full runtime.
+- You want to test or inspect schema transitions directly.
+- You are extending dcrouter with new persistent data and need versioned upgrades.
+
+If you boot the full `DcRouter` runtime, this package is already used for you during startup.
 
 ## Usage
 
 ```typescript
 import { createMigrationRunner } from '@serve.zone/dcrouter-migrations';
 
-const migration = await createMigrationRunner(db, '13.18.0');
+const migration = await createMigrationRunner(db, '13.20.0');
 const result = await migration.run();
 
 console.log(result.currentVersionBefore, result.currentVersionAfter);
 ```
 
-## What These Migrations Handle
+## What the Current Chain Covers
 
-The migration chain currently covers dcrouter-specific storage transitions such as:
+- target profile target field migration from `host` to `ip`
+- legacy domain source rename from `manual` to `dcrouter`
+- legacy DNS record source rename from `manual` to `local`
+- route storage unification from `StoredRouteDoc` to `RouteDoc`
+- route `origin` backfill for migrated API routes
+- `systemKey` backfill for persisted config, email, and DNS routes
 
-- target profile target field renames
+## Authoring Rules
-- domain and DNS record source renames
-- route collection unification into `RouteDoc`
-- persisted route metadata backfills such as `origin` and `systemKey`
 
-## Important Behavior
+- Add new migration logic only in `ts_migrations/index.ts`.
-
+- Keep every step idempotent so reruns are safe.
-- fresh installs are stamped directly to the current target version
+- Make each step's `.to()` version line up with the release version that ships it.
-- migration steps are registered in strict version order
+- When adding new collection references, use the exact smartdata class-name collection casing for new code.
-- migrations run before services load DB-backed state
-- route-related migrations use smartdata collection names exactly as declared in code
-
-If you are embedding dcrouter's DB layer outside the main runtime, run this package before any feature code assumes the latest schema.
 
 ## 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.
 

ts_web/00_commitinfo_data.ts

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

ts_web/elements/network/ops-view-vpn.ts

@@ -49,19 +49,28 @@ export class OpsViewVpn extends DeesElement {
   @state()
   accessor vpnState: appstate.IVpnState = appstate.vpnStatePart.getState()!;
 
+  @state()
+  accessor targetProfilesState: appstate.ITargetProfilesState = appstate.targetProfilesStatePart.getState()!;
+
   constructor() {
     super();
     const sub = appstate.vpnStatePart.select().subscribe((newState) => {
       this.vpnState = newState;
     });
     this.rxSubscriptions.push(sub);
+
+    const targetProfilesSub = appstate.targetProfilesStatePart.select().subscribe((newState) => {
+      this.targetProfilesState = newState;
+    });
+    this.rxSubscriptions.push(targetProfilesSub);
   }
 
   async connectedCallback() {
     await super.connectedCallback();
-    await appstate.vpnStatePart.dispatchAction(appstate.fetchVpnAction, null);
+    await Promise.all([
-    // Ensure target profiles are loaded for autocomplete candidates
+      appstate.vpnStatePart.dispatchAction(appstate.fetchVpnAction, null),
-    await appstate.targetProfilesStatePart.dispatchAction(appstate.fetchTargetProfilesAction, null);
+      appstate.targetProfilesStatePart.dispatchAction(appstate.fetchTargetProfilesAction, null),
+    ]);
   }
 
   public static styles = [
@@ -330,13 +339,7 @@ export class OpsViewVpn extends DeesElement {
             'Status': statusHtml,
             'Routing': routingHtml,
             'VPN IP': client.assignedIp || '-',
-            'Target Profiles': client.targetProfileIds?.length
+            'Target Profiles': this.renderTargetProfileBadges(client.targetProfileIds),
-              ? html`${client.targetProfileIds.map(id => {
-                  const profileState = appstate.targetProfilesStatePart.getState();
-                  const profile = profileState?.profiles.find(p => p.id === id);
-                  return html`<span class="tagBadge">${profile?.name || id}</span>`;
-                })}`
-              : '-',
             'Description': client.description || '-',
             'Created': new Date(client.createdAt).toLocaleDateString(),
           };
@@ -347,6 +350,7 @@ export class OpsViewVpn extends DeesElement {
             iconName: 'lucide:plus',
             type: ['header'],
             actionFunc: async () => {
+              await this.ensureTargetProfilesLoaded();
               const { DeesModal } = await import('@design.estate/dees-catalog');
               const profileCandidates = this.getTargetProfileCandidates();
               const createModal = await DeesModal.createAndShow({
@@ -647,6 +651,7 @@ export class OpsViewVpn extends DeesElement {
             type: ['contextmenu', 'inRow'],
             actionFunc: async (actionData: any) => {
               const client = actionData.item as interfaces.data.IVpnClient;
+              await this.ensureTargetProfilesLoaded();
               const { DeesModal } = await import('@design.estate/dees-catalog');
               const currentDescription = client.description ?? '';
               const currentTargetProfileNames = this.resolveProfileIdsToLabels(client.targetProfileIds) || [];
@@ -810,12 +815,28 @@ export class OpsViewVpn extends DeesElement {
     `;
   }
 
+  private async ensureTargetProfilesLoaded(): Promise<void> {
+    await appstate.targetProfilesStatePart.dispatchAction(appstate.fetchTargetProfilesAction, null);
+  }
+
+  private renderTargetProfileBadges(ids?: string[]): TemplateResult | string {
+    const labels = this.resolveProfileIdsToLabels(ids, {
+      pendingLabel: 'Loading profile...',
+      missingLabel: (id) => `Unknown profile (${id})`,
+    });
+
+    if (!labels?.length) {
+      return '-';
+    }
+
+    return html`${labels.map((label) => html`<span class="tagBadge">${label}</span>`)}`;
+  }
+
   /**
    * Build stable profile labels for list inputs.
    */
   private getTargetProfileChoices() {
-    const profileState = appstate.targetProfilesStatePart.getState();
+    const profiles = this.targetProfilesState.profiles || [];
-    const profiles = profileState?.profiles || [];
     const nameCounts = new Map<string, number>();
 
     for (const profile of profiles) {
@@ -837,12 +858,27 @@ export class OpsViewVpn extends DeesElement {
   /**
    * Convert profile IDs to form labels (for populating edit form values).
    */
-  private resolveProfileIdsToLabels(ids?: string[]): string[] | undefined {
+  private resolveProfileIdsToLabels(
+    ids?: string[],
+    options: {
+      pendingLabel?: string;
+      missingLabel?: (id: string) => string;
+    } = {},
+  ): string[] | undefined {
     if (!ids?.length) return undefined;
     const choices = this.getTargetProfileChoices();
     const labelsById = new Map(choices.map((profile) => [profile.id, profile.label]));
     return ids.map((id) => {
-      return labelsById.get(id) || id;
+      const label = labelsById.get(id);
+      if (label) {
+        return label;
+      }
+
+      if (this.targetProfilesState.lastUpdated === 0 && !this.targetProfilesState.error) {
+        return options.pendingLabel || 'Loading profile...';
+      }
+
+      return options.missingLabel?.(id) || id;
     });
   }
 

ts_web/readme.md

@@ -1,76 +1,56 @@
 # @serve.zone/dcrouter-web
 
-Browser UI package for dcrouter's operations dashboard. 🖥️
+Browser-side frontend for the dcrouter Ops dashboard. This folder is the SPA entrypoint, router, app state, and web-component UI rendered by OpsServer.
-
-This package contains the browser entrypoint, app state, router, and web components that power the Ops dashboard served by dcrouter.
 
 ## Issue Reporting and Security
 
 For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
 
-## What Is In Here
+## What It Boots
 
-| Path | Purpose |
+- `index.ts` initializes the app router and renders `<ops-dashboard>` into `document.body`
+- `router.ts` defines top-level dashboard routes and subviews
+- `appstate.ts` holds reactive state, TypedRequest actions, and TypedSocket log streaming
+- `elements/` contains the dashboard shell and feature views
+
+## View Map
+
+| Top-level view | Subviews |
 | --- | --- |
-| `index.ts` | Browser entrypoint that initializes routing and renders `<ops-dashboard>` |
+| `overview` | `stats`, `configuration` |
-| `appstate.ts` | Central reactive state and action definitions |
+| `network` | `activity`, `routes`, `sourceprofiles`, `networktargets`, `targetprofiles`, `remoteingress`, `vpn` |
-| `router.ts` | URL-based dashboard routing |
+| `email` | `log`, `security`, `domains` |
-| `elements/` | Dashboard views and reusable UI pieces |
+| `access` | `apitokens`, `users` |
-
+| `security` | `overview`, `blocked`, `authentication` |
-## Main Views
+| `domains` | `providers`, `domains`, `dns`, `certificates` |
-
+| `logs` | flat view |
-The dashboard currently includes views for:
-
-- overview and configuration
-- network activity and route management
-- source profiles, target profiles, and network targets
-- email activity and email domains
-- DNS providers, domains, DNS records, and certificates
-- API tokens and users
-- VPN, remote ingress, logs, and security views
-
-## Route Management UX
-
-The web UI reflects dcrouter's current route ownership model:
-
-- system routes are shown separately from user routes
-- system routes are visible and toggleable
-- system routes are not directly editable or deletable
-- API routes are fully managed through the route-management forms
 
 ## How It Talks To dcrouter
 
-The frontend uses TypedRequest and shared interfaces from `@serve.zone/dcrouter-interfaces`.
+- TypedRequest for the main API surface
-
+- shared request and data contracts from `@serve.zone/dcrouter-interfaces`
-State actions in `appstate.ts` fetch and mutate:
+- TypedSocket for real-time log streaming
-
+- QR code generation for VPN client UX
-- stats and health
-- logs
-- routes and tokens
-- certificates and ACME config
-- DNS providers, domains, and records
-- email domains and email operations
-- VPN, remote ingress, and RADIUS data
 
 ## Development Notes
 
-The browser bundle is built from this package and served by the main dcrouter package.
+This package is the frontend module boundary, but it is built and served as part of the main workspace.
 
 ```bash
-pnpm run bundle
+pnpm run build
 pnpm run watch
 ```
 
-The generated bundle is written into `dist_serve/` by the main build pipeline.
+The built dashboard assets are emitted into `dist_serve/` by the workspace build pipeline.
 
-## When To Use This Package
+## What This Package Is For
 
-- Use it if you want the dashboard frontend as a package/module boundary.
+- Use it when you want the dashboard frontend as its own published module boundary.
-- Use the main `@serve.zone/dcrouter` package if you want the server that actually serves this UI.
+- Use `@serve.zone/dcrouter` when you want the server that actually hosts this UI and the backend API.
 
 ## 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.