v13.9.0

.dockerignore

@@ -1 +1,7 @@
 node_modules/
+.nogit/
+.git/
+.playwright-mcp/
+.vscode/
+test/
+test_watch/

.gitea/workflows/docker_nottags.yaml

@@ -6,7 +6,7 @@ on:
       - '**'
 
 env:
-  IMAGE: registry.gitlab.com/hosttoday/ht-docker-node:npmci
+  IMAGE: code.foss.global/host.today/ht-docker-node:szci
   NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@gitea.lossless.digital/${{gitea.repository}}.git
   NPMCI_TOKEN_NPM: ${{secrets.NPMCI_TOKEN_NPM}}
   NPMCI_TOKEN_NPM2: ${{secrets.NPMCI_TOKEN_NPM2}}

.gitea/workflows/docker_tags.yaml

@@ -6,7 +6,7 @@ on:
       - '*'
 
 env:
-  IMAGE: registry.gitlab.com/hosttoday/ht-docker-node:npmci
+  IMAGE: code.foss.global/host.today/ht-docker-node:szci
   NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@gitea.lossless.digital/${{gitea.repository}}.git
   NPMCI_TOKEN_NPM: ${{secrets.NPMCI_TOKEN_NPM}}
   NPMCI_TOKEN_NPM2: ${{secrets.NPMCI_TOKEN_NPM2}}
@@ -74,7 +74,7 @@ jobs:
     if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
     runs-on: ubuntu-latest
     container:
-      image: registry.gitlab.com/hosttoday/ht-docker-dbase:npmci
+      image: code.foss.global/host.today/ht-docker-node:dbase_dind
 
     steps:
       - uses: actions/checkout@v3
@@ -82,15 +82,13 @@ jobs:
       - name: Prepare
         run: |
           pnpm install -g pnpm
-          pnpm install -g @shipzone/npmci
+          pnpm install -g @git.zone/tsdocker
 
       - name: Release
         run: |
-          npmci docker login
-          npmci docker build
-          npmci docker test
-          # npmci docker push gitea.lossless.digital
-          npmci docker push dockerregistry.lossless.digital
+          tsdocker login
+          tsdocker build
+          tsdocker push
 
   metadata:
     needs: test

.gitignore

@@ -21,3 +21,4 @@ dist_*/
 **/.claude/settings.local.json
 .nogit/data/
 readme.plan.md
+.playwright-mcp/

.smartconfig.json

@@ -22,7 +22,8 @@
         "to": "./dist_serve/bundle.js",
         "outputMode": "bundle",
         "bundler": "esbuild",
-        "production": true
+        "production": true,
+        "includeFiles": ["./html/**/*.html"]
       }
     ]
   },
@@ -71,9 +72,14 @@
     "dockerRegistryRepoMap": {
       "registry.gitlab.com": "code.foss.global/serve.zone/dcrouter"
     },
-    "dockerBuildargEnvMap": {
-      "NPMCI_TOKEN_NPM2": "NPMCI_TOKEN_NPM2"
-    },
     "npmRegistryUrl": "verdaccio.lossless.digital"
+  },
+  "@git.zone/tsdocker": {
+    "registries": ["code.foss.global"],
+    "registryRepoMap": {
+      "code.foss.global": "serve.zone/dcrouter",
+      "dockerregistry.lossless.digital": "serve.zone/dcrouter"
+    },
+    "platforms": ["linux/amd64", "linux/arm64"]
   }
 }

.vscode/settings.json

@@ -1,7 +1,7 @@
 {
   "json.schemas": [
     {
-      "fileMatch": ["/npmextra.json"],
+      "fileMatch": ["/.smartconfig.json"],
       "schema": {
         "type": "object",
         "properties": {

Dockerfile

@@ -1,46 +1,34 @@
 # gitzone dockerfile_service
 ## STAGE 1 // BUILD
-FROM registry.gitlab.com/hosttoday/ht-docker-node:npmci as node1
+FROM code.foss.global/host.today/ht-docker-node:lts AS build
 COPY ./ /app
 WORKDIR /app
-ARG NPMCI_TOKEN_NPM2
-ENV NPMCI_TOKEN_NPM2 $NPMCI_TOKEN_NPM2
-RUN npmci npm prepare
 RUN pnpm config set store-dir .pnpm-store
 RUN rm -rf node_modules && pnpm install
 RUN pnpm run build
+RUN rm -rf .pnpm-store node_modules && pnpm install --prod
+
+## STAGE 2 // PRODUCTION
+FROM code.foss.global/host.today/ht-docker-node:alpine-node AS production
+
+# gcompat + libstdc++ for glibc-linked Rust binaries (smartproxy, smartmta, remoteingress)
+RUN apk add --no-cache gcompat libstdc++
 
-# gitzone dockerfile_service
-## STAGE 2 // install production
-FROM registry.gitlab.com/hosttoday/ht-docker-node:npmci as node2
 WORKDIR /app
-COPY --from=node1 /app /app
-RUN rm -rf .pnpm-store
-ARG NPMCI_TOKEN_NPM2
-ENV NPMCI_TOKEN_NPM2 $NPMCI_TOKEN_NPM2
-RUN npmci npm prepare
-RUN pnpm config set store-dir .pnpm-store
-RUN rm -rf node_modules/ && pnpm install --prod
+COPY --from=build /app /app
 
+ENV DCROUTER_MODE=OCI_CONTAINER
+ENV DCROUTER_HEAP_SIZE=512
+ENV UV_THREADPOOL_SIZE=16
 
-## STAGE 3 // rebuild dependencies for alpine
-FROM registry.gitlab.com/hosttoday/ht-docker-node:alpinenpmci as node3
-WORKDIR /app
-COPY --from=node2 /app /app
-ARG NPMCI_TOKEN_NPM2
-ENV NPMCI_TOKEN_NPM2 $NPMCI_TOKEN_NPM2
-RUN npmci npm prepare
-RUN pnpm config set store-dir .pnpm-store
-RUN pnpm rebuild -r
-
-## STAGE 4 // the final production image with all dependencies in place
-FROM registry.gitlab.com/hosttoday/ht-docker-node:alpine as node4
-WORKDIR /app
-COPY --from=node3 /app /app
-
-### Healthchecks
 RUN pnpm install -g @servezone/healthy
-HEALTHCHECK --interval=30s --timeout=30s --start-period=30s --retries=3 CMD [ "healthy" ]
+HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=3 CMD [ "healthy" ]
 
-EXPOSE 80
-CMD ["npm", "start"]
+LABEL org.opencontainers.image.title="dcrouter" \
+      org.opencontainers.image.description="Multi-service datacenter gateway" \
+      org.opencontainers.image.source="https://code.foss.global/serve.zone/dcrouter"
+
+# HTTP/HTTPS, SMTP/Submission/SMTPS, DNS, RADIUS, OpsServer, RemoteIngress, dynamic range
+EXPOSE 80 443 25 587 465 53/tcp 53/udp 1812/udp 1813/udp 3000 8443 29000-30000
+
+CMD ["sh", "-c", "node --max_old_space_size=${DCROUTER_HEAP_SIZE} ./cli.js"]

license

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Task Venture Capital GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package.json

@@ -1,63 +1,74 @@
 {
   "name": "@serve.zone/dcrouter",
   "private": false,
-  "version": "5.4.3",
+  "version": "13.9.0",
   "description": "A multifaceted routing service handling mail and SMS delivery functions.",
   "type": "module",
   "exports": {
     ".": "./dist_ts/index.js",
-    "./interfaces": "./dist_ts_interfaces/index.js"
+    "./interfaces": "./dist_ts_interfaces/index.js",
+    "./apiclient": "./dist_ts_apiclient/index.js"
   },
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "scripts": {
     "test": "(tstest test/ --logfile --timeout 60)",
-    "start": "(node --max_old_space_size=250 ./cli.js)",
+    "start": "(node ./cli.js)",
     "startTs": "(node cli.ts.js)",
     "build": "(tsbuild tsfolders --allowimplicitany && npm run bundle)",
+    "build:docker": "tsdocker build --verbose",
+    "release:docker": "tsdocker push --verbose",
     "bundle": "(tsbundle)",
     "watch": "tswatch"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.1.2",
-    "@git.zone/tsbundle": "^2.8.3",
-    "@git.zone/tsrun": "^2.0.1",
-    "@git.zone/tstest": "^3.1.8",
-    "@git.zone/tswatch": "^3.1.0",
-    "@types/node": "^25.2.3"
+    "@git.zone/tsbuild": "^4.4.0",
+    "@git.zone/tsbundle": "^2.10.0",
+    "@git.zone/tsrun": "^2.0.2",
+    "@git.zone/tstest": "^3.6.3",
+    "@git.zone/tswatch": "^3.3.2",
+    "@types/node": "^25.5.2"
   },
   "dependencies": {
-    "@api.global/typedrequest": "^3.2.6",
+    "@api.global/typedrequest": "^3.3.0",
     "@api.global/typedrequest-interfaces": "^3.0.19",
-    "@api.global/typedserver": "^8.3.0",
-    "@api.global/typedsocket": "^4.1.0",
+    "@api.global/typedserver": "^8.4.6",
+    "@api.global/typedsocket": "^4.1.2",
     "@apiclient.xyz/cloudflare": "^7.1.0",
-    "@design.estate/dees-catalog": "^3.42.0",
-    "@design.estate/dees-element": "^2.1.6",
-    "@push.rocks/projectinfo": "^5.0.2",
+    "@design.estate/dees-catalog": "^3.70.0",
+    "@design.estate/dees-element": "^2.2.4",
+    "@push.rocks/lik": "^6.4.0",
+    "@push.rocks/projectinfo": "^5.1.0",
     "@push.rocks/qenv": "^6.1.3",
-    "@push.rocks/smartacme": "^8.0.0",
-    "@push.rocks/smartdata": "^7.0.15",
-    "@push.rocks/smartdns": "^7.8.1",
-    "@push.rocks/smartfile": "^13.1.2",
+    "@push.rocks/smartacme": "^9.5.0",
+    "@push.rocks/smartdata": "^7.1.7",
+    "@push.rocks/smartdb": "^2.6.2",
+    "@push.rocks/smartdns": "^7.9.0",
+    "@push.rocks/smartfs": "^1.5.0",
     "@push.rocks/smartguard": "^3.1.0",
     "@push.rocks/smartjwt": "^2.2.1",
-    "@push.rocks/smartlog": "^3.1.10",
-    "@push.rocks/smartmetrics": "^2.0.10",
-    "@push.rocks/smartmongo": "^5.1.0",
-    "@push.rocks/smartmta": "^5.2.2",
-    "@push.rocks/smartnetwork": "^4.4.0",
+    "@push.rocks/smartlog": "^3.2.2",
+    "@push.rocks/smartmetrics": "^3.0.3",
+    "@push.rocks/smartmigration": "1.2.0",
+    "@push.rocks/smartmta": "^5.3.1",
+    "@push.rocks/smartnetwork": "^4.5.2",
     "@push.rocks/smartpath": "^6.0.0",
     "@push.rocks/smartpromise": "^4.2.3",
-    "@push.rocks/smartproxy": "^25.1.0",
+    "@push.rocks/smartproxy": "^27.5.0",
     "@push.rocks/smartradius": "^1.1.1",
     "@push.rocks/smartrequest": "^5.0.1",
     "@push.rocks/smartrx": "^3.0.10",
-    "@push.rocks/smartstate": "^2.0.30",
+    "@push.rocks/smartstate": "^2.3.0",
     "@push.rocks/smartunique": "^3.0.9",
+    "@push.rocks/smartvpn": "1.19.2",
+    "@push.rocks/taskbuffer": "^8.0.2",
+    "@serve.zone/catalog": "^2.12.3",
     "@serve.zone/interfaces": "^5.3.0",
-    "@tsclass/tsclass": "^9.3.0",
-    "lru-cache": "^11.2.6",
+    "@serve.zone/remoteingress": "^4.15.3",
+    "@tsclass/tsclass": "^9.5.0",
+    "@types/qrcode": "^1.5.6",
+    "lru-cache": "^11.3.2",
+    "qrcode": "^1.5.4",
     "uuid": "^13.0.0"
   },
   "keywords": [
@@ -97,13 +108,15 @@
   "files": [
     "ts/**/*",
     "ts_web/**/*",
+    "ts_apiclient/**/*",
     "dist/**/*",
     "dist_*/**/*",
     "dist_ts/**/*",
     "dist_ts_web/**/*",
+    "dist_ts_apiclient/**/*",
     "assets/**/*",
     "cli.js",
-    "npmextra.json",
+    ".smartconfig.json",
     "readme.md"
   ]
 }

readme.hints.md

@@ -133,7 +133,7 @@ The project now uses tswatch for development:
 ```bash
 pnpm run watch
 ```
-Configuration in `npmextra.json`:
+Configuration in `.smartconfig.json`:
 ```json
 {
   "@git.zone/tswatch": {

readme.storage.md

@@ -0,0 +1,84 @@
+# DCRouter Storage Overview
+
+DCRouter uses a **unified database layer** backed by `@push.rocks/smartdata` for all persistent data. All data is stored as typed document classes in a single database.
+
+## Database Modes
+
+### Embedded Mode (default)
+When no external MongoDB URL is provided, DCRouter starts an embedded `LocalSmartDb` (Rust-based MongoDB-compatible engine) via `@push.rocks/smartdb`.
+
+```
+~/.serve.zone/dcrouter/tsmdb/
+```
+
+### External Mode
+Connect to any MongoDB-compatible database by providing a connection URL.
+
+```typescript
+dbConfig: {
+  mongoDbUrl: 'mongodb://host:27017',
+  dbName: 'dcrouter',
+}
+```
+
+## Configuration
+
+```typescript
+dbConfig: {
+  enabled: true,                                    // default: true
+  mongoDbUrl: undefined,                            // default: embedded LocalSmartDb
+  storagePath: '~/.serve.zone/dcrouter/tsmdb',     // default (embedded mode only)
+  dbName: 'dcrouter',                               // default
+  cleanupIntervalHours: 1,                          // TTL cleanup interval
+}
+```
+
+## Document Classes
+
+All data is stored as smartdata document classes in `ts/db/documents/`.
+
+| Document Class | Collection | Unique Key | Purpose |
+|---|---|---|---|
+| `StoredRouteDoc` | storedRoutes | `id` | Programmatic routes (created via API) |
+| `RouteOverrideDoc` | routeOverrides | `routeName` | Hardcoded route enable/disable overrides |
+| `ApiTokenDoc` | apiTokens | `id` | API tokens (hashed secrets, scopes, expiry) |
+| `VpnServerKeysDoc` | vpnServerKeys | `configId` (singleton) | VPN server Noise + WireGuard keypairs |
+| `VpnClientDoc` | vpnClients | `clientId` | VPN client registrations |
+| `AcmeCertDoc` | acmeCerts | `domainName` | ACME certificates and keys |
+| `ProxyCertDoc` | proxyCerts | `domain` | SmartProxy TLS certificates |
+| `CertBackoffDoc` | certBackoff | `domain` | Per-domain cert provision backoff state |
+| `RemoteIngressEdgeDoc` | remoteIngressEdges | `id` | Edge node registrations |
+| `VlanMappingsDoc` | vlanMappings | `configId` (singleton) | MAC-to-VLAN mapping table |
+| `AccountingSessionDoc` | accountingSessions | `sessionId` | RADIUS accounting sessions |
+| `CachedEmail` | cachedEmails | `id` | Email metadata (TTL: 30 days) |
+| `CachedIPReputation` | cachedIPReputation | `ipAddress` | IP reputation results (TTL: 24 hours) |
+
+## Architecture
+
+```
+DcRouterDb (singleton)
+  ├── LocalSmartDb (embedded, Rust) ─── or ─── External MongoDB
+  └── SmartdataDb (ORM)
+        └── @Collection(() => getDb())
+              ├── StoredRouteDoc
+              ├── RouteOverrideDoc
+              ├── ApiTokenDoc
+              ├── VpnServerKeysDoc / VpnClientDoc
+              ├── AcmeCertDoc / ProxyCertDoc / CertBackoffDoc
+              ├── RemoteIngressEdgeDoc
+              ├── VlanMappingsDoc / AccountingSessionDoc
+              ├── CachedEmail (TTL)
+              └── CachedIPReputation (TTL)
+```
+
+### TTL Cleanup
+
+`CacheCleaner` runs on a configurable interval (default: 1 hour) and removes expired documents where `expiresAt < now()`.
+
+## Disabling
+
+For tests or lightweight deployments without persistence:
+
+```typescript
+dbConfig: { enabled: false }
+```

test/test.apiclient.ts

@@ -0,0 +1,376 @@
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import {
+  DcRouterApiClient,
+  Route,
+  RouteBuilder,
+  RouteManager,
+  Certificate,
+  CertificateManager,
+  ApiToken,
+  ApiTokenBuilder,
+  ApiTokenManager,
+  RemoteIngress,
+  RemoteIngressBuilder,
+  RemoteIngressManager,
+  Email,
+  EmailManager,
+  StatsManager,
+  ConfigManager,
+  LogManager,
+  RadiusManager,
+  RadiusClientManager,
+  RadiusVlanManager,
+  RadiusSessionManager,
+} from '../ts_apiclient/index.js';
+
+// =============================================================================
+// Instantiation & Structure
+// =============================================================================
+
+tap.test('DcRouterApiClient - should instantiate with baseUrl', async () => {
+  const client = new DcRouterApiClient({ baseUrl: 'https://localhost:3000' });
+  expect(client).toBeTruthy();
+  expect(client.baseUrl).toEqual('https://localhost:3000');
+  expect(client.identity).toBeUndefined();
+});
+
+tap.test('DcRouterApiClient - should strip trailing slashes from baseUrl', async () => {
+  const client = new DcRouterApiClient({ baseUrl: 'https://localhost:3000///' });
+  expect(client.baseUrl).toEqual('https://localhost:3000');
+});
+
+tap.test('DcRouterApiClient - should accept optional apiToken', async () => {
+  const client = new DcRouterApiClient({
+    baseUrl: 'https://localhost:3000',
+    apiToken: 'dcr_test_token',
+  });
+  expect(client.apiToken).toEqual('dcr_test_token');
+});
+
+tap.test('DcRouterApiClient - should have all resource managers', async () => {
+  const client = new DcRouterApiClient({ baseUrl: 'https://localhost:3000' });
+  expect(client.routes).toBeInstanceOf(RouteManager);
+  expect(client.certificates).toBeInstanceOf(CertificateManager);
+  expect(client.apiTokens).toBeInstanceOf(ApiTokenManager);
+  expect(client.remoteIngress).toBeInstanceOf(RemoteIngressManager);
+  expect(client.stats).toBeInstanceOf(StatsManager);
+  expect(client.config).toBeInstanceOf(ConfigManager);
+  expect(client.logs).toBeInstanceOf(LogManager);
+  expect(client.emails).toBeInstanceOf(EmailManager);
+  expect(client.radius).toBeInstanceOf(RadiusManager);
+});
+
+// =============================================================================
+// buildRequestPayload
+// =============================================================================
+
+tap.test('DcRouterApiClient - buildRequestPayload includes identity when set', async () => {
+  const client = new DcRouterApiClient({ baseUrl: 'https://localhost:3000' });
+  const identity = {
+    jwt: 'test-jwt',
+    userId: 'user1',
+    name: 'Admin',
+    expiresAt: Date.now() + 3600000,
+  };
+  client.identity = identity;
+
+  const payload = client.buildRequestPayload({ extra: 'data' });
+  expect(payload.identity).toEqual(identity);
+  expect(payload.extra).toEqual('data');
+});
+
+tap.test('DcRouterApiClient - buildRequestPayload includes apiToken when set', async () => {
+  const client = new DcRouterApiClient({
+    baseUrl: 'https://localhost:3000',
+    apiToken: 'dcr_abc123',
+  });
+
+  const payload = client.buildRequestPayload();
+  expect(payload.apiToken).toEqual('dcr_abc123');
+});
+
+tap.test('DcRouterApiClient - buildRequestPayload with both identity and apiToken', async () => {
+  const client = new DcRouterApiClient({
+    baseUrl: 'https://localhost:3000',
+    apiToken: 'dcr_abc123',
+  });
+  client.identity = {
+    jwt: 'test-jwt',
+    userId: 'user1',
+    name: 'Admin',
+    expiresAt: Date.now() + 3600000,
+  };
+
+  const payload = client.buildRequestPayload({ foo: 'bar' });
+  expect(payload.identity).toBeTruthy();
+  expect(payload.apiToken).toEqual('dcr_abc123');
+  expect(payload.foo).toEqual('bar');
+});
+
+// =============================================================================
+// Route Builder
+// =============================================================================
+
+tap.test('RouteBuilder - should support fluent builder pattern', async () => {
+  const client = new DcRouterApiClient({ baseUrl: 'https://localhost:3000' });
+  const builder = client.routes.build();
+  expect(builder).toBeInstanceOf(RouteBuilder);
+
+  // Fluent methods return `this` (same reference)
+  const result = builder
+    .setName('test-route')
+    .setMatch({ ports: 443, domains: 'example.com' })
+    .setAction({ type: 'forward', targets: [{ host: 'backend', port: 8080 }] })
+    .setEnabled(true);
+
+  expect(result === builder).toBeTrue();
+});
+
+// =============================================================================
+// ApiToken Builder
+// =============================================================================
+
+tap.test('ApiTokenBuilder - should support fluent builder pattern', async () => {
+  const client = new DcRouterApiClient({ baseUrl: 'https://localhost:3000' });
+  const builder = client.apiTokens.build();
+  expect(builder).toBeInstanceOf(ApiTokenBuilder);
+
+  const result = builder
+    .setName('ci-token')
+    .setScopes(['routes:read', 'routes:write'])
+    .addScope('config:read')
+    .setExpiresInDays(30);
+
+  expect(result === builder).toBeTrue();
+});
+
+// =============================================================================
+// RemoteIngress Builder
+// =============================================================================
+
+tap.test('RemoteIngressBuilder - should support fluent builder pattern', async () => {
+  const client = new DcRouterApiClient({ baseUrl: 'https://localhost:3000' });
+  const builder = client.remoteIngress.build();
+  expect(builder).toBeInstanceOf(RemoteIngressBuilder);
+
+  const result = builder
+    .setName('edge-1')
+    .setListenPorts([80, 443])
+    .setAutoDerivePorts(true)
+    .setTags(['production']);
+
+  expect(result === builder).toBeTrue();
+});
+
+// =============================================================================
+// Route resource class
+// =============================================================================
+
+tap.test('Route - should hydrate from IMergedRoute data', async () => {
+  const client = new DcRouterApiClient({ baseUrl: 'https://localhost:3000' });
+  const route = new Route(client, {
+    route: {
+      name: 'test-route',
+      match: { ports: 443, domains: 'example.com' },
+      action: { type: 'forward', targets: [{ host: 'backend', port: 8080 }] },
+    },
+    source: 'programmatic',
+    enabled: true,
+    overridden: false,
+    storedRouteId: 'route-123',
+    createdAt: 1000,
+    updatedAt: 2000,
+  });
+
+  expect(route.name).toEqual('test-route');
+  expect(route.source).toEqual('programmatic');
+  expect(route.enabled).toEqual(true);
+  expect(route.overridden).toEqual(false);
+  expect(route.storedRouteId).toEqual('route-123');
+  expect(route.routeConfig.match.ports).toEqual(443);
+});
+
+tap.test('Route - should throw on update/delete/toggle for hardcoded routes', async () => {
+  const client = new DcRouterApiClient({ baseUrl: 'https://localhost:3000' });
+  const route = new Route(client, {
+    route: {
+      name: 'hardcoded-route',
+      match: { ports: 80 },
+      action: { type: 'forward', targets: [{ host: 'localhost', port: 8080 }] },
+    },
+    source: 'hardcoded',
+    enabled: true,
+    overridden: false,
+    // No storedRouteId for hardcoded routes
+  });
+
+  let updateError: Error | undefined;
+  try {
+    await route.update({ name: 'new-name' });
+  } catch (e) {
+    updateError = e as Error;
+  }
+  expect(updateError).toBeTruthy();
+  expect(updateError!.message).toInclude('hardcoded');
+
+  let deleteError: Error | undefined;
+  try {
+    await route.delete();
+  } catch (e) {
+    deleteError = e as Error;
+  }
+  expect(deleteError).toBeTruthy();
+
+  let toggleError: Error | undefined;
+  try {
+    await route.toggle(false);
+  } catch (e) {
+    toggleError = e as Error;
+  }
+  expect(toggleError).toBeTruthy();
+});
+
+// =============================================================================
+// Certificate resource class
+// =============================================================================
+
+tap.test('Certificate - should hydrate from ICertificateInfo data', async () => {
+  const client = new DcRouterApiClient({ baseUrl: 'https://localhost:3000' });
+  const cert = new Certificate(client, {
+    domain: 'example.com',
+    routeNames: ['main-route'],
+    status: 'valid',
+    source: 'acme',
+    tlsMode: 'terminate',
+    expiryDate: '2027-01-01T00:00:00Z',
+    issuer: "Let's Encrypt",
+    canReprovision: true,
+  });
+
+  expect(cert.domain).toEqual('example.com');
+  expect(cert.status).toEqual('valid');
+  expect(cert.source).toEqual('acme');
+  expect(cert.canReprovision).toEqual(true);
+  expect(cert.routeNames.length).toEqual(1);
+});
+
+// =============================================================================
+// ApiToken resource class
+// =============================================================================
+
+tap.test('ApiToken - should hydrate from IApiTokenInfo data', async () => {
+  const client = new DcRouterApiClient({ baseUrl: 'https://localhost:3000' });
+  const token = new ApiToken(
+    client,
+    {
+      id: 'token-1',
+      name: 'ci-token',
+      scopes: ['routes:read', 'routes:write'],
+      createdAt: Date.now(),
+      expiresAt: null,
+      lastUsedAt: null,
+      enabled: true,
+    },
+    'dcr_secret_value',
+  );
+
+  expect(token.id).toEqual('token-1');
+  expect(token.name).toEqual('ci-token');
+  expect(token.scopes.length).toEqual(2);
+  expect(token.enabled).toEqual(true);
+  expect(token.tokenValue).toEqual('dcr_secret_value');
+});
+
+// =============================================================================
+// RemoteIngress resource class
+// =============================================================================
+
+tap.test('RemoteIngress - should hydrate from IRemoteIngress data', async () => {
+  const client = new DcRouterApiClient({ baseUrl: 'https://localhost:3000' });
+  const edge = new RemoteIngress(client, {
+    id: 'edge-1',
+    name: 'test-edge',
+    secret: 'secret123',
+    listenPorts: [80, 443],
+    enabled: true,
+    autoDerivePorts: true,
+    tags: ['prod'],
+    createdAt: 1000,
+    updatedAt: 2000,
+    effectiveListenPorts: [80, 443, 8080],
+    manualPorts: [80, 443],
+    derivedPorts: [8080],
+  });
+
+  expect(edge.id).toEqual('edge-1');
+  expect(edge.name).toEqual('test-edge');
+  expect(edge.listenPorts.length).toEqual(2);
+  expect(edge.effectiveListenPorts!.length).toEqual(3);
+  expect(edge.autoDerivePorts).toEqual(true);
+});
+
+// =============================================================================
+// Email resource class
+// =============================================================================
+
+tap.test('Email - should hydrate from IEmail data', async () => {
+  const client = new DcRouterApiClient({ baseUrl: 'https://localhost:3000' });
+  const email = new Email(client, {
+    id: 'email-1',
+    direction: 'inbound',
+    status: 'delivered',
+    from: 'sender@example.com',
+    to: 'recipient@example.com',
+    subject: 'Test email',
+    timestamp: '2026-03-06T00:00:00Z',
+    messageId: '<msg-1@example.com>',
+    size: '1234',
+  });
+
+  expect(email.id).toEqual('email-1');
+  expect(email.direction).toEqual('inbound');
+  expect(email.status).toEqual('delivered');
+  expect(email.from).toEqual('sender@example.com');
+  expect(email.subject).toEqual('Test email');
+});
+
+// =============================================================================
+// RadiusManager structure
+// =============================================================================
+
+tap.test('RadiusManager - should have sub-managers', async () => {
+  const client = new DcRouterApiClient({ baseUrl: 'https://localhost:3000' });
+  expect(client.radius.clients).toBeInstanceOf(RadiusClientManager);
+  expect(client.radius.vlans).toBeInstanceOf(RadiusVlanManager);
+  expect(client.radius.sessions).toBeInstanceOf(RadiusSessionManager);
+});
+
+// =============================================================================
+// Exports verification
+// =============================================================================
+
+tap.test('Exports - all expected classes should be importable', async () => {
+  expect(DcRouterApiClient).toBeTruthy();
+  expect(Route).toBeTruthy();
+  expect(RouteBuilder).toBeTruthy();
+  expect(RouteManager).toBeTruthy();
+  expect(Certificate).toBeTruthy();
+  expect(CertificateManager).toBeTruthy();
+  expect(ApiToken).toBeTruthy();
+  expect(ApiTokenBuilder).toBeTruthy();
+  expect(ApiTokenManager).toBeTruthy();
+  expect(RemoteIngress).toBeTruthy();
+  expect(RemoteIngressBuilder).toBeTruthy();
+  expect(RemoteIngressManager).toBeTruthy();
+  expect(Email).toBeTruthy();
+  expect(EmailManager).toBeTruthy();
+  expect(StatsManager).toBeTruthy();
+  expect(ConfigManager).toBeTruthy();
+  expect(LogManager).toBeTruthy();
+  expect(RadiusManager).toBeTruthy();
+  expect(RadiusClientManager).toBeTruthy();
+  expect(RadiusVlanManager).toBeTruthy();
+  expect(RadiusSessionManager).toBeTruthy();
+});
+
+export default tap.start();

test/test.cert-renewal.ts

@@ -0,0 +1,196 @@
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import { deriveCertDomainName } from '../ts/opsserver/handlers/certificate.handler.js';
+
+// ──────────────────────────────────────────────────────────────────────────────
+// deriveCertDomainName — pure helper that mirrors smartacme's certmatcher.
+// Used by the force-renew sibling-propagation logic to identify which routes
+// share a single underlying ACME certificate.
+// ──────────────────────────────────────────────────────────────────────────────
+
+tap.test('deriveCertDomainName collapses 3-level subdomain to base', async () => {
+  expect(deriveCertDomainName('outline.task.vc')).toEqual('task.vc');
+  expect(deriveCertDomainName('pr.task.vc')).toEqual('task.vc');
+  expect(deriveCertDomainName('mtd.task.vc')).toEqual('task.vc');
+});
+
+tap.test('deriveCertDomainName returns base domain unchanged for 2-level domain', async () => {
+  expect(deriveCertDomainName('task.vc')).toEqual('task.vc');
+  expect(deriveCertDomainName('example.com')).toEqual('example.com');
+});
+
+tap.test('deriveCertDomainName strips wildcard prefix', async () => {
+  expect(deriveCertDomainName('*.task.vc')).toEqual('task.vc');
+  expect(deriveCertDomainName('*.example.com')).toEqual('example.com');
+});
+
+tap.test('deriveCertDomainName collapses subdomain and wildcard to same identity', async () => {
+  // This is the core property: outline.task.vc and *.task.vc must yield
+  // the same cert identity, otherwise sibling propagation cannot work.
+  const subdomain = deriveCertDomainName('outline.task.vc');
+  const wildcard = deriveCertDomainName('*.task.vc');
+  expect(subdomain).toEqual(wildcard);
+});
+
+tap.test('deriveCertDomainName returns undefined for 4+ level domains', async () => {
+  // Matches smartacme's "deeper domains not supported" behavior.
+  expect(deriveCertDomainName('a.b.task.vc')).toBeUndefined();
+  expect(deriveCertDomainName('one.two.three.example.com')).toBeUndefined();
+});
+
+tap.test('deriveCertDomainName returns undefined for malformed inputs', async () => {
+  expect(deriveCertDomainName('vc')).toBeUndefined();
+  expect(deriveCertDomainName('')).toBeUndefined();
+});
+
+// ──────────────────────────────────────────────────────────────────────────────
+// CertificateHandler.reprovisionCertificateDomain — verify the includeWildcard
+// option is forwarded to smartAcme.getCertificateForDomain on force renew.
+//
+// This is the regression test for Bug 1: previously the call passed only
+// `{ forceRenew: true }`, causing the re-issued cert to drop the wildcard SAN
+// and break every sibling subdomain.
+// ──────────────────────────────────────────────────────────────────────────────
+
+import { CertificateHandler } from '../ts/opsserver/handlers/certificate.handler.js';
+
+// Build a minimal stub of OpsServer + DcRouter that satisfies CertificateHandler.
+// We only need: viewRouter.addTypedHandler / adminRouter.addTypedHandler (no-op),
+// dcRouterRef.smartProxy.routeManager.getRoutes(), dcRouterRef.smartAcme,
+// dcRouterRef.findRouteNamesForDomain, dcRouterRef.certificateStatusMap.
+function makeStubOpsServer(opts: {
+  routes: Array<{ name: string; domains: string[] }>;
+  smartAcmeStub: { getCertificateForDomain: (domain: string, options: any) => Promise<any> };
+}) {
+  const captured: { typedHandlers: any[] } = { typedHandlers: [] };
+  const router = {
+    addTypedHandler(handler: any) { captured.typedHandlers.push(handler); },
+  };
+
+  const routes = opts.routes.map((r) => ({
+    name: r.name,
+    match: { domains: r.domains, ports: 443 },
+    action: { type: 'forward', tls: { certificate: 'auto' } },
+  }));
+
+  const dcRouterRef: any = {
+    smartProxy: {
+      routeManager: { getRoutes: () => routes },
+    },
+    smartAcme: opts.smartAcmeStub,
+    findRouteNamesForDomain: (domain: string) =>
+      routes.filter((r) => r.match.domains.includes(domain)).map((r) => r.name),
+    certificateStatusMap: new Map<string, any>(),
+    certProvisionScheduler: null,
+    routeConfigManager: null,
+  };
+
+  const opsServerRef: any = {
+    viewRouter: router,
+    adminRouter: router,
+    dcRouterRef,
+  };
+
+  return { opsServerRef, dcRouterRef, captured };
+}
+
+tap.test('reprovisionCertificateDomain passes includeWildcard=true for non-wildcard domain', async () => {
+  const calls: Array<{ domain: string; options: any }> = [];
+
+  const { opsServerRef, dcRouterRef } = makeStubOpsServer({
+    routes: [
+      { name: 'outline-route', domains: ['outline.task.vc'] },
+      { name: 'pr-route', domains: ['pr.task.vc'] },
+      { name: 'mtd-route', domains: ['mtd.task.vc'] },
+    ],
+    smartAcmeStub: {
+      getCertificateForDomain: async (domain: string, options: any) => {
+        calls.push({ domain, options });
+        // Return a cert object shaped like SmartacmeCert
+        return {
+          id: 'test-id',
+          domainName: 'task.vc',
+          created: Date.now(),
+          validUntil: Date.now() + 90 * 24 * 60 * 60 * 1000,
+          privateKey: '-----BEGIN PRIVATE KEY-----\nfake\n-----END PRIVATE KEY-----',
+          publicKey: '-----BEGIN CERTIFICATE-----\nfake\n-----END CERTIFICATE-----',
+          csr: '',
+        };
+      },
+    },
+  });
+
+  // Override updateRoutes/applyRoutes to no-op so the test doesn't try to talk to a real proxy
+  dcRouterRef.smartProxy.updateRoutes = async () => {};
+
+  // Construct handler — registerHandlers will run and register typed handlers on our stub router.
+  const handler = new CertificateHandler(opsServerRef);
+
+  // Invoke the private reprovision method directly. The Bug 1 fix is verified
+  // by inspecting the captured smartAcme call options regardless of whether
+  // sibling propagation succeeds (it relies on a real DB for ProxyCertDoc).
+  await (handler as any).reprovisionCertificateDomain('outline.task.vc', true);
+
+  // Sibling propagation may fail because ProxyCertDoc.findByDomain needs a real DB.
+  // The Bug 1 fix is verified by the captured smartAcme call regardless.
+  expect(calls.length).toBeGreaterThanOrEqual(1);
+  expect(calls[0].domain).toEqual('outline.task.vc');
+  expect(calls[0].options).toEqual({ forceRenew: true, includeWildcard: true });
+});
+
+tap.test('reprovisionCertificateDomain passes includeWildcard=false for wildcard domain', async () => {
+  const calls: Array<{ domain: string; options: any }> = [];
+
+  const { opsServerRef, dcRouterRef } = makeStubOpsServer({
+    routes: [
+      { name: 'wildcard-route', domains: ['*.task.vc'] },
+    ],
+    smartAcmeStub: {
+      getCertificateForDomain: async (domain: string, options: any) => {
+        calls.push({ domain, options });
+        return {
+          id: 'test-id',
+          domainName: 'task.vc',
+          created: Date.now(),
+          validUntil: Date.now() + 90 * 24 * 60 * 60 * 1000,
+          privateKey: '-----BEGIN PRIVATE KEY-----\nfake\n-----END PRIVATE KEY-----',
+          publicKey: '-----BEGIN CERTIFICATE-----\nfake\n-----END CERTIFICATE-----',
+          csr: '',
+        };
+      },
+    },
+  });
+
+  dcRouterRef.smartProxy.updateRoutes = async () => {};
+
+  const handler = new CertificateHandler(opsServerRef);
+  await (handler as any).reprovisionCertificateDomain('*.task.vc', true);
+
+  expect(calls.length).toBeGreaterThanOrEqual(1);
+  expect(calls[0].domain).toEqual('*.task.vc');
+  expect(calls[0].options).toEqual({ forceRenew: true, includeWildcard: false });
+});
+
+tap.test('reprovisionCertificateDomain does not call smartAcme when forceRenew is false', async () => {
+  const calls: Array<{ domain: string; options: any }> = [];
+
+  const { opsServerRef, dcRouterRef } = makeStubOpsServer({
+    routes: [{ name: 'outline-route', domains: ['outline.task.vc'] }],
+    smartAcmeStub: {
+      getCertificateForDomain: async (domain: string, options: any) => {
+        calls.push({ domain, options });
+        return {} as any;
+      },
+    },
+  });
+
+  dcRouterRef.smartProxy.updateRoutes = async () => {};
+
+  const handler = new CertificateHandler(opsServerRef);
+  await (handler as any).reprovisionCertificateDomain('outline.task.vc', false);
+
+  // forceRenew=false should NOT call getCertificateForDomain — it just triggers
+  // applyRoutes and lets the cert provisioning pipeline handle it.
+  expect(calls.length).toEqual(0);
+});
+
+export default tap.start();

test/test.dcrouter.email.ts

@@ -129,7 +129,8 @@ tap.test('DcRouter class - Email config with domains and routes', async () => {
     tls: {
       contactEmail: 'test@example.com'
     },
-    cacheConfig: {
+    opsServerPort: 3104,
+    dbConfig: {
       enabled: false,
     }
   };

test/test.dns-socket-handler.ts

@@ -9,7 +9,8 @@ tap.test('should NOT instantiate DNS server when dnsNsDomains is not set', async
     smartProxyConfig: {
       routes: []
     },
-    cacheConfig: { enabled: false }
+    opsServerPort: 3100,
+    dbConfig: { enabled: false }
   });
 
   await dcRouter.start();

test/test.http3-augmentation.ts

@@ -0,0 +1,304 @@
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import {
+  routeQualifiesForHttp3,
+  augmentRouteWithHttp3,
+  augmentRoutesWithHttp3,
+  type IHttp3Config,
+} from '../ts/http3/index.js';
+import type * as plugins from '../ts/plugins.js';
+
+// Helper to create a basic HTTPS forward route on port 443
+function makeRoute(
+  overrides: Partial<plugins.smartproxy.IRouteConfig> = {},
+): plugins.smartproxy.IRouteConfig {
+  return {
+    match: { ports: 443, ...overrides.match },
+    action: {
+      type: 'forward',
+      targets: [{ host: 'localhost', port: 8080 }],
+      tls: { mode: 'terminate', certificate: 'auto' },
+      ...overrides.action,
+    },
+    name: overrides.name ?? 'test-https-route',
+    ...Object.fromEntries(
+      Object.entries(overrides).filter(([k]) => !['match', 'action', 'name'].includes(k)),
+    ),
+  } as plugins.smartproxy.IRouteConfig;
+}
+
+const defaultConfig: IHttp3Config = { enabled: true };
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Qualification tests
+// ──────────────────────────────────────────────────────────────────────────────
+
+tap.test('should augment qualifying HTTPS route on port 443', async () => {
+  const route = makeRoute();
+  const result = augmentRouteWithHttp3(route, defaultConfig);
+
+  expect(result.match.transport).toEqual('all');
+  expect(result.action.udp).toBeTruthy();
+  expect(result.action.udp!.quic).toBeTruthy();
+  expect(result.action.udp!.quic!.enableHttp3).toBeTrue();
+  expect(result.action.udp!.quic!.altSvcMaxAge).toEqual(86400);
+});
+
+tap.test('should NOT augment route on non-443 port', async () => {
+  const route = makeRoute({ match: { ports: 8080 } });
+  const result = augmentRouteWithHttp3(route, defaultConfig);
+
+  expect(result.match.transport).toBeUndefined();
+  expect(result.action.udp).toBeUndefined();
+});
+
+tap.test('should NOT augment socket-handler type route', async () => {
+  const route = makeRoute({
+    action: {
+      type: 'socket-handler' as any,
+      socketHandler: (() => {}) as any,
+    },
+  });
+  const result = augmentRouteWithHttp3(route, defaultConfig);
+
+  expect(result.match.transport).toBeUndefined();
+});
+
+tap.test('should NOT augment route without TLS', async () => {
+  const route: plugins.smartproxy.IRouteConfig = {
+    match: { ports: 443 },
+    action: {
+      type: 'forward',
+      targets: [{ host: 'localhost', port: 8080 }],
+    },
+    name: 'no-tls-route',
+  };
+  const result = augmentRouteWithHttp3(route, defaultConfig);
+
+  expect(result.match.transport).toBeUndefined();
+});
+
+tap.test('should NOT augment email routes', async () => {
+  const emailNames = ['smtp-route', 'submission-route', 'smtps-route', 'email-port-2525-route'];
+  for (const name of emailNames) {
+    const route = makeRoute({ name });
+    const result = augmentRouteWithHttp3(route, defaultConfig);
+    expect(result.match.transport).toBeUndefined();
+  }
+});
+
+tap.test('should respect per-route opt-out (options.http3 = false)', async () => {
+  const route = makeRoute({
+    action: {
+      type: 'forward',
+      targets: [{ host: 'localhost', port: 8080 }],
+      tls: { mode: 'terminate', certificate: 'auto' },
+      options: { http3: false },
+    },
+  });
+  const result = augmentRouteWithHttp3(route, defaultConfig);
+
+  expect(result.match.transport).toBeUndefined();
+  expect(result.action.udp).toBeUndefined();
+});
+
+tap.test('should respect per-route opt-in when global is disabled', async () => {
+  const route = makeRoute({
+    action: {
+      type: 'forward',
+      targets: [{ host: 'localhost', port: 8080 }],
+      tls: { mode: 'terminate', certificate: 'auto' },
+      options: { http3: true },
+    },
+  });
+  const result = augmentRouteWithHttp3(route, { enabled: false });
+
+  expect(result.match.transport).toEqual('all');
+  expect(result.action.udp!.quic!.enableHttp3).toBeTrue();
+});
+
+tap.test('should NOT double-augment routes with transport: all', async () => {
+  const route = makeRoute({
+    match: { ports: 443, transport: 'all' as any },
+  });
+  const result = augmentRouteWithHttp3(route, defaultConfig);
+
+  // Should be the exact same object (no augmentation)
+  expect(result).toEqual(route);
+});
+
+tap.test('should NOT double-augment routes with existing udp.quic', async () => {
+  const route = makeRoute({
+    action: {
+      type: 'forward',
+      targets: [{ host: 'localhost', port: 8080 }],
+      tls: { mode: 'terminate', certificate: 'auto' },
+      udp: { quic: { enableHttp3: true } },
+    },
+  });
+  const result = augmentRouteWithHttp3(route, defaultConfig);
+
+  expect(result).toEqual(route);
+});
+
+tap.test('should augment route with port range including 443', async () => {
+  const route = makeRoute({
+    match: { ports: [{ from: 400, to: 500 }] },
+  });
+  const result = augmentRouteWithHttp3(route, defaultConfig);
+
+  expect(result.match.transport).toEqual('all');
+  expect(result.action.udp!.quic!.enableHttp3).toBeTrue();
+});
+
+tap.test('should augment route with port array including 443', async () => {
+  const route = makeRoute({
+    match: { ports: [80, 443] },
+  });
+  const result = augmentRouteWithHttp3(route, defaultConfig);
+
+  expect(result.match.transport).toEqual('all');
+  expect(result.action.udp!.quic!.enableHttp3).toBeTrue();
+});
+
+tap.test('should NOT augment route with port range NOT including 443', async () => {
+  const route = makeRoute({
+    match: { ports: [{ from: 8000, to: 9000 }] },
+  });
+  const result = augmentRouteWithHttp3(route, defaultConfig);
+
+  expect(result.match.transport).toBeUndefined();
+});
+
+tap.test('should augment TLS passthrough routes', async () => {
+  const route = makeRoute({
+    action: {
+      type: 'forward',
+      targets: [{ host: 'localhost', port: 8080 }],
+      tls: { mode: 'passthrough' },
+    },
+  });
+  const result = augmentRouteWithHttp3(route, defaultConfig);
+
+  expect(result.match.transport).toEqual('all');
+  expect(result.action.udp!.quic!.enableHttp3).toBeTrue();
+});
+
+tap.test('should augment terminate-and-reencrypt routes', async () => {
+  const route = makeRoute({
+    action: {
+      type: 'forward',
+      targets: [{ host: 'localhost', port: 8080 }],
+      tls: { mode: 'terminate-and-reencrypt', certificate: 'auto' },
+    },
+  });
+  const result = augmentRouteWithHttp3(route, defaultConfig);
+
+  expect(result.match.transport).toEqual('all');
+  expect(result.action.udp!.quic!.enableHttp3).toBeTrue();
+});
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Configuration tests
+// ──────────────────────────────────────────────────────────────────────────────
+
+tap.test('should apply default QUIC settings when none provided', async () => {
+  const route = makeRoute();
+  const result = augmentRouteWithHttp3(route, defaultConfig);
+
+  expect(result.action.udp!.quic!.altSvcMaxAge).toEqual(86400);
+  // Undefined means SmartProxy will use its own defaults
+  expect(result.action.udp!.quic!.maxIdleTimeout).toBeUndefined();
+  expect(result.action.udp!.quic!.altSvcPort).toBeUndefined();
+});
+
+tap.test('should apply custom QUIC settings', async () => {
+  const route = makeRoute();
+  const config: IHttp3Config = {
+    enabled: true,
+    quicSettings: {
+      maxIdleTimeout: 60000,
+      maxConcurrentBidiStreams: 200,
+      maxConcurrentUniStreams: 50,
+      initialCongestionWindow: 65536,
+    },
+    altSvc: {
+      port: 8443,
+      maxAge: 3600,
+    },
+    udpSettings: {
+      sessionTimeout: 120000,
+      maxSessionsPerIP: 500,
+      maxDatagramSize: 32768,
+    },
+  };
+  const result = augmentRouteWithHttp3(route, config);
+
+  expect(result.action.udp!.quic!.maxIdleTimeout).toEqual(60000);
+  expect(result.action.udp!.quic!.maxConcurrentBidiStreams).toEqual(200);
+  expect(result.action.udp!.quic!.maxConcurrentUniStreams).toEqual(50);
+  expect(result.action.udp!.quic!.initialCongestionWindow).toEqual(65536);
+  expect(result.action.udp!.quic!.altSvcPort).toEqual(8443);
+  expect(result.action.udp!.quic!.altSvcMaxAge).toEqual(3600);
+  expect(result.action.udp!.sessionTimeout).toEqual(120000);
+  expect(result.action.udp!.maxSessionsPerIP).toEqual(500);
+  expect(result.action.udp!.maxDatagramSize).toEqual(32768);
+});
+
+tap.test('should not mutate the original route', async () => {
+  const route = makeRoute();
+  const originalTransport = route.match.transport;
+  const originalUdp = route.action.udp;
+
+  augmentRouteWithHttp3(route, defaultConfig);
+
+  expect(route.match.transport).toEqual(originalTransport);
+  expect(route.action.udp).toEqual(originalUdp);
+});
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Batch augmentation
+// ──────────────────────────────────────────────────────────────────────────────
+
+tap.test('should augment multiple routes in a batch', async () => {
+  const routes = [
+    makeRoute({ name: 'web-app' }),
+    makeRoute({ name: 'smtp-route', match: { ports: 25 } }),
+    makeRoute({ name: 'api-gateway' }),
+    makeRoute({
+      name: 'dns-query',
+      action: { type: 'socket-handler' as any, socketHandler: (() => {}) as any },
+    }),
+  ];
+
+  const results = augmentRoutesWithHttp3(routes, defaultConfig);
+
+  // web-app and api-gateway should be augmented
+  expect(results[0].match.transport).toEqual('all');
+  expect(results[2].match.transport).toEqual('all');
+
+  // smtp and dns should NOT be augmented
+  expect(results[1].match.transport).toBeUndefined();
+  expect(results[3].match.transport).toBeUndefined();
+});
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Default enabled behavior
+// ──────────────────────────────────────────────────────────────────────────────
+
+tap.test('should treat undefined enabled as true (default on)', async () => {
+  const route = makeRoute();
+  const result = augmentRouteWithHttp3(route, {}); // no enabled field at all
+
+  expect(result.match.transport).toEqual('all');
+  expect(result.action.udp!.quic!.enableHttp3).toBeTrue();
+});
+
+tap.test('should disable when enabled is explicitly false', async () => {
+  const route = makeRoute();
+  const result = augmentRouteWithHttp3(route, { enabled: false });
+
+  expect(result.match.transport).toBeUndefined();
+  expect(result.action.udp).toBeUndefined();
+});
+
+export default tap.start();

test/test.jwt-auth.ts

@@ -9,7 +9,8 @@ let identity: interfaces.data.IIdentity;
 tap.test('should start DCRouter with OpsServer', async () => {
   testDcRouter = new DcRouter({
     // Minimal config for testing
-    cacheConfig: { enabled: false },
+    opsServerPort: 3102,
+    dbConfig: { enabled: false },
   });
   
   await testDcRouter.start();
@@ -18,7 +19,7 @@ tap.test('should start DCRouter with OpsServer', async () => {
 
 tap.test('should login with admin credentials and receive JWT', async () => {
   const loginRequest = new TypedRequest<interfaces.requests.IReq_AdminLoginWithUsernameAndPassword>(
-    'http://localhost:3000/typedrequest',
+    'http://localhost:3102/typedrequest',
     'adminLoginWithUsernameAndPassword'
   );
   
@@ -41,7 +42,7 @@ tap.test('should login with admin credentials and receive JWT', async () => {
 
 tap.test('should verify valid JWT identity', async () => {
   const verifyRequest = new TypedRequest<interfaces.requests.IReq_VerifyIdentity>(
-    'http://localhost:3000/typedrequest',
+    'http://localhost:3102/typedrequest',
     'verifyIdentity'
   );
   
@@ -57,7 +58,7 @@ tap.test('should verify valid JWT identity', async () => {
 
 tap.test('should reject invalid JWT', async () => {
   const verifyRequest = new TypedRequest<interfaces.requests.IReq_VerifyIdentity>(
-    'http://localhost:3000/typedrequest',
+    'http://localhost:3102/typedrequest',
     'verifyIdentity'
   );
   
@@ -74,7 +75,7 @@ tap.test('should reject invalid JWT', async () => {
 
 tap.test('should verify JWT matches identity data', async () => {
   const verifyRequest = new TypedRequest<interfaces.requests.IReq_VerifyIdentity>(
-    'http://localhost:3000/typedrequest',
+    'http://localhost:3102/typedrequest',
     'verifyIdentity'
   );
   
@@ -91,7 +92,7 @@ tap.test('should verify JWT matches identity data', async () => {
 
 tap.test('should handle logout', async () => {
   const logoutRequest = new TypedRequest<interfaces.requests.IReq_AdminLogout>(
-    'http://localhost:3000/typedrequest',
+    'http://localhost:3102/typedrequest',
     'adminLogout'
   );
   
@@ -105,7 +106,7 @@ tap.test('should handle logout', async () => {
 
 tap.test('should reject wrong credentials', async () => {
   const loginRequest = new TypedRequest<interfaces.requests.IReq_AdminLoginWithUsernameAndPassword>(
-    'http://localhost:3000/typedrequest',
+    'http://localhost:3102/typedrequest',
     'adminLoginWithUsernameAndPassword'
   );
   

test/test.opsserver-api.ts

@@ -4,27 +4,45 @@ import { TypedRequest } from '@api.global/typedrequest';
 import * as interfaces from '../ts_interfaces/index.js';
 
 let testDcRouter: DcRouter;
+let adminIdentity: interfaces.data.IIdentity;
 
 tap.test('should start DCRouter with OpsServer', async () => {
   testDcRouter = new DcRouter({
     // Minimal config for testing
-    cacheConfig: { enabled: false },
+    opsServerPort: 3101,
+    dbConfig: { enabled: false },
   });
-  
+
   await testDcRouter.start();
   expect(testDcRouter.opsServer).toBeInstanceOf(Object);
 });
 
+tap.test('should login as admin', async () => {
+  const loginRequest = new TypedRequest<interfaces.requests.IReq_AdminLoginWithUsernameAndPassword>(
+    'http://localhost:3101/typedrequest',
+    'adminLoginWithUsernameAndPassword'
+  );
+
+  const response = await loginRequest.fire({
+    username: 'admin',
+    password: 'admin',
+  });
+
+  expect(response).toHaveProperty('identity');
+  adminIdentity = response.identity;
+});
+
 tap.test('should respond to health status request', async () => {
   const healthRequest = new TypedRequest<interfaces.requests.IReq_GetHealthStatus>(
-    'http://localhost:3000/typedrequest',
+    'http://localhost:3101/typedrequest',
     'getHealthStatus'
   );
-  
+
   const response = await healthRequest.fire({
-    detailed: false
+    identity: adminIdentity,
+    detailed: false,
   });
-  
+
   expect(response).toHaveProperty('health');
   expect(response.health.healthy).toBeTrue();
   expect(response.health.services).toHaveProperty('OpsServer');
@@ -32,14 +50,15 @@ tap.test('should respond to health status request', async () => {
 
 tap.test('should respond to server statistics request', async () => {
   const statsRequest = new TypedRequest<interfaces.requests.IReq_GetServerStatistics>(
-    'http://localhost:3000/typedrequest',
+    'http://localhost:3101/typedrequest',
     'getServerStatistics'
   );
-  
+
   const response = await statsRequest.fire({
-    includeHistory: false
+    identity: adminIdentity,
+    includeHistory: false,
   });
-  
+
   expect(response).toHaveProperty('stats');
   expect(response.stats).toHaveProperty('uptime');
   expect(response.stats).toHaveProperty('cpuUsage');
@@ -48,37 +67,58 @@ tap.test('should respond to server statistics request', async () => {
 
 tap.test('should respond to configuration request', async () => {
   const configRequest = new TypedRequest<interfaces.requests.IReq_GetConfiguration>(
-    'http://localhost:3000/typedrequest',
+    'http://localhost:3101/typedrequest',
     'getConfiguration'
   );
-  
-  const response = await configRequest.fire({});
-  
+
+  const response = await configRequest.fire({
+    identity: adminIdentity,
+  });
+
   expect(response).toHaveProperty('config');
+  expect(response.config).toHaveProperty('system');
+  expect(response.config).toHaveProperty('smartProxy');
   expect(response.config).toHaveProperty('email');
   expect(response.config).toHaveProperty('dns');
-  expect(response.config).toHaveProperty('proxy');
-  expect(response.config).toHaveProperty('security');
+  expect(response.config).toHaveProperty('tls');
+  expect(response.config).toHaveProperty('cache');
+  expect(response.config).toHaveProperty('radius');
+  expect(response.config).toHaveProperty('remoteIngress');
 });
 
 tap.test('should handle log retrieval request', async () => {
   const logsRequest = new TypedRequest<interfaces.requests.IReq_GetRecentLogs>(
-    'http://localhost:3000/typedrequest',
+    'http://localhost:3101/typedrequest',
     'getRecentLogs'
   );
-  
+
   const response = await logsRequest.fire({
-    limit: 10
+    identity: adminIdentity,
+    limit: 10,
   });
-  
+
   expect(response).toHaveProperty('logs');
   expect(response).toHaveProperty('total');
   expect(response).toHaveProperty('hasMore');
   expect(response.logs).toBeArray();
 });
 
+tap.test('should reject unauthenticated requests', async () => {
+  const healthRequest = new TypedRequest<interfaces.requests.IReq_GetHealthStatus>(
+    'http://localhost:3101/typedrequest',
+    'getHealthStatus'
+  );
+
+  try {
+    await healthRequest.fire({} as any);
+    expect(true).toBeFalse(); // Should not reach here
+  } catch (error) {
+    expect(error).toBeTruthy();
+  }
+});
+
 tap.test('should stop DCRouter', async () => {
   await testDcRouter.stop();
 });
 
-export default tap.start();
+export default tap.start();

test/test.protected-endpoint.ts

@@ -9,7 +9,8 @@ let adminIdentity: interfaces.data.IIdentity;
 tap.test('should start DCRouter with OpsServer', async () => {
   testDcRouter = new DcRouter({
     // Minimal config for testing
-    cacheConfig: { enabled: false },
+    opsServerPort: 3103,
+    dbConfig: { enabled: false },
   });
 
   await testDcRouter.start();
@@ -18,7 +19,7 @@ tap.test('should start DCRouter with OpsServer', async () => {
 
 tap.test('should login as admin', async () => {
   const loginRequest = new TypedRequest<interfaces.requests.IReq_AdminLoginWithUsernameAndPassword>(
-    'http://localhost:3000/typedrequest',
+    'http://localhost:3103/typedrequest',
     'adminLoginWithUsernameAndPassword'
   );
 
@@ -34,7 +35,7 @@ tap.test('should login as admin', async () => {
 
 tap.test('should allow admin to verify identity', async () => {
   const verifyRequest = new TypedRequest<interfaces.requests.IReq_VerifyIdentity>(
-    'http://localhost:3000/typedrequest',
+    'http://localhost:3103/typedrequest',
     'verifyIdentity'
   );
 
@@ -49,7 +50,7 @@ tap.test('should allow admin to verify identity', async () => {
 
 tap.test('should reject verify identity without identity', async () => {
   const verifyRequest = new TypedRequest<interfaces.requests.IReq_VerifyIdentity>(
-    'http://localhost:3000/typedrequest',
+    'http://localhost:3103/typedrequest',
     'verifyIdentity'
   );
 
@@ -64,7 +65,7 @@ tap.test('should reject verify identity without identity', async () => {
 
 tap.test('should reject verify identity with invalid JWT', async () => {
   const verifyRequest = new TypedRequest<interfaces.requests.IReq_VerifyIdentity>(
-    'http://localhost:3000/typedrequest',
+    'http://localhost:3103/typedrequest',
     'verifyIdentity'
   );
 
@@ -82,35 +83,42 @@ tap.test('should reject verify identity with invalid JWT', async () => {
   }
 });
 
-tap.test('should allow access to public endpoints without auth', async () => {
+tap.test('should reject protected endpoints without auth', async () => {
   const healthRequest = new TypedRequest<interfaces.requests.IReq_GetHealthStatus>(
-    'http://localhost:3000/typedrequest',
+    'http://localhost:3103/typedrequest',
     'getHealthStatus'
   );
 
-  // No identity provided
-  const response = await healthRequest.fire({});
-
-  expect(response).toHaveProperty('health');
-  expect(response.health.healthy).toBeTrue();
-  console.log('Public endpoint accessible without auth');
+  try {
+    // No identity provided — should be rejected
+    await healthRequest.fire({} as any);
+    expect(true).toBeFalse(); // Should not reach here
+  } catch (error) {
+    expect(error).toBeTruthy();
+    console.log('Protected endpoint correctly rejects unauthenticated request');
+  }
 });
 
-tap.test('should allow read-only config access', async () => {
+tap.test('should allow authenticated access to protected endpoints', async () => {
   const configRequest = new TypedRequest<interfaces.requests.IReq_GetConfiguration>(
-    'http://localhost:3000/typedrequest',
+    'http://localhost:3103/typedrequest',
     'getConfiguration'
   );
 
-  // Config is read-only and doesn't require auth
-  const response = await configRequest.fire({});
+  const response = await configRequest.fire({
+    identity: adminIdentity,
+  });
 
   expect(response).toHaveProperty('config');
+  expect(response.config).toHaveProperty('system');
+  expect(response.config).toHaveProperty('smartProxy');
   expect(response.config).toHaveProperty('email');
   expect(response.config).toHaveProperty('dns');
-  expect(response.config).toHaveProperty('proxy');
-  expect(response.config).toHaveProperty('security');
-  console.log('Configuration read successfully');
+  expect(response.config).toHaveProperty('tls');
+  expect(response.config).toHaveProperty('cache');
+  expect(response.config).toHaveProperty('radius');
+  expect(response.config).toHaveProperty('remoteIngress');
+  console.log('Authenticated access to config successful');
 });
 
 tap.test('should stop DCRouter', async () => {

test/test.reference-resolver.ts

@@ -0,0 +1,371 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import { ReferenceResolver } from '../ts/config/classes.reference-resolver.js';
+import type { ISourceProfile, INetworkTarget, IRouteMetadata } from '../ts_interfaces/data/route-management.js';
+import type { IRouteConfig } from '@push.rocks/smartproxy';
+
+// ============================================================================
+// Helpers: access private maps for direct unit testing without DB
+// ============================================================================
+
+function injectProfile(resolver: ReferenceResolver, profile: ISourceProfile): void {
+  (resolver as any).profiles.set(profile.id, profile);
+}
+
+function injectTarget(resolver: ReferenceResolver, target: INetworkTarget): void {
+  (resolver as any).targets.set(target.id, target);
+}
+
+function makeProfile(overrides: Partial<ISourceProfile> = {}): ISourceProfile {
+  return {
+    id: 'profile-1',
+    name: 'STANDARD',
+    description: 'Test profile',
+    security: {
+      ipAllowList: ['192.168.0.0/16', '10.0.0.0/8'],
+      maxConnections: 1000,
+    },
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+    createdBy: 'test',
+    ...overrides,
+  };
+}
+
+function makeTarget(overrides: Partial<INetworkTarget> = {}): INetworkTarget {
+  return {
+    id: 'target-1',
+    name: 'INFRA',
+    description: 'Test target',
+    host: '192.168.5.247',
+    port: 443,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+    createdBy: 'test',
+    ...overrides,
+  };
+}
+
+function makeRoute(overrides: Partial<IRouteConfig> = {}): IRouteConfig {
+  return {
+    name: 'test-route',
+    match: { ports: 443, domains: 'test.example.com' },
+    action: { type: 'forward', targets: [{ host: 'placeholder', port: 80 }] },
+    ...overrides,
+  } as IRouteConfig;
+}
+
+// ============================================================================
+// Resolution tests
+// ============================================================================
+
+let resolver: ReferenceResolver;
+
+tap.test('should create ReferenceResolver instance', async () => {
+  resolver = new ReferenceResolver();
+  expect(resolver).toBeTruthy();
+});
+
+tap.test('should list empty profiles and targets initially', async () => {
+  expect(resolver.listProfiles()).toBeArray();
+  expect(resolver.listProfiles().length).toEqual(0);
+  expect(resolver.listTargets()).toBeArray();
+  expect(resolver.listTargets().length).toEqual(0);
+});
+
+// ---- Source profile resolution ----
+
+tap.test('should resolve source profile onto a route', async () => {
+  const profile = makeProfile();
+  injectProfile(resolver, profile);
+
+  const route = makeRoute();
+  const metadata: IRouteMetadata = { sourceProfileRef: 'profile-1' };
+
+  const result = resolver.resolveRoute(route, metadata);
+
+  expect(result.route.security).toBeTruthy();
+  expect(result.route.security!.ipAllowList).toContain('192.168.0.0/16');
+  expect(result.route.security!.ipAllowList).toContain('10.0.0.0/8');
+  expect(result.route.security!.maxConnections).toEqual(1000);
+  expect(result.metadata.sourceProfileName).toEqual('STANDARD');
+  expect(result.metadata.lastResolvedAt).toBeTruthy();
+});
+
+tap.test('should merge inline route security with profile security', async () => {
+  const route = makeRoute({
+    security: {
+      ipAllowList: ['127.0.0.1'],
+      maxConnections: 5000,
+    },
+  });
+  const metadata: IRouteMetadata = { sourceProfileRef: 'profile-1' };
+
+  const result = resolver.resolveRoute(route, metadata);
+
+  // IP lists are unioned
+  expect(result.route.security!.ipAllowList).toContain('192.168.0.0/16');
+  expect(result.route.security!.ipAllowList).toContain('10.0.0.0/8');
+  expect(result.route.security!.ipAllowList).toContain('127.0.0.1');
+
+  // Inline maxConnections overrides profile
+  expect(result.route.security!.maxConnections).toEqual(5000);
+});
+
+tap.test('should deduplicate IP lists during merge', async () => {
+  const route = makeRoute({
+    security: {
+      ipAllowList: ['192.168.0.0/16', '127.0.0.1'],
+    },
+  });
+  const metadata: IRouteMetadata = { sourceProfileRef: 'profile-1' };
+
+  const result = resolver.resolveRoute(route, metadata);
+
+  // 192.168.0.0/16 appears in both profile and route, should be deduplicated
+  const count = result.route.security!.ipAllowList!.filter(ip => ip === '192.168.0.0/16').length;
+  expect(count).toEqual(1);
+});
+
+tap.test('should handle missing profile gracefully', async () => {
+  const route = makeRoute();
+  const metadata: IRouteMetadata = { sourceProfileRef: 'nonexistent-profile' };
+
+  const result = resolver.resolveRoute(route, metadata);
+
+  // Route should be unchanged
+  expect(result.route.security).toBeUndefined();
+  expect(result.metadata.sourceProfileName).toBeUndefined();
+});
+
+// ---- Profile inheritance ----
+
+tap.test('should resolve profile inheritance (extendsProfiles)', async () => {
+  const baseProfile = makeProfile({
+    id: 'base-profile',
+    name: 'BASE',
+    security: {
+      ipAllowList: ['10.0.0.0/8'],
+      maxConnections: 500,
+    },
+  });
+  injectProfile(resolver, baseProfile);
+
+  const extendedProfile = makeProfile({
+    id: 'extended-profile',
+    name: 'EXTENDED',
+    security: {
+      ipAllowList: ['160.79.104.0/21'],
+    },
+    extendsProfiles: ['base-profile'],
+  });
+  injectProfile(resolver, extendedProfile);
+
+  const route = makeRoute();
+  const metadata: IRouteMetadata = { sourceProfileRef: 'extended-profile' };
+
+  const result = resolver.resolveRoute(route, metadata);
+
+  // Should have IPs from both base and extended profiles
+  expect(result.route.security!.ipAllowList).toContain('10.0.0.0/8');
+  expect(result.route.security!.ipAllowList).toContain('160.79.104.0/21');
+  // maxConnections from base (extended doesn't override)
+  expect(result.route.security!.maxConnections).toEqual(500);
+  expect(result.metadata.sourceProfileName).toEqual('EXTENDED');
+});
+
+tap.test('should detect circular profile inheritance', async () => {
+  const profileA = makeProfile({
+    id: 'circular-a',
+    name: 'A',
+    security: { ipAllowList: ['1.1.1.1'] },
+    extendsProfiles: ['circular-b'],
+  });
+  const profileB = makeProfile({
+    id: 'circular-b',
+    name: 'B',
+    security: { ipAllowList: ['2.2.2.2'] },
+    extendsProfiles: ['circular-a'],
+  });
+  injectProfile(resolver, profileA);
+  injectProfile(resolver, profileB);
+
+  const route = makeRoute();
+  const metadata: IRouteMetadata = { sourceProfileRef: 'circular-a' };
+
+  // Should not infinite loop — resolves what it can
+  const result = resolver.resolveRoute(route, metadata);
+  expect(result.route.security).toBeTruthy();
+  expect(result.route.security!.ipAllowList).toContain('1.1.1.1');
+});
+
+// ---- Network target resolution ----
+
+tap.test('should resolve network target onto a route', async () => {
+  const target = makeTarget();
+  injectTarget(resolver, target);
+
+  const route = makeRoute();
+  const metadata: IRouteMetadata = { networkTargetRef: 'target-1' };
+
+  const result = resolver.resolveRoute(route, metadata);
+
+  expect(result.route.action.targets).toBeTruthy();
+  expect(result.route.action.targets![0].host).toEqual('192.168.5.247');
+  expect(result.route.action.targets![0].port).toEqual(443);
+  expect(result.metadata.networkTargetName).toEqual('INFRA');
+  expect(result.metadata.lastResolvedAt).toBeTruthy();
+});
+
+tap.test('should handle missing target gracefully', async () => {
+  const route = makeRoute();
+  const metadata: IRouteMetadata = { networkTargetRef: 'nonexistent-target' };
+
+  const result = resolver.resolveRoute(route, metadata);
+
+  // Route targets should be unchanged (still the placeholder)
+  expect(result.route.action.targets![0].host).toEqual('placeholder');
+  expect(result.metadata.networkTargetName).toBeUndefined();
+});
+
+// ---- Combined resolution ----
+
+tap.test('should resolve both profile and target simultaneously', async () => {
+  const route = makeRoute();
+  const metadata: IRouteMetadata = {
+    sourceProfileRef: 'profile-1',
+    networkTargetRef: 'target-1',
+  };
+
+  const result = resolver.resolveRoute(route, metadata);
+
+  // Security from profile
+  expect(result.route.security!.ipAllowList).toContain('192.168.0.0/16');
+  expect(result.route.security!.maxConnections).toEqual(1000);
+
+  // Target from network target
+  expect(result.route.action.targets![0].host).toEqual('192.168.5.247');
+  expect(result.route.action.targets![0].port).toEqual(443);
+
+  // Both names recorded
+  expect(result.metadata.sourceProfileName).toEqual('STANDARD');
+  expect(result.metadata.networkTargetName).toEqual('INFRA');
+});
+
+tap.test('should skip resolution when no metadata refs', async () => {
+  const route = makeRoute({
+    security: { ipAllowList: ['1.2.3.4'] },
+  });
+  const metadata: IRouteMetadata = {};
+
+  const result = resolver.resolveRoute(route, metadata);
+
+  // Route should be completely unchanged
+  expect(result.route.security!.ipAllowList).toContain('1.2.3.4');
+  expect(result.route.security!.ipAllowList!.length).toEqual(1);
+  expect(result.route.action.targets![0].host).toEqual('placeholder');
+});
+
+tap.test('should be idempotent — resolving twice gives same result', async () => {
+  const route = makeRoute();
+  const metadata: IRouteMetadata = {
+    sourceProfileRef: 'profile-1',
+    networkTargetRef: 'target-1',
+  };
+
+  const first = resolver.resolveRoute(route, metadata);
+  const second = resolver.resolveRoute(first.route, first.metadata);
+
+  expect(second.route.security!.ipAllowList!.length).toEqual(first.route.security!.ipAllowList!.length);
+  expect(second.route.action.targets![0].host).toEqual(first.route.action.targets![0].host);
+  expect(second.route.action.targets![0].port).toEqual(first.route.action.targets![0].port);
+});
+
+// ---- Lookup helpers ----
+
+tap.test('should find routes by profile ref (sync)', async () => {
+  const storedRoutes = new Map<string, any>();
+  storedRoutes.set('route-a', {
+    id: 'route-a',
+    route: makeRoute({ name: 'route-a' }),
+    enabled: true,
+    metadata: { sourceProfileRef: 'profile-1' },
+  });
+  storedRoutes.set('route-b', {
+    id: 'route-b',
+    route: makeRoute({ name: 'route-b' }),
+    enabled: true,
+    metadata: { networkTargetRef: 'target-1' },
+  });
+  storedRoutes.set('route-c', {
+    id: 'route-c',
+    route: makeRoute({ name: 'route-c' }),
+    enabled: true,
+    metadata: { sourceProfileRef: 'profile-1', networkTargetRef: 'target-1' },
+  });
+
+  const profileRefs = resolver.findRoutesByProfileRefSync('profile-1', storedRoutes);
+  expect(profileRefs.length).toEqual(2);
+  expect(profileRefs).toContain('route-a');
+  expect(profileRefs).toContain('route-c');
+
+  const targetRefs = resolver.findRoutesByTargetRefSync('target-1', storedRoutes);
+  expect(targetRefs.length).toEqual(2);
+  expect(targetRefs).toContain('route-b');
+  expect(targetRefs).toContain('route-c');
+});
+
+tap.test('should get profile usage for a specific profile ID', async () => {
+  const storedRoutes = new Map<string, any>();
+  storedRoutes.set('route-x', {
+    id: 'route-x',
+    route: makeRoute({ name: 'my-route' }),
+    enabled: true,
+    metadata: { sourceProfileRef: 'profile-1' },
+  });
+
+  const usage = resolver.getProfileUsageForId('profile-1', storedRoutes);
+  expect(usage.length).toEqual(1);
+  expect(usage[0].id).toEqual('route-x');
+  expect(usage[0].routeName).toEqual('my-route');
+});
+
+tap.test('should get target usage for a specific target ID', async () => {
+  const storedRoutes = new Map<string, any>();
+  storedRoutes.set('route-y', {
+    id: 'route-y',
+    route: makeRoute({ name: 'other-route' }),
+    enabled: true,
+    metadata: { networkTargetRef: 'target-1' },
+  });
+
+  const usage = resolver.getTargetUsageForId('target-1', storedRoutes);
+  expect(usage.length).toEqual(1);
+  expect(usage[0].id).toEqual('route-y');
+  expect(usage[0].routeName).toEqual('other-route');
+});
+
+// ---- Profile/target getters ----
+
+tap.test('should get profile by name', async () => {
+  const profile = resolver.getProfileByName('STANDARD');
+  expect(profile).toBeTruthy();
+  expect(profile!.id).toEqual('profile-1');
+});
+
+tap.test('should get target by name', async () => {
+  const target = resolver.getTargetByName('INFRA');
+  expect(target).toBeTruthy();
+  expect(target!.id).toEqual('target-1');
+});
+
+tap.test('should return undefined for nonexistent profile name', async () => {
+  const profile = resolver.getProfileByName('NONEXISTENT');
+  expect(profile).toBeUndefined();
+});
+
+tap.test('should return undefined for nonexistent target name', async () => {
+  const target = resolver.getTargetByName('NONEXISTENT');
+  expect(target).toBeUndefined();
+});
+
+export default tap.start();

test/test.source-profiles-api.ts

@@ -0,0 +1,208 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import { DcRouter } from '../ts/index.js';
+import { TypedRequest } from '@api.global/typedrequest';
+import * as interfaces from '../ts_interfaces/index.js';
+
+const TEST_PORT = 3200;
+const TEST_URL = `http://localhost:${TEST_PORT}/typedrequest`;
+
+let testDcRouter: DcRouter;
+let adminIdentity: interfaces.data.IIdentity;
+
+// ============================================================================
+// Setup — db disabled, handlers return graceful fallbacks
+// ============================================================================
+
+tap.test('should start DCRouter with OpsServer', async () => {
+  testDcRouter = new DcRouter({
+    opsServerPort: TEST_PORT,
+    dbConfig: { enabled: false },
+  });
+
+  await testDcRouter.start();
+  expect(testDcRouter.opsServer).toBeInstanceOf(Object);
+});
+
+tap.test('should login as admin', async () => {
+  const loginRequest = new TypedRequest<interfaces.requests.IReq_AdminLoginWithUsernameAndPassword>(
+    TEST_URL,
+    'adminLoginWithUsernameAndPassword'
+  );
+
+  const response = await loginRequest.fire({
+    username: 'admin',
+    password: 'admin',
+  });
+
+  expect(response).toHaveProperty('identity');
+  adminIdentity = response.identity;
+});
+
+// ============================================================================
+// Source Profile endpoints (graceful fallbacks when resolver unavailable)
+// ============================================================================
+
+tap.test('should return empty profiles list when resolver not initialized', async () => {
+  const req = new TypedRequest<interfaces.requests.IReq_GetSourceProfiles>(
+    TEST_URL,
+    'getSourceProfiles'
+  );
+
+  const response = await req.fire({
+    identity: adminIdentity,
+  });
+
+  expect(response.profiles).toBeArray();
+  expect(response.profiles.length).toEqual(0);
+});
+
+tap.test('should return null for single profile when resolver not initialized', async () => {
+  const req = new TypedRequest<interfaces.requests.IReq_GetSourceProfile>(
+    TEST_URL,
+    'getSourceProfile'
+  );
+
+  const response = await req.fire({
+    identity: adminIdentity,
+    id: 'nonexistent',
+  });
+
+  expect(response.profile).toEqual(null);
+});
+
+tap.test('should return failure for create profile when resolver not initialized', async () => {
+  const req = new TypedRequest<interfaces.requests.IReq_CreateSourceProfile>(
+    TEST_URL,
+    'createSourceProfile'
+  );
+
+  const response = await req.fire({
+    identity: adminIdentity,
+    name: 'TEST',
+    security: { ipAllowList: ['*'] },
+  });
+
+  expect(response.success).toBeFalse();
+  expect(response.message).toBeTruthy();
+});
+
+tap.test('should return empty profile usage when resolver not initialized', async () => {
+  const req = new TypedRequest<interfaces.requests.IReq_GetSourceProfileUsage>(
+    TEST_URL,
+    'getSourceProfileUsage'
+  );
+
+  const response = await req.fire({
+    identity: adminIdentity,
+    id: 'nonexistent',
+  });
+
+  expect(response.routes).toBeArray();
+  expect(response.routes.length).toEqual(0);
+});
+
+// ============================================================================
+// Network Target endpoints (graceful fallbacks when resolver unavailable)
+// ============================================================================
+
+tap.test('should return empty targets list when resolver not initialized', async () => {
+  const req = new TypedRequest<interfaces.requests.IReq_GetNetworkTargets>(
+    TEST_URL,
+    'getNetworkTargets'
+  );
+
+  const response = await req.fire({
+    identity: adminIdentity,
+  });
+
+  expect(response.targets).toBeArray();
+  expect(response.targets.length).toEqual(0);
+});
+
+tap.test('should return null for single target when resolver not initialized', async () => {
+  const req = new TypedRequest<interfaces.requests.IReq_GetNetworkTarget>(
+    TEST_URL,
+    'getNetworkTarget'
+  );
+
+  const response = await req.fire({
+    identity: adminIdentity,
+    id: 'nonexistent',
+  });
+
+  expect(response.target).toEqual(null);
+});
+
+tap.test('should return failure for create target when resolver not initialized', async () => {
+  const req = new TypedRequest<interfaces.requests.IReq_CreateNetworkTarget>(
+    TEST_URL,
+    'createNetworkTarget'
+  );
+
+  const response = await req.fire({
+    identity: adminIdentity,
+    name: 'TEST',
+    host: '127.0.0.1',
+    port: 443,
+  });
+
+  expect(response.success).toBeFalse();
+  expect(response.message).toBeTruthy();
+});
+
+tap.test('should return empty target usage when resolver not initialized', async () => {
+  const req = new TypedRequest<interfaces.requests.IReq_GetNetworkTargetUsage>(
+    TEST_URL,
+    'getNetworkTargetUsage'
+  );
+
+  const response = await req.fire({
+    identity: adminIdentity,
+    id: 'nonexistent',
+  });
+
+  expect(response.routes).toBeArray();
+  expect(response.routes.length).toEqual(0);
+});
+
+// ============================================================================
+// Auth rejection
+// ============================================================================
+
+tap.test('should reject unauthenticated profile requests', async () => {
+  const req = new TypedRequest<interfaces.requests.IReq_GetSourceProfiles>(
+    TEST_URL,
+    'getSourceProfiles'
+  );
+
+  try {
+    await req.fire({} as any);
+    expect(true).toBeFalse();
+  } catch (error) {
+    expect(error).toBeTruthy();
+  }
+});
+
+tap.test('should reject unauthenticated target requests', async () => {
+  const req = new TypedRequest<interfaces.requests.IReq_GetNetworkTargets>(
+    TEST_URL,
+    'getNetworkTargets'
+  );
+
+  try {
+    await req.fire({} as any);
+    expect(true).toBeFalse();
+  } catch (error) {
+    expect(error).toBeTruthy();
+  }
+});
+
+// ============================================================================
+// Cleanup
+// ============================================================================
+
+tap.test('should stop DCRouter', async () => {
+  await testDcRouter.stop();
+});
+
+export default tap.start();

test/test.storagemanager.ts

@@ -1,289 +0,0 @@
-import { tap, expect } from '@git.zone/tstest/tapbundle';
-import * as plugins from '../ts/plugins.js';
-import * as paths from '../ts/paths.js';
-import { StorageManager } from '../ts/storage/classes.storagemanager.js';
-import { promises as fs } from 'fs';
-import * as path from 'path';
-
-// Test data
-const testData = {
-  string: 'Hello, World!',
-  json: { name: 'test', value: 42, nested: { data: true } },
-  largeString: 'x'.repeat(10000)
-};
-
-tap.test('Storage Manager - Memory Backend', async () => {
-  // Create StorageManager without config (defaults to memory)
-  const storage = new StorageManager();
-  
-  // Test basic get/set
-  await storage.set('/test/key', testData.string);
-  const value = await storage.get('/test/key');
-  expect(value).toEqual(testData.string);
-  
-  // Test JSON helpers
-  await storage.setJSON('/test/json', testData.json);
-  const jsonValue = await storage.getJSON('/test/json');
-  expect(jsonValue).toEqual(testData.json);
-  
-  // Test exists
-  expect(await storage.exists('/test/key')).toEqual(true);
-  expect(await storage.exists('/nonexistent')).toEqual(false);
-  
-  // Test delete
-  await storage.delete('/test/key');
-  expect(await storage.exists('/test/key')).toEqual(false);
-  
-  // Test list
-  await storage.set('/items/1', 'one');
-  await storage.set('/items/2', 'two');
-  await storage.set('/other/3', 'three');
-  
-  const items = await storage.list('/items');
-  expect(items.length).toEqual(2);
-  expect(items).toContain('/items/1');
-  expect(items).toContain('/items/2');
-  
-  // Verify memory backend
-  expect(storage.getBackend()).toEqual('memory');
-});
-
-tap.test('Storage Manager - Filesystem Backend', async () => {
-  const testDir = path.join(paths.dataDir, '.test-storage');
-  
-  // Clean up test directory if it exists
-  try {
-    await fs.rm(testDir, { recursive: true, force: true });
-  } catch {}
-  
-  // Create StorageManager with filesystem path
-  const storage = new StorageManager({ fsPath: testDir });
-  
-  // Test basic operations
-  await storage.set('/test/file', testData.string);
-  const value = await storage.get('/test/file');
-  expect(value).toEqual(testData.string);
-  
-  // Verify file exists on disk
-  const filePath = path.join(testDir, 'test', 'file');
-  const fileExists = await fs.access(filePath).then(() => true).catch(() => false);
-  expect(fileExists).toEqual(true);
-  
-  // Test atomic writes (temp file should not exist)
-  const tempPath = filePath + '.tmp';
-  const tempExists = await fs.access(tempPath).then(() => true).catch(() => false);
-  expect(tempExists).toEqual(false);
-  
-  // Test nested paths
-  await storage.set('/deeply/nested/path/to/file', testData.largeString);
-  const nestedValue = await storage.get('/deeply/nested/path/to/file');
-  expect(nestedValue).toEqual(testData.largeString);
-  
-  // Test list with filesystem
-  await storage.set('/fs/items/a', 'alpha');
-  await storage.set('/fs/items/b', 'beta');
-  await storage.set('/fs/other/c', 'gamma');
-  
-  // Filesystem backend now properly supports list
-  const fsItems = await storage.list('/fs/items');
-  expect(fsItems.length).toEqual(2); // Should find both items
-  
-  // Clean up
-  await fs.rm(testDir, { recursive: true, force: true });
-});
-
-tap.test('Storage Manager - Custom Function Backend', async () => {
-  // Create in-memory storage for custom functions
-  const customStore = new Map<string, string>();
-  
-  const storage = new StorageManager({
-    readFunction: async (key: string) => {
-      return customStore.get(key) || null;
-    },
-    writeFunction: async (key: string, value: string) => {
-      customStore.set(key, value);
-    }
-  });
-  
-  // Test basic operations
-  await storage.set('/custom/key', testData.string);
-  expect(customStore.has('/custom/key')).toEqual(true);
-  
-  const value = await storage.get('/custom/key');
-  expect(value).toEqual(testData.string);
-  
-  // Test that delete sets empty value (as per implementation)
-  await storage.delete('/custom/key');
-  expect(customStore.get('/custom/key')).toEqual('');
-  
-  // Verify custom backend (filesystem is implemented as custom backend internally)
-  expect(storage.getBackend()).toEqual('custom');
-});
-
-tap.test('Storage Manager - Key Validation', async () => {
-  const storage = new StorageManager();
-  
-  // Test key normalization
-  await storage.set('test/key', 'value1'); // Missing leading slash
-  const value1 = await storage.get('/test/key');
-  expect(value1).toEqual('value1');
-  
-  // Test dangerous path elements are removed
-  await storage.set('/test/../danger/key', 'value2');
-  const value2 = await storage.get('/test/danger/key'); // .. is removed, not the whole path segment
-  expect(value2).toEqual('value2');
-  
-  // Test multiple slashes are normalized
-  await storage.set('/test///multiple////slashes', 'value3');
-  const value3 = await storage.get('/test/multiple/slashes');
-  expect(value3).toEqual('value3');
-  
-  // Test invalid keys throw errors
-  let emptyKeyError: Error | null = null;
-  try {
-    await storage.set('', 'value');
-  } catch (error) {
-    emptyKeyError = error as Error;
-  }
-  expect(emptyKeyError).toBeTruthy();
-  expect(emptyKeyError?.message).toEqual('Storage key must be a non-empty string');
-  
-  let nullKeyError: Error | null = null;
-  try {
-    await storage.set(null as any, 'value');
-  } catch (error) {
-    nullKeyError = error as Error;
-  }
-  expect(nullKeyError).toBeTruthy();
-  expect(nullKeyError?.message).toEqual('Storage key must be a non-empty string');
-});
-
-tap.test('Storage Manager - Concurrent Access', async () => {
-  const storage = new StorageManager();
-  const promises: Promise<void>[] = [];
-  
-  // Simulate concurrent writes
-  for (let i = 0; i < 100; i++) {
-    promises.push(storage.set(`/concurrent/key${i}`, `value${i}`));
-  }
-  
-  await Promise.all(promises);
-  
-  // Verify all writes succeeded
-  for (let i = 0; i < 100; i++) {
-    const value = await storage.get(`/concurrent/key${i}`);
-    expect(value).toEqual(`value${i}`);
-  }
-  
-  // Test concurrent reads
-  const readPromises: Promise<string | null>[] = [];
-  for (let i = 0; i < 100; i++) {
-    readPromises.push(storage.get(`/concurrent/key${i}`));
-  }
-  
-  const results = await Promise.all(readPromises);
-  for (let i = 0; i < 100; i++) {
-    expect(results[i]).toEqual(`value${i}`);
-  }
-});
-
-tap.test('Storage Manager - Backend Priority', async () => {
-  const testDir = path.join(paths.dataDir, '.test-storage-priority');
-  
-  // Test that custom functions take priority over fsPath
-  let warningLogged = false;
-  const originalWarn = console.warn;
-  console.warn = (message: string) => {
-    if (message.includes('Using custom read/write functions')) {
-      warningLogged = true;
-    }
-  };
-  
-  const storage = new StorageManager({
-    fsPath: testDir,
-    readFunction: async () => 'custom-value',
-    writeFunction: async () => {}
-  });
-  
-  console.warn = originalWarn;
-  
-  expect(warningLogged).toEqual(true);
-  expect(storage.getBackend()).toEqual('custom'); // Custom functions take priority
-  
-  // Clean up
-  try {
-    await fs.rm(testDir, { recursive: true, force: true });
-  } catch {}
-});
-
-tap.test('Storage Manager - Error Handling', async () => {
-  // Test filesystem errors
-  const storage = new StorageManager({
-    readFunction: async () => {
-      throw new Error('Read error');
-    },
-    writeFunction: async () => {
-      throw new Error('Write error');
-    }
-  });
-  
-  // Read errors should return null
-  const value = await storage.get('/error/key');
-  expect(value).toEqual(null);
-  
-  // Write errors should propagate
-  let writeError: Error | null = null;
-  try {
-    await storage.set('/error/key', 'value');
-  } catch (error) {
-    writeError = error as Error;
-  }
-  expect(writeError).toBeTruthy();
-  expect(writeError?.message).toEqual('Write error');
-  
-  // Test JSON parse errors
-  const jsonStorage = new StorageManager({
-    readFunction: async () => 'invalid json',
-    writeFunction: async () => {}
-  });
-  
-  // Test JSON parse errors
-  let jsonError: Error | null = null;
-  try {
-    await jsonStorage.getJSON('/invalid/json');
-  } catch (error) {
-    jsonError = error as Error;
-  }
-  expect(jsonError).toBeTruthy();
-  expect(jsonError?.message).toContain('JSON');
-});
-
-tap.test('Storage Manager - List Operations', async () => {
-  const storage = new StorageManager();
-  
-  // Populate storage with hierarchical data
-  await storage.set('/app/config/database', 'db-config');
-  await storage.set('/app/config/cache', 'cache-config');
-  await storage.set('/app/data/users/1', 'user1');
-  await storage.set('/app/data/users/2', 'user2');
-  await storage.set('/app/logs/error.log', 'errors');
-  
-  // List root
-  const rootItems = await storage.list('/');
-  expect(rootItems.length).toBeGreaterThanOrEqual(5);
-  
-  // List specific paths
-  const configItems = await storage.list('/app/config');
-  expect(configItems.length).toEqual(2);
-  expect(configItems).toContain('/app/config/database');
-  expect(configItems).toContain('/app/config/cache');
-  
-  const userItems = await storage.list('/app/data/users');
-  expect(userItems.length).toEqual(2);
-  
-  // List non-existent path
-  const emptyList = await storage.list('/nonexistent/path');
-  expect(emptyList.length).toEqual(0);
-});
-
-export default tap.start();

test_watch/devserver.ts

@@ -1,21 +1,55 @@
 import { DcRouter } from '../ts/index.js';
 
 const devRouter = new DcRouter({
-  // Configure services as needed for development
-  // OpsServer always starts on port 3000
-
-  // Example: Add SmartProxy routes
-  // smartProxyConfig: {
-  //   routes: [...]
-  // },
-
-  // Example: Add email configuration
-  // emailConfig: {
-  //   ports: [2525],
-  //   hostname: 'localhost',
-  //   domains: [],
-  //   routes: []
-  // },
+  // Server public IP (used for VPN AllowedIPs)
+  publicIp: '203.0.113.1',
+  // SmartProxy routes for development/demo
+  smartProxyConfig: {
+    routes: [
+      {
+        name: 'web-traffic',
+        match: { ports: [18080], domains: ['example.com', '*.example.com'] },
+        action: { type: 'forward', targets: [{ host: 'localhost', port: 3001 }] },
+      },
+      {
+        name: 'api-gateway',
+        match: { ports: [18080], domains: ['api.example.com'], path: '/v1/*' },
+        action: { type: 'forward', targets: [{ host: 'localhost', port: 4000 }] },
+      },
+      {
+        name: 'tls-passthrough',
+        match: { ports: [18443], domains: ['secure.example.com'] },
+        action: {
+          type: 'forward',
+          targets: [{ host: 'localhost', port: 4443 }],
+          tls: { mode: 'passthrough' },
+        },
+      },
+      {
+        name: 'vpn-internal-app',
+        match: { ports: [18080], domains: ['internal.example.com'] },
+        action: { type: 'forward', targets: [{ host: 'localhost', port: 5000 }] },
+        vpnOnly: true,
+      },
+      {
+        name: 'vpn-eng-dashboard',
+        match: { ports: [18080], domains: ['eng.example.com'] },
+        action: { type: 'forward', targets: [{ host: 'localhost', port: 5001 }] },
+        vpnOnly: true,
+      },
+    ] as any[],
+  },
+  // VPN with pre-defined clients
+  vpnConfig: {
+    enabled: true,
+    serverEndpoint: 'vpn.dev.local',
+    clients: [
+      { clientId: 'dev-laptop', description: 'Developer laptop' },
+      { clientId: 'ci-runner', description: 'CI/CD pipeline' },
+      { clientId: 'admin-desktop', description: 'Admin workstation' },
+    ],
+  },
+  dbConfig: { enabled: true },
 });
 
 console.log('Starting DcRouter in development mode...');

ts/00_commitinfo_data.ts

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

ts/acme/index.ts

@@ -0,0 +1 @@
+export * from './manager.acme-config.js';

ts/acme/manager.acme-config.ts

@@ -0,0 +1,182 @@
+import { logger } from '../logger.js';
+import { AcmeConfigDoc } from '../db/documents/index.js';
+import type { IDcRouterOptions } from '../classes.dcrouter.js';
+import type { IAcmeConfig } from '../../ts_interfaces/data/acme-config.js';
+
+/**
+ * AcmeConfigManager — owns the singleton ACME configuration in the DB.
+ *
+ * Lifecycle:
+ *  - `start()` — loads from the DB; if empty, seeds from legacy constructor
+ *    fields (`tls.contactEmail`, `smartProxyConfig.acme.*`) on first boot.
+ *  - `getConfig()` — returns the in-memory cached `IAcmeConfig` (or null)
+ *  - `updateConfig(args, updatedBy)` — upserts and refreshes the cache
+ *
+ * Reload semantics: updates take effect on the next dcrouter restart because
+ * `SmartAcme` is instantiated once in `setupSmartProxy()`. `renewThresholdDays`
+ * applies immediately to the next renewal check. See
+ * `ts_web/elements/domains/ops-view-certificates.ts` for the UI warning.
+ */
+export class AcmeConfigManager {
+  private cached: IAcmeConfig | null = null;
+
+  constructor(private options: IDcRouterOptions) {}
+
+  public async start(): Promise<void> {
+    logger.log('info', 'AcmeConfigManager: starting');
+    let doc = await AcmeConfigDoc.load();
+
+    if (!doc) {
+      // First-boot path: seed from legacy constructor fields if present.
+      const seed = this.deriveSeedFromOptions();
+      if (seed) {
+        doc = await this.createSeedDoc(seed);
+        logger.log(
+          'info',
+          `AcmeConfigManager: seeded from constructor legacy fields (accountEmail=${seed.accountEmail}, useProduction=${seed.useProduction})`,
+        );
+      } else {
+        logger.log(
+          'info',
+          'AcmeConfigManager: no AcmeConfig in DB and no legacy constructor fields — ACME disabled until configured via Domains > Certificates > Settings.',
+        );
+      }
+    } else if (this.deriveSeedFromOptions()) {
+      logger.log(
+        'warn',
+        'AcmeConfigManager: ignoring constructor tls.contactEmail / smartProxyConfig.acme — DB already has AcmeConfigDoc. Manage via Domains > Certificates > Settings.',
+      );
+    }
+
+    this.cached = doc ? this.toPlain(doc) : null;
+    if (this.cached) {
+      logger.log(
+        'info',
+        `AcmeConfigManager: loaded ACME config (accountEmail=${this.cached.accountEmail}, enabled=${this.cached.enabled}, useProduction=${this.cached.useProduction})`,
+      );
+    }
+  }
+
+  public async stop(): Promise<void> {
+    this.cached = null;
+  }
+
+  /**
+   * Returns the current ACME config, or null if not configured.
+   * In-memory — does not hit the DB.
+   */
+  public getConfig(): IAcmeConfig | null {
+    return this.cached;
+  }
+
+  /**
+   * True if there is an enabled ACME config. Used by `setupSmartProxy()` to
+   * decide whether to instantiate SmartAcme.
+   */
+  public hasEnabledConfig(): boolean {
+    return this.cached !== null && this.cached.enabled;
+  }
+
+  /**
+   * Upsert the ACME config. All fields are optional; missing fields are
+   * preserved from the existing row (or defaulted if there is no row yet).
+   */
+  public async updateConfig(
+    args: Partial<Omit<IAcmeConfig, 'updatedAt' | 'updatedBy'>>,
+    updatedBy: string,
+  ): Promise<IAcmeConfig> {
+    let doc = await AcmeConfigDoc.load();
+    const now = Date.now();
+
+    if (!doc) {
+      doc = new AcmeConfigDoc();
+      doc.configId = 'acme-config';
+      doc.accountEmail = args.accountEmail ?? '';
+      doc.enabled = args.enabled ?? true;
+      doc.useProduction = args.useProduction ?? true;
+      doc.autoRenew = args.autoRenew ?? true;
+      doc.renewThresholdDays = args.renewThresholdDays ?? 30;
+    } else {
+      if (args.accountEmail !== undefined) doc.accountEmail = args.accountEmail;
+      if (args.enabled !== undefined) doc.enabled = args.enabled;
+      if (args.useProduction !== undefined) doc.useProduction = args.useProduction;
+      if (args.autoRenew !== undefined) doc.autoRenew = args.autoRenew;
+      if (args.renewThresholdDays !== undefined) doc.renewThresholdDays = args.renewThresholdDays;
+    }
+
+    doc.updatedAt = now;
+    doc.updatedBy = updatedBy;
+    await doc.save();
+
+    this.cached = this.toPlain(doc);
+    return this.cached;
+  }
+
+  // ==========================================================================
+  // Internal helpers
+  // ==========================================================================
+
+  /**
+   * Build a seed object from the legacy constructor fields. Returns null
+   * if the user has not provided any of them.
+   *
+   * Supports BOTH `tls.contactEmail` (short form) and `smartProxyConfig.acme`
+   * (full form). `smartProxyConfig.acme` wins when both are present.
+   */
+  private deriveSeedFromOptions(): Omit<IAcmeConfig, 'updatedAt' | 'updatedBy'> | null {
+    const acme = this.options.smartProxyConfig?.acme;
+    const tls = this.options.tls;
+
+    // Prefer the explicit smartProxyConfig.acme block if present.
+    if (acme?.accountEmail) {
+      return {
+        accountEmail: acme.accountEmail,
+        enabled: acme.enabled !== false,
+        useProduction: acme.useProduction !== false,
+        autoRenew: acme.autoRenew !== false,
+        renewThresholdDays: acme.renewThresholdDays ?? 30,
+      };
+    }
+
+    // Fall back to the short tls.contactEmail form.
+    if (tls?.contactEmail) {
+      return {
+        accountEmail: tls.contactEmail,
+        enabled: true,
+        useProduction: true,
+        autoRenew: true,
+        renewThresholdDays: 30,
+      };
+    }
+
+    return null;
+  }
+
+  private async createSeedDoc(
+    seed: Omit<IAcmeConfig, 'updatedAt' | 'updatedBy'>,
+  ): Promise<AcmeConfigDoc> {
+    const doc = new AcmeConfigDoc();
+    doc.configId = 'acme-config';
+    doc.accountEmail = seed.accountEmail;
+    doc.enabled = seed.enabled;
+    doc.useProduction = seed.useProduction;
+    doc.autoRenew = seed.autoRenew;
+    doc.renewThresholdDays = seed.renewThresholdDays;
+    doc.updatedAt = Date.now();
+    doc.updatedBy = 'seed';
+    await doc.save();
+    return doc;
+  }
+
+  private toPlain(doc: AcmeConfigDoc): IAcmeConfig {
+    return {
+      accountEmail: doc.accountEmail,
+      enabled: doc.enabled,
+      useProduction: doc.useProduction,
+      autoRenew: doc.autoRenew,
+      renewThresholdDays: doc.renewThresholdDays,
+      updatedAt: doc.updatedAt,
+      updatedBy: doc.updatedBy,
+    };
+  }
+}

ts/cache/classes.cachedb.ts

@@ -1,155 +0,0 @@
-import * as plugins from '../plugins.js';
-import { logger } from '../logger.js';
-import { defaultTsmDbPath } from '../paths.js';
-
-/**
- * Configuration options for CacheDb
- */
-export interface ICacheDbOptions {
-  /** Base storage path for TsmDB data (default: ~/.serve.zone/dcrouter/tsmdb) */
-  storagePath?: string;
-  /** Database name (default: dcrouter) */
-  dbName?: string;
-  /** Enable debug logging */
-  debug?: boolean;
-}
-
-/**
- * CacheDb - Wrapper around LocalTsmDb and smartdata
- *
- * Provides persistent caching using smartdata as the ORM layer
- * and LocalTsmDb as the embedded database engine.
- */
-export class CacheDb {
-  private static instance: CacheDb | null = null;
-
-  private localTsmDb: plugins.smartmongo.LocalTsmDb;
-  private smartdataDb: plugins.smartdata.SmartdataDb;
-  private options: Required<ICacheDbOptions>;
-  private isStarted: boolean = false;
-
-  constructor(options: ICacheDbOptions = {}) {
-    this.options = {
-      storagePath: options.storagePath || defaultTsmDbPath,
-      dbName: options.dbName || 'dcrouter',
-      debug: options.debug || false,
-    };
-  }
-
-  /**
-   * Get or create the singleton instance
-   */
-  public static getInstance(options?: ICacheDbOptions): CacheDb {
-    if (!CacheDb.instance) {
-      CacheDb.instance = new CacheDb(options);
-    }
-    return CacheDb.instance;
-  }
-
-  /**
-   * Reset the singleton instance (useful for testing)
-   */
-  public static resetInstance(): void {
-    CacheDb.instance = null;
-  }
-
-  /**
-   * Start the cache database
-   * - Initializes LocalTsmDb with file persistence
-   * - Connects smartdata to the LocalTsmDb via Unix socket
-   */
-  public async start(): Promise<void> {
-    if (this.isStarted) {
-      logger.log('warn', 'CacheDb already started');
-      return;
-    }
-
-    try {
-      // Ensure storage directory exists
-      await plugins.fsUtils.ensureDir(this.options.storagePath);
-
-      // Create LocalTsmDb instance
-      this.localTsmDb = new plugins.smartmongo.LocalTsmDb({
-        folderPath: this.options.storagePath,
-      });
-
-      // Start LocalTsmDb and get connection info
-      const connectionInfo = await this.localTsmDb.start();
-
-      if (this.options.debug) {
-        logger.log('debug', `LocalTsmDb started with URI: ${connectionInfo.connectionUri}`);
-      }
-
-      // Initialize smartdata with the connection URI
-      this.smartdataDb = new plugins.smartdata.SmartdataDb({
-        mongoDbUrl: connectionInfo.connectionUri,
-        mongoDbName: this.options.dbName,
-      });
-      await this.smartdataDb.init();
-
-      this.isStarted = true;
-      logger.log('info', `CacheDb started at ${this.options.storagePath}`);
-    } catch (error) {
-      logger.log('error', `Failed to start CacheDb: ${error.message}`);
-      throw error;
-    }
-  }
-
-  /**
-   * Stop the cache database
-   */
-  public async stop(): Promise<void> {
-    if (!this.isStarted) {
-      return;
-    }
-
-    try {
-      // Close smartdata connection
-      if (this.smartdataDb) {
-        await this.smartdataDb.close();
-      }
-
-      // Stop LocalTsmDb
-      if (this.localTsmDb) {
-        await this.localTsmDb.stop();
-      }
-
-      this.isStarted = false;
-      logger.log('info', 'CacheDb stopped');
-    } catch (error) {
-      logger.log('error', `Error stopping CacheDb: ${error.message}`);
-      throw error;
-    }
-  }
-
-  /**
-   * Get the smartdata database instance
-   */
-  public getDb(): plugins.smartdata.SmartdataDb {
-    if (!this.isStarted) {
-      throw new Error('CacheDb not started. Call start() first.');
-    }
-    return this.smartdataDb;
-  }
-
-  /**
-   * Check if the database is ready
-   */
-  public isReady(): boolean {
-    return this.isStarted;
-  }
-
-  /**
-   * Get the storage path
-   */
-  public getStoragePath(): string {
-    return this.options.storagePath;
-  }
-
-  /**
-   * Get the database name
-   */
-  public getDbName(): string {
-    return this.options.dbName;
-  }
-}

ts/cache/documents/index.ts

@@ -1,2 +0,0 @@
-export * from './classes.cached.email.js';
-export * from './classes.cached.ip.reputation.js';

ts/classes.cert-provision-scheduler.ts

@@ -0,0 +1,165 @@
+import { logger } from './logger.js';
+import { CertBackoffDoc } from './db/index.js';
+
+interface IBackoffEntry {
+  failures: number;
+  lastFailure: string; // ISO string
+  retryAfter: string;  // ISO string
+  lastError?: string;
+}
+
+/**
+ * Manages certificate provisioning scheduling with:
+ * - Per-domain exponential backoff persisted via CertBackoffDoc
+ *
+ * Note: Serial stagger queue was removed — smartacme v9 handles
+ * concurrency, per-domain dedup, and rate limiting internally.
+ */
+export class CertProvisionScheduler {
+  private maxBackoffHours: number;
+
+  // In-memory backoff cache (mirrors storage for fast lookups)
+  private backoffCache = new Map<string, IBackoffEntry>();
+
+  constructor(
+    options?: { maxBackoffHours?: number }
+  ) {
+    this.maxBackoffHours = options?.maxBackoffHours ?? 24;
+  }
+
+  /**
+   * Sanitized domain key for storage lookups
+   */
+  private sanitizeDomain(domain: string): string {
+    return domain.replace(/\*/g, '_wildcard_').replace(/[^a-zA-Z0-9._-]/g, '_');
+  }
+
+  /**
+   * Load backoff entry from database (with in-memory cache)
+   */
+  private async loadBackoff(domain: string): Promise<IBackoffEntry | null> {
+    const cached = this.backoffCache.get(domain);
+    if (cached) return cached;
+
+    const sanitized = this.sanitizeDomain(domain);
+    const doc = await CertBackoffDoc.findByDomain(sanitized);
+    if (doc) {
+      const entry: IBackoffEntry = {
+        failures: doc.failures,
+        lastFailure: doc.lastFailure,
+        retryAfter: doc.retryAfter,
+        lastError: doc.lastError,
+      };
+      this.backoffCache.set(domain, entry);
+      return entry;
+    }
+    return null;
+  }
+
+  /**
+   * Save backoff entry to both cache and database
+   */
+  private async saveBackoff(domain: string, entry: IBackoffEntry): Promise<void> {
+    this.backoffCache.set(domain, entry);
+    const sanitized = this.sanitizeDomain(domain);
+    let doc = await CertBackoffDoc.findByDomain(sanitized);
+    if (!doc) {
+      doc = new CertBackoffDoc();
+      doc.domain = sanitized;
+    }
+    doc.failures = entry.failures;
+    doc.lastFailure = entry.lastFailure;
+    doc.retryAfter = entry.retryAfter;
+    doc.lastError = entry.lastError || '';
+    await doc.save();
+  }
+
+  /**
+   * Check if a domain is currently in backoff.
+   * Expired entries are pruned from the cache to prevent unbounded growth.
+   */
+  async isInBackoff(domain: string): Promise<boolean> {
+    const entry = await this.loadBackoff(domain);
+    if (!entry) return false;
+
+    const retryAfter = new Date(entry.retryAfter);
+    if (retryAfter.getTime() > Date.now()) {
+      return true;
+    }
+
+    // Backoff has expired — prune the stale entry
+    this.backoffCache.delete(domain);
+    return false;
+  }
+
+  /**
+   * Record a provisioning failure for a domain.
+   * Sets exponential backoff: min(failures^2 * 1h, maxBackoffHours)
+   */
+  async recordFailure(domain: string, error?: string): Promise<void> {
+    const existing = await this.loadBackoff(domain);
+    const failures = (existing?.failures ?? 0) + 1;
+
+    // Exponential backoff: failures^2 hours, capped
+    const backoffHours = Math.min(failures * failures, this.maxBackoffHours);
+    const retryAfter = new Date(Date.now() + backoffHours * 60 * 60 * 1000);
+
+    const entry: IBackoffEntry = {
+      failures,
+      lastFailure: new Date().toISOString(),
+      retryAfter: retryAfter.toISOString(),
+      lastError: error,
+    };
+
+    await this.saveBackoff(domain, entry);
+    logger.log('warn', `Cert backoff for ${domain}: ${failures} failures, retry after ${retryAfter.toISOString()}`);
+  }
+
+  /**
+   * Clear backoff for a domain (on success or manual override)
+   */
+  async clearBackoff(domain: string): Promise<void> {
+    this.backoffCache.delete(domain);
+    try {
+      const sanitized = this.sanitizeDomain(domain);
+      const doc = await CertBackoffDoc.findByDomain(sanitized);
+      if (doc) {
+        await doc.delete();
+      }
+    } catch {
+      // Ignore delete errors (doc may not exist)
+    }
+  }
+
+  /**
+   * Clear all in-memory backoff cache entries
+   */
+  public clear(): void {
+    this.backoffCache.clear();
+  }
+
+  /**
+   * Get backoff info for UI display
+   */
+  async getBackoffInfo(domain: string): Promise<{
+    failures: number;
+    retryAfter?: string;
+    lastError?: string;
+  } | null> {
+    const entry = await this.loadBackoff(domain);
+    if (!entry) return null;
+
+    // Only return if still in backoff — prune expired entries
+    const retryAfter = new Date(entry.retryAfter);
+    if (retryAfter.getTime() <= Date.now()) {
+      this.backoffCache.delete(domain);
+      return null;
+    }
+
+    return {
+      failures: entry.failures,
+      retryAfter: entry.retryAfter,
+      lastError: entry.lastError,
+    };
+  }
+}

ts/classes.storage-cert-manager.ts

@@ -0,0 +1,58 @@
+import * as plugins from './plugins.js';
+import { AcmeCertDoc } from './db/index.js';
+
+/**
+ * ICertManager implementation backed by smartdata document classes.
+ * Persists SmartAcme certificates via AcmeCertDoc so they
+ * survive process restarts without re-hitting ACME.
+ */
+export class StorageBackedCertManager implements plugins.smartacme.ICertManager {
+  constructor() {}
+
+  async init(): Promise<void> {}
+
+  async retrieveCertificate(domainName: string): Promise<plugins.smartacme.Cert | null> {
+    const doc = await AcmeCertDoc.findByDomain(domainName);
+    if (!doc) return null;
+    return new plugins.smartacme.Cert({
+      id: doc.id,
+      domainName: doc.domainName,
+      created: doc.created,
+      privateKey: doc.privateKey,
+      publicKey: doc.publicKey,
+      csr: doc.csr,
+      validUntil: doc.validUntil,
+    });
+  }
+
+  async storeCertificate(cert: plugins.smartacme.Cert): Promise<void> {
+    let doc = await AcmeCertDoc.findByDomain(cert.domainName);
+    if (!doc) {
+      doc = new AcmeCertDoc();
+      doc.id = cert.id;
+      doc.domainName = cert.domainName;
+    }
+    doc.created = cert.created;
+    doc.privateKey = cert.privateKey;
+    doc.publicKey = cert.publicKey;
+    doc.csr = cert.csr;
+    doc.validUntil = cert.validUntil;
+    await doc.save();
+  }
+
+  async deleteCertificate(domainName: string): Promise<void> {
+    const doc = await AcmeCertDoc.findByDomain(domainName);
+    if (doc) {
+      await doc.delete();
+    }
+  }
+
+  async close(): Promise<void> {}
+
+  async wipe(): Promise<void> {
+    const docs = await AcmeCertDoc.findAll();
+    for (const doc of docs) {
+      await doc.delete();
+    }
+  }
+}

ts/config/classes.api-token-manager.ts

@@ -0,0 +1,204 @@
+import * as plugins from '../plugins.js';
+import { logger } from '../logger.js';
+import { ApiTokenDoc } from '../db/index.js';
+import type {
+  IStoredApiToken,
+  IApiTokenInfo,
+  TApiTokenScope,
+} from '../../ts_interfaces/data/route-management.js';
+
+const TOKEN_PREFIX_STR = 'dcr_';
+
+export class ApiTokenManager {
+  private tokens = new Map<string, IStoredApiToken>();
+
+  constructor() {}
+
+  public async initialize(): Promise<void> {
+    await this.loadTokens();
+    if (this.tokens.size > 0) {
+      logger.log('info', `Loaded ${this.tokens.size} API token(s) from storage`);
+    }
+  }
+
+  // =========================================================================
+  // Token lifecycle
+  // =========================================================================
+
+  /**
+   * Create a new API token. Returns the raw token value (shown once).
+   */
+  public async createToken(
+    name: string,
+    scopes: TApiTokenScope[],
+    expiresInDays: number | null,
+    createdBy: string,
+  ): Promise<{ id: string; rawToken: string }> {
+    const id = plugins.uuid.v4();
+    const randomBytes = plugins.crypto.randomBytes(32);
+    const rawPayload = `${id}:${randomBytes.toString('base64url')}`;
+    const rawToken = `${TOKEN_PREFIX_STR}${rawPayload}`;
+
+    const tokenHash = plugins.crypto.createHash('sha256').update(rawToken).digest('hex');
+
+    const now = Date.now();
+    const stored: IStoredApiToken = {
+      id,
+      name,
+      tokenHash,
+      scopes,
+      createdAt: now,
+      expiresAt: expiresInDays != null ? now + expiresInDays * 86400000 : null,
+      lastUsedAt: null,
+      createdBy,
+      enabled: true,
+    };
+
+    this.tokens.set(id, stored);
+    await this.persistToken(stored);
+    logger.log('info', `API token '${name}' created (id: ${id})`);
+    return { id, rawToken };
+  }
+
+  /**
+   * Validate a raw token string. Returns the stored token if valid, null otherwise.
+   * Also updates lastUsedAt.
+   */
+  public async validateToken(rawToken: string): Promise<IStoredApiToken | null> {
+    if (!rawToken.startsWith(TOKEN_PREFIX_STR)) return null;
+
+    const hash = plugins.crypto.createHash('sha256').update(rawToken).digest('hex');
+
+    for (const stored of this.tokens.values()) {
+      if (stored.tokenHash === hash) {
+        if (!stored.enabled) return null;
+        if (stored.expiresAt !== null && stored.expiresAt < Date.now()) return null;
+
+        // Update lastUsedAt (fire and forget)
+        stored.lastUsedAt = Date.now();
+        this.persistToken(stored).catch(() => {});
+        return stored;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Check if a token has a specific scope.
+   */
+  public hasScope(token: IStoredApiToken, scope: TApiTokenScope): boolean {
+    return token.scopes.includes(scope);
+  }
+
+  /**
+   * List all tokens (safe info only, no hashes).
+   */
+  public listTokens(): IApiTokenInfo[] {
+    const result: IApiTokenInfo[] = [];
+    for (const stored of this.tokens.values()) {
+      result.push({
+        id: stored.id,
+        name: stored.name,
+        scopes: stored.scopes,
+        createdAt: stored.createdAt,
+        expiresAt: stored.expiresAt,
+        lastUsedAt: stored.lastUsedAt,
+        enabled: stored.enabled,
+      });
+    }
+    return result;
+  }
+
+  /**
+   * Revoke (delete) a token.
+   */
+  public async revokeToken(id: string): Promise<boolean> {
+    if (!this.tokens.has(id)) return false;
+    const token = this.tokens.get(id)!;
+    this.tokens.delete(id);
+    const doc = await ApiTokenDoc.findById(id);
+    if (doc) await doc.delete();
+    logger.log('info', `API token '${token.name}' revoked (id: ${id})`);
+    return true;
+  }
+
+  /**
+   * Roll (regenerate) a token's secret while keeping its identity.
+   * Returns the new raw token value (shown once).
+   */
+  public async rollToken(id: string): Promise<{ id: string; rawToken: string } | null> {
+    const stored = this.tokens.get(id);
+    if (!stored) return null;
+
+    const randomBytes = plugins.crypto.randomBytes(32);
+    const rawPayload = `${id}:${randomBytes.toString('base64url')}`;
+    const rawToken = `${TOKEN_PREFIX_STR}${rawPayload}`;
+
+    stored.tokenHash = plugins.crypto.createHash('sha256').update(rawToken).digest('hex');
+    await this.persistToken(stored);
+    logger.log('info', `API token '${stored.name}' rolled (id: ${id})`);
+    return { id, rawToken };
+  }
+
+  /**
+   * Enable or disable a token.
+   */
+  public async toggleToken(id: string, enabled: boolean): Promise<boolean> {
+    const stored = this.tokens.get(id);
+    if (!stored) return false;
+    stored.enabled = enabled;
+    await this.persistToken(stored);
+    logger.log('info', `API token '${stored.name}' ${enabled ? 'enabled' : 'disabled'} (id: ${id})`);
+    return true;
+  }
+
+  // =========================================================================
+  // Private
+  // =========================================================================
+
+  private async loadTokens(): Promise<void> {
+    const docs = await ApiTokenDoc.findAll();
+    for (const doc of docs) {
+      if (doc.id) {
+        this.tokens.set(doc.id, {
+          id: doc.id,
+          name: doc.name,
+          tokenHash: doc.tokenHash,
+          scopes: doc.scopes,
+          createdAt: doc.createdAt,
+          expiresAt: doc.expiresAt,
+          lastUsedAt: doc.lastUsedAt,
+          createdBy: doc.createdBy,
+          enabled: doc.enabled,
+        });
+      }
+    }
+  }
+
+  private async persistToken(stored: IStoredApiToken): Promise<void> {
+    const existing = await ApiTokenDoc.findById(stored.id);
+    if (existing) {
+      existing.name = stored.name;
+      existing.tokenHash = stored.tokenHash;
+      existing.scopes = stored.scopes;
+      existing.createdAt = stored.createdAt;
+      existing.expiresAt = stored.expiresAt;
+      existing.lastUsedAt = stored.lastUsedAt;
+      existing.createdBy = stored.createdBy;
+      existing.enabled = stored.enabled;
+      await existing.save();
+    } else {
+      const doc = new ApiTokenDoc();
+      doc.id = stored.id;
+      doc.name = stored.name;
+      doc.tokenHash = stored.tokenHash;
+      doc.scopes = stored.scopes;
+      doc.createdAt = stored.createdAt;
+      doc.expiresAt = stored.expiresAt;
+      doc.lastUsedAt = stored.lastUsedAt;
+      doc.createdBy = stored.createdBy;
+      doc.enabled = stored.enabled;
+      await doc.save();
+    }
+  }
+}

ts/config/classes.db-seeder.ts

@@ -0,0 +1,95 @@
+import { logger } from '../logger.js';
+import type { ReferenceResolver } from './classes.reference-resolver.js';
+import type { IRouteSecurity } from '../../ts_interfaces/data/route-management.js';
+
+export interface ISeedData {
+  profiles?: Array<{
+    name: string;
+    description?: string;
+    security: IRouteSecurity;
+    extendsProfiles?: string[];
+  }>;
+  targets?: Array<{
+    name: string;
+    description?: string;
+    host: string | string[];
+    port: number;
+  }>;
+}
+
+export class DbSeeder {
+  constructor(private referenceResolver: ReferenceResolver) {}
+
+  /**
+   * Check if DB is empty and seed if configured.
+   * Called once during ConfigManagers service startup, after initialize().
+   */
+  public async seedIfEmpty(
+    seedOnEmpty?: boolean,
+    seedData?: ISeedData,
+  ): Promise<void> {
+    if (!seedOnEmpty) return;
+
+    const existingProfiles = this.referenceResolver.listProfiles();
+    const existingTargets = this.referenceResolver.listTargets();
+
+    if (existingProfiles.length > 0 || existingTargets.length > 0) {
+      logger.log('info', 'DB already contains profiles/targets, skipping seed');
+      return;
+    }
+
+    logger.log('info', 'Seeding database with initial profiles and targets...');
+
+    const profilesToSeed: NonNullable<ISeedData['profiles']> = seedData?.profiles ?? DEFAULT_PROFILES;
+    const targetsToSeed: NonNullable<ISeedData['targets']> = seedData?.targets ?? DEFAULT_TARGETS;
+
+    for (const p of profilesToSeed) {
+      await this.referenceResolver.createProfile({
+        name: p.name,
+        description: p.description,
+        security: p.security,
+        extendsProfiles: p.extendsProfiles,
+        createdBy: 'system-seed',
+      });
+    }
+
+    for (const t of targetsToSeed) {
+      await this.referenceResolver.createTarget({
+        name: t.name,
+        description: t.description,
+        host: t.host,
+        port: t.port,
+        createdBy: 'system-seed',
+      });
+    }
+
+    logger.log('info', `Seeded ${profilesToSeed.length} profile(s) and ${targetsToSeed.length} target(s)`);
+  }
+}
+
+const DEFAULT_PROFILES: Array<NonNullable<ISeedData['profiles']>[number]> = [
+  {
+    name: 'PUBLIC',
+    description: 'Allow all traffic — no IP restrictions',
+    security: {
+      ipAllowList: ['*'],
+    },
+  },
+  {
+    name: 'STANDARD',
+    description: 'Standard internal access with common private subnets',
+    security: {
+      ipAllowList: ['192.168.0.0/16', '10.0.0.0/8', '127.0.0.1', '::1'],
+      maxConnections: 1000,
+    },
+  },
+];
+
+const DEFAULT_TARGETS: Array<NonNullable<ISeedData['targets']>[number]> = [
+  {
+    name: 'LOCALHOST',
+    description: 'Local machine on port 443',
+    host: '127.0.0.1',
+    port: 443,
+  },
+];

ts/config/classes.reference-resolver.ts

@@ -0,0 +1,577 @@
+import * as plugins from '../plugins.js';
+import { logger } from '../logger.js';
+import { SourceProfileDoc, NetworkTargetDoc, StoredRouteDoc } from '../db/index.js';
+import type {
+  ISourceProfile,
+  INetworkTarget,
+  IRouteMetadata,
+  IStoredRoute,
+  IRouteSecurity,
+} from '../../ts_interfaces/data/route-management.js';
+
+const MAX_INHERITANCE_DEPTH = 5;
+
+export class ReferenceResolver {
+  private profiles = new Map<string, ISourceProfile>();
+  private targets = new Map<string, INetworkTarget>();
+
+  // =========================================================================
+  // Lifecycle
+  // =========================================================================
+
+  public async initialize(): Promise<void> {
+    await this.loadProfiles();
+    await this.loadTargets();
+  }
+
+  // =========================================================================
+  // Profile CRUD
+  // =========================================================================
+
+  public async createProfile(data: {
+    name: string;
+    description?: string;
+    security: IRouteSecurity;
+    extendsProfiles?: string[];
+    createdBy: string;
+  }): Promise<string> {
+    const id = plugins.uuid.v4();
+    const now = Date.now();
+
+    const profile: ISourceProfile = {
+      id,
+      name: data.name,
+      description: data.description,
+      security: data.security,
+      extendsProfiles: data.extendsProfiles,
+      createdAt: now,
+      updatedAt: now,
+      createdBy: data.createdBy,
+    };
+
+    this.profiles.set(id, profile);
+    await this.persistProfile(profile);
+    logger.log('info', `Created source profile '${profile.name}' (${id})`);
+    return id;
+  }
+
+  public async updateProfile(
+    id: string,
+    patch: Partial<Omit<ISourceProfile, 'id' | 'createdAt' | 'createdBy'>>,
+  ): Promise<{ affectedRouteIds: string[] }> {
+    const profile = this.profiles.get(id);
+    if (!profile) {
+      throw new Error(`Source profile '${id}' not found`);
+    }
+
+    if (patch.name !== undefined) profile.name = patch.name;
+    if (patch.description !== undefined) profile.description = patch.description;
+    if (patch.security !== undefined) profile.security = patch.security;
+    if (patch.extendsProfiles !== undefined) profile.extendsProfiles = patch.extendsProfiles;
+    profile.updatedAt = Date.now();
+
+    await this.persistProfile(profile);
+    logger.log('info', `Updated source profile '${profile.name}' (${id})`);
+
+    // Find routes referencing this profile
+    const affectedRouteIds = await this.findRoutesByProfileRef(id);
+    return { affectedRouteIds };
+  }
+
+  public async deleteProfile(
+    id: string,
+    force: boolean,
+    storedRoutes?: Map<string, IStoredRoute>,
+  ): Promise<{ success: boolean; message?: string }> {
+    const profile = this.profiles.get(id);
+    if (!profile) {
+      return { success: false, message: `Source profile '${id}' not found` };
+    }
+
+    // Check usage
+    const affectedIds = storedRoutes
+      ? this.findRoutesByProfileRefSync(id, storedRoutes)
+      : await this.findRoutesByProfileRef(id);
+
+    if (affectedIds.length > 0 && !force) {
+      return {
+        success: false,
+        message: `Profile '${profile.name}' is in use by ${affectedIds.length} route(s). Use force=true to delete.`,
+      };
+    }
+
+    // Delete from DB
+    const doc = await SourceProfileDoc.findById(id);
+    if (doc) await doc.delete();
+    this.profiles.delete(id);
+
+    // If force-deleting with referencing routes, clear refs but keep resolved values
+    if (affectedIds.length > 0) {
+      await this.clearProfileRefsOnRoutes(affectedIds);
+      logger.log('warn', `Force-deleted profile '${profile.name}'; cleared refs on ${affectedIds.length} route(s)`);
+    } else {
+      logger.log('info', `Deleted source profile '${profile.name}' (${id})`);
+    }
+
+    return { success: true };
+  }
+
+  public getProfile(id: string): ISourceProfile | undefined {
+    return this.profiles.get(id);
+  }
+
+  public getProfileByName(name: string): ISourceProfile | undefined {
+    for (const profile of this.profiles.values()) {
+      if (profile.name === name) return profile;
+    }
+    return undefined;
+  }
+
+  public listProfiles(): ISourceProfile[] {
+    return [...this.profiles.values()];
+  }
+
+  public getProfileUsage(storedRoutes: Map<string, IStoredRoute>): Map<string, Array<{ id: string; routeName: string }>> {
+    const usage = new Map<string, Array<{ id: string; routeName: string }>>();
+    for (const profile of this.profiles.values()) {
+      usage.set(profile.id, []);
+    }
+    for (const [routeId, stored] of storedRoutes) {
+      const ref = stored.metadata?.sourceProfileRef;
+      if (ref && usage.has(ref)) {
+        usage.get(ref)!.push({ id: routeId, routeName: stored.route.name || routeId });
+      }
+    }
+    return usage;
+  }
+
+  public getProfileUsageForId(
+    profileId: string,
+    storedRoutes: Map<string, IStoredRoute>,
+  ): Array<{ id: string; routeName: string }> {
+    const routes: Array<{ id: string; routeName: string }> = [];
+    for (const [routeId, stored] of storedRoutes) {
+      if (stored.metadata?.sourceProfileRef === profileId) {
+        routes.push({ id: routeId, routeName: stored.route.name || routeId });
+      }
+    }
+    return routes;
+  }
+
+  // =========================================================================
+  // Target CRUD
+  // =========================================================================
+
+  public async createTarget(data: {
+    name: string;
+    description?: string;
+    host: string | string[];
+    port: number;
+    createdBy: string;
+  }): Promise<string> {
+    const id = plugins.uuid.v4();
+    const now = Date.now();
+
+    const target: INetworkTarget = {
+      id,
+      name: data.name,
+      description: data.description,
+      host: data.host,
+      port: data.port,
+      createdAt: now,
+      updatedAt: now,
+      createdBy: data.createdBy,
+    };
+
+    this.targets.set(id, target);
+    await this.persistTarget(target);
+    logger.log('info', `Created network target '${target.name}' (${id})`);
+    return id;
+  }
+
+  public async updateTarget(
+    id: string,
+    patch: Partial<Omit<INetworkTarget, 'id' | 'createdAt' | 'createdBy'>>,
+  ): Promise<{ affectedRouteIds: string[] }> {
+    const target = this.targets.get(id);
+    if (!target) {
+      throw new Error(`Network target '${id}' not found`);
+    }
+
+    if (patch.name !== undefined) target.name = patch.name;
+    if (patch.description !== undefined) target.description = patch.description;
+    if (patch.host !== undefined) target.host = patch.host;
+    if (patch.port !== undefined) target.port = patch.port;
+    target.updatedAt = Date.now();
+
+    await this.persistTarget(target);
+    logger.log('info', `Updated network target '${target.name}' (${id})`);
+
+    const affectedRouteIds = await this.findRoutesByTargetRef(id);
+    return { affectedRouteIds };
+  }
+
+  public async deleteTarget(
+    id: string,
+    force: boolean,
+    storedRoutes?: Map<string, IStoredRoute>,
+  ): Promise<{ success: boolean; message?: string }> {
+    const target = this.targets.get(id);
+    if (!target) {
+      return { success: false, message: `Network target '${id}' not found` };
+    }
+
+    const affectedIds = storedRoutes
+      ? this.findRoutesByTargetRefSync(id, storedRoutes)
+      : await this.findRoutesByTargetRef(id);
+
+    if (affectedIds.length > 0 && !force) {
+      return {
+        success: false,
+        message: `Target '${target.name}' is in use by ${affectedIds.length} route(s). Use force=true to delete.`,
+      };
+    }
+
+    const doc = await NetworkTargetDoc.findById(id);
+    if (doc) await doc.delete();
+    this.targets.delete(id);
+
+    if (affectedIds.length > 0) {
+      await this.clearTargetRefsOnRoutes(affectedIds);
+      logger.log('warn', `Force-deleted target '${target.name}'; cleared refs on ${affectedIds.length} route(s)`);
+    } else {
+      logger.log('info', `Deleted network target '${target.name}' (${id})`);
+    }
+
+    return { success: true };
+  }
+
+  public getTarget(id: string): INetworkTarget | undefined {
+    return this.targets.get(id);
+  }
+
+  public getTargetByName(name: string): INetworkTarget | undefined {
+    for (const target of this.targets.values()) {
+      if (target.name === name) return target;
+    }
+    return undefined;
+  }
+
+  public listTargets(): INetworkTarget[] {
+    return [...this.targets.values()];
+  }
+
+  public getTargetUsageForId(
+    targetId: string,
+    storedRoutes: Map<string, IStoredRoute>,
+  ): Array<{ id: string; routeName: string }> {
+    const routes: Array<{ id: string; routeName: string }> = [];
+    for (const [routeId, stored] of storedRoutes) {
+      if (stored.metadata?.networkTargetRef === targetId) {
+        routes.push({ id: routeId, routeName: stored.route.name || routeId });
+      }
+    }
+    return routes;
+  }
+
+  // =========================================================================
+  // Resolution
+  // =========================================================================
+
+  /**
+   * Resolve references for a single route.
+   * Materializes source profile and/or network target into the route's fields.
+   * Returns the resolved route and updated metadata.
+   */
+  public resolveRoute(
+    route: plugins.smartproxy.IRouteConfig,
+    metadata?: IRouteMetadata,
+  ): { route: plugins.smartproxy.IRouteConfig; metadata: IRouteMetadata } {
+    const resolvedMetadata: IRouteMetadata = { ...metadata };
+
+    if (resolvedMetadata.sourceProfileRef) {
+      const resolvedSecurity = this.resolveSourceProfile(resolvedMetadata.sourceProfileRef);
+      if (resolvedSecurity) {
+        const profile = this.profiles.get(resolvedMetadata.sourceProfileRef);
+        // Merge: profile provides base, route's inline values override
+        route = {
+          ...route,
+          security: this.mergeSecurityFields(resolvedSecurity, route.security),
+        };
+        resolvedMetadata.sourceProfileName = profile?.name;
+        resolvedMetadata.lastResolvedAt = Date.now();
+      } else {
+        logger.log('warn', `Source profile '${resolvedMetadata.sourceProfileRef}' not found during resolution`);
+      }
+    }
+
+    if (resolvedMetadata.networkTargetRef) {
+      const target = this.targets.get(resolvedMetadata.networkTargetRef);
+      if (target) {
+        const hosts = Array.isArray(target.host) ? target.host : [target.host];
+        route = {
+          ...route,
+          action: {
+            ...route.action,
+            targets: hosts.map((h) => ({
+              host: h,
+              port: target.port,
+            })),
+          },
+        };
+        resolvedMetadata.networkTargetName = target.name;
+        resolvedMetadata.lastResolvedAt = Date.now();
+      } else {
+        logger.log('warn', `Network target '${resolvedMetadata.networkTargetRef}' not found during resolution`);
+      }
+    }
+
+    return { route, metadata: resolvedMetadata };
+  }
+
+  // =========================================================================
+  // Reference lookup helpers
+  // =========================================================================
+
+  public async findRoutesByProfileRef(profileId: string): Promise<string[]> {
+    const docs = await StoredRouteDoc.findAll();
+    return docs
+      .filter((doc) => doc.metadata?.sourceProfileRef === profileId)
+      .map((doc) => doc.id);
+  }
+
+  public async findRoutesByTargetRef(targetId: string): Promise<string[]> {
+    const docs = await StoredRouteDoc.findAll();
+    return docs
+      .filter((doc) => doc.metadata?.networkTargetRef === targetId)
+      .map((doc) => doc.id);
+  }
+
+  public findRoutesByProfileRefSync(profileId: string, storedRoutes: Map<string, IStoredRoute>): string[] {
+    const ids: string[] = [];
+    for (const [routeId, stored] of storedRoutes) {
+      if (stored.metadata?.sourceProfileRef === profileId) {
+        ids.push(routeId);
+      }
+    }
+    return ids;
+  }
+
+  public findRoutesByTargetRefSync(targetId: string, storedRoutes: Map<string, IStoredRoute>): string[] {
+    const ids: string[] = [];
+    for (const [routeId, stored] of storedRoutes) {
+      if (stored.metadata?.networkTargetRef === targetId) {
+        ids.push(routeId);
+      }
+    }
+    return ids;
+  }
+
+  // =========================================================================
+  // Private: source profile resolution with inheritance
+  // =========================================================================
+
+  private resolveSourceProfile(
+    profileId: string,
+    visited: Set<string> = new Set(),
+    depth: number = 0,
+  ): IRouteSecurity | null {
+    if (depth > MAX_INHERITANCE_DEPTH) {
+      logger.log('warn', `Max inheritance depth (${MAX_INHERITANCE_DEPTH}) exceeded resolving profile '${profileId}'`);
+      return null;
+    }
+
+    if (visited.has(profileId)) {
+      logger.log('warn', `Circular inheritance detected for profile '${profileId}'`);
+      return null;
+    }
+
+    const profile = this.profiles.get(profileId);
+    if (!profile) return null;
+
+    visited.add(profileId);
+
+    // Start with an empty base
+    let baseSecurity: IRouteSecurity = {};
+
+    // Resolve parent profiles first (top-down, later overrides earlier)
+    if (profile.extendsProfiles?.length) {
+      for (const parentId of profile.extendsProfiles) {
+        const parentSecurity = this.resolveSourceProfile(parentId, new Set(visited), depth + 1);
+        if (parentSecurity) {
+          baseSecurity = this.mergeSecurityFields(baseSecurity, parentSecurity);
+        }
+      }
+    }
+
+    // Apply this profile's security on top
+    return this.mergeSecurityFields(baseSecurity, profile.security);
+  }
+
+  /**
+   * Merge two IRouteSecurity objects.
+   * `override` values take precedence over `base` values.
+   * For ipAllowList/ipBlockList: union arrays and deduplicate.
+   * For scalar/object fields: override wins if present.
+   */
+  private mergeSecurityFields(
+    base: IRouteSecurity | undefined,
+    override: IRouteSecurity | undefined,
+  ): IRouteSecurity {
+    if (!base && !override) return {};
+    if (!base) return { ...override };
+    if (!override) return { ...base };
+
+    const merged: IRouteSecurity = { ...base };
+
+    // IP lists: union
+    if (override.ipAllowList || base.ipAllowList) {
+      merged.ipAllowList = [...new Set([
+        ...(base.ipAllowList || []),
+        ...(override.ipAllowList || []),
+      ])];
+    }
+
+    if (override.ipBlockList || base.ipBlockList) {
+      merged.ipBlockList = [...new Set([
+        ...(base.ipBlockList || []),
+        ...(override.ipBlockList || []),
+      ])];
+    }
+
+    // Scalar/object fields: override wins
+    if (override.maxConnections !== undefined) merged.maxConnections = override.maxConnections;
+    if (override.rateLimit !== undefined) merged.rateLimit = override.rateLimit;
+    if (override.authentication !== undefined) merged.authentication = override.authentication;
+    if (override.basicAuth !== undefined) merged.basicAuth = override.basicAuth;
+    if (override.jwtAuth !== undefined) merged.jwtAuth = override.jwtAuth;
+
+    return merged;
+  }
+
+  // =========================================================================
+  // Private: persistence
+  // =========================================================================
+
+  private async loadProfiles(): Promise<void> {
+    const docs = await SourceProfileDoc.findAll();
+    for (const doc of docs) {
+      if (doc.id) {
+        this.profiles.set(doc.id, {
+          id: doc.id,
+          name: doc.name,
+          description: doc.description,
+          security: doc.security,
+          extendsProfiles: doc.extendsProfiles,
+          createdAt: doc.createdAt,
+          updatedAt: doc.updatedAt,
+          createdBy: doc.createdBy,
+        });
+      }
+    }
+    if (this.profiles.size > 0) {
+      logger.log('info', `Loaded ${this.profiles.size} source profile(s) from storage`);
+    }
+  }
+
+  private async loadTargets(): Promise<void> {
+    const docs = await NetworkTargetDoc.findAll();
+    for (const doc of docs) {
+      if (doc.id) {
+        this.targets.set(doc.id, {
+          id: doc.id,
+          name: doc.name,
+          description: doc.description,
+          host: doc.host,
+          port: doc.port,
+          createdAt: doc.createdAt,
+          updatedAt: doc.updatedAt,
+          createdBy: doc.createdBy,
+        });
+      }
+    }
+    if (this.targets.size > 0) {
+      logger.log('info', `Loaded ${this.targets.size} network target(s) from storage`);
+    }
+  }
+
+  private async persistProfile(profile: ISourceProfile): Promise<void> {
+    const existingDoc = await SourceProfileDoc.findById(profile.id);
+    if (existingDoc) {
+      existingDoc.name = profile.name;
+      existingDoc.description = profile.description;
+      existingDoc.security = profile.security;
+      existingDoc.extendsProfiles = profile.extendsProfiles;
+      existingDoc.updatedAt = profile.updatedAt;
+      await existingDoc.save();
+    } else {
+      const doc = new SourceProfileDoc();
+      doc.id = profile.id;
+      doc.name = profile.name;
+      doc.description = profile.description;
+      doc.security = profile.security;
+      doc.extendsProfiles = profile.extendsProfiles;
+      doc.createdAt = profile.createdAt;
+      doc.updatedAt = profile.updatedAt;
+      doc.createdBy = profile.createdBy;
+      await doc.save();
+    }
+  }
+
+  private async persistTarget(target: INetworkTarget): Promise<void> {
+    const existingDoc = await NetworkTargetDoc.findById(target.id);
+    if (existingDoc) {
+      existingDoc.name = target.name;
+      existingDoc.description = target.description;
+      existingDoc.host = target.host;
+      existingDoc.port = target.port;
+      existingDoc.updatedAt = target.updatedAt;
+      await existingDoc.save();
+    } else {
+      const doc = new NetworkTargetDoc();
+      doc.id = target.id;
+      doc.name = target.name;
+      doc.description = target.description;
+      doc.host = target.host;
+      doc.port = target.port;
+      doc.createdAt = target.createdAt;
+      doc.updatedAt = target.updatedAt;
+      doc.createdBy = target.createdBy;
+      await doc.save();
+    }
+  }
+
+  // =========================================================================
+  // Private: ref cleanup on force-delete
+  // =========================================================================
+
+  private async clearProfileRefsOnRoutes(routeIds: string[]): Promise<void> {
+    for (const routeId of routeIds) {
+      const doc = await StoredRouteDoc.findById(routeId);
+      if (doc?.metadata) {
+        doc.metadata = {
+          ...doc.metadata,
+          sourceProfileRef: undefined,
+          sourceProfileName: undefined,
+        };
+        doc.updatedAt = Date.now();
+        await doc.save();
+      }
+    }
+  }
+
+  private async clearTargetRefsOnRoutes(routeIds: string[]): Promise<void> {
+    for (const routeId of routeIds) {
+      const doc = await StoredRouteDoc.findById(routeId);
+      if (doc?.metadata) {
+        doc.metadata = {
+          ...doc.metadata,
+          networkTargetRef: undefined,
+          networkTargetName: undefined,
+        };
+        doc.updatedAt = Date.now();
+        await doc.save();
+      }
+    }
+  }
+}

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

@@ -0,0 +1,450 @@
+import * as plugins from '../plugins.js';
+import { logger } from '../logger.js';
+import { StoredRouteDoc, RouteOverrideDoc } from '../db/index.js';
+import type {
+  IStoredRoute,
+  IRouteOverride,
+  IMergedRoute,
+  IRouteWarning,
+  IRouteMetadata,
+} from '../../ts_interfaces/data/route-management.js';
+import type { IDcRouterRouteConfig } from '../../ts_interfaces/data/remoteingress.js';
+import { type IHttp3Config, augmentRouteWithHttp3 } from '../http3/index.js';
+import type { ReferenceResolver } from './classes.reference-resolver.js';
+
+/** An IP allow entry: plain IP/CIDR or domain-scoped. */
+export type TIpAllowEntry = string | { ip: string; domains: string[] };
+
+/**
+ * Simple async mutex — serializes concurrent applyRoutes() calls so the Rust engine
+ * never receives rapid overlapping route updates that can churn UDP/QUIC listeners.
+ */
+class RouteUpdateMutex {
+  private locked = false;
+  private queue: Array<() => void> = [];
+
+  async runExclusive<T>(fn: () => Promise<T>): Promise<T> {
+    await new Promise<void>((resolve) => {
+      if (!this.locked) {
+        this.locked = true;
+        resolve();
+      } else {
+        this.queue.push(resolve);
+      }
+    });
+    try {
+      return await fn();
+    } finally {
+      this.locked = false;
+      const next = this.queue.shift();
+      if (next) {
+        this.locked = true;
+        next();
+      }
+    }
+  }
+}
+
+export class RouteConfigManager {
+  private storedRoutes = new Map<string, IStoredRoute>();
+  private overrides = new Map<string, IRouteOverride>();
+  private warnings: IRouteWarning[] = [];
+  private routeUpdateMutex = new RouteUpdateMutex();
+
+  constructor(
+    private getHardcodedRoutes: () => plugins.smartproxy.IRouteConfig[],
+    private getSmartProxy: () => plugins.smartproxy.SmartProxy | undefined,
+    private getHttp3Config?: () => IHttp3Config | undefined,
+    private getVpnClientIpsForRoute?: (route: IDcRouterRouteConfig, routeId?: string) => TIpAllowEntry[],
+    private referenceResolver?: ReferenceResolver,
+    private onRoutesApplied?: (routes: plugins.smartproxy.IRouteConfig[]) => void,
+  ) {}
+
+  /** Expose stored routes map for reference resolution lookups. */
+  public getStoredRoutes(): Map<string, IStoredRoute> {
+    return this.storedRoutes;
+  }
+
+  /**
+   * Load persisted routes and overrides, compute warnings, apply to SmartProxy.
+   */
+  public async initialize(): Promise<void> {
+    await this.loadStoredRoutes();
+    await this.loadOverrides();
+    this.computeWarnings();
+    this.logWarnings();
+    await this.applyRoutes();
+  }
+
+  // =========================================================================
+  // Merged view
+  // =========================================================================
+
+  public getMergedRoutes(): { routes: IMergedRoute[]; warnings: IRouteWarning[] } {
+    const merged: IMergedRoute[] = [];
+
+    // Hardcoded routes
+    for (const route of this.getHardcodedRoutes()) {
+      const name = route.name || '';
+      const override = this.overrides.get(name);
+      merged.push({
+        route,
+        source: 'hardcoded',
+        enabled: override ? override.enabled : true,
+        overridden: !!override,
+      });
+    }
+
+    // Programmatic routes
+    for (const stored of this.storedRoutes.values()) {
+      merged.push({
+        route: stored.route,
+        source: 'programmatic',
+        enabled: stored.enabled,
+        overridden: false,
+        storedRouteId: stored.id,
+        createdAt: stored.createdAt,
+        updatedAt: stored.updatedAt,
+        metadata: stored.metadata,
+      });
+    }
+
+    return { routes: merged, warnings: [...this.warnings] };
+  }
+
+  // =========================================================================
+  // Programmatic route CRUD
+  // =========================================================================
+
+  public async createRoute(
+    route: IDcRouterRouteConfig,
+    createdBy: string,
+    enabled = true,
+    metadata?: IRouteMetadata,
+  ): Promise<string> {
+    const id = plugins.uuid.v4();
+    const now = Date.now();
+
+    // Ensure route has a name
+    if (!route.name) {
+      route.name = `programmatic-${id.slice(0, 8)}`;
+    }
+
+    // Resolve references if metadata has refs and resolver is available
+    let resolvedMetadata = metadata;
+    if (metadata && this.referenceResolver) {
+      const resolved = this.referenceResolver.resolveRoute(route, metadata);
+      route = resolved.route;
+      resolvedMetadata = resolved.metadata;
+    }
+
+    const stored: IStoredRoute = {
+      id,
+      route,
+      enabled,
+      createdAt: now,
+      updatedAt: now,
+      createdBy,
+      metadata: resolvedMetadata,
+    };
+
+    this.storedRoutes.set(id, stored);
+    await this.persistRoute(stored);
+    await this.applyRoutes();
+    return id;
+  }
+
+  public async updateRoute(
+    id: string,
+    patch: {
+      route?: Partial<IDcRouterRouteConfig>;
+      enabled?: boolean;
+      metadata?: Partial<IRouteMetadata>;
+    },
+  ): Promise<boolean> {
+    const stored = this.storedRoutes.get(id);
+    if (!stored) return false;
+
+    if (patch.route) {
+      const mergedAction = patch.route.action
+        ? { ...stored.route.action, ...patch.route.action }
+        : stored.route.action;
+      // Handle explicit null to remove nested action properties (e.g., tls: null)
+      if (patch.route.action) {
+        for (const [key, val] of Object.entries(patch.route.action)) {
+          if (val === null) {
+            delete (mergedAction as any)[key];
+          }
+        }
+      }
+      stored.route = { ...stored.route, ...patch.route, action: mergedAction } as IDcRouterRouteConfig;
+    }
+    if (patch.enabled !== undefined) {
+      stored.enabled = patch.enabled;
+    }
+    if (patch.metadata !== undefined) {
+      stored.metadata = { ...stored.metadata, ...patch.metadata };
+    }
+
+    // Re-resolve if metadata refs exist and resolver is available
+    if (stored.metadata && this.referenceResolver) {
+      const resolved = this.referenceResolver.resolveRoute(stored.route, stored.metadata);
+      stored.route = resolved.route;
+      stored.metadata = resolved.metadata;
+    }
+
+    stored.updatedAt = Date.now();
+
+    await this.persistRoute(stored);
+    await this.applyRoutes();
+    return true;
+  }
+
+  public async deleteRoute(id: string): Promise<boolean> {
+    if (!this.storedRoutes.has(id)) return false;
+    this.storedRoutes.delete(id);
+    const doc = await StoredRouteDoc.findById(id);
+    if (doc) await doc.delete();
+    await this.applyRoutes();
+    return true;
+  }
+
+  public async toggleRoute(id: string, enabled: boolean): Promise<boolean> {
+    return this.updateRoute(id, { enabled });
+  }
+
+  // =========================================================================
+  // Hardcoded route overrides
+  // =========================================================================
+
+  public async setOverride(routeName: string, enabled: boolean, updatedBy: string): Promise<void> {
+    const override: IRouteOverride = {
+      routeName,
+      enabled,
+      updatedAt: Date.now(),
+      updatedBy,
+    };
+    this.overrides.set(routeName, override);
+    const existingDoc = await RouteOverrideDoc.findByRouteName(routeName);
+    if (existingDoc) {
+      existingDoc.enabled = override.enabled;
+      existingDoc.updatedAt = override.updatedAt;
+      existingDoc.updatedBy = override.updatedBy;
+      await existingDoc.save();
+    } else {
+      const doc = new RouteOverrideDoc();
+      doc.routeName = override.routeName;
+      doc.enabled = override.enabled;
+      doc.updatedAt = override.updatedAt;
+      doc.updatedBy = override.updatedBy;
+      await doc.save();
+    }
+    this.computeWarnings();
+    await this.applyRoutes();
+  }
+
+  public async removeOverride(routeName: string): Promise<boolean> {
+    if (!this.overrides.has(routeName)) return false;
+    this.overrides.delete(routeName);
+    const doc = await RouteOverrideDoc.findByRouteName(routeName);
+    if (doc) await doc.delete();
+    this.computeWarnings();
+    await this.applyRoutes();
+    return true;
+  }
+
+  // =========================================================================
+  // Private: persistence
+  // =========================================================================
+
+  private async loadStoredRoutes(): Promise<void> {
+    const docs = await StoredRouteDoc.findAll();
+    for (const doc of docs) {
+      if (doc.id) {
+        this.storedRoutes.set(doc.id, {
+          id: doc.id,
+          route: doc.route,
+          enabled: doc.enabled,
+          createdAt: doc.createdAt,
+          updatedAt: doc.updatedAt,
+          createdBy: doc.createdBy,
+          metadata: doc.metadata,
+        });
+      }
+    }
+    if (this.storedRoutes.size > 0) {
+      logger.log('info', `Loaded ${this.storedRoutes.size} programmatic route(s) from storage`);
+    }
+  }
+
+  private async loadOverrides(): Promise<void> {
+    const docs = await RouteOverrideDoc.findAll();
+    for (const doc of docs) {
+      if (doc.routeName) {
+        this.overrides.set(doc.routeName, {
+          routeName: doc.routeName,
+          enabled: doc.enabled,
+          updatedAt: doc.updatedAt,
+          updatedBy: doc.updatedBy,
+        });
+      }
+    }
+    if (this.overrides.size > 0) {
+      logger.log('info', `Loaded ${this.overrides.size} route override(s) from storage`);
+    }
+  }
+
+  private async persistRoute(stored: IStoredRoute): Promise<void> {
+    const existingDoc = await StoredRouteDoc.findById(stored.id);
+    if (existingDoc) {
+      existingDoc.route = stored.route;
+      existingDoc.enabled = stored.enabled;
+      existingDoc.updatedAt = stored.updatedAt;
+      existingDoc.createdBy = stored.createdBy;
+      existingDoc.metadata = stored.metadata;
+      await existingDoc.save();
+    } else {
+      const doc = new StoredRouteDoc();
+      doc.id = stored.id;
+      doc.route = stored.route;
+      doc.enabled = stored.enabled;
+      doc.createdAt = stored.createdAt;
+      doc.updatedAt = stored.updatedAt;
+      doc.createdBy = stored.createdBy;
+      doc.metadata = stored.metadata;
+      await doc.save();
+    }
+  }
+
+  // =========================================================================
+  // Private: warnings
+  // =========================================================================
+
+  private computeWarnings(): void {
+    this.warnings = [];
+    const hardcodedNames = new Set(this.getHardcodedRoutes().map((r) => r.name || ''));
+
+    // Check overrides
+    for (const [routeName, override] of this.overrides) {
+      if (!hardcodedNames.has(routeName)) {
+        this.warnings.push({
+          type: 'orphaned-override',
+          routeName,
+          message: `Orphaned override for route '${routeName}' — hardcoded route no longer exists`,
+        });
+      } else if (!override.enabled) {
+        this.warnings.push({
+          type: 'disabled-hardcoded',
+          routeName,
+          message: `Route '${routeName}' is disabled via API override`,
+        });
+      }
+    }
+
+    // Check disabled programmatic routes
+    for (const stored of this.storedRoutes.values()) {
+      if (!stored.enabled) {
+        const name = stored.route.name || stored.id;
+        this.warnings.push({
+          type: 'disabled-programmatic',
+          routeName: name,
+          message: `Programmatic route '${name}' (id: ${stored.id}) is disabled`,
+        });
+      }
+    }
+  }
+
+  private logWarnings(): void {
+    for (const w of this.warnings) {
+      logger.log('warn', w.message);
+    }
+  }
+
+  // =========================================================================
+  // Re-resolve routes after profile/target changes
+  // =========================================================================
+
+  /**
+   * Re-resolve specific routes by ID (after a profile or target is updated).
+   * Persists each route and calls applyRoutes() once at the end.
+   */
+  public async reResolveRoutes(routeIds: string[]): Promise<void> {
+    if (!this.referenceResolver || routeIds.length === 0) return;
+
+    for (const routeId of routeIds) {
+      const stored = this.storedRoutes.get(routeId);
+      if (!stored?.metadata) continue;
+
+      const resolved = this.referenceResolver.resolveRoute(stored.route, stored.metadata);
+      stored.route = resolved.route;
+      stored.metadata = resolved.metadata;
+      stored.updatedAt = Date.now();
+      await this.persistRoute(stored);
+    }
+
+    await this.applyRoutes();
+    logger.log('info', `Re-resolved ${routeIds.length} route(s) after profile/target change`);
+  }
+
+  // =========================================================================
+  // Private: apply merged routes to SmartProxy
+  // =========================================================================
+
+  public async applyRoutes(): Promise<void> {
+    await this.routeUpdateMutex.runExclusive(async () => {
+      const smartProxy = this.getSmartProxy();
+      if (!smartProxy) return;
+
+      const enabledRoutes: plugins.smartproxy.IRouteConfig[] = [];
+
+      const http3Config = this.getHttp3Config?.();
+      const vpnCallback = this.getVpnClientIpsForRoute;
+
+      // Helper: inject VPN security into a vpnOnly route
+      const injectVpn = (route: plugins.smartproxy.IRouteConfig, routeId?: string): plugins.smartproxy.IRouteConfig => {
+        if (!vpnCallback) return route;
+        const dcRoute = route as IDcRouterRouteConfig;
+        if (!dcRoute.vpnOnly) return route;
+        const vpnEntries = vpnCallback(dcRoute, routeId);
+        const existingEntries = route.security?.ipAllowList || [];
+        return {
+          ...route,
+          security: {
+            ...route.security,
+            ipAllowList: [...existingEntries, ...vpnEntries],
+          },
+        };
+      };
+
+      // Add enabled hardcoded routes (respecting overrides, with fresh VPN injection)
+      for (const route of this.getHardcodedRoutes()) {
+        const name = route.name || '';
+        const override = this.overrides.get(name);
+        if (override && !override.enabled) {
+          continue; // Skip disabled hardcoded route
+        }
+        enabledRoutes.push(injectVpn(route));
+      }
+
+      // Add enabled programmatic routes (with HTTP/3 and VPN augmentation)
+      for (const stored of this.storedRoutes.values()) {
+        if (stored.enabled) {
+          let route = stored.route;
+          if (http3Config?.enabled !== false) {
+            route = augmentRouteWithHttp3(route, { enabled: true, ...http3Config });
+          }
+          enabledRoutes.push(injectVpn(route, stored.id));
+        }
+      }
+
+      await smartProxy.updateRoutes(enabledRoutes);
+
+      // Notify listeners (e.g. RemoteIngressManager) of the merged route set
+      if (this.onRoutesApplied) {
+        this.onRoutesApplied(enabledRoutes);
+      }
+
+      logger.log('info', `Applied ${enabledRoutes.length} routes to SmartProxy (${this.storedRoutes.size} programmatic, ${this.overrides.size} overrides)`);
+    });
+  }
+}

ts/config/classes.target-profile-manager.ts

@@ -0,0 +1,428 @@
+import * as plugins from '../plugins.js';
+import { logger } from '../logger.js';
+import { TargetProfileDoc, VpnClientDoc } from '../db/index.js';
+import type { ITargetProfile, ITargetProfileTarget } from '../../ts_interfaces/data/target-profile.js';
+import type { IDcRouterRouteConfig } from '../../ts_interfaces/data/remoteingress.js';
+import type { IStoredRoute } from '../../ts_interfaces/data/route-management.js';
+
+/**
+ * Manages TargetProfiles (target-side: what can be accessed).
+ * TargetProfiles define what resources a VPN client can reach:
+ * domains, specific IP:port targets, and/or direct route references.
+ */
+export class TargetProfileManager {
+  private profiles = new Map<string, ITargetProfile>();
+
+  // =========================================================================
+  // Lifecycle
+  // =========================================================================
+
+  public async initialize(): Promise<void> {
+    await this.loadProfiles();
+  }
+
+  // =========================================================================
+  // CRUD
+  // =========================================================================
+
+  public async createProfile(data: {
+    name: string;
+    description?: string;
+    domains?: string[];
+    targets?: ITargetProfileTarget[];
+    routeRefs?: string[];
+    createdBy: string;
+  }): Promise<string> {
+    // Enforce unique profile names
+    for (const existing of this.profiles.values()) {
+      if (existing.name === data.name) {
+        throw new Error(`Target profile with name '${data.name}' already exists (id: ${existing.id})`);
+      }
+    }
+
+    const id = plugins.uuid.v4();
+    const now = Date.now();
+
+    const profile: ITargetProfile = {
+      id,
+      name: data.name,
+      description: data.description,
+      domains: data.domains,
+      targets: data.targets,
+      routeRefs: data.routeRefs,
+      createdAt: now,
+      updatedAt: now,
+      createdBy: data.createdBy,
+    };
+
+    this.profiles.set(id, profile);
+    await this.persistProfile(profile);
+    logger.log('info', `Created target profile '${profile.name}' (${id})`);
+    return id;
+  }
+
+  public async updateProfile(
+    id: string,
+    patch: Partial<Omit<ITargetProfile, 'id' | 'createdAt' | 'createdBy'>>,
+  ): Promise<void> {
+    const profile = this.profiles.get(id);
+    if (!profile) {
+      throw new Error(`Target profile '${id}' not found`);
+    }
+
+    if (patch.name !== undefined) profile.name = patch.name;
+    if (patch.description !== undefined) profile.description = patch.description;
+    if (patch.domains !== undefined) profile.domains = patch.domains;
+    if (patch.targets !== undefined) profile.targets = patch.targets;
+    if (patch.routeRefs !== undefined) profile.routeRefs = patch.routeRefs;
+    profile.updatedAt = Date.now();
+
+    await this.persistProfile(profile);
+    logger.log('info', `Updated target profile '${profile.name}' (${id})`);
+  }
+
+  public async deleteProfile(
+    id: string,
+    force?: boolean,
+  ): Promise<{ success: boolean; message?: string }> {
+    const profile = this.profiles.get(id);
+    if (!profile) {
+      return { success: false, message: `Target profile '${id}' not found` };
+    }
+
+    // Check if any VPN clients reference this profile
+    const clients = await VpnClientDoc.findAll();
+    const referencingClients = clients.filter(
+      (c) => c.targetProfileIds?.includes(id),
+    );
+
+    if (referencingClients.length > 0 && !force) {
+      return {
+        success: false,
+        message: `Profile '${profile.name}' is in use by ${referencingClients.length} VPN client(s). Use force=true to delete.`,
+      };
+    }
+
+    // Delete from DB
+    const doc = await TargetProfileDoc.findById(id);
+    if (doc) await doc.delete();
+    this.profiles.delete(id);
+
+    if (referencingClients.length > 0) {
+      // Remove profile ref from clients
+      for (const client of referencingClients) {
+        client.targetProfileIds = client.targetProfileIds?.filter((pid) => pid !== id);
+        client.updatedAt = Date.now();
+        await client.save();
+      }
+      logger.log('warn', `Force-deleted target profile '${profile.name}'; removed refs from ${referencingClients.length} client(s)`);
+    } else {
+      logger.log('info', `Deleted target profile '${profile.name}' (${id})`);
+    }
+
+    return { success: true };
+  }
+
+  public getProfile(id: string): ITargetProfile | undefined {
+    return this.profiles.get(id);
+  }
+
+  public listProfiles(): ITargetProfile[] {
+    return [...this.profiles.values()];
+  }
+
+  /**
+   * Get which VPN clients reference a target profile.
+   */
+  public async getProfileUsage(profileId: string): Promise<Array<{ clientId: string; description?: string }>> {
+    const clients = await VpnClientDoc.findAll();
+    return clients
+      .filter((c) => c.targetProfileIds?.includes(profileId))
+      .map((c) => ({ clientId: c.clientId, description: c.description }));
+  }
+
+  // =========================================================================
+  // Direct target IPs (bypass SmartProxy)
+  // =========================================================================
+
+  /**
+   * For a set of target profile IDs, collect all explicit target IPs.
+   * These IPs bypass the SmartProxy forceTarget rewrite — VPN clients can
+   * connect to them directly through the tunnel.
+   */
+  public getDirectTargetIps(targetProfileIds: string[]): string[] {
+    const ips = new Set<string>();
+    for (const profileId of targetProfileIds) {
+      const profile = this.profiles.get(profileId);
+      if (!profile?.targets?.length) continue;
+      for (const t of profile.targets) {
+        ips.add(t.ip);
+      }
+    }
+    return [...ips];
+  }
+
+  // =========================================================================
+  // Core matching: route → client IPs
+  // =========================================================================
+
+  /**
+   * For a vpnOnly route, find all enabled VPN clients whose assigned TargetProfile
+   * matches the route. Returns IP allow entries for injection into ipAllowList.
+   *
+   * Entries are domain-scoped when a profile matches via specific domains that are
+   * a subset of the route's wildcard. Plain IPs are returned for routeRef/target matches
+   * or when profile domains exactly equal the route's domains.
+   */
+  public getMatchingClientIps(
+    route: IDcRouterRouteConfig,
+    routeId: string | undefined,
+    clients: VpnClientDoc[],
+  ): Array<string | { ip: string; domains: string[] }> {
+    const entries: Array<string | { ip: string; domains: string[] }> = [];
+    const routeDomains: string[] = (route.match as any)?.domains || [];
+
+    for (const client of clients) {
+      if (!client.enabled || !client.assignedIp) continue;
+      if (!client.targetProfileIds?.length) continue;
+
+      // Collect scoped domains from all matching profiles for this client
+      let fullAccess = false;
+      const scopedDomains = new Set<string>();
+
+      for (const profileId of client.targetProfileIds) {
+        const profile = this.profiles.get(profileId);
+        if (!profile) continue;
+
+        const matchResult = this.routeMatchesProfileDetailed(route, routeId, profile, routeDomains);
+        if (matchResult === 'full') {
+          fullAccess = true;
+          break; // No need to check more profiles
+        }
+        if (matchResult !== 'none') {
+          for (const d of matchResult.domains) scopedDomains.add(d);
+        }
+      }
+
+      if (fullAccess) {
+        entries.push(client.assignedIp);
+      } else if (scopedDomains.size > 0) {
+        entries.push({ ip: client.assignedIp, domains: [...scopedDomains] });
+      }
+    }
+
+    return entries;
+  }
+
+  /**
+   * For a given client (by its targetProfileIds), compute the set of
+   * domains and target IPs it can access. Used for WireGuard AllowedIPs.
+   */
+  public getClientAccessSpec(
+    targetProfileIds: string[],
+    allRoutes: IDcRouterRouteConfig[],
+    storedRoutes: Map<string, IStoredRoute>,
+  ): { domains: string[]; targetIps: string[] } {
+    const domains = new Set<string>();
+    const targetIps = new Set<string>();
+
+    // Collect all access specifiers from assigned profiles
+    for (const profileId of targetProfileIds) {
+      const profile = this.profiles.get(profileId);
+      if (!profile) continue;
+
+      // Direct domain entries
+      if (profile.domains?.length) {
+        for (const d of profile.domains) {
+          domains.add(d);
+        }
+      }
+
+      // Direct target IP entries
+      if (profile.targets?.length) {
+        for (const t of profile.targets) {
+          targetIps.add(t.ip);
+        }
+      }
+
+      // Route references: scan constructor routes
+      for (const route of allRoutes) {
+        if (this.routeMatchesProfile(route as IDcRouterRouteConfig, undefined, profile)) {
+          const routeDomains = (route.match as any)?.domains;
+          if (Array.isArray(routeDomains)) {
+            for (const d of routeDomains) {
+              domains.add(d);
+            }
+          }
+        }
+      }
+
+      // Route references: scan stored routes
+      for (const [storedId, stored] of storedRoutes) {
+        if (!stored.enabled) continue;
+        if (this.routeMatchesProfile(stored.route as IDcRouterRouteConfig, storedId, profile)) {
+          const routeDomains = (stored.route.match as any)?.domains;
+          if (Array.isArray(routeDomains)) {
+            for (const d of routeDomains) {
+              domains.add(d);
+            }
+          }
+        }
+      }
+    }
+
+    return {
+      domains: [...domains],
+      targetIps: [...targetIps],
+    };
+  }
+
+  // =========================================================================
+  // Private: matching logic
+  // =========================================================================
+
+  /**
+   * Check if a route matches a profile (boolean convenience wrapper).
+   */
+  private routeMatchesProfile(
+    route: IDcRouterRouteConfig,
+    routeId: string | undefined,
+    profile: ITargetProfile,
+  ): boolean {
+    const routeDomains: string[] = (route.match as any)?.domains || [];
+    const result = this.routeMatchesProfileDetailed(route, routeId, profile, routeDomains);
+    return result !== 'none';
+  }
+
+  /**
+   * Detailed match: returns 'full' (plain IP, entire route), 'scoped' (domain-limited),
+   * or 'none' (no match).
+   *
+   * - routeRefs / target matches → 'full' (explicit reference = full access)
+   * - domain match where profile domains are a subset of route wildcard → 'scoped'
+   * - domain match where domains are identical or profile is a wildcard → 'full'
+   */
+  private routeMatchesProfileDetailed(
+    route: IDcRouterRouteConfig,
+    routeId: string | undefined,
+    profile: ITargetProfile,
+    routeDomains: string[],
+  ): 'full' | { type: 'scoped'; domains: string[] } | 'none' {
+    // 1. Route reference match → full access
+    if (profile.routeRefs?.length) {
+      if (routeId && profile.routeRefs.includes(routeId)) return 'full';
+      if (route.name && profile.routeRefs.includes(route.name)) return 'full';
+    }
+
+    // 2. Domain match
+    if (profile.domains?.length && routeDomains.length) {
+      const matchedProfileDomains: string[] = [];
+
+      for (const profileDomain of profile.domains) {
+        for (const routeDomain of routeDomains) {
+          if (this.domainMatchesPattern(routeDomain, profileDomain) ||
+              this.domainMatchesPattern(profileDomain, routeDomain)) {
+            matchedProfileDomains.push(profileDomain);
+            break; // This profileDomain matched, move to the next
+          }
+        }
+      }
+
+      if (matchedProfileDomains.length > 0) {
+        // Check if profile domains cover the route entirely (same wildcards = full access)
+        const isFullCoverage = routeDomains.every((rd) =>
+          matchedProfileDomains.some((pd) =>
+            rd === pd || this.domainMatchesPattern(rd, pd),
+          ),
+        );
+        if (isFullCoverage) return 'full';
+
+        // Profile domains are a subset → scoped access to those specific domains
+        return { type: 'scoped', domains: matchedProfileDomains };
+      }
+    }
+
+    // 3. Target match (host + port) → full access (precise by nature)
+    if (profile.targets?.length) {
+      const routeTargets = (route.action as any)?.targets;
+      if (Array.isArray(routeTargets)) {
+        for (const profileTarget of profile.targets) {
+          for (const routeTarget of routeTargets) {
+            const routeHost = routeTarget.host;
+            const routePort = routeTarget.port;
+            if (routeHost === profileTarget.ip && routePort === profileTarget.port) {
+              return 'full';
+            }
+          }
+        }
+      }
+    }
+
+    return 'none';
+  }
+
+  /**
+   * Check if a domain matches a pattern.
+   * - '*.example.com' matches 'sub.example.com', 'a.b.example.com'
+   * - 'example.com' matches only 'example.com'
+   */
+  private domainMatchesPattern(domain: string, pattern: string): boolean {
+    if (pattern === domain) return true;
+    if (pattern.startsWith('*.')) {
+      const suffix = pattern.slice(1); // '.example.com'
+      return domain.endsWith(suffix) && domain.length > suffix.length;
+    }
+    return false;
+  }
+
+  // =========================================================================
+  // Private: persistence
+  // =========================================================================
+
+  private async loadProfiles(): Promise<void> {
+    const docs = await TargetProfileDoc.findAll();
+    for (const doc of docs) {
+      if (doc.id) {
+        this.profiles.set(doc.id, {
+          id: doc.id,
+          name: doc.name,
+          description: doc.description,
+          domains: doc.domains,
+          targets: doc.targets,
+          routeRefs: doc.routeRefs,
+          createdAt: doc.createdAt,
+          updatedAt: doc.updatedAt,
+          createdBy: doc.createdBy,
+        });
+      }
+    }
+    if (this.profiles.size > 0) {
+      logger.log('info', `Loaded ${this.profiles.size} target profile(s) from storage`);
+    }
+  }
+
+  private async persistProfile(profile: ITargetProfile): Promise<void> {
+    const existingDoc = await TargetProfileDoc.findById(profile.id);
+    if (existingDoc) {
+      existingDoc.name = profile.name;
+      existingDoc.description = profile.description;
+      existingDoc.domains = profile.domains;
+      existingDoc.targets = profile.targets;
+      existingDoc.routeRefs = profile.routeRefs;
+      existingDoc.updatedAt = profile.updatedAt;
+      await existingDoc.save();
+    } else {
+      const doc = new TargetProfileDoc();
+      doc.id = profile.id;
+      doc.name = profile.name;
+      doc.description = profile.description;
+      doc.domains = profile.domains;
+      doc.targets = profile.targets;
+      doc.routeRefs = profile.routeRefs;
+      doc.createdAt = profile.createdAt;
+      doc.updatedAt = profile.updatedAt;
+      doc.createdBy = profile.createdBy;
+      await doc.save();
+    }
+  }
+}

ts/config/index.ts

@@ -1,2 +1,7 @@
 // Export validation tools only
-export * from './validator.js';
+export * from './validator.js';
+export { RouteConfigManager } from './classes.route-config-manager.js';
+export { ApiTokenManager } from './classes.api-token-manager.js';
+export { ReferenceResolver } from './classes.reference-resolver.js';
+export { DbSeeder } from './classes.db-seeder.js';
+export { TargetProfileManager } from './classes.target-profile-manager.js';

ts/config/validator.ts

@@ -170,7 +170,7 @@ export class ConfigValidator {
                 } else if (rules.items.schema && itemType === 'object') {
                   const itemResult = this.validate(value[i], rules.items.schema);
                   if (!itemResult.valid) {
-                    errors.push(...itemResult.errors.map(err => `${key}[${i}].${err}`));
+                    errors.push(...itemResult.errors!.map(err => `${key}[${i}].${err}`));
                   }
                 }
               }
@@ -181,7 +181,7 @@ export class ConfigValidator {
             if (rules.schema) {
               const nestedResult = this.validate(value, rules.schema);
               if (!nestedResult.valid) {
-                errors.push(...nestedResult.errors.map(err => `${key}.${err}`));
+                errors.push(...nestedResult.errors!.map(err => `${key}.${err}`));
               }
               validatedConfig[key] = nestedResult.config;
             }
@@ -233,8 +233,8 @@ export class ConfigValidator {
 
       // Apply defaults to array items
       if (result[key] && rules.type === 'array' && rules.items && rules.items.schema) {
-        result[key] = result[key].map(item => 
-          typeof item === 'object' ? this.applyDefaults(item, rules.items.schema) : item
+        result[key] = result[key].map(item =>
+          typeof item === 'object' ? this.applyDefaults(item, rules.items!.schema!) : item
         );
       }
     }
@@ -255,7 +255,7 @@ export class ConfigValidator {
     
     if (!result.valid) {
       throw new ValidationError(
-        `Configuration validation failed: ${result.errors.join(', ')}`,
+        `Configuration validation failed: ${result.errors!.join(', ')}`,
         'CONFIG_VALIDATION_ERROR',
         { data: { errors: result.errors } }
       );

ts/db/classes.cache.cleaner.ts

@@ -1,6 +1,6 @@
 import * as plugins from '../plugins.js';
 import { logger } from '../logger.js';
-import { CacheDb } from './classes.cachedb.js';
+import { DcRouterDb } from './classes.dcrouter-db.js';
 
 // Import document classes for cleanup
 import { CachedEmail } from './documents/classes.cached.email.js';
@@ -26,10 +26,10 @@ export class CacheCleaner {
   private cleanupInterval: ReturnType<typeof setInterval> | null = null;
   private isRunning: boolean = false;
   private options: Required<ICacheCleanerOptions>;
-  private cacheDb: CacheDb;
+  private dcRouterDb: DcRouterDb;
 
-  constructor(cacheDb: CacheDb, options: ICacheCleanerOptions = {}) {
-    this.cacheDb = cacheDb;
+  constructor(dcRouterDb: DcRouterDb, options: ICacheCleanerOptions = {}) {
+    this.dcRouterDb = dcRouterDb;
     this.options = {
       intervalMs: options.intervalMs || 60 * 60 * 1000, // 1 hour default
       verbose: options.verbose || false,
@@ -48,14 +48,14 @@ export class CacheCleaner {
     this.isRunning = true;
 
     // Run cleanup immediately on start
-    this.runCleanup().catch((error) => {
-      logger.log('error', `Initial cache cleanup failed: ${error.message}`);
+    this.runCleanup().catch((error: unknown) => {
+      logger.log('error', `Initial cache cleanup failed: ${(error as Error).message}`);
     });
 
     // Schedule periodic cleanup
     this.cleanupInterval = setInterval(() => {
-      this.runCleanup().catch((error) => {
-        logger.log('error', `Cache cleanup failed: ${error.message}`);
+      this.runCleanup().catch((error: unknown) => {
+        logger.log('error', `Cache cleanup failed: ${(error as Error).message}`);
       });
     }, this.options.intervalMs);
 
@@ -86,8 +86,8 @@ export class CacheCleaner {
    * Run a single cleanup cycle
    */
   public async runCleanup(): Promise<void> {
-    if (!this.cacheDb.isReady()) {
-      logger.log('warn', 'CacheDb not ready, skipping cleanup');
+    if (!this.dcRouterDb.isReady()) {
+      logger.log('warn', 'DcRouterDb not ready, skipping cleanup');
       return;
     }
 
@@ -113,8 +113,8 @@ export class CacheCleaner {
           `Cache cleanup completed. Deleted ${totalDeleted} expired documents. ${summary || 'No deletions.'}`
         );
       }
-    } catch (error) {
-      logger.log('error', `Cache cleanup error: ${error.message}`);
+    } catch (error: unknown) {
+      logger.log('error', `Cache cleanup error: ${(error as Error).message}`);
       throw error;
     }
   }
@@ -138,14 +138,14 @@ export class CacheCleaner {
         try {
           await doc.delete();
           deletedCount++;
-        } catch (deleteError) {
-          logger.log('warn', `Failed to delete expired document: ${deleteError.message}`);
+        } catch (deleteError: unknown) {
+          logger.log('warn', `Failed to delete expired document: ${(deleteError as Error).message}`);
         }
       }
 
       return deletedCount;
-    } catch (error) {
-      logger.log('error', `Error cleaning collection: ${error.message}`);
+    } catch (error: unknown) {
+      logger.log('error', `Error cleaning collection: ${(error as Error).message}`);
       return 0;
     }
   }

ts/db/classes.cached.document.ts

@@ -22,7 +22,7 @@ export abstract class CachedDocument<T extends CachedDocument<T>> extends plugin
    * Timestamp when the document expires and should be cleaned up
    * NOTE: Subclasses must add @svDb() decorator
    */
-  public expiresAt: Date;
+  public expiresAt!: Date;
 
   /**
    * Timestamp of last access (for LRU-style eviction if needed)

ts/db/classes.dcrouter-db.ts

@@ -0,0 +1,179 @@
+import * as plugins from '../plugins.js';
+import { logger } from '../logger.js';
+import { defaultTsmDbPath } from '../paths.js';
+
+/**
+ * Configuration options for the unified DCRouter database
+ */
+export interface IDcRouterDbConfig {
+  /** External MongoDB connection URL. If absent, uses embedded LocalSmartDb. */
+  mongoDbUrl?: string;
+  /** Storage path for embedded LocalSmartDb data (default: ~/.serve.zone/dcrouter/tsmdb) */
+  storagePath?: string;
+  /** Database name (default: dcrouter) */
+  dbName?: string;
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+/**
+ * DcRouterDb - Unified database layer for DCRouter
+ *
+ * Replaces both StorageManager (flat-file key-value) and CacheDb (embedded MongoDB).
+ * All data is stored as smartdata document classes in a single database.
+ *
+ * Two modes:
+ * - **Embedded** (default): Spawns a LocalSmartDb (Rust-based MongoDB-compatible engine)
+ * - **External**: Connects to a provided MongoDB URL
+ */
+export class DcRouterDb {
+  private static instance: DcRouterDb | null = null;
+
+  private localSmartDb: plugins.smartdb.LocalSmartDb | null = null;
+  private smartdataDb!: plugins.smartdata.SmartdataDb;
+  private options: Required<IDcRouterDbConfig>;
+  private isStarted: boolean = false;
+
+  constructor(options: IDcRouterDbConfig = {}) {
+    this.options = {
+      mongoDbUrl: options.mongoDbUrl || '',
+      storagePath: options.storagePath || defaultTsmDbPath,
+      dbName: options.dbName || 'dcrouter',
+      debug: options.debug || false,
+    };
+  }
+
+  /**
+   * Get or create the singleton instance
+   */
+  public static getInstance(options?: IDcRouterDbConfig): DcRouterDb {
+    if (!DcRouterDb.instance) {
+      DcRouterDb.instance = new DcRouterDb(options);
+    }
+    return DcRouterDb.instance;
+  }
+
+  /**
+   * Reset the singleton instance (useful for testing)
+   */
+  public static resetInstance(): void {
+    DcRouterDb.instance = null;
+  }
+
+  /**
+   * Start the database
+   * - If mongoDbUrl is provided, connects directly to external MongoDB
+   * - Otherwise, starts an embedded LocalSmartDb instance
+   */
+  public async start(): Promise<void> {
+    if (this.isStarted) {
+      logger.log('warn', 'DcRouterDb already started');
+      return;
+    }
+
+    try {
+      let connectionUri: string;
+
+      if (this.options.mongoDbUrl) {
+        // External MongoDB mode
+        connectionUri = this.options.mongoDbUrl;
+        logger.log('info', `DcRouterDb connecting to external MongoDB`);
+      } else {
+        // Embedded LocalSmartDb mode
+        await plugins.fsUtils.ensureDir(this.options.storagePath);
+
+        this.localSmartDb = new plugins.smartdb.LocalSmartDb({
+          folderPath: this.options.storagePath,
+        });
+
+        const connectionInfo = await this.localSmartDb.start();
+        connectionUri = connectionInfo.connectionUri;
+
+        if (this.options.debug) {
+          logger.log('debug', `LocalSmartDb started with URI: ${connectionUri}`);
+        }
+
+        logger.log('info', `DcRouterDb started embedded instance at ${this.options.storagePath}`);
+      }
+
+      // Initialize smartdata ORM
+      this.smartdataDb = new plugins.smartdata.SmartdataDb({
+        mongoDbUrl: connectionUri,
+        mongoDbName: this.options.dbName,
+      });
+      await this.smartdataDb.init();
+
+      this.isStarted = true;
+      logger.log('info', `DcRouterDb ready (db: ${this.options.dbName})`);
+    } catch (error: unknown) {
+      logger.log('error', `Failed to start DcRouterDb: ${(error as Error).message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Stop the database
+   */
+  public async stop(): Promise<void> {
+    if (!this.isStarted) {
+      return;
+    }
+
+    try {
+      // Close smartdata connection
+      if (this.smartdataDb) {
+        await this.smartdataDb.close();
+      }
+
+      // Stop embedded LocalSmartDb if running
+      if (this.localSmartDb) {
+        await this.localSmartDb.stop();
+        this.localSmartDb = null;
+      }
+
+      this.isStarted = false;
+      logger.log('info', 'DcRouterDb stopped');
+    } catch (error: unknown) {
+      logger.log('error', `Error stopping DcRouterDb: ${(error as Error).message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Get the smartdata database instance for @Collection decorators
+   */
+  public getDb(): plugins.smartdata.SmartdataDb {
+    if (!this.isStarted) {
+      throw new Error('DcRouterDb not started. Call start() first.');
+    }
+    return this.smartdataDb;
+  }
+
+  /**
+   * Check if the database is ready
+   */
+  public isReady(): boolean {
+    return this.isStarted;
+  }
+
+  /**
+   * Whether running in embedded mode (LocalSmartDb) vs external MongoDB
+   */
+  public isEmbedded(): boolean {
+    return !this.options.mongoDbUrl;
+  }
+
+  /**
+   * Get the storage path (only relevant for embedded mode)
+   */
+  public getStoragePath(): string {
+    return this.options.storagePath;
+  }
+
+  /**
+   * Get the database name
+   */
+  public getDbName(): string {
+    return this.options.dbName;
+  }
+}

ts/db/documents/classes.accounting-session.doc.ts

@@ -0,0 +1,106 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class AccountingSessionDoc extends plugins.smartdata.SmartDataDbDoc<AccountingSessionDoc, AccountingSessionDoc> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public sessionId!: string;
+
+  @plugins.smartdata.svDb()
+  public username!: string;
+
+  @plugins.smartdata.svDb()
+  public macAddress!: string;
+
+  @plugins.smartdata.svDb()
+  public nasIpAddress!: string;
+
+  @plugins.smartdata.svDb()
+  public nasPort!: number;
+
+  @plugins.smartdata.svDb()
+  public nasPortType!: string;
+
+  @plugins.smartdata.svDb()
+  public nasIdentifier!: string;
+
+  @plugins.smartdata.svDb()
+  public vlanId!: number;
+
+  @plugins.smartdata.svDb()
+  public framedIpAddress!: string;
+
+  @plugins.smartdata.svDb()
+  public calledStationId!: string;
+
+  @plugins.smartdata.svDb()
+  public callingStationId!: string;
+
+  @plugins.smartdata.svDb()
+  public startTime!: number;
+
+  @plugins.smartdata.svDb()
+  public endTime!: number;
+
+  @plugins.smartdata.svDb()
+  public lastUpdateTime!: number;
+
+  @plugins.smartdata.index()
+  @plugins.smartdata.svDb()
+  public status!: 'active' | 'stopped' | 'terminated';
+
+  @plugins.smartdata.svDb()
+  public terminateCause!: string;
+
+  @plugins.smartdata.svDb()
+  public inputOctets!: number;
+
+  @plugins.smartdata.svDb()
+  public outputOctets!: number;
+
+  @plugins.smartdata.svDb()
+  public inputPackets!: number;
+
+  @plugins.smartdata.svDb()
+  public outputPackets!: number;
+
+  @plugins.smartdata.svDb()
+  public sessionTime!: number;
+
+  @plugins.smartdata.svDb()
+  public serviceType!: string;
+
+  constructor() {
+    super();
+  }
+
+  public static async findBySessionId(sessionId: string): Promise<AccountingSessionDoc | null> {
+    return await AccountingSessionDoc.getInstance({ sessionId });
+  }
+
+  public static async findActive(): Promise<AccountingSessionDoc[]> {
+    return await AccountingSessionDoc.getInstances({ status: 'active' });
+  }
+
+  public static async findByUsername(username: string): Promise<AccountingSessionDoc[]> {
+    return await AccountingSessionDoc.getInstances({ username });
+  }
+
+  public static async findByNas(nasIpAddress: string): Promise<AccountingSessionDoc[]> {
+    return await AccountingSessionDoc.getInstances({ nasIpAddress });
+  }
+
+  public static async findByVlan(vlanId: number): Promise<AccountingSessionDoc[]> {
+    return await AccountingSessionDoc.getInstances({ vlanId });
+  }
+
+  public static async findStoppedBefore(cutoffTime: number): Promise<AccountingSessionDoc[]> {
+    return await AccountingSessionDoc.getInstances({
+      status: { $in: ['stopped', 'terminated'] } as any,
+      endTime: { $lt: cutoffTime, $gt: 0 } as any,
+    });
+  }
+}

ts/db/documents/classes.acme-cert.doc.ts

@@ -0,0 +1,41 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class AcmeCertDoc extends plugins.smartdata.SmartDataDbDoc<AcmeCertDoc, AcmeCertDoc> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public domainName!: string;
+
+  @plugins.smartdata.svDb()
+  public id!: string;
+
+  @plugins.smartdata.svDb()
+  public created!: number;
+
+  @plugins.smartdata.svDb()
+  public privateKey!: string;
+
+  @plugins.smartdata.svDb()
+  public publicKey!: string;
+
+  @plugins.smartdata.svDb()
+  public csr!: string;
+
+  @plugins.smartdata.svDb()
+  public validUntil!: number;
+
+  constructor() {
+    super();
+  }
+
+  public static async findByDomain(domainName: string): Promise<AcmeCertDoc | null> {
+    return await AcmeCertDoc.getInstance({ domainName });
+  }
+
+  public static async findAll(): Promise<AcmeCertDoc[]> {
+    return await AcmeCertDoc.getInstances({});
+  }
+}

ts/db/documents/classes.acme-config.doc.ts

@@ -0,0 +1,49 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+/**
+ * Singleton ACME configuration document. One row per dcrouter instance,
+ * keyed on the fixed `configId = 'acme-config'` following the
+ * `VpnServerKeysDoc` pattern.
+ *
+ * Replaces the legacy `tls.contactEmail` and `smartProxyConfig.acme.*`
+ * constructor fields. Managed via the OpsServer UI at
+ * **Domains > Certificates > Settings**.
+ */
+@plugins.smartdata.Collection(() => getDb())
+export class AcmeConfigDoc extends plugins.smartdata.SmartDataDbDoc<AcmeConfigDoc, AcmeConfigDoc> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public configId: string = 'acme-config';
+
+  @plugins.smartdata.svDb()
+  public accountEmail: string = '';
+
+  @plugins.smartdata.svDb()
+  public enabled: boolean = true;
+
+  @plugins.smartdata.svDb()
+  public useProduction: boolean = true;
+
+  @plugins.smartdata.svDb()
+  public autoRenew: boolean = true;
+
+  @plugins.smartdata.svDb()
+  public renewThresholdDays: number = 30;
+
+  @plugins.smartdata.svDb()
+  public updatedAt: number = 0;
+
+  @plugins.smartdata.svDb()
+  public updatedBy: string = '';
+
+  constructor() {
+    super();
+  }
+
+  public static async load(): Promise<AcmeConfigDoc | null> {
+    return await AcmeConfigDoc.getInstance({ configId: 'acme-config' });
+  }
+}

ts/db/documents/classes.api-token.doc.ts

@@ -0,0 +1,56 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+import type { TApiTokenScope } from '../../../ts_interfaces/data/route-management.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class ApiTokenDoc extends plugins.smartdata.SmartDataDbDoc<ApiTokenDoc, ApiTokenDoc> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public id!: string;
+
+  @plugins.smartdata.svDb()
+  public name: string = '';
+
+  @plugins.smartdata.svDb()
+  public tokenHash!: string;
+
+  @plugins.smartdata.svDb()
+  public scopes!: TApiTokenScope[];
+
+  @plugins.smartdata.svDb()
+  public createdAt!: number;
+
+  @plugins.smartdata.svDb()
+  public expiresAt!: number | null;
+
+  @plugins.smartdata.svDb()
+  public lastUsedAt!: number | null;
+
+  @plugins.smartdata.svDb()
+  public createdBy!: string;
+
+  @plugins.smartdata.svDb()
+  public enabled!: boolean;
+
+  constructor() {
+    super();
+  }
+
+  public static async findById(id: string): Promise<ApiTokenDoc | null> {
+    return await ApiTokenDoc.getInstance({ id });
+  }
+
+  public static async findByTokenHash(tokenHash: string): Promise<ApiTokenDoc | null> {
+    return await ApiTokenDoc.getInstance({ tokenHash });
+  }
+
+  public static async findAll(): Promise<ApiTokenDoc[]> {
+    return await ApiTokenDoc.getInstances({});
+  }
+
+  public static async findEnabled(): Promise<ApiTokenDoc[]> {
+    return await ApiTokenDoc.getInstances({ enabled: true });
+  }
+}

ts/db/documents/classes.cached.email.ts

@@ -1,6 +1,6 @@
 import * as plugins from '../../plugins.js';
 import { CachedDocument, TTL } from '../classes.cached.document.js';
-import { CacheDb } from '../classes.cachedb.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
 
 /**
  * Email status in the cache
@@ -10,7 +10,7 @@ export type TCachedEmailStatus = 'pending' | 'processing' | 'delivered' | 'faile
 /**
  * Helper to get the smartdata database instance
  */
-const getDb = () => CacheDb.getInstance().getDb();
+const getDb = () => DcRouterDb.getInstance().getDb();
 
 /**
  * CachedEmail - Stores email queue items in the cache
@@ -35,55 +35,55 @@ export class CachedEmail extends CachedDocument<CachedEmail> {
    */
   @plugins.smartdata.unI()
   @plugins.smartdata.svDb()
-  public id: string;
+  public id!: string;
 
   /**
    * Email message ID (RFC 822 Message-ID header)
    */
   @plugins.smartdata.svDb()
-  public messageId: string;
+  public messageId!: string;
 
   /**
    * Sender email address (envelope from)
    */
   @plugins.smartdata.svDb()
-  public from: string;
+  public from!: string;
 
   /**
    * Recipient email addresses
    */
   @plugins.smartdata.svDb()
-  public to: string[];
+  public to!: string[];
 
   /**
    * CC recipients
    */
   @plugins.smartdata.svDb()
-  public cc: string[];
+  public cc!: string[];
 
   /**
    * BCC recipients
    */
   @plugins.smartdata.svDb()
-  public bcc: string[];
+  public bcc!: string[];
 
   /**
    * Email subject
    */
   @plugins.smartdata.svDb()
-  public subject: string;
+  public subject!: string;
 
   /**
    * Raw RFC822 email content
    */
   @plugins.smartdata.svDb()
-  public rawContent: string;
+  public rawContent!: string;
 
   /**
    * Current status of the email
    */
   @plugins.smartdata.svDb()
-  public status: TCachedEmailStatus;
+  public status!: TCachedEmailStatus;
 
   /**
    * Number of delivery attempts
@@ -101,25 +101,25 @@ export class CachedEmail extends CachedDocument<CachedEmail> {
    * Timestamp for next delivery attempt
    */
   @plugins.smartdata.svDb()
-  public nextAttempt: Date;
+  public nextAttempt!: Date;
 
   /**
    * Last error message if delivery failed
    */
   @plugins.smartdata.svDb()
-  public lastError: string;
+  public lastError!: string;
 
   /**
    * Timestamp when the email was successfully delivered
    */
   @plugins.smartdata.svDb()
-  public deliveredAt: Date;
+  public deliveredAt!: Date;
 
   /**
    * Sender domain (for querying/filtering)
    */
   @plugins.smartdata.svDb()
-  public senderDomain: string;
+  public senderDomain!: string;
 
   /**
    * Priority level (higher = more important)
@@ -131,7 +131,7 @@ export class CachedEmail extends CachedDocument<CachedEmail> {
    * JSON-serialized route data
    */
   @plugins.smartdata.svDb()
-  public routeData: string;
+  public routeData!: string;
 
   /**
    * DKIM signature status

ts/db/documents/classes.cached.ip.reputation.ts

@@ -1,11 +1,11 @@
 import * as plugins from '../../plugins.js';
 import { CachedDocument, TTL } from '../classes.cached.document.js';
-import { CacheDb } from '../classes.cachedb.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
 
 /**
  * Helper to get the smartdata database instance
  */
-const getDb = () => CacheDb.getInstance().getDb();
+const getDb = () => DcRouterDb.getInstance().getDb();
 
 /**
  * IP reputation result data
@@ -45,61 +45,61 @@ export class CachedIPReputation extends CachedDocument<CachedIPReputation> {
    */
   @plugins.smartdata.unI()
   @plugins.smartdata.svDb()
-  public ipAddress: string;
+  public ipAddress!: string;
 
   /**
    * Reputation score (0-100, higher = better)
    */
   @plugins.smartdata.svDb()
-  public score: number;
+  public score!: number;
 
   /**
    * Whether the IP is flagged as spam source
    */
   @plugins.smartdata.svDb()
-  public isSpam: boolean;
+  public isSpam!: boolean;
 
   /**
    * Whether the IP is a known proxy
    */
   @plugins.smartdata.svDb()
-  public isProxy: boolean;
+  public isProxy!: boolean;
 
   /**
    * Whether the IP is a Tor exit node
    */
   @plugins.smartdata.svDb()
-  public isTor: boolean;
+  public isTor!: boolean;
 
   /**
    * Whether the IP is a VPN endpoint
    */
   @plugins.smartdata.svDb()
-  public isVPN: boolean;
+  public isVPN!: boolean;
 
   /**
    * Country code (ISO 3166-1 alpha-2)
    */
   @plugins.smartdata.svDb()
-  public country: string;
+  public country!: string;
 
   /**
    * Autonomous System Number
    */
   @plugins.smartdata.svDb()
-  public asn: string;
+  public asn!: string;
 
   /**
    * Organization name
    */
   @plugins.smartdata.svDb()
-  public org: string;
+  public org!: string;
 
   /**
    * List of blacklists the IP appears on
    */
   @plugins.smartdata.svDb()
-  public blacklists: string[];
+  public blacklists!: string[];
 
   /**
    * Number of times this IP has been checked

ts/db/documents/classes.cert-backoff.doc.ts

@@ -0,0 +1,35 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class CertBackoffDoc extends plugins.smartdata.SmartDataDbDoc<CertBackoffDoc, CertBackoffDoc> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public domain!: string;
+
+  @plugins.smartdata.svDb()
+  public failures!: number;
+
+  @plugins.smartdata.svDb()
+  public lastFailure!: string;
+
+  @plugins.smartdata.svDb()
+  public retryAfter!: string;
+
+  @plugins.smartdata.svDb()
+  public lastError!: string;
+
+  constructor() {
+    super();
+  }
+
+  public static async findByDomain(domain: string): Promise<CertBackoffDoc | null> {
+    return await CertBackoffDoc.getInstance({ domain });
+  }
+
+  public static async findAll(): Promise<CertBackoffDoc[]> {
+    return await CertBackoffDoc.getInstances({});
+  }
+}

ts/db/documents/classes.dns-provider.doc.ts

@@ -0,0 +1,63 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+import type {
+  TDnsProviderType,
+  TDnsProviderStatus,
+  TDnsProviderCredentials,
+} from '../../../ts_interfaces/data/dns-provider.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class DnsProviderDoc extends plugins.smartdata.SmartDataDbDoc<DnsProviderDoc, DnsProviderDoc> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public id!: string;
+
+  @plugins.smartdata.svDb()
+  public name: string = '';
+
+  @plugins.smartdata.svDb()
+  public type!: TDnsProviderType;
+
+  /**
+   * Provider credentials, persisted as an opaque object. Shape varies by `type`.
+   * Never returned to the UI — handlers map to IDnsProviderPublic before sending.
+   */
+  @plugins.smartdata.svDb()
+  public credentials!: TDnsProviderCredentials;
+
+  @plugins.smartdata.svDb()
+  public status: TDnsProviderStatus = 'untested';
+
+  @plugins.smartdata.svDb()
+  public lastTestedAt?: number;
+
+  @plugins.smartdata.svDb()
+  public lastError?: string;
+
+  @plugins.smartdata.svDb()
+  public createdAt!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public createdBy!: string;
+
+  constructor() {
+    super();
+  }
+
+  public static async findById(id: string): Promise<DnsProviderDoc | null> {
+    return await DnsProviderDoc.getInstance({ id });
+  }
+
+  public static async findAll(): Promise<DnsProviderDoc[]> {
+    return await DnsProviderDoc.getInstances({});
+  }
+
+  public static async findByType(type: TDnsProviderType): Promise<DnsProviderDoc[]> {
+    return await DnsProviderDoc.getInstances({ type });
+  }
+}

ts/db/documents/classes.dns-record.doc.ts

@@ -0,0 +1,62 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+import type { TDnsRecordType, TDnsRecordSource } from '../../../ts_interfaces/data/dns-record.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class DnsRecordDoc extends plugins.smartdata.SmartDataDbDoc<DnsRecordDoc, DnsRecordDoc> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public id!: string;
+
+  @plugins.smartdata.svDb()
+  public domainId!: string;
+
+  /** FQDN of the record (e.g. 'www.example.com'). */
+  @plugins.smartdata.svDb()
+  public name: string = '';
+
+  @plugins.smartdata.svDb()
+  public type!: TDnsRecordType;
+
+  @plugins.smartdata.svDb()
+  public value!: string;
+
+  @plugins.smartdata.svDb()
+  public ttl: number = 300;
+
+  @plugins.smartdata.svDb()
+  public proxied?: boolean;
+
+  @plugins.smartdata.svDb()
+  public source!: TDnsRecordSource;
+
+  @plugins.smartdata.svDb()
+  public providerRecordId?: string;
+
+  @plugins.smartdata.svDb()
+  public createdAt!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public createdBy!: string;
+
+  constructor() {
+    super();
+  }
+
+  public static async findById(id: string): Promise<DnsRecordDoc | null> {
+    return await DnsRecordDoc.getInstance({ id });
+  }
+
+  public static async findAll(): Promise<DnsRecordDoc[]> {
+    return await DnsRecordDoc.getInstances({});
+  }
+
+  public static async findByDomainId(domainId: string): Promise<DnsRecordDoc[]> {
+    return await DnsRecordDoc.getInstances({ domainId });
+  }
+}

ts/db/documents/classes.domain.doc.ts

@@ -0,0 +1,66 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+import type { TDomainSource } from '../../../ts_interfaces/data/domain.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class DomainDoc extends plugins.smartdata.SmartDataDbDoc<DomainDoc, DomainDoc> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public id!: string;
+
+  /** FQDN — kept lowercased on save. */
+  @plugins.smartdata.svDb()
+  public name: string = '';
+
+  @plugins.smartdata.svDb()
+  public source!: TDomainSource;
+
+  @plugins.smartdata.svDb()
+  public providerId?: string;
+
+  @plugins.smartdata.svDb()
+  public authoritative: boolean = false;
+
+  @plugins.smartdata.svDb()
+  public nameservers?: string[];
+
+  @plugins.smartdata.svDb()
+  public externalZoneId?: string;
+
+  @plugins.smartdata.svDb()
+  public lastSyncedAt?: number;
+
+  @plugins.smartdata.svDb()
+  public description?: string;
+
+  @plugins.smartdata.svDb()
+  public createdAt!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public createdBy!: string;
+
+  constructor() {
+    super();
+  }
+
+  public static async findById(id: string): Promise<DomainDoc | null> {
+    return await DomainDoc.getInstance({ id });
+  }
+
+  public static async findByName(name: string): Promise<DomainDoc | null> {
+    return await DomainDoc.getInstance({ name: name.toLowerCase() });
+  }
+
+  public static async findAll(): Promise<DomainDoc[]> {
+    return await DomainDoc.getInstances({});
+  }
+
+  public static async findByProviderId(providerId: string): Promise<DomainDoc[]> {
+    return await DomainDoc.getInstances({ providerId });
+  }
+}

ts/db/documents/classes.network-target.doc.ts

@@ -0,0 +1,48 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class NetworkTargetDoc extends plugins.smartdata.SmartDataDbDoc<NetworkTargetDoc, NetworkTargetDoc> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public id!: string;
+
+  @plugins.smartdata.svDb()
+  public name: string = '';
+
+  @plugins.smartdata.svDb()
+  public description?: string;
+
+  @plugins.smartdata.svDb()
+  public host!: string | string[];
+
+  @plugins.smartdata.svDb()
+  public port!: number;
+
+  @plugins.smartdata.svDb()
+  public createdAt!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public createdBy!: string;
+
+  constructor() {
+    super();
+  }
+
+  public static async findById(id: string): Promise<NetworkTargetDoc | null> {
+    return await NetworkTargetDoc.getInstance({ id });
+  }
+
+  public static async findByName(name: string): Promise<NetworkTargetDoc | null> {
+    return await NetworkTargetDoc.getInstance({ name });
+  }
+
+  public static async findAll(): Promise<NetworkTargetDoc[]> {
+    return await NetworkTargetDoc.getInstances({});
+  }
+}

ts/db/documents/classes.proxy-cert.doc.ts

@@ -0,0 +1,38 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class ProxyCertDoc extends plugins.smartdata.SmartDataDbDoc<ProxyCertDoc, ProxyCertDoc> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public domain!: string;
+
+  @plugins.smartdata.svDb()
+  public publicKey!: string;
+
+  @plugins.smartdata.svDb()
+  public privateKey!: string;
+
+  @plugins.smartdata.svDb()
+  public ca!: string;
+
+  @plugins.smartdata.svDb()
+  public validUntil!: number;
+
+  @plugins.smartdata.svDb()
+  public validFrom!: number;
+
+  constructor() {
+    super();
+  }
+
+  public static async findByDomain(domain: string): Promise<ProxyCertDoc | null> {
+    return await ProxyCertDoc.getInstance({ domain });
+  }
+
+  public static async findAll(): Promise<ProxyCertDoc[]> {
+    return await ProxyCertDoc.getInstances({});
+  }
+}

ts/db/documents/classes.remote-ingress-edge.doc.ts

@@ -0,0 +1,54 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class RemoteIngressEdgeDoc extends plugins.smartdata.SmartDataDbDoc<RemoteIngressEdgeDoc, RemoteIngressEdgeDoc> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public id!: string;
+
+  @plugins.smartdata.svDb()
+  public name: string = '';
+
+  @plugins.smartdata.svDb()
+  public secret!: string;
+
+  @plugins.smartdata.svDb()
+  public listenPorts!: number[];
+
+  @plugins.smartdata.svDb()
+  public listenPortsUdp!: number[];
+
+  @plugins.smartdata.svDb()
+  public enabled!: boolean;
+
+  @plugins.smartdata.svDb()
+  public autoDerivePorts!: boolean;
+
+  @plugins.smartdata.svDb()
+  public tags!: string[];
+
+  @plugins.smartdata.svDb()
+  public createdAt!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: number;
+
+  constructor() {
+    super();
+  }
+
+  public static async findById(id: string): Promise<RemoteIngressEdgeDoc | null> {
+    return await RemoteIngressEdgeDoc.getInstance({ id });
+  }
+
+  public static async findAll(): Promise<RemoteIngressEdgeDoc[]> {
+    return await RemoteIngressEdgeDoc.getInstances({});
+  }
+
+  public static async findEnabled(): Promise<RemoteIngressEdgeDoc[]> {
+    return await RemoteIngressEdgeDoc.getInstances({ enabled: true });
+  }
+}

ts/db/documents/classes.route-override.doc.ts

@@ -0,0 +1,32 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class RouteOverrideDoc extends plugins.smartdata.SmartDataDbDoc<RouteOverrideDoc, RouteOverrideDoc> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public routeName!: string;
+
+  @plugins.smartdata.svDb()
+  public enabled!: boolean;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedBy!: string;
+
+  constructor() {
+    super();
+  }
+
+  public static async findByRouteName(routeName: string): Promise<RouteOverrideDoc | null> {
+    return await RouteOverrideDoc.getInstance({ routeName });
+  }
+
+  public static async findAll(): Promise<RouteOverrideDoc[]> {
+    return await RouteOverrideDoc.getInstances({});
+  }
+}

ts/db/documents/classes.source-profile.doc.ts

@@ -0,0 +1,45 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+import type { IRouteSecurity } from '../../../ts_interfaces/data/route-management.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class SourceProfileDoc extends plugins.smartdata.SmartDataDbDoc<SourceProfileDoc, SourceProfileDoc> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public id!: string;
+
+  @plugins.smartdata.svDb()
+  public name: string = '';
+
+  @plugins.smartdata.svDb()
+  public description?: string;
+
+  @plugins.smartdata.svDb()
+  public security!: IRouteSecurity;
+
+  @plugins.smartdata.svDb()
+  public extendsProfiles?: string[];
+
+  @plugins.smartdata.svDb()
+  public createdAt!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public createdBy!: string;
+
+  constructor() {
+    super();
+  }
+
+  public static async findById(id: string): Promise<SourceProfileDoc | null> {
+    return await SourceProfileDoc.getInstance({ id });
+  }
+
+  public static async findAll(): Promise<SourceProfileDoc[]> {
+    return await SourceProfileDoc.getInstances({});
+  }
+}

ts/db/documents/classes.stored-route.doc.ts

@@ -0,0 +1,43 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+import type { IRouteMetadata } from '../../../ts_interfaces/data/route-management.js';
+import type { IDcRouterRouteConfig } from '../../../ts_interfaces/data/remoteingress.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class StoredRouteDoc extends plugins.smartdata.SmartDataDbDoc<StoredRouteDoc, StoredRouteDoc> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public id!: string;
+
+  @plugins.smartdata.svDb()
+  public route!: IDcRouterRouteConfig;
+
+  @plugins.smartdata.svDb()
+  public enabled!: boolean;
+
+  @plugins.smartdata.svDb()
+  public createdAt!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public createdBy!: string;
+
+  @plugins.smartdata.svDb()
+  public metadata?: IRouteMetadata;
+
+  constructor() {
+    super();
+  }
+
+  public static async findById(id: string): Promise<StoredRouteDoc | null> {
+    return await StoredRouteDoc.getInstance({ id });
+  }
+
+  public static async findAll(): Promise<StoredRouteDoc[]> {
+    return await StoredRouteDoc.getInstances({});
+  }
+}

ts/db/documents/classes.target-profile.doc.ts

@@ -0,0 +1,48 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+import type { ITargetProfileTarget } from '../../../ts_interfaces/data/target-profile.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class TargetProfileDoc extends plugins.smartdata.SmartDataDbDoc<TargetProfileDoc, TargetProfileDoc> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public id!: string;
+
+  @plugins.smartdata.svDb()
+  public name: string = '';
+
+  @plugins.smartdata.svDb()
+  public description?: string;
+
+  @plugins.smartdata.svDb()
+  public domains?: string[];
+
+  @plugins.smartdata.svDb()
+  public targets?: ITargetProfileTarget[];
+
+  @plugins.smartdata.svDb()
+  public routeRefs?: string[];
+
+  @plugins.smartdata.svDb()
+  public createdAt!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public createdBy!: string;
+
+  constructor() {
+    super();
+  }
+
+  public static async findById(id: string): Promise<TargetProfileDoc | null> {
+    return await TargetProfileDoc.getInstance({ id });
+  }
+
+  public static async findAll(): Promise<TargetProfileDoc[]> {
+    return await TargetProfileDoc.getInstances({});
+  }
+}

ts/db/documents/classes.vlan-mappings.doc.ts

@@ -0,0 +1,32 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+export interface IMacVlanMapping {
+  mac: string;
+  vlan: number;
+  description?: string;
+  enabled: boolean;
+  createdAt: number;
+  updatedAt: number;
+}
+
+@plugins.smartdata.Collection(() => getDb())
+export class VlanMappingsDoc extends plugins.smartdata.SmartDataDbDoc<VlanMappingsDoc, VlanMappingsDoc> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public configId: string = 'vlan-mappings';
+
+  @plugins.smartdata.svDb()
+  public mappings!: IMacVlanMapping[];
+
+  constructor() {
+    super();
+    this.mappings = [];
+  }
+
+  public static async load(): Promise<VlanMappingsDoc | null> {
+    return await VlanMappingsDoc.getInstance({ configId: 'vlan-mappings' });
+  }
+}

ts/db/documents/classes.vpn-client.doc.ts

@@ -0,0 +1,70 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class VpnClientDoc extends plugins.smartdata.SmartDataDbDoc<VpnClientDoc, VpnClientDoc> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public clientId!: string;
+
+  @plugins.smartdata.svDb()
+  public enabled!: boolean;
+
+  @plugins.smartdata.svDb()
+  public targetProfileIds?: string[];
+
+  @plugins.smartdata.svDb()
+  public description?: string;
+
+  @plugins.smartdata.svDb()
+  public assignedIp?: string;
+
+  @plugins.smartdata.svDb()
+  public noisePublicKey!: string;
+
+  @plugins.smartdata.svDb()
+  public wgPublicKey!: string;
+
+  @plugins.smartdata.svDb()
+  public wgPrivateKey?: string;
+
+  @plugins.smartdata.svDb()
+  public createdAt!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public expiresAt?: string;
+
+  @plugins.smartdata.svDb()
+  public destinationAllowList?: string[];
+
+  @plugins.smartdata.svDb()
+  public destinationBlockList?: string[];
+
+  @plugins.smartdata.svDb()
+  public useHostIp?: boolean;
+
+  @plugins.smartdata.svDb()
+  public useDhcp?: boolean;
+
+  @plugins.smartdata.svDb()
+  public staticIp?: string;
+
+  @plugins.smartdata.svDb()
+  public forceVlan?: boolean;
+
+  @plugins.smartdata.svDb()
+  public vlanId?: number;
+
+  constructor() {
+    super();
+  }
+
+  public static async findAll(): Promise<VpnClientDoc[]> {
+    return await VpnClientDoc.getInstances({});
+  }
+}

ts/db/documents/classes.vpn-server-keys.doc.ts

@@ -0,0 +1,31 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class VpnServerKeysDoc extends plugins.smartdata.SmartDataDbDoc<VpnServerKeysDoc, VpnServerKeysDoc> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public configId: string = 'vpn-server-keys';
+
+  @plugins.smartdata.svDb()
+  public noisePrivateKey!: string;
+
+  @plugins.smartdata.svDb()
+  public noisePublicKey!: string;
+
+  @plugins.smartdata.svDb()
+  public wgPrivateKey!: string;
+
+  @plugins.smartdata.svDb()
+  public wgPublicKey!: string;
+
+  constructor() {
+    super();
+  }
+
+  public static async load(): Promise<VpnServerKeysDoc | null> {
+    return await VpnServerKeysDoc.getInstance({ configId: 'vpn-server-keys' });
+  }
+}

ts/db/documents/index.ts

@@ -0,0 +1,35 @@
+// Cached/TTL document classes
+export * from './classes.cached.email.js';
+export * from './classes.cached.ip.reputation.js';
+
+// Config document classes
+export * from './classes.stored-route.doc.js';
+export * from './classes.route-override.doc.js';
+export * from './classes.api-token.doc.js';
+export * from './classes.source-profile.doc.js';
+export * from './classes.target-profile.doc.js';
+export * from './classes.network-target.doc.js';
+
+// VPN document classes
+export * from './classes.vpn-server-keys.doc.js';
+export * from './classes.vpn-client.doc.js';
+
+// Certificate document classes
+export * from './classes.acme-cert.doc.js';
+export * from './classes.proxy-cert.doc.js';
+export * from './classes.cert-backoff.doc.js';
+
+// Remote ingress document classes
+export * from './classes.remote-ingress-edge.doc.js';
+
+// RADIUS document classes
+export * from './classes.vlan-mappings.doc.js';
+export * from './classes.accounting-session.doc.js';
+
+// DNS / Domain management document classes
+export * from './classes.dns-provider.doc.js';
+export * from './classes.domain.doc.js';
+export * from './classes.dns-record.doc.js';
+
+// ACME configuration (singleton)
+export * from './classes.acme-config.doc.js';

ts/db/index.ts

@@ -1,6 +1,10 @@
-// Core cache infrastructure
-export * from './classes.cachedb.js';
+// Unified database manager
+export * from './classes.dcrouter-db.js';
+
+// TTL base class and constants
 export * from './classes.cached.document.js';
+
+// Cache cleaner
 export * from './classes.cache.cleaner.js';
 
 // Document classes

ts/dns/index.ts

@@ -0,0 +1,2 @@
+export * from './manager.dns.js';
+export * from './providers/index.js';

ts/dns/manager.dns.ts

@@ -0,0 +1,880 @@
+import * as plugins from '../plugins.js';
+import { logger } from '../logger.js';
+import {
+  DnsProviderDoc,
+  DomainDoc,
+  DnsRecordDoc,
+} from '../db/documents/index.js';
+import type { IDcRouterOptions } from '../classes.dcrouter.js';
+import type { IDnsProviderClient, IProviderRecord } from './providers/interfaces.js';
+import { createDnsProvider } from './providers/factory.js';
+import type {
+  TDnsRecordType,
+  TDnsRecordSource,
+} from '../../ts_interfaces/data/dns-record.js';
+import type {
+  TDnsProviderType,
+  TDnsProviderCredentials,
+  IDnsProviderPublic,
+  IProviderDomainListing,
+} from '../../ts_interfaces/data/dns-provider.js';
+
+/**
+ * DnsManager — owns runtime DNS state on top of the embedded DnsServer.
+ *
+ * Responsibilities:
+ *  - Load Domain/DnsRecord docs from the DB on start
+ *  - First-boot seeding from legacy constructor config (dnsScopes/dnsRecords/dnsNsDomains)
+ *  - Register dcrouter-hosted domain records with smartdns.DnsServer at startup
+ *  - Provide CRUD methods used by OpsServer handlers (dcrouter-hosted domains hit
+ *    smartdns, provider domains hit the provider API)
+ *  - Expose a provider lookup used by the ACME DNS-01 wiring in setupSmartProxy()
+ *
+ * Provider-managed domains are NEVER served from the embedded DnsServer — the
+ * provider stays authoritative. We only mirror their records locally for the UI
+ * and to track providerRecordIds for updates / deletes.
+ */
+export class DnsManager {
+  /**
+   * Reference to the active smartdns DnsServer (set by DcRouter once it exists).
+   * May be undefined if dnsScopes/dnsNsDomains aren't configured.
+   */
+  public dnsServer?: plugins.smartdns.dnsServerMod.DnsServer;
+
+  /**
+   * Cached provider clients, keyed by DnsProviderDoc.id.
+   * Created lazily when a provider is first needed.
+   */
+  private providerClients = new Map<string, IDnsProviderClient>();
+
+  constructor(private options: IDcRouterOptions) {}
+
+  // ==========================================================================
+  // Lifecycle
+  // ==========================================================================
+
+  /**
+   * Called from DcRouter after DcRouterDb is up. Performs first-boot seeding
+   * from legacy constructor config if (and only if) the DB is empty.
+   */
+  public async start(): Promise<void> {
+    logger.log('info', 'DnsManager: starting');
+    await this.seedFromConstructorConfigIfEmpty();
+  }
+
+  public async stop(): Promise<void> {
+    this.providerClients.clear();
+    this.dnsServer = undefined;
+  }
+
+  /**
+   * Wire the embedded DnsServer instance after it has been created by
+   * DcRouter.setupDnsWithSocketHandler(). After this, local records on
+   * dcrouter-hosted domains loaded from the DB are registered with the server.
+   */
+  public async attachDnsServer(dnsServer: plugins.smartdns.dnsServerMod.DnsServer): Promise<void> {
+    this.dnsServer = dnsServer;
+    await this.applyDcrouterDomainsToDnsServer();
+  }
+
+  // ==========================================================================
+  // First-boot seeding
+  // ==========================================================================
+
+  /**
+   * If no DomainDocs exist yet but the constructor has legacy DNS fields,
+   * seed them as dcrouter-hosted (`domain.source: 'dcrouter'`) zones with
+   * local (`record.source: 'local'`) records. On subsequent boots (DB has
+   * entries), constructor config is ignored with a warning.
+   */
+  private async seedFromConstructorConfigIfEmpty(): Promise<void> {
+    const existingDomains = await DomainDoc.findAll();
+    const hasLegacyConfig =
+      (this.options.dnsScopes && this.options.dnsScopes.length > 0) ||
+      (this.options.dnsRecords && this.options.dnsRecords.length > 0);
+
+    if (existingDomains.length > 0) {
+      if (hasLegacyConfig) {
+        logger.log(
+          'warn',
+          'DnsManager: DB has DomainDoc entries — ignoring legacy dnsScopes/dnsRecords/dnsNsDomains constructor config. ' +
+            'Manage DNS via the Domains UI instead.',
+        );
+      }
+      return;
+    }
+
+    if (!hasLegacyConfig) {
+      return;
+    }
+
+    logger.log('info', 'DnsManager: seeding DB from legacy constructor DNS config');
+
+    const now = Date.now();
+    const seededDomains = new Map<string, DomainDoc>();
+
+    // Create one DomainDoc per dnsScope (these are the authoritative zones)
+    for (const scope of this.options.dnsScopes ?? []) {
+      const domain = new DomainDoc();
+      domain.id = plugins.uuid.v4();
+      domain.name = scope.toLowerCase();
+      domain.source = 'dcrouter';
+      domain.authoritative = true;
+      domain.createdAt = now;
+      domain.updatedAt = now;
+      domain.createdBy = 'seed';
+      await domain.save();
+      seededDomains.set(domain.name, domain);
+      logger.log('info', `DnsManager: seeded DomainDoc for ${domain.name}`);
+    }
+
+    // Map each legacy dnsRecord to its parent DomainDoc
+    for (const rec of this.options.dnsRecords ?? []) {
+      const parent = this.findParentDomain(rec.name, seededDomains);
+      if (!parent) {
+        logger.log(
+          'warn',
+          `DnsManager: legacy dnsRecord '${rec.name}' has no matching dnsScope — skipping seed`,
+        );
+        continue;
+      }
+      const record = new DnsRecordDoc();
+      record.id = plugins.uuid.v4();
+      record.domainId = parent.id;
+      record.name = rec.name.toLowerCase();
+      record.type = rec.type as TDnsRecordType;
+      record.value = rec.value;
+      record.ttl = rec.ttl ?? 300;
+      record.source = 'local';
+      record.createdAt = now;
+      record.updatedAt = now;
+      record.createdBy = 'seed';
+      await record.save();
+    }
+
+    logger.log(
+      'info',
+      `DnsManager: seeded ${seededDomains.size} domain(s) and ${this.options.dnsRecords?.length ?? 0} record(s) from legacy config`,
+    );
+  }
+
+  private findParentDomain(
+    recordName: string,
+    domains: Map<string, DomainDoc>,
+  ): DomainDoc | null {
+    const lower = recordName.toLowerCase().replace(/^\*\./, '');
+    let candidate: DomainDoc | null = null;
+    for (const [name, doc] of domains) {
+      if (lower === name || lower.endsWith(`.${name}`)) {
+        if (!candidate || name.length > candidate.name.length) {
+          candidate = doc;
+        }
+      }
+    }
+    return candidate;
+  }
+
+  // ==========================================================================
+  // DcRouter-hosted domain DnsServer wiring
+  // ==========================================================================
+
+  /**
+   * Register all records from dcrouter-hosted domains in the DB with the
+   * embedded DnsServer. Called once after attachDnsServer().
+   */
+  private async applyDcrouterDomainsToDnsServer(): Promise<void> {
+    if (!this.dnsServer) {
+      return;
+    }
+    const allDomains = await DomainDoc.findAll();
+    const dcrouterDomains = allDomains.filter((d) => d.source === 'dcrouter');
+    let registered = 0;
+    for (const domain of dcrouterDomains) {
+      const records = await DnsRecordDoc.findByDomainId(domain.id);
+      for (const rec of records) {
+        this.registerRecordWithDnsServer(rec);
+        registered++;
+      }
+    }
+    logger.log(
+      'info',
+      `DnsManager: registered ${registered} dcrouter-hosted DNS record(s) from DB`,
+    );
+  }
+
+  /**
+   * Register a single record with the embedded DnsServer. The handler closure
+   * captures the record fields, so updates require a re-register cycle.
+   */
+  private registerRecordWithDnsServer(rec: DnsRecordDoc): void {
+    if (!this.dnsServer) return;
+    this.dnsServer.registerHandler(rec.name, [rec.type], (question) => {
+      if (question.name === rec.name && question.type === rec.type) {
+        return {
+          name: rec.name,
+          type: rec.type,
+          class: 'IN',
+          ttl: rec.ttl,
+          data: this.parseRecordData(rec.type, rec.value),
+        };
+      }
+      return null;
+    });
+  }
+
+  private parseRecordData(type: TDnsRecordType, value: string): any {
+    switch (type) {
+      case 'A':
+      case 'AAAA':
+      case 'CNAME':
+      case 'TXT':
+      case 'NS':
+      case 'CAA':
+        return value;
+      case 'MX': {
+        const [priorityStr, exchange] = value.split(' ');
+        return { priority: parseInt(priorityStr, 10), exchange };
+      }
+      case 'SOA': {
+        const parts = value.split(' ');
+        return {
+          mname: parts[0],
+          rname: parts[1],
+          serial: parseInt(parts[2], 10),
+          refresh: parseInt(parts[3], 10),
+          retry: parseInt(parts[4], 10),
+          expire: parseInt(parts[5], 10),
+          minimum: parseInt(parts[6], 10),
+        };
+      }
+      default:
+        return value;
+    }
+  }
+
+  // ==========================================================================
+  // Provider lookup (used by ACME DNS-01 + record CRUD)
+  // ==========================================================================
+
+  /**
+   * Get the provider client for a given DnsProviderDoc id, instantiating
+   * (and caching) it on first use.
+   */
+  public async getProviderClientById(providerId: string): Promise<IDnsProviderClient | null> {
+    const cached = this.providerClients.get(providerId);
+    if (cached) return cached;
+    const doc = await DnsProviderDoc.findById(providerId);
+    if (!doc) return null;
+    const client = createDnsProvider(doc.type, doc.credentials);
+    this.providerClients.set(providerId, client);
+    return client;
+  }
+
+  /**
+   * Find the IDnsProviderClient that owns the given FQDN (by walking up its
+   * labels to find a matching DomainDoc with `source === 'provider'`).
+   * Returns null if no provider claims this FQDN.
+   *
+   * Used by:
+   *  - SmartAcme DNS-01 wiring in setupSmartProxy()
+   *  - DnsRecordHandler when creating provider records
+   */
+  public async getProviderClientForDomain(fqdn: string): Promise<IDnsProviderClient | null> {
+    const lower = fqdn.toLowerCase().replace(/^\*\./, '').replace(/\.$/, '');
+    const allDomains = await DomainDoc.findAll();
+    const providerDomains = allDomains
+      .filter((d) => d.source === 'provider' && d.providerId)
+      // longest-match wins
+      .sort((a, b) => b.name.length - a.name.length);
+
+    for (const domain of providerDomains) {
+      if (lower === domain.name || lower.endsWith(`.${domain.name}`)) {
+        return this.getProviderClientById(domain.providerId!);
+      }
+    }
+    return null;
+  }
+
+  /**
+   * True if any cloudflare provider exists in the DB. Used by setupSmartProxy()
+   * to decide whether to wire SmartAcme with a DNS-01 handler.
+   */
+  public async hasAcmeCapableProvider(): Promise<boolean> {
+    const providers = await DnsProviderDoc.findAll();
+    return providers.length > 0;
+  }
+
+  /**
+   * Build an IConvenientDnsProvider that dispatches each ACME challenge to
+   * the right provider client (whichever provider type owns the parent zone),
+   * based on the challenge's hostName. Provider-agnostic — uses the IDnsProviderClient
+   * interface, so any registered provider implementation works.
+   * Returned object plugs directly into smartacme's Dns01Handler.
+   */
+  public buildAcmeConvenientDnsProvider(): plugins.tsclass.network.IConvenientDnsProvider {
+    const self = this;
+    const adapter = {
+      async acmeSetDnsChallenge(dnsChallenge: { hostName: string; challenge: string }) {
+        const client = await self.getProviderClientForDomain(dnsChallenge.hostName);
+        if (!client) {
+          throw new Error(
+            `DnsManager: no DNS provider configured for ${dnsChallenge.hostName}. ` +
+              'Add one in the Domains > Providers UI before issuing certificates.',
+          );
+        }
+        // Clean any leftover challenge records first to avoid duplicates.
+        try {
+          const existing = await client.listRecords(dnsChallenge.hostName);
+          for (const r of existing) {
+            if (r.type === 'TXT' && r.name === dnsChallenge.hostName) {
+              await client.deleteRecord(dnsChallenge.hostName, r.providerRecordId).catch(() => {});
+            }
+          }
+        } catch (err: unknown) {
+          logger.log('warn', `DnsManager: failed to clean existing TXT for ${dnsChallenge.hostName}: ${(err as Error).message}`);
+        }
+        await client.createRecord(dnsChallenge.hostName, {
+          name: dnsChallenge.hostName,
+          type: 'TXT',
+          value: dnsChallenge.challenge,
+          ttl: 120,
+        });
+      },
+      async acmeRemoveDnsChallenge(dnsChallenge: { hostName: string; challenge: string }) {
+        const client = await self.getProviderClientForDomain(dnsChallenge.hostName);
+        if (!client) {
+          // The domain may have been removed; nothing to clean up.
+          return;
+        }
+        try {
+          const existing = await client.listRecords(dnsChallenge.hostName);
+          for (const r of existing) {
+            if (r.type === 'TXT' && r.name === dnsChallenge.hostName) {
+              await client.deleteRecord(dnsChallenge.hostName, r.providerRecordId);
+            }
+          }
+        } catch (err: unknown) {
+          logger.log('warn', `DnsManager: failed to remove TXT for ${dnsChallenge.hostName}: ${(err as Error).message}`);
+        }
+      },
+      async isDomainSupported(domain: string): Promise<boolean> {
+        const client = await self.getProviderClientForDomain(domain);
+        return !!client;
+      },
+    };
+    return { convenience: adapter } as plugins.tsclass.network.IConvenientDnsProvider;
+  }
+
+  // ==========================================================================
+  // Provider CRUD (used by DnsProviderHandler)
+  // ==========================================================================
+
+  public async listProviders(): Promise<IDnsProviderPublic[]> {
+    const docs = await DnsProviderDoc.findAll();
+    return docs.map((d) => this.toPublicProvider(d));
+  }
+
+  public async getProvider(id: string): Promise<IDnsProviderPublic | null> {
+    const doc = await DnsProviderDoc.findById(id);
+    return doc ? this.toPublicProvider(doc) : null;
+  }
+
+  public async createProvider(args: {
+    name: string;
+    type: TDnsProviderType;
+    credentials: TDnsProviderCredentials;
+    createdBy: string;
+  }): Promise<string> {
+    if (args.type === 'dcrouter') {
+      throw new Error(
+        'createProvider: cannot create a DnsProviderDoc with type "dcrouter" — ' +
+          'that type is reserved for the built-in pseudo-provider surfaced at read time.',
+      );
+    }
+    const now = Date.now();
+    const doc = new DnsProviderDoc();
+    doc.id = plugins.uuid.v4();
+    doc.name = args.name;
+    doc.type = args.type;
+    doc.credentials = args.credentials;
+    doc.status = 'untested';
+    doc.createdAt = now;
+    doc.updatedAt = now;
+    doc.createdBy = args.createdBy;
+    await doc.save();
+    return doc.id;
+  }
+
+  public async updateProvider(
+    id: string,
+    args: { name?: string; credentials?: TDnsProviderCredentials },
+  ): Promise<boolean> {
+    const doc = await DnsProviderDoc.findById(id);
+    if (!doc) return false;
+    if (args.name !== undefined) doc.name = args.name;
+    if (args.credentials !== undefined) {
+      doc.credentials = args.credentials;
+      doc.status = 'untested';
+      doc.lastError = undefined;
+      // Invalidate cached client so the next use re-instantiates with the new credentials.
+      this.providerClients.delete(id);
+    }
+    doc.updatedAt = Date.now();
+    await doc.save();
+    return true;
+  }
+
+  public async deleteProvider(id: string, force: boolean): Promise<{ success: boolean; message?: string }> {
+    const doc = await DnsProviderDoc.findById(id);
+    if (!doc) return { success: false, message: 'Provider not found' };
+    const linkedDomains = await DomainDoc.findByProviderId(id);
+    if (linkedDomains.length > 0 && !force) {
+      return {
+        success: false,
+        message: `Provider is referenced by ${linkedDomains.length} domain(s). Pass force: true to delete anyway.`,
+      };
+    }
+    // If forcing, also delete the linked domains and their records.
+    if (force) {
+      for (const domain of linkedDomains) {
+        await this.deleteDomain(domain.id);
+      }
+    }
+    await doc.delete();
+    this.providerClients.delete(id);
+    return { success: true };
+  }
+
+  public async testProvider(id: string): Promise<{ ok: boolean; error?: string; testedAt: number }> {
+    const doc = await DnsProviderDoc.findById(id);
+    if (!doc) {
+      return { ok: false, error: 'Provider not found', testedAt: Date.now() };
+    }
+    const client = createDnsProvider(doc.type, doc.credentials);
+    const result = await client.testConnection();
+    doc.status = result.ok ? 'ok' : 'error';
+    doc.lastTestedAt = Date.now();
+    doc.lastError = result.ok ? undefined : result.error;
+    await doc.save();
+    if (result.ok) {
+      this.providerClients.set(id, client); // cache the working client
+    }
+    return { ok: result.ok, error: result.error, testedAt: doc.lastTestedAt };
+  }
+
+  public async listProviderDomains(providerId: string): Promise<IProviderDomainListing[]> {
+    const client = await this.getProviderClientById(providerId);
+    if (!client) {
+      throw new Error('Provider not found');
+    }
+    return await client.listDomains();
+  }
+
+  // ==========================================================================
+  // Domain CRUD (used by DomainHandler)
+  // ==========================================================================
+
+  public async listDomains(): Promise<DomainDoc[]> {
+    return await DomainDoc.findAll();
+  }
+
+  public async getDomain(id: string): Promise<DomainDoc | null> {
+    return await DomainDoc.findById(id);
+  }
+
+  /**
+   * Create a dcrouter-hosted (authoritative) domain. dcrouter will serve
+   * DNS records for this domain via the embedded smartdns.DnsServer.
+   */
+  public async createDcrouterDomain(args: {
+    name: string;
+    description?: string;
+    createdBy: string;
+  }): Promise<string> {
+    const now = Date.now();
+    const doc = new DomainDoc();
+    doc.id = plugins.uuid.v4();
+    doc.name = args.name.toLowerCase();
+    doc.source = 'dcrouter';
+    doc.authoritative = true;
+    doc.description = args.description;
+    doc.createdAt = now;
+    doc.updatedAt = now;
+    doc.createdBy = args.createdBy;
+    await doc.save();
+    return doc.id;
+  }
+
+  /**
+   * Import one or more domains from a provider, pulling all of their DNS
+   * records into local DnsRecordDocs.
+   */
+  public async importDomainsFromProvider(args: {
+    providerId: string;
+    domainNames: string[];
+    createdBy: string;
+  }): Promise<string[]> {
+    const provider = await DnsProviderDoc.findById(args.providerId);
+    if (!provider) {
+      throw new Error('Provider not found');
+    }
+    const client = await this.getProviderClientById(args.providerId);
+    if (!client) {
+      throw new Error('Failed to instantiate provider client');
+    }
+    const allProviderDomains = await client.listDomains();
+    const importedIds: string[] = [];
+    const now = Date.now();
+
+    for (const wantedName of args.domainNames) {
+      const lower = wantedName.toLowerCase();
+      const listing = allProviderDomains.find((d) => d.name.toLowerCase() === lower);
+      if (!listing) {
+        logger.log('warn', `DnsManager: import skipped — provider does not list domain ${wantedName}`);
+        continue;
+      }
+      // Skip if already imported
+      const existing = await DomainDoc.findByName(lower);
+      if (existing) {
+        logger.log('warn', `DnsManager: domain ${wantedName} already imported — skipping`);
+        continue;
+      }
+
+      const domain = new DomainDoc();
+      domain.id = plugins.uuid.v4();
+      domain.name = lower;
+      domain.source = 'provider';
+      domain.providerId = args.providerId;
+      domain.authoritative = false;
+      domain.nameservers = listing.nameservers;
+      domain.externalZoneId = listing.externalId;
+      domain.lastSyncedAt = now;
+      domain.createdAt = now;
+      domain.updatedAt = now;
+      domain.createdBy = args.createdBy;
+      await domain.save();
+      importedIds.push(domain.id);
+
+      // Pull records for the imported domain
+      try {
+        const providerRecords = await client.listRecords(lower);
+        for (const pr of providerRecords) {
+          await this.createSyncedRecord(domain.id, pr, args.createdBy);
+        }
+        logger.log('info', `DnsManager: imported ${providerRecords.length} record(s) for ${lower}`);
+      } catch (err: unknown) {
+        logger.log('warn', `DnsManager: failed to import records for ${lower}: ${(err as Error).message}`);
+      }
+    }
+    return importedIds;
+  }
+
+  public async updateDomain(id: string, args: { description?: string }): Promise<boolean> {
+    const doc = await DomainDoc.findById(id);
+    if (!doc) return false;
+    if (args.description !== undefined) doc.description = args.description;
+    doc.updatedAt = Date.now();
+    await doc.save();
+    return true;
+  }
+
+  /**
+   * Delete a domain and all of its DNS records. For provider domains, only
+   * removes the local mirror — does NOT touch the provider.
+   * For dcrouter-hosted domains, also unregisters records from the embedded
+   * DnsServer.
+   *
+   * Note: smartdns has no public unregister-by-name API in the version pinned
+   * here, so local record deletes only take effect after a restart. The DB
+   * is the source of truth and the next start will not register the deleted
+   * record.
+   */
+  public async deleteDomain(id: string): Promise<boolean> {
+    const doc = await DomainDoc.findById(id);
+    if (!doc) return false;
+    const records = await DnsRecordDoc.findByDomainId(id);
+    for (const r of records) {
+      await r.delete();
+    }
+    await doc.delete();
+    return true;
+  }
+
+  /**
+   * Force-resync a provider-managed domain: re-pull all records from the
+   * provider API, replacing the cached DnsRecordDocs.
+   */
+  public async syncDomain(id: string): Promise<{ success: boolean; recordCount?: number; message?: string }> {
+    const doc = await DomainDoc.findById(id);
+    if (!doc) return { success: false, message: 'Domain not found' };
+    if (doc.source !== 'provider' || !doc.providerId) {
+      return { success: false, message: 'Domain is not provider-managed' };
+    }
+    const client = await this.getProviderClientById(doc.providerId);
+    if (!client) {
+      return { success: false, message: 'Provider client unavailable' };
+    }
+    const providerRecords = await client.listRecords(doc.name);
+
+    // Drop existing records and replace
+    const existing = await DnsRecordDoc.findByDomainId(id);
+    for (const r of existing) {
+      await r.delete();
+    }
+    for (const pr of providerRecords) {
+      await this.createSyncedRecord(id, pr, doc.createdBy);
+    }
+    doc.lastSyncedAt = Date.now();
+    doc.updatedAt = doc.lastSyncedAt;
+    await doc.save();
+    return { success: true, recordCount: providerRecords.length };
+  }
+
+  // ==========================================================================
+  // Record CRUD (used by DnsRecordHandler)
+  // ==========================================================================
+
+  public async listRecordsForDomain(domainId: string): Promise<DnsRecordDoc[]> {
+    return await DnsRecordDoc.findByDomainId(domainId);
+  }
+
+  public async getRecord(id: string): Promise<DnsRecordDoc | null> {
+    return await DnsRecordDoc.findById(id);
+  }
+
+  public async createRecord(args: {
+    domainId: string;
+    name: string;
+    type: TDnsRecordType;
+    value: string;
+    ttl?: number;
+    proxied?: boolean;
+    createdBy: string;
+  }): Promise<{ success: boolean; id?: string; message?: string }> {
+    const domain = await DomainDoc.findById(args.domainId);
+    if (!domain) return { success: false, message: 'Domain not found' };
+
+    const now = Date.now();
+    const doc = new DnsRecordDoc();
+    doc.id = plugins.uuid.v4();
+    doc.domainId = args.domainId;
+    doc.name = args.name.toLowerCase();
+    doc.type = args.type;
+    doc.value = args.value;
+    doc.ttl = args.ttl ?? 300;
+    if (args.proxied !== undefined) doc.proxied = args.proxied;
+    doc.source = 'local';
+    doc.createdAt = now;
+    doc.updatedAt = now;
+    doc.createdBy = args.createdBy;
+
+    if (domain.source === 'provider') {
+      // Push to provider first; only persist locally on success
+      if (!domain.providerId) {
+        return { success: false, message: 'Provider domain has no providerId' };
+      }
+      const client = await this.getProviderClientById(domain.providerId);
+      if (!client) return { success: false, message: 'Provider client unavailable' };
+      try {
+        const created = await client.createRecord(domain.name, {
+          name: doc.name,
+          type: doc.type,
+          value: doc.value,
+          ttl: doc.ttl,
+          proxied: doc.proxied,
+        });
+        doc.providerRecordId = created.providerRecordId;
+        doc.source = 'synced';
+      } catch (err: unknown) {
+        return { success: false, message: `Provider rejected record: ${(err as Error).message}` };
+      }
+    } else {
+      // dcrouter-hosted / authoritative — register with embedded DnsServer immediately
+      this.registerRecordWithDnsServer(doc);
+    }
+
+    await doc.save();
+    return { success: true, id: doc.id };
+  }
+
+  public async updateRecord(args: {
+    id: string;
+    name?: string;
+    value?: string;
+    ttl?: number;
+    proxied?: boolean;
+  }): Promise<{ success: boolean; message?: string }> {
+    const doc = await DnsRecordDoc.findById(args.id);
+    if (!doc) return { success: false, message: 'Record not found' };
+    const domain = await DomainDoc.findById(doc.domainId);
+    if (!domain) return { success: false, message: 'Parent domain not found' };
+
+    if (args.name !== undefined) doc.name = args.name.toLowerCase();
+    if (args.value !== undefined) doc.value = args.value;
+    if (args.ttl !== undefined) doc.ttl = args.ttl;
+    if (args.proxied !== undefined) doc.proxied = args.proxied;
+    doc.updatedAt = Date.now();
+
+    if (domain.source === 'provider') {
+      if (!domain.providerId || !doc.providerRecordId) {
+        return { success: false, message: 'Provider record metadata missing' };
+      }
+      const client = await this.getProviderClientById(domain.providerId);
+      if (!client) return { success: false, message: 'Provider client unavailable' };
+      try {
+        await client.updateRecord(domain.name, doc.providerRecordId, {
+          name: doc.name,
+          type: doc.type,
+          value: doc.value,
+          ttl: doc.ttl,
+          proxied: doc.proxied,
+        });
+      } catch (err: unknown) {
+        return { success: false, message: `Provider rejected update: ${(err as Error).message}` };
+      }
+    } else {
+      // Re-register the local record so the new closure picks up the updated fields
+      this.registerRecordWithDnsServer(doc);
+    }
+
+    await doc.save();
+    return { success: true };
+  }
+
+  public async deleteRecord(id: string): Promise<{ success: boolean; message?: string }> {
+    const doc = await DnsRecordDoc.findById(id);
+    if (!doc) return { success: false, message: 'Record not found' };
+    const domain = await DomainDoc.findById(doc.domainId);
+    if (!domain) return { success: false, message: 'Parent domain not found' };
+
+    if (domain.source === 'provider') {
+      if (domain.providerId && doc.providerRecordId) {
+        const client = await this.getProviderClientById(domain.providerId);
+        if (client) {
+          try {
+            await client.deleteRecord(domain.name, doc.providerRecordId);
+          } catch (err: unknown) {
+            return { success: false, message: `Provider rejected delete: ${(err as Error).message}` };
+          }
+        }
+      }
+    }
+    // For local records: smartdns has no unregister API in the pinned version,
+    // so the record stays served until the next restart. The DB delete still
+    // takes effect — on restart, the record will not be re-registered.
+
+    await doc.delete();
+    return { success: true };
+  }
+
+  // ==========================================================================
+  // Internal helpers
+  // ==========================================================================
+
+  private async createSyncedRecord(
+    domainId: string,
+    pr: IProviderRecord,
+    createdBy: string,
+  ): Promise<void> {
+    const now = Date.now();
+    const doc = new DnsRecordDoc();
+    doc.id = plugins.uuid.v4();
+    doc.domainId = domainId;
+    doc.name = pr.name.toLowerCase();
+    doc.type = pr.type;
+    doc.value = pr.value;
+    doc.ttl = pr.ttl;
+    if (pr.proxied !== undefined) doc.proxied = pr.proxied;
+    doc.source = 'synced';
+    doc.providerRecordId = pr.providerRecordId;
+    doc.createdAt = now;
+    doc.updatedAt = now;
+    doc.createdBy = createdBy;
+    await doc.save();
+  }
+
+  /**
+   * Convert a DnsProviderDoc to its public, secret-stripped representation
+   * for the OpsServer API.
+   */
+  public toPublicProvider(doc: DnsProviderDoc): IDnsProviderPublic {
+    return {
+      id: doc.id,
+      name: doc.name,
+      type: doc.type,
+      status: doc.status,
+      lastTestedAt: doc.lastTestedAt,
+      lastError: doc.lastError,
+      createdAt: doc.createdAt,
+      updatedAt: doc.updatedAt,
+      createdBy: doc.createdBy,
+      hasCredentials: !!doc.credentials,
+    };
+  }
+
+  /**
+   * Convert a DomainDoc to its plain interface representation.
+   */
+  public toPublicDomain(doc: DomainDoc): {
+    id: string;
+    name: string;
+    source: 'dcrouter' | 'provider';
+    providerId?: string;
+    authoritative: boolean;
+    nameservers?: string[];
+    externalZoneId?: string;
+    lastSyncedAt?: number;
+    description?: string;
+    createdAt: number;
+    updatedAt: number;
+    createdBy: string;
+  } {
+    return {
+      id: doc.id,
+      name: doc.name,
+      source: doc.source,
+      providerId: doc.providerId,
+      authoritative: doc.authoritative,
+      nameservers: doc.nameservers,
+      externalZoneId: doc.externalZoneId,
+      lastSyncedAt: doc.lastSyncedAt,
+      description: doc.description,
+      createdAt: doc.createdAt,
+      updatedAt: doc.updatedAt,
+      createdBy: doc.createdBy,
+    };
+  }
+
+  /**
+   * Convert a DnsRecordDoc to its plain interface representation.
+   */
+  public toPublicRecord(doc: DnsRecordDoc): {
+    id: string;
+    domainId: string;
+    name: string;
+    type: TDnsRecordType;
+    value: string;
+    ttl: number;
+    proxied?: boolean;
+    source: TDnsRecordSource;
+    providerRecordId?: string;
+    createdAt: number;
+    updatedAt: number;
+    createdBy: string;
+  } {
+    return {
+      id: doc.id,
+      domainId: doc.domainId,
+      name: doc.name,
+      type: doc.type,
+      value: doc.value,
+      ttl: doc.ttl,
+      proxied: doc.proxied,
+      source: doc.source,
+      providerRecordId: doc.providerRecordId,
+      createdAt: doc.createdAt,
+      updatedAt: doc.updatedAt,
+      createdBy: doc.createdBy,
+    };
+  }
+}

ts/dns/providers/cloudflare.provider.ts

@@ -0,0 +1,131 @@
+import * as plugins from '../../plugins.js';
+import { logger } from '../../logger.js';
+import type {
+  IDnsProviderClient,
+  IConnectionTestResult,
+  IProviderRecord,
+  IProviderRecordInput,
+} from './interfaces.js';
+import type { IProviderDomainListing } from '../../../ts_interfaces/data/dns-provider.js';
+import type { TDnsRecordType } from '../../../ts_interfaces/data/dns-record.js';
+
+/**
+ * Cloudflare implementation of IDnsProviderClient.
+ *
+ * Wraps `@apiclient.xyz/cloudflare`. Records at Cloudflare are addressed by
+ * an internal record id, which we surface as `providerRecordId` so the rest
+ * of the system can issue updates and deletes without ambiguity (Cloudflare
+ * can have multiple records of the same name+type).
+ */
+export class CloudflareDnsProvider implements IDnsProviderClient {
+  private cfAccount: plugins.cloudflare.CloudflareAccount;
+
+  constructor(apiToken: string) {
+    if (!apiToken) {
+      throw new Error('CloudflareDnsProvider: apiToken is required');
+    }
+    this.cfAccount = new plugins.cloudflare.CloudflareAccount(apiToken);
+  }
+
+  public async testConnection(): Promise<IConnectionTestResult> {
+    try {
+      // Listing zones is the lightest-weight call that proves the token works.
+      await this.cfAccount.zoneManager.listZones();
+      return { ok: true };
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.log('warn', `CloudflareDnsProvider testConnection failed: ${message}`);
+      return { ok: false, error: message };
+    }
+  }
+
+  public async listDomains(): Promise<IProviderDomainListing[]> {
+    const zones = await this.cfAccount.zoneManager.listZones();
+    return zones.map((zone) => ({
+      name: zone.name,
+      externalId: zone.id,
+      nameservers: zone.name_servers ?? [],
+    }));
+  }
+
+  public async listRecords(domain: string): Promise<IProviderRecord[]> {
+    const records = await this.cfAccount.recordManager.listRecords(domain);
+    return records
+      .filter((r) => this.isSupportedType(r.type))
+      .map((r) => ({
+        providerRecordId: r.id,
+        name: r.name,
+        type: r.type as TDnsRecordType,
+        value: r.content,
+        ttl: r.ttl,
+        proxied: r.proxied,
+      }));
+  }
+
+  public async createRecord(
+    domain: string,
+    record: IProviderRecordInput,
+  ): Promise<IProviderRecord> {
+    const zoneId = await this.cfAccount.zoneManager.getZoneId(domain);
+    const apiRecord: any = {
+      zone_id: zoneId,
+      type: record.type,
+      name: record.name,
+      content: record.value,
+      ttl: record.ttl ?? 1, // 1 = automatic
+    };
+    if (record.proxied !== undefined) {
+      apiRecord.proxied = record.proxied;
+    }
+    const created = await (this.cfAccount as any).apiAccount.dns.records.create(apiRecord);
+    return {
+      providerRecordId: created.id,
+      name: created.name,
+      type: created.type as TDnsRecordType,
+      value: created.content,
+      ttl: created.ttl,
+      proxied: created.proxied,
+    };
+  }
+
+  public async updateRecord(
+    domain: string,
+    providerRecordId: string,
+    record: IProviderRecordInput,
+  ): Promise<IProviderRecord> {
+    const zoneId = await this.cfAccount.zoneManager.getZoneId(domain);
+    const apiRecord: any = {
+      zone_id: zoneId,
+      type: record.type,
+      name: record.name,
+      content: record.value,
+      ttl: record.ttl ?? 1,
+    };
+    if (record.proxied !== undefined) {
+      apiRecord.proxied = record.proxied;
+    }
+    const updated = await (this.cfAccount as any).apiAccount.dns.records.edit(
+      providerRecordId,
+      apiRecord,
+    );
+    return {
+      providerRecordId: updated.id,
+      name: updated.name,
+      type: updated.type as TDnsRecordType,
+      value: updated.content,
+      ttl: updated.ttl,
+      proxied: updated.proxied,
+    };
+  }
+
+  public async deleteRecord(domain: string, providerRecordId: string): Promise<void> {
+    const zoneId = await this.cfAccount.zoneManager.getZoneId(domain);
+    await (this.cfAccount as any).apiAccount.dns.records.delete(providerRecordId, {
+      zone_id: zoneId,
+    });
+  }
+
+  private isSupportedType(type: string): boolean {
+    return ['A', 'AAAA', 'CNAME', 'MX', 'TXT', 'NS', 'SOA', 'CAA'].includes(type);
+  }
+}

ts/dns/providers/factory.ts

@@ -0,0 +1,59 @@
+import type { IDnsProviderClient } from './interfaces.js';
+import type {
+  TDnsProviderType,
+  TDnsProviderCredentials,
+} from '../../../ts_interfaces/data/dns-provider.js';
+import { CloudflareDnsProvider } from './cloudflare.provider.js';
+
+/**
+ * Instantiate a runtime DNS provider client from a stored DnsProviderDoc.
+ *
+ * @throws if the provider type is not supported.
+ *
+ * ## Adding a new provider (e.g. Route53)
+ *
+ * 1. **Type union** — extend `TDnsProviderType` in
+ *    `ts_interfaces/data/dns-provider.ts` (e.g. `'cloudflare' | 'route53'`).
+ * 2. **Credentials interface** — add `IRoute53Credentials` and append it to
+ *    the `TDnsProviderCredentials` discriminated union.
+ * 3. **Descriptor** — append a new entry to `dnsProviderTypeDescriptors` so
+ *    the OpsServer UI picks up the new type and renders the right credential
+ *    form fields automatically.
+ * 4. **Provider class** — create `ts/dns/providers/route53.provider.ts`
+ *    implementing `IDnsProviderClient`.
+ * 5. **Factory case** — add a new `case 'route53':` below. The
+ *    `_exhaustive: never` line will fail to compile until you do.
+ * 6. **Index** — re-export the new class from `ts/dns/providers/index.ts`.
+ */
+export function createDnsProvider(
+  type: TDnsProviderType,
+  credentials: TDnsProviderCredentials,
+): IDnsProviderClient {
+  switch (type) {
+    case 'cloudflare': {
+      if (credentials.type !== 'cloudflare') {
+        throw new Error(
+          `createDnsProvider: type mismatch — provider type is 'cloudflare' but credentials.type is '${credentials.type}'`,
+        );
+      }
+      return new CloudflareDnsProvider(credentials.apiToken);
+    }
+    case 'dcrouter': {
+      // The built-in DcRouter pseudo-provider has no runtime client — dcrouter
+      // itself serves the records via the embedded smartdns.DnsServer. This
+      // case exists only to satisfy the exhaustive switch; it should never
+      // actually run because the handler layer rejects any CRUD that would
+      // result in a DnsProviderDoc with type: 'dcrouter'.
+      throw new Error(
+        `createDnsProvider: 'dcrouter' is a built-in pseudo-provider — no runtime client exists. ` +
+          `This call indicates a DnsProviderDoc with type: 'dcrouter' was persisted, which should never happen.`,
+      );
+    }
+    default: {
+      // If you see a TypeScript error here after extending TDnsProviderType,
+      // add a `case` for the new type above. The `never` enforces exhaustiveness.
+      const _exhaustive: never = type;
+      throw new Error(`createDnsProvider: unsupported provider type: ${_exhaustive}`);
+    }
+  }
+}

ts/dns/providers/index.ts

@@ -0,0 +1,3 @@
+export * from './interfaces.js';
+export * from './cloudflare.provider.js';
+export * from './factory.js';

ts/dns/providers/interfaces.ts

@@ -0,0 +1,67 @@
+import type { TDnsRecordType } from '../../../ts_interfaces/data/dns-record.js';
+import type { IProviderDomainListing } from '../../../ts_interfaces/data/dns-provider.js';
+
+/**
+ * A DNS record as seen at a provider's API. The `providerRecordId` field
+ * is the provider's internal identifier, used for subsequent updates and
+ * deletes (since providers can have multiple records of the same name+type).
+ */
+export interface IProviderRecord {
+  providerRecordId: string;
+  name: string;
+  type: TDnsRecordType;
+  value: string;
+  ttl: number;
+  proxied?: boolean;
+}
+
+/**
+ * Input shape for creating / updating a DNS record at a provider.
+ */
+export interface IProviderRecordInput {
+  name: string;
+  type: TDnsRecordType;
+  value: string;
+  ttl?: number;
+  proxied?: boolean;
+}
+
+/**
+ * Outcome of a connection test against a provider's API.
+ */
+export interface IConnectionTestResult {
+  ok: boolean;
+  error?: string;
+}
+
+/**
+ * Pluggable DNS provider client interface. One implementation per provider type
+ * (Cloudflare, Route53, …). Implementations live in ts/dns/providers/ and are
+ * instantiated by `createDnsProvider()` in factory.ts.
+ *
+ * NOT a smartdata interface — this is the *runtime* client. The persisted
+ * representation is in `IDnsProvider` (ts_interfaces/data/dns-provider.ts).
+ */
+export interface IDnsProviderClient {
+  /** Lightweight check that credentials are valid and the API is reachable. */
+  testConnection(): Promise<IConnectionTestResult>;
+
+  /** List all DNS zones visible to this provider account. */
+  listDomains(): Promise<IProviderDomainListing[]>;
+
+  /** List all DNS records for a zone (FQDN). */
+  listRecords(domain: string): Promise<IProviderRecord[]>;
+
+  /** Create a new DNS record at the provider; returns the created record (with id). */
+  createRecord(domain: string, record: IProviderRecordInput): Promise<IProviderRecord>;
+
+  /** Update an existing record by provider id; returns the updated record. */
+  updateRecord(
+    domain: string,
+    providerRecordId: string,
+    record: IProviderRecordInput,
+  ): Promise<IProviderRecord>;
+
+  /** Delete a record by provider id. */
+  deleteRecord(domain: string, providerRecordId: string): Promise<void>;
+}

ts/errors/base.errors.ts

@@ -227,7 +227,7 @@ export class PlatformError extends Error {
     const { retry } = this.context;
     if (!retry) return false;
     
-    return retry.currentRetry < retry.maxRetries;
+    return (retry.currentRetry ?? 0) < (retry.maxRetries ?? 0);
   }
 
   /**

ts/http3/http3-route-augmentation.ts

@@ -0,0 +1,153 @@
+import type * as plugins from '../plugins.js';
+
+/**
+ * Configuration for HTTP/3 (QUIC) route augmentation.
+ * HTTP/3 is enabled by default on all qualifying HTTPS routes.
+ */
+export interface IHttp3Config {
+  /** Enable HTTP/3 augmentation on qualifying routes (default: true) */
+  enabled?: boolean;
+  /** QUIC-specific settings applied to all augmented routes */
+  quicSettings?: {
+    /** QUIC connection idle timeout in ms (default: 30000) */
+    maxIdleTimeout?: number;
+    /** Max concurrent bidirectional streams per connection (default: 100) */
+    maxConcurrentBidiStreams?: number;
+    /** Max concurrent unidirectional streams per connection (default: 100) */
+    maxConcurrentUniStreams?: number;
+    /** Initial congestion window size in bytes */
+    initialCongestionWindow?: number;
+  };
+  /** Alt-Svc header settings */
+  altSvc?: {
+    /** Port advertised in Alt-Svc header (default: same as listening port) */
+    port?: number;
+    /** Max age for Alt-Svc advertisement in seconds (default: 86400) */
+    maxAge?: number;
+  };
+  /** UDP session settings */
+  udpSettings?: {
+    /** Idle timeout for UDP sessions in ms (default: 60000) */
+    sessionTimeout?: number;
+    /** Max concurrent UDP sessions per source IP (default: 1000) */
+    maxSessionsPerIP?: number;
+    /** Max accepted datagram size in bytes (default: 65535) */
+    maxDatagramSize?: number;
+  };
+}
+
+type TPortRange = plugins.smartproxy.IRouteConfig['match']['ports'];
+
+/**
+ * Check whether a TPortRange includes port 443.
+ */
+function portRangeIncludes443(ports: TPortRange): boolean {
+  if (typeof ports === 'number') return ports === 443;
+  if (Array.isArray(ports)) {
+    return ports.some((p) => {
+      if (typeof p === 'number') return p === 443;
+      return p.from <= 443 && p.to >= 443;
+    });
+  }
+  return false;
+}
+
+/**
+ * Check if a route name indicates an email route that should not get HTTP/3.
+ */
+function isEmailRoute(route: plugins.smartproxy.IRouteConfig): boolean {
+  const name = route.name?.toLowerCase() || '';
+  return (
+    name.startsWith('smtp-') ||
+    name.startsWith('submission-') ||
+    name.startsWith('smtps-') ||
+    name.startsWith('email-')
+  );
+}
+
+/**
+ * Determine if a route qualifies for HTTP/3 augmentation.
+ */
+export function routeQualifiesForHttp3(
+  route: plugins.smartproxy.IRouteConfig,
+  globalConfig: IHttp3Config,
+): boolean {
+  // Check global enable + per-route override
+  const globalEnabled = globalConfig.enabled !== false; // default true
+  const perRouteOverride = route.action.options?.http3;
+
+  // If per-route explicitly set, use that; otherwise use global
+  const shouldAugment =
+    perRouteOverride !== undefined ? perRouteOverride : globalEnabled;
+  if (!shouldAugment) return false;
+
+  // Must be forward type
+  if (route.action.type !== 'forward') return false;
+
+  // Must include port 443
+  if (!portRangeIncludes443(route.match.ports)) return false;
+
+  // Must have TLS
+  if (!route.action.tls) return false;
+
+  // Skip email routes
+  if (isEmailRoute(route)) return false;
+
+  // Skip if already configured with transport 'all' or 'udp'
+  if (route.match.transport === 'all' || route.match.transport === 'udp') return false;
+
+  // Skip if already has QUIC config
+  if (route.action.udp?.quic) return false;
+
+  return true;
+}
+
+/**
+ * Augment a single route with HTTP/3 fields.
+ * Returns a new route object (does not mutate the original).
+ */
+export function augmentRouteWithHttp3(
+  route: plugins.smartproxy.IRouteConfig,
+  config: IHttp3Config,
+): plugins.smartproxy.IRouteConfig {
+  if (!routeQualifiesForHttp3(route, config)) {
+    return route;
+  }
+
+  return {
+    ...route,
+    match: {
+      ...route.match,
+      transport: 'all' as const,
+    },
+    action: {
+      ...route.action,
+      udp: {
+        ...(route.action.udp || {}),
+        sessionTimeout: config.udpSettings?.sessionTimeout,
+        maxSessionsPerIP: config.udpSettings?.maxSessionsPerIP,
+        maxDatagramSize: config.udpSettings?.maxDatagramSize,
+        quic: {
+          enableHttp3: true,
+          maxIdleTimeout: config.quicSettings?.maxIdleTimeout,
+          maxConcurrentBidiStreams: config.quicSettings?.maxConcurrentBidiStreams,
+          maxConcurrentUniStreams: config.quicSettings?.maxConcurrentUniStreams,
+          altSvcPort: config.altSvc?.port,
+          altSvcMaxAge: config.altSvc?.maxAge ?? 86400,
+          initialCongestionWindow: config.quicSettings?.initialCongestionWindow,
+        },
+      },
+    },
+  };
+}
+
+/**
+ * Augment all qualifying routes in an array.
+ * Returns a new array (does not mutate originals).
+ */
+export function augmentRoutesWithHttp3(
+  routes: plugins.smartproxy.IRouteConfig[],
+  config: IHttp3Config,
+): plugins.smartproxy.IRouteConfig[] {
+  return routes.map((route) => augmentRouteWithHttp3(route, config));
+}

ts/http3/index.ts

@@ -0,0 +1 @@
+export * from './http3-route-augmentation.js';

ts/index.ts

@@ -5,9 +5,36 @@ export { UnifiedEmailServer } from '@push.rocks/smartmta';
 export type { IUnifiedEmailServerOptions, IEmailRoute, IEmailDomainConfig } from '@push.rocks/smartmta';
 
 // DcRouter
+import { DcRouter } from './classes.dcrouter.js';
 export * from './classes.dcrouter.js';
 
 // RADIUS module
 export * from './radius/index.js';
 
-export const runCli = async () => {};
+// Remote Ingress module
+export * from './remoteingress/index.js';
+
+// HTTP/3 module
+export type { IHttp3Config } from './http3/index.js';
+
+export const runCli = async () => {
+  let options: import('./classes.dcrouter.js').IDcRouterOptions = {};
+
+  if (process.env.DCROUTER_MODE === 'OCI_CONTAINER') {
+    const { getOciContainerConfig } = await import('../ts_oci_container/index.js');
+    options = getOciContainerConfig();
+    console.log('[DCRouter] Starting in OCI Container mode...');
+  }
+
+  const dcRouter = new DcRouter(options);
+  await dcRouter.start();
+  console.log('[DCRouter] Running. Send SIGTERM or SIGINT to stop.');
+
+  const shutdown = async () => {
+    console.log('[DCRouter] Shutting down...');
+    await dcRouter.stop();
+    process.exit(0);
+  };
+  process.once('SIGINT', shutdown);
+  process.once('SIGTERM', shutdown);
+};

ts/logger.ts

@@ -1,5 +1,6 @@
 import * as plugins from './plugins.js';
 import { randomUUID } from 'node:crypto';
+import { SmartlogDestinationBuffer } from '@push.rocks/smartlog/destination-buffer';
 
 // Map NODE_ENV to valid TEnvironment
 const nodeEnv = process.env.NODE_ENV || 'production';
@@ -10,8 +11,11 @@ const envMap: Record<string, 'local' | 'test' | 'staging' | 'production'> = {
   'production': 'production'
 };
 
-// Default Smartlog instance
-const baseLogger = new plugins.smartlog.Smartlog({
+// In-memory log buffer for the OpsServer UI
+export const logBuffer = new SmartlogDestinationBuffer({ maxEntries: 2000 });
+
+// Default Smartlog instance (exported so OpsServer can add push destinations)
+export const baseLogger = new plugins.smartlog.Smartlog({
   logContext: {
     environment: envMap[nodeEnv] || 'production',
     runtime: 'node',
@@ -19,6 +23,9 @@ const baseLogger = new plugins.smartlog.Smartlog({
   }
 });
 
+// Wire the buffer destination so all logs are captured
+baseLogger.addLogDestination(logBuffer);
+
 // Extended logger compatible with the original enhanced logger API
 class StandardLogger {
   private defaultContext: Record<string, any> = {};

ts/monitoring/classes.metricsmanager.ts

@@ -1,9 +1,11 @@
 import * as plugins from '../plugins.js';
 import { DcRouter } from '../classes.dcrouter.js';
 import { MetricsCache } from './classes.metricscache.js';
+import { SecurityLogger, SecurityEventType } from '../security/classes.securitylogger.js';
+import { logger } from '../logger.js';
 
 export class MetricsManager {
-  private logger: plugins.smartlog.Smartlog;
+  private metricsLogger: plugins.smartlog.Smartlog;
   private smartMetrics: plugins.smartmetrics.SmartMetrics;
   private dcRouter: DcRouter;
   private resetInterval?: NodeJS.Timeout;
@@ -33,10 +35,17 @@ export class MetricsManager {
     queryTypes: {} as Record<string, number>,
     topDomains: new Map<string, number>(),
     lastResetDate: new Date().toDateString(),
-    queryTimestamps: [] as number[], // Track query timestamps for rate calculation
+    // Per-second query count ring buffer (300 entries = 5 minutes)
+    queryRing: new Int32Array(300),
+    queryRingLastSecond: 0, // last epoch second that was written
     responseTimes: [] as number[], // Track response times in ms
+    recentQueries: [] as Array<{ timestamp: number; domain: string; type: string; answered: boolean; responseTimeMs: number }>,
   };
   
+  // Per-minute time-series buckets for charts
+  private emailMinuteBuckets = new Map<number, { sent: number; received: number; failed: number }>();
+  private dnsMinuteBuckets = new Map<number, { queries: number }>();
+
   // Track security-specific metrics
   private securityMetrics = {
     blockedIPs: 0,
@@ -50,15 +59,15 @@ export class MetricsManager {
   
   constructor(dcRouter: DcRouter) {
     this.dcRouter = dcRouter;
-    // Create a new Smartlog instance for metrics
-    this.logger = new plugins.smartlog.Smartlog({
+    // Create a Smartlog instance for SmartMetrics (requires its own instance)
+    this.metricsLogger = new plugins.smartlog.Smartlog({
       logContext: {
         environment: 'production',
         runtime: 'node',
         zone: 'dcrouter-metrics',
       }
     });
-    this.smartMetrics = new plugins.smartmetrics.SmartMetrics(this.logger, 'dcrouter');
+    this.smartMetrics = new plugins.smartmetrics.SmartMetrics(this.metricsLogger, 'dcrouter');
     // Initialize metrics cache with 500ms TTL
     this.metricsCache = new MetricsCache(500);
   }
@@ -88,11 +97,13 @@ export class MetricsManager {
         this.dnsMetrics.cacheMisses = 0;
         this.dnsMetrics.queryTypes = {};
         this.dnsMetrics.topDomains.clear();
-        this.dnsMetrics.queryTimestamps = [];
+        this.dnsMetrics.queryRing.fill(0);
+        this.dnsMetrics.queryRingLastSecond = 0;
         this.dnsMetrics.responseTimes = [];
+        this.dnsMetrics.recentQueries = [];
         this.dnsMetrics.lastResetDate = currentDate;
       }
-      
+
       if (currentDate !== this.securityMetrics.lastResetDate) {
         this.securityMetrics.blockedIPs = 0;
         this.securityMetrics.authFailures = 0;
@@ -102,20 +113,29 @@ export class MetricsManager {
         this.securityMetrics.incidents = [];
         this.securityMetrics.lastResetDate = currentDate;
       }
+
+      // Prune old time-series buckets every minute (don't wait for lazy query)
+      this.pruneOldBuckets();
     }, 60000); // Check every minute
     
-    this.logger.log('info', 'MetricsManager started');
+    logger.log('info', 'MetricsManager started');
   }
-  
+
   public async stop(): Promise<void> {
     // Clear the reset interval
     if (this.resetInterval) {
       clearInterval(this.resetInterval);
       this.resetInterval = undefined;
     }
-    
+
     this.smartMetrics.stop();
-    this.logger.log('info', 'MetricsManager stopped');
+
+    // Clear caches and time-series buckets on shutdown
+    this.metricsCache.clear();
+    this.emailMinuteBuckets.clear();
+    this.dnsMinuteBuckets.clear();
+
+    logger.log('info', 'MetricsManager stopped');
   }
   
   // Get server metrics from SmartMetrics and SmartProxy
@@ -124,23 +144,23 @@ export class MetricsManager {
       const smartMetricsData = await this.smartMetrics.getMetrics();
       const proxyMetrics = this.dcRouter.smartProxy ? this.dcRouter.smartProxy.getMetrics() : null;
       const proxyStats = this.dcRouter.smartProxy ? await this.dcRouter.smartProxy.getStatistics() : null;
+      const { heapUsed, heapTotal, external, rss } = process.memoryUsage();
 
       return {
         uptime: process.uptime(),
         startTime: Date.now() - (process.uptime() * 1000),
         memoryUsage: {
-          heapUsed: process.memoryUsage().heapUsed,
-          heapTotal: process.memoryUsage().heapTotal,
-          external: process.memoryUsage().external,
-          rss: process.memoryUsage().rss,
-          // Add SmartMetrics memory data
+          heapUsed,
+          heapTotal,
+          external,
+          rss,
           maxMemoryMB: this.smartMetrics.maxMemoryMB,
           actualUsageBytes: smartMetricsData.memoryUsageBytes,
           actualUsagePercentage: smartMetricsData.memoryPercentage,
         },
         cpuUsage: {
-          user: parseFloat(smartMetricsData.cpuUsageText || '0'),
-          system: 0, // SmartMetrics doesn't separate user/system
+          user: smartMetricsData.cpuPercentage,
+          system: 0,
         },
         activeConnections: proxyStats ? proxyStats.activeConnections : 0,
         totalConnections: proxyMetrics ? proxyMetrics.totals.connections() : 0,
@@ -202,11 +222,8 @@ export class MetricsManager {
         .slice(0, 10)
         .map(([domain, count]) => ({ domain, count }));
       
-      // Calculate queries per second from recent timestamps
-      const now = Date.now();
-      const oneMinuteAgo = now - 60000;
-      const recentQueries = this.dnsMetrics.queryTimestamps.filter(ts => ts >= oneMinuteAgo);
-      const queriesPerSecond = recentQueries.length / 60;
+      // Calculate queries per second from ring buffer (sum last 60 seconds)
+      const queriesPerSecond = this.getQueryRingSum(60) / 60;
       
       // Calculate average response time
       const avgResponseTime = this.dnsMetrics.responseTimes.length > 0
@@ -223,24 +240,50 @@ export class MetricsManager {
         queryTypes: this.dnsMetrics.queryTypes,
         averageResponseTime: Math.round(avgResponseTime),
         activeDomains: this.dnsMetrics.topDomains.size,
+        recentQueries: this.dnsMetrics.recentQueries.slice(),
       };
     });
   }
   
+  /**
+   * Sync security metrics from the SecurityLogger singleton (last 24h).
+   * Called before returning security stats so counters reflect real events.
+   */
+  private syncFromSecurityLogger(): void {
+    try {
+      const securityLogger = SecurityLogger.getInstance();
+      const summary = securityLogger.getEventsSummary(86400000); // last 24h
+
+      this.securityMetrics.spamDetected = summary.byType[SecurityEventType.SPAM] || 0;
+      this.securityMetrics.malwareDetected = summary.byType[SecurityEventType.MALWARE] || 0;
+      this.securityMetrics.phishingDetected = summary.byType[SecurityEventType.DMARC] || 0; // phishing via DMARC
+      this.securityMetrics.authFailures =
+        summary.byType[SecurityEventType.AUTHENTICATION] || 0;
+      this.securityMetrics.blockedIPs =
+        (summary.byType[SecurityEventType.IP_REPUTATION] || 0) +
+        (summary.byType[SecurityEventType.REJECTED_CONNECTION] || 0);
+    } catch {
+      // SecurityLogger may not be initialized yet — ignore
+    }
+  }
+
   // Get security metrics
   public async getSecurityStats() {
     return this.metricsCache.get('securityStats', () => {
+      // Sync counters from the real SecurityLogger events
+      this.syncFromSecurityLogger();
+
       // Get recent incidents (last 20)
       const recentIncidents = this.securityMetrics.incidents.slice(-20);
-      
+
       return {
         blockedIPs: this.securityMetrics.blockedIPs,
         authFailures: this.securityMetrics.authFailures,
         spamDetected: this.securityMetrics.spamDetected,
         malwareDetected: this.securityMetrics.malwareDetected,
         phishingDetected: this.securityMetrics.phishingDetected,
-        totalThreatsBlocked: this.securityMetrics.spamDetected + 
-          this.securityMetrics.malwareDetected + 
+        totalThreatsBlocked: this.securityMetrics.spamDetected +
+          this.securityMetrics.malwareDetected +
           this.securityMetrics.phishingDetected,
         recentIncidents,
       };
@@ -253,11 +296,11 @@ export class MetricsManager {
       const proxyMetrics = this.dcRouter.smartProxy ? this.dcRouter.smartProxy.getMetrics() : null;
       
       if (!proxyMetrics) {
-        return [];
+        return [] as Array<{ type: string; count: number; source: string; lastActivity: Date }>;
       }
-      
+
       const connectionsByRoute = proxyMetrics.connections.byRoute();
-      const connectionInfo = [];
+      const connectionInfo: Array<{ type: string; count: number; source: string; lastActivity: Date }> = [];
       
       for (const [routeName, count] of connectionsByRoute) {
         connectionInfo.push({
@@ -275,10 +318,19 @@ export class MetricsManager {
   // Email event tracking methods
   public trackEmailSent(recipient?: string, deliveryTimeMs?: number): void {
     this.emailMetrics.sentToday++;
+    this.incrementEmailBucket('sent');
     
     if (recipient) {
       const count = this.emailMetrics.recipients.get(recipient) || 0;
       this.emailMetrics.recipients.set(recipient, count + 1);
+
+      // Cap recipients map to prevent unbounded growth within a day
+      if (this.emailMetrics.recipients.size > this.MAX_TOP_DOMAINS) {
+        const sorted = Array.from(this.emailMetrics.recipients.entries())
+          .sort((a, b) => b[1] - a[1])
+          .slice(0, Math.floor(this.MAX_TOP_DOMAINS * 0.8));
+        this.emailMetrics.recipients = new Map(sorted);
+      }
     }
     
     if (deliveryTimeMs) {
@@ -303,6 +355,7 @@ export class MetricsManager {
   
   public trackEmailReceived(sender?: string): void {
     this.emailMetrics.receivedToday++;
+    this.incrementEmailBucket('received');
     
     this.emailMetrics.recentActivity.push({
       timestamp: Date.now(),
@@ -318,6 +371,7 @@ export class MetricsManager {
   
   public trackEmailFailed(recipient?: string, reason?: string): void {
     this.emailMetrics.failedToday++;
+    this.incrementEmailBucket('failed');
     
     this.emailMetrics.recentActivity.push({
       timestamp: Date.now(),
@@ -351,8 +405,21 @@ export class MetricsManager {
   }
   
   // DNS event tracking methods
-  public trackDnsQuery(queryType: string, domain: string, cacheHit: boolean, responseTimeMs?: number): void {
+  public trackDnsQuery(queryType: string, domain: string, cacheHit: boolean, responseTimeMs?: number, answered?: boolean): void {
     this.dnsMetrics.totalQueries++;
+    this.incrementDnsBucket();
+
+    // Store recent query entry
+    this.dnsMetrics.recentQueries.push({
+      timestamp: Date.now(),
+      domain,
+      type: queryType,
+      answered: answered ?? true,
+      responseTimeMs: responseTimeMs ?? 0,
+    });
+    if (this.dnsMetrics.recentQueries.length > 100) {
+      this.dnsMetrics.recentQueries.shift();
+    }
     
     if (cacheHit) {
       this.dnsMetrics.cacheHits++;
@@ -360,12 +427,8 @@ export class MetricsManager {
       this.dnsMetrics.cacheMisses++;
     }
     
-    // Track query timestamp
-    this.dnsMetrics.queryTimestamps.push(Date.now());
-    
-    // Keep only timestamps from last 5 minutes
-    const fiveMinutesAgo = Date.now() - 300000;
-    this.dnsMetrics.queryTimestamps = this.dnsMetrics.queryTimestamps.filter(ts => ts >= fiveMinutesAgo);
+    // Increment per-second query counter in ring buffer
+    this.incrementQueryRing();
     
     // Track response time if provided
     if (responseTimeMs) {
@@ -484,41 +547,314 @@ export class MetricsManager {
     // Use shorter cache TTL for network stats to ensure real-time updates
     return this.metricsCache.get('networkStats', () => {
       const proxyMetrics = this.dcRouter.smartProxy ? this.dcRouter.smartProxy.getMetrics() : null;
-      
+
       if (!proxyMetrics) {
         return {
           connectionsByIP: new Map<string, number>(),
           throughputRate: { bytesInPerSecond: 0, bytesOutPerSecond: 0 },
-          topIPs: [],
+          topIPs: [] as Array<{ ip: string; count: number }>,
           totalDataTransferred: { bytesIn: 0, bytesOut: 0 },
+          throughputHistory: [] as Array<{ timestamp: number; in: number; out: number }>,
+          throughputByIP: new Map<string, { in: number; out: number }>(),
+          requestsPerSecond: 0,
+          requestsTotal: 0,
+          backends: [] as Array<any>,
         };
       }
-      
+
       // Get metrics using the new API
       const connectionsByIP = proxyMetrics.connections.byIP();
       const instantThroughput = proxyMetrics.throughput.instant();
-      
+
       // Get throughput rate
       const throughputRate = {
         bytesInPerSecond: instantThroughput.in,
         bytesOutPerSecond: instantThroughput.out
       };
-      
+
       // Get top IPs
       const topIPs = proxyMetrics.connections.topIPs(10);
-      
+
       // Get total data transferred
       const totalDataTransferred = {
         bytesIn: proxyMetrics.totals.bytesIn(),
         bytesOut: proxyMetrics.totals.bytesOut()
       };
-      
+
+      // Get throughput history from Rust engine (up to 300 seconds)
+      const throughputHistory = proxyMetrics.throughput.history(300);
+
+      // Get per-IP throughput
+      const throughputByIP = proxyMetrics.throughput.byIP();
+
+      // Get HTTP request rates
+      const requestsPerSecond = proxyMetrics.requests.perSecond();
+      const requestsTotal = proxyMetrics.requests.total();
+
+      // Get frontend/backend protocol distribution
+      const frontendProtocols = proxyMetrics.connections.frontendProtocols() ?? null;
+      const backendProtocols = proxyMetrics.connections.backendProtocols() ?? null;
+
+      // Collect backend protocol data
+      const backendMetrics = proxyMetrics.backends.byBackend();
+      const protocolCache = proxyMetrics.backends.detectedProtocols();
+
+      // Group protocol cache entries by host:port so we can match them to backend metrics.
+      // The protocol cache is keyed by (host, port, domain) in Rust, so the same host:port
+      // can have multiple entries for different domains.
+      const cacheByBackend = new Map<string, (typeof protocolCache)[number][]>();
+      for (const entry of protocolCache) {
+        const backendKey = `${entry.host}:${entry.port}`;
+        let entries = cacheByBackend.get(backendKey);
+        if (!entries) {
+          entries = [];
+          cacheByBackend.set(backendKey, entries);
+        }
+        entries.push(entry);
+      }
+
+      const backends: Array<any> = [];
+      const seenCacheKeys = new Set<string>();
+
+      for (const [key, bm] of backendMetrics) {
+        const cacheEntries = cacheByBackend.get(key);
+        if (!cacheEntries || cacheEntries.length === 0) {
+          // No protocol cache entry — emit one row with backend metrics only
+          backends.push({
+            backend: key,
+            domain: null,
+            protocol: bm.protocol,
+            activeConnections: bm.activeConnections,
+            totalConnections: bm.totalConnections,
+            connectErrors: bm.connectErrors,
+            handshakeErrors: bm.handshakeErrors,
+            requestErrors: bm.requestErrors,
+            avgConnectTimeMs: Math.round(bm.avgConnectTimeMs * 10) / 10,
+            poolHitRate: Math.round(bm.poolHitRate * 1000) / 1000,
+            h2Failures: bm.h2Failures,
+            h2Suppressed: false,
+            h3Suppressed: false,
+            h2CooldownRemainingSecs: null,
+            h3CooldownRemainingSecs: null,
+            h2ConsecutiveFailures: null,
+            h3ConsecutiveFailures: null,
+            h3Port: null,
+            cacheAgeSecs: null,
+          });
+        } else {
+          // One row per domain, each enriched with the shared backend metrics
+          for (const cache of cacheEntries) {
+            const compositeKey = `${cache.host}:${cache.port}:${cache.domain ?? ''}`;
+            seenCacheKeys.add(compositeKey);
+            backends.push({
+              backend: key,
+              domain: cache.domain ?? null,
+              protocol: cache.protocol ?? bm.protocol,
+              activeConnections: bm.activeConnections,
+              totalConnections: bm.totalConnections,
+              connectErrors: bm.connectErrors,
+              handshakeErrors: bm.handshakeErrors,
+              requestErrors: bm.requestErrors,
+              avgConnectTimeMs: Math.round(bm.avgConnectTimeMs * 10) / 10,
+              poolHitRate: Math.round(bm.poolHitRate * 1000) / 1000,
+              h2Failures: bm.h2Failures,
+              h2Suppressed: cache.h2Suppressed,
+              h3Suppressed: cache.h3Suppressed,
+              h2CooldownRemainingSecs: cache.h2CooldownRemainingSecs,
+              h3CooldownRemainingSecs: cache.h3CooldownRemainingSecs,
+              h2ConsecutiveFailures: cache.h2ConsecutiveFailures,
+              h3ConsecutiveFailures: cache.h3ConsecutiveFailures,
+              h3Port: cache.h3Port,
+              cacheAgeSecs: cache.ageSecs,
+            });
+          }
+        }
+      }
+
+      // Include protocol cache entries with no matching backend metric
+      for (const entry of protocolCache) {
+        const compositeKey = `${entry.host}:${entry.port}:${entry.domain ?? ''}`;
+        if (!seenCacheKeys.has(compositeKey)) {
+          backends.push({
+            backend: `${entry.host}:${entry.port}`,
+            domain: entry.domain,
+            protocol: entry.protocol,
+            activeConnections: 0,
+            totalConnections: 0,
+            connectErrors: 0,
+            handshakeErrors: 0,
+            requestErrors: 0,
+            avgConnectTimeMs: 0,
+            poolHitRate: 0,
+            h2Failures: 0,
+            h2Suppressed: entry.h2Suppressed,
+            h3Suppressed: entry.h3Suppressed,
+            h2CooldownRemainingSecs: entry.h2CooldownRemainingSecs,
+            h3CooldownRemainingSecs: entry.h3CooldownRemainingSecs,
+            h2ConsecutiveFailures: entry.h2ConsecutiveFailures,
+            h3ConsecutiveFailures: entry.h3ConsecutiveFailures,
+            h3Port: entry.h3Port,
+            cacheAgeSecs: entry.ageSecs,
+          });
+        }
+      }
+
       return {
         connectionsByIP,
         throughputRate,
         topIPs,
         totalDataTransferred,
+        throughputHistory,
+        throughputByIP,
+        requestsPerSecond,
+        requestsTotal,
+        backends,
+        frontendProtocols,
+        backendProtocols,
       };
-    }, 200); // Use 200ms cache for more frequent updates
+    }, 1000); // 1s cache — matches typical dashboard poll interval
+  }
+
+  // --- Time-series helpers ---
+
+  private static minuteKey(ts: number = Date.now()): number {
+    return Math.floor(ts / 60000) * 60000;
+  }
+
+  private incrementEmailBucket(field: 'sent' | 'received' | 'failed'): void {
+    const key = MetricsManager.minuteKey();
+    let bucket = this.emailMinuteBuckets.get(key);
+    if (!bucket) {
+      bucket = { sent: 0, received: 0, failed: 0 };
+      this.emailMinuteBuckets.set(key, bucket);
+    }
+    bucket[field]++;
+  }
+
+  private incrementDnsBucket(): void {
+    const key = MetricsManager.minuteKey();
+    let bucket = this.dnsMinuteBuckets.get(key);
+    if (!bucket) {
+      bucket = { queries: 0 };
+      this.dnsMinuteBuckets.set(key, bucket);
+    }
+    bucket.queries++;
+  }
+
+  /**
+   * Increment the per-second query counter in the ring buffer.
+   * Zeros any stale slots between the last write and the current second.
+   */
+  private incrementQueryRing(): void {
+    const currentSecond = Math.floor(Date.now() / 1000);
+    const ring = this.dnsMetrics.queryRing;
+    const last = this.dnsMetrics.queryRingLastSecond;
+
+    if (last === 0) {
+      // First call — zero and anchor
+      ring.fill(0);
+      this.dnsMetrics.queryRingLastSecond = currentSecond;
+      ring[currentSecond % ring.length] = 1;
+      return;
+    }
+
+    const gap = currentSecond - last;
+    if (gap >= ring.length) {
+      // Entire ring is stale — clear all
+      ring.fill(0);
+    } else if (gap > 0) {
+      // Zero slots from (last+1) to currentSecond (inclusive)
+      for (let s = last + 1; s <= currentSecond; s++) {
+        ring[s % ring.length] = 0;
+      }
+    }
+
+    this.dnsMetrics.queryRingLastSecond = currentSecond;
+    ring[currentSecond % ring.length]++;
+  }
+
+  /**
+   * Sum query counts from the ring buffer for the last N seconds.
+   */
+  private getQueryRingSum(seconds: number): number {
+    const currentSecond = Math.floor(Date.now() / 1000);
+    const ring = this.dnsMetrics.queryRing;
+    const last = this.dnsMetrics.queryRingLastSecond;
+
+    if (last === 0) return 0;
+
+    // First, zero stale slots so reads are accurate even without writes
+    const gap = currentSecond - last;
+    if (gap >= ring.length) return 0; // all data is stale
+
+    let sum = 0;
+    const limit = Math.min(seconds, ring.length);
+    for (let i = 0; i < limit; i++) {
+      const sec = currentSecond - i;
+      if (sec < last - (ring.length - 1)) break; // slot is from older cycle
+      if (sec > last) continue; // no writes yet for this second
+      sum += ring[sec % ring.length];
+    }
+    return sum;
+  }
+
+  private pruneOldBuckets(): void {
+    const cutoff = Date.now() - 86400000; // 24h
+    for (const key of this.emailMinuteBuckets.keys()) {
+      if (key < cutoff) this.emailMinuteBuckets.delete(key);
+    }
+    for (const key of this.dnsMinuteBuckets.keys()) {
+      if (key < cutoff) this.dnsMinuteBuckets.delete(key);
+    }
+  }
+
+  /**
+   * Get email time-series data for the last N hours, aggregated per minute.
+   */
+  public getEmailTimeSeries(hours: number = 24): {
+    sent: Array<{ timestamp: number; value: number }>;
+    received: Array<{ timestamp: number; value: number }>;
+    failed: Array<{ timestamp: number; value: number }>;
+  } {
+    this.pruneOldBuckets();
+    const cutoff = Date.now() - hours * 3600000;
+    const sent: Array<{ timestamp: number; value: number }> = [];
+    const received: Array<{ timestamp: number; value: number }> = [];
+    const failed: Array<{ timestamp: number; value: number }> = [];
+
+    const sortedKeys = Array.from(this.emailMinuteBuckets.keys())
+      .filter((k) => k >= cutoff)
+      .sort((a, b) => a - b);
+
+    for (const key of sortedKeys) {
+      const bucket = this.emailMinuteBuckets.get(key)!;
+      sent.push({ timestamp: key, value: bucket.sent });
+      received.push({ timestamp: key, value: bucket.received });
+      failed.push({ timestamp: key, value: bucket.failed });
+    }
+
+    return { sent, received, failed };
+  }
+
+  /**
+   * Get DNS time-series data for the last N hours, aggregated per minute.
+   */
+  public getDnsTimeSeries(hours: number = 24): {
+    queries: Array<{ timestamp: number; value: number }>;
+  } {
+    this.pruneOldBuckets();
+    const cutoff = Date.now() - hours * 3600000;
+    const queries: Array<{ timestamp: number; value: number }> = [];
+
+    const sortedKeys = Array.from(this.dnsMinuteBuckets.keys())
+      .filter((k) => k >= cutoff)
+      .sort((a, b) => a - b);
+
+    for (const key of sortedKeys) {
+      const bucket = this.dnsMinuteBuckets.get(key)!;
+      queries.push({ timestamp: key, value: bucket.queries });
+    }
+
+    return { queries };
   }
 }

ts/opsserver/classes.opsserver.ts

@@ -2,27 +2,45 @@ import type DcRouter from '../classes.dcrouter.js';
 import * as plugins from '../plugins.js';
 import * as paths from '../paths.js';
 import * as handlers from './handlers/index.js';
+import * as interfaces from '../../ts_interfaces/index.js';
+import { requireValidIdentity, requireAdminIdentity } from './helpers/guards.js';
 
 export class OpsServer {
   public dcRouterRef: DcRouter;
-  public server: plugins.typedserver.utilityservers.UtilityWebsiteServer;
-  
-  // TypedRouter for OpsServer-specific handlers
+  public server!: plugins.typedserver.utilityservers.UtilityWebsiteServer;
+
+  // Main TypedRouter — unauthenticated endpoints (login/logout/verify) and own-auth handlers
   public typedrouter = new plugins.typedrequest.TypedRouter();
-  
+
+  // Auth-enforced routers — middleware validates identity before any handler runs
+  public viewRouter = new plugins.typedrequest.TypedRouter<{ request: { identity: interfaces.data.IIdentity } }>();
+  public adminRouter = new plugins.typedrequest.TypedRouter<{ request: { identity: interfaces.data.IIdentity } }>();
+
   // Handler instances
-  public adminHandler: handlers.AdminHandler;
-  private configHandler: handlers.ConfigHandler;
-  private logsHandler: handlers.LogsHandler;
-  private securityHandler: handlers.SecurityHandler;
-  private statsHandler: handlers.StatsHandler;
-  private radiusHandler: handlers.RadiusHandler;
-  private emailOpsHandler: handlers.EmailOpsHandler;
-  private certificateHandler: handlers.CertificateHandler;
+  public adminHandler!: handlers.AdminHandler;
+  private configHandler!: handlers.ConfigHandler;
+  private logsHandler!: handlers.LogsHandler;
+  private securityHandler!: handlers.SecurityHandler;
+  private statsHandler!: handlers.StatsHandler;
+  private radiusHandler!: handlers.RadiusHandler;
+  private emailOpsHandler!: handlers.EmailOpsHandler;
+  private certificateHandler!: handlers.CertificateHandler;
+  private remoteIngressHandler!: handlers.RemoteIngressHandler;
+  private routeManagementHandler!: handlers.RouteManagementHandler;
+  private apiTokenHandler!: handlers.ApiTokenHandler;
+  private vpnHandler!: handlers.VpnHandler;
+  private sourceProfileHandler!: handlers.SourceProfileHandler;
+  private targetProfileHandler!: handlers.TargetProfileHandler;
+  private networkTargetHandler!: handlers.NetworkTargetHandler;
+  private usersHandler!: handlers.UsersHandler;
+  private dnsProviderHandler!: handlers.DnsProviderHandler;
+  private domainHandler!: handlers.DomainHandler;
+  private dnsRecordHandler!: handlers.DnsRecordHandler;
+  private acmeConfigHandler!: handlers.AcmeConfigHandler;
 
   constructor(dcRouterRefArg: DcRouter) {
     this.dcRouterRef = dcRouterRefArg;
-    
+
     // Add our typedrouter to the dcRouter's main typedrouter
     this.dcRouterRef.typedrouter.addTypedRouter(this.typedrouter);
   }
@@ -30,7 +48,7 @@ export class OpsServer {
   public async start() {
     this.server = new plugins.typedserver.utilityservers.UtilityWebsiteServer({
       domain: 'localhost',
-      feedMetadata: null,
+      feedMetadata: undefined,
       serveDir: paths.distServe,
     });
     
@@ -41,17 +59,32 @@ export class OpsServer {
     // Set up handlers
     await this.setupHandlers();
 
-    await this.server.start(3000);
+    await this.server.start(this.dcRouterRef.options.opsServerPort ?? 3000);
   }
   
   /**
    * Set up all TypedRequest handlers
    */
   private async setupHandlers(): Promise<void> {
-    // Instantiate all handlers - they self-register with the typedrouter
+    // AdminHandler must be initialized first (JWT setup needed for guards)
     this.adminHandler = new handlers.AdminHandler(this);
-    await this.adminHandler.initialize(); // JWT needs async initialization
-    
+    await this.adminHandler.initialize();
+
+    // viewRouter middleware: requires valid identity (any logged-in user)
+    this.viewRouter.addMiddleware(async (typedRequest) => {
+      await requireValidIdentity(this.adminHandler, typedRequest.request);
+    });
+
+    // adminRouter middleware: requires admin identity
+    this.adminRouter.addMiddleware(async (typedRequest) => {
+      await requireAdminIdentity(this.adminHandler, typedRequest.request);
+    });
+
+    // Connect auth routers to the main typedrouter
+    this.typedrouter.addTypedRouter(this.viewRouter);
+    this.typedrouter.addTypedRouter(this.adminRouter);
+
+    // Instantiate all handlers — they self-register with the appropriate router
     this.configHandler = new handlers.ConfigHandler(this);
     this.logsHandler = new handlers.LogsHandler(this);
     this.securityHandler = new handlers.SecurityHandler(this);
@@ -59,11 +92,27 @@ export class OpsServer {
     this.radiusHandler = new handlers.RadiusHandler(this);
     this.emailOpsHandler = new handlers.EmailOpsHandler(this);
     this.certificateHandler = new handlers.CertificateHandler(this);
+    this.remoteIngressHandler = new handlers.RemoteIngressHandler(this);
+    this.routeManagementHandler = new handlers.RouteManagementHandler(this);
+    this.apiTokenHandler = new handlers.ApiTokenHandler(this);
+    this.vpnHandler = new handlers.VpnHandler(this);
+    this.sourceProfileHandler = new handlers.SourceProfileHandler(this);
+    this.targetProfileHandler = new handlers.TargetProfileHandler(this);
+    this.networkTargetHandler = new handlers.NetworkTargetHandler(this);
+    this.usersHandler = new handlers.UsersHandler(this);
+    this.dnsProviderHandler = new handlers.DnsProviderHandler(this);
+    this.domainHandler = new handlers.DomainHandler(this);
+    this.dnsRecordHandler = new handlers.DnsRecordHandler(this);
+    this.acmeConfigHandler = new handlers.AcmeConfigHandler(this);
 
     console.log('✅ OpsServer TypedRequest handlers initialized');
   }
 
   public async stop() {
+    // Clean up log handler streams and push destination before stopping the server
+    if (this.logsHandler) {
+      this.logsHandler.cleanup();
+    }
     if (this.server) {
       await this.server.stop();
     }

ts/opsserver/handlers/acme-config.handler.ts

@@ -0,0 +1,94 @@
+import * as plugins from '../../plugins.js';
+import type { OpsServer } from '../classes.opsserver.js';
+import * as interfaces from '../../../ts_interfaces/index.js';
+
+/**
+ * CRUD handler for the singleton `AcmeConfigDoc`.
+ *
+ * Auth: same dual-mode pattern as other handlers — admin JWT or API token
+ * with `acme-config:read` / `acme-config:write` scope.
+ */
+export class AcmeConfigHandler {
+  public typedrouter = new plugins.typedrequest.TypedRouter();
+
+  constructor(private opsServerRef: OpsServer) {
+    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
+    this.registerHandlers();
+  }
+
+  private async requireAuth(
+    request: { identity?: interfaces.data.IIdentity; apiToken?: string },
+    requiredScope?: interfaces.data.TApiTokenScope,
+  ): Promise<string> {
+    if (request.identity?.jwt) {
+      try {
+        const isAdmin = await this.opsServerRef.adminHandler.adminIdentityGuard.exec({
+          identity: request.identity,
+        });
+        if (isAdmin) return request.identity.userId;
+      } catch { /* fall through */ }
+    }
+
+    if (request.apiToken) {
+      const tokenManager = this.opsServerRef.dcRouterRef.apiTokenManager;
+      if (tokenManager) {
+        const token = await tokenManager.validateToken(request.apiToken);
+        if (token) {
+          if (!requiredScope || tokenManager.hasScope(token, requiredScope)) {
+            return token.createdBy;
+          }
+          throw new plugins.typedrequest.TypedResponseError('insufficient scope');
+        }
+      }
+    }
+
+    throw new plugins.typedrequest.TypedResponseError('unauthorized');
+  }
+
+  private registerHandlers(): void {
+    // Get current ACME config
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetAcmeConfig>(
+        'getAcmeConfig',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'acme-config:read');
+          const mgr = this.opsServerRef.dcRouterRef.acmeConfigManager;
+          if (!mgr) return { config: null };
+          return { config: mgr.getConfig() };
+        },
+      ),
+    );
+
+    // Update (upsert) the ACME config
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_UpdateAcmeConfig>(
+        'updateAcmeConfig',
+        async (dataArg) => {
+          const userId = await this.requireAuth(dataArg, 'acme-config:write');
+          const mgr = this.opsServerRef.dcRouterRef.acmeConfigManager;
+          if (!mgr) {
+            return {
+              success: false,
+              message: 'AcmeConfigManager not initialized (DB disabled?)',
+            };
+          }
+          try {
+            const updated = await mgr.updateConfig(
+              {
+                accountEmail: dataArg.accountEmail,
+                enabled: dataArg.enabled,
+                useProduction: dataArg.useProduction,
+                autoRenew: dataArg.autoRenew,
+                renewThresholdDays: dataArg.renewThresholdDays,
+              },
+              userId,
+            );
+            return { success: true, config: updated };
+          } catch (err: unknown) {
+            return { success: false, message: (err as Error).message };
+          }
+        },
+      ),
+    );
+  }
+}

ts/opsserver/handlers/admin.handler.ts

@@ -12,7 +12,7 @@ export class AdminHandler {
   public typedrouter = new plugins.typedrequest.TypedRouter();
   
   // JWT instance
-  public smartjwtInstance: plugins.smartjwt.SmartJwt<IJwtData>;
+  public smartjwtInstance!: plugins.smartjwt.SmartJwt<IJwtData>;
   
   // Simple in-memory user storage (in production, use proper database)
   private users = new Map<string, {
@@ -52,6 +52,18 @@ export class AdminHandler {
       role: 'admin',
     });
   }
+
+  /**
+   * Return a safe projection of the users Map — excludes password fields.
+   * Used by UsersHandler to serve the admin-only listUsers endpoint.
+   */
+  public listUsers(): Array<{ id: string; username: string; role: string }> {
+    return Array.from(this.users.values()).map((user) => ({
+      id: user.id,
+      username: user.username,
+      role: user.role,
+    }));
+  }
   
   private registerHandlers(): void {
     // Admin Login Handler

ts/opsserver/handlers/api-token.handler.ts

@@ -0,0 +1,97 @@
+import * as plugins from '../../plugins.js';
+import type { OpsServer } from '../classes.opsserver.js';
+import * as interfaces from '../../../ts_interfaces/index.js';
+
+export class ApiTokenHandler {
+  constructor(private opsServerRef: OpsServer) {
+    this.registerHandlers();
+  }
+
+  private registerHandlers(): void {
+    // All token management endpoints register directly on adminRouter
+    // (middleware enforces admin JWT check, so no per-handler requireAdmin needed)
+    const router = this.opsServerRef.adminRouter;
+
+    // Create API token
+    router.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_CreateApiToken>(
+        'createApiToken',
+        async (dataArg) => {
+          const manager = this.opsServerRef.dcRouterRef.apiTokenManager;
+          if (!manager) {
+            return { success: false, message: 'Token management not initialized' };
+          }
+          const result = await manager.createToken(
+            dataArg.name,
+            dataArg.scopes,
+            dataArg.expiresInDays ?? null,
+            dataArg.identity.userId,
+          );
+          return { success: true, tokenId: result.id, tokenValue: result.rawToken };
+        },
+      ),
+    );
+
+    // List API tokens
+    router.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ListApiTokens>(
+        'listApiTokens',
+        async (dataArg) => {
+          const manager = this.opsServerRef.dcRouterRef.apiTokenManager;
+          if (!manager) {
+            return { tokens: [] };
+          }
+          return { tokens: manager.listTokens() };
+        },
+      ),
+    );
+
+    // Revoke API token
+    router.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_RevokeApiToken>(
+        'revokeApiToken',
+        async (dataArg) => {
+          const manager = this.opsServerRef.dcRouterRef.apiTokenManager;
+          if (!manager) {
+            return { success: false, message: 'Token management not initialized' };
+          }
+          const ok = await manager.revokeToken(dataArg.id);
+          return { success: ok, message: ok ? undefined : 'Token not found' };
+        },
+      ),
+    );
+
+    // Roll API token
+    router.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_RollApiToken>(
+        'rollApiToken',
+        async (dataArg) => {
+          const manager = this.opsServerRef.dcRouterRef.apiTokenManager;
+          if (!manager) {
+            return { success: false, message: 'Token management not initialized' };
+          }
+          const result = await manager.rollToken(dataArg.id);
+          if (!result) {
+            return { success: false, message: 'Token not found' };
+          }
+          return { success: true, tokenValue: result.rawToken };
+        },
+      ),
+    );
+
+    // Toggle API token
+    router.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ToggleApiToken>(
+        'toggleApiToken',
+        async (dataArg) => {
+          const manager = this.opsServerRef.dcRouterRef.apiTokenManager;
+          if (!manager) {
+            return { success: false, message: 'Token management not initialized' };
+          }
+          const ok = await manager.toggleToken(dataArg.id, dataArg.enabled);
+          return { success: ok, message: ok ? undefined : 'Token not found' };
+        },
+      ),
+    );
+  }
+}

ts/opsserver/handlers/certificate.handler.ts

@@ -1,18 +1,43 @@
 import * as plugins from '../../plugins.js';
 import type { OpsServer } from '../classes.opsserver.js';
 import * as interfaces from '../../../ts_interfaces/index.js';
+import { AcmeCertDoc, ProxyCertDoc } from '../../db/index.js';
+import { logger } from '../../logger.js';
+
+/**
+ * Mirrors `SmartacmeCertMatcher.getCertificateDomainNameByDomainName` from
+ * @push.rocks/smartacme. Inlined here because the original is `private` on
+ * SmartAcme. The cert identity ('task.vc' for both 'outline.task.vc' and
+ * '*.task.vc') is what AcmeCertDoc is keyed by, so two route domains with
+ * the same identity share the same underlying ACME cert.
+ *
+ * Returns undefined for domains with 4+ levels (matching smartacme's
+ * "deeper domains not supported" behavior) and for malformed inputs.
+ *
+ * Exported for unit testing.
+ */
+export function deriveCertDomainName(domain: string): string | undefined {
+  if (domain.startsWith('*.')) {
+    return domain.slice(2);
+  }
+  const parts = domain.split('.');
+  if (parts.length < 2 || parts.length > 3) return undefined;
+  return parts.slice(-2).join('.');
+}
 
 export class CertificateHandler {
-  public typedrouter = new plugins.typedrequest.TypedRouter();
-
   constructor(private opsServerRef: OpsServer) {
-    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
     this.registerHandlers();
   }
 
   private registerHandlers(): void {
+    const viewRouter = this.opsServerRef.viewRouter;
+    const adminRouter = this.opsServerRef.adminRouter;
+
+    // ---- Read endpoints (viewRouter — valid identity required via middleware) ----
+
     // Get Certificate Overview
-    this.typedrouter.addTypedHandler(
+    viewRouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetCertificateOverview>(
         'getCertificateOverview',
         async (dataArg) => {
@@ -23,24 +48,77 @@ export class CertificateHandler {
       )
     );
 
-    // Reprovision Certificate
-    this.typedrouter.addTypedHandler(
+    // ---- Write endpoints (adminRouter — admin identity required via middleware) ----
+
+    // Legacy route-based reprovision (backward compat)
+    adminRouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ReprovisionCertificate>(
         'reprovisionCertificate',
         async (dataArg) => {
-          return this.reprovisionCertificate(dataArg.routeName);
+          return this.reprovisionCertificateByRoute(dataArg.routeName);
+        }
+      )
+    );
+
+    // Domain-based reprovision (preferred)
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ReprovisionCertificateDomain>(
+        'reprovisionCertificateDomain',
+        async (dataArg) => {
+          return this.reprovisionCertificateDomain(dataArg.domain, dataArg.forceRenew);
+        }
+      )
+    );
+
+    // Delete certificate
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_DeleteCertificate>(
+        'deleteCertificate',
+        async (dataArg) => {
+          return this.deleteCertificate(dataArg.domain);
+        }
+      )
+    );
+
+    // Export certificate
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ExportCertificate>(
+        'exportCertificate',
+        async (dataArg) => {
+          return this.exportCertificate(dataArg.domain);
+        }
+      )
+    );
+
+    // Import certificate
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ImportCertificate>(
+        'importCertificate',
+        async (dataArg) => {
+          return this.importCertificate(dataArg.cert);
         }
       )
     );
   }
 
+  /**
+   * Build domain-centric certificate overview.
+   * Instead of one row per route, we produce one row per unique domain.
+   */
   private async buildCertificateOverview(): Promise<interfaces.requests.ICertificateInfo[]> {
     const dcRouter = this.opsServerRef.dcRouterRef;
     const smartProxy = dcRouter.smartProxy;
     if (!smartProxy) return [];
 
     const routes = smartProxy.routeManager.getRoutes();
-    const certificates: interfaces.requests.ICertificateInfo[] = [];
+
+    // Phase 1: Collect unique domains with their associated route info
+    const domainMap = new Map<string, {
+      routeNames: string[];
+      source: interfaces.requests.TCertificateSource;
+      tlsMode: 'terminate' | 'terminate-and-reencrypt' | 'passthrough';
+      canReprovision: boolean;
+    }>();
 
     for (const route of routes) {
       if (!route.name) continue;
@@ -58,7 +136,6 @@ export class CertificateHandler {
       // Determine source
       let source: interfaces.requests.TCertificateSource = 'none';
       if (tls.certificate === 'auto') {
-        // Check if a certProvisionFunction is configured
         if ((smartProxy.settings as any).certProvisionFunction) {
           source = 'provision-function';
         } else {
@@ -68,15 +145,44 @@ export class CertificateHandler {
         source = 'static';
       }
 
-      // Start with unknown status
+      const canReprovision = source === 'acme' || source === 'provision-function';
+      const tlsMode = tls.mode as 'terminate' | 'terminate-and-reencrypt' | 'passthrough';
+
+      for (const domain of routeDomains) {
+        const existing = domainMap.get(domain);
+        if (existing) {
+          // Add this route name to the existing domain entry
+          if (!existing.routeNames.includes(route.name)) {
+            existing.routeNames.push(route.name);
+          }
+          // Upgrade source if more specific
+          if (existing.source === 'none' && source !== 'none') {
+            existing.source = source;
+            existing.canReprovision = canReprovision;
+          }
+        } else {
+          domainMap.set(domain, {
+            routeNames: [route.name],
+            source,
+            tlsMode,
+            canReprovision,
+          });
+        }
+      }
+    }
+
+    // Phase 2: Resolve status for each unique domain
+    const certificates: interfaces.requests.ICertificateInfo[] = [];
+
+    for (const [domain, info] of domainMap) {
       let status: interfaces.requests.TCertificateStatus = 'unknown';
       let expiryDate: string | undefined;
       let issuedAt: string | undefined;
       let issuer: string | undefined;
       let error: string | undefined;
 
-      // Check event-based status from DcRouter's certificateStatusMap
-      const eventStatus = dcRouter.certificateStatusMap.get(route.name);
+      // Check event-based status from certificateStatusMap (now keyed by domain)
+      const eventStatus = dcRouter.certificateStatusMap.get(domain);
       if (eventStatus) {
         status = eventStatus.status;
         expiryDate = eventStatus.expiryDate;
@@ -87,10 +193,10 @@ export class CertificateHandler {
         }
       }
 
-      // Try Rust-side certificate status if no event data
-      if (status === 'unknown') {
+      // Try SmartProxy certificate status if no event data
+      if (status === 'unknown' && info.routeNames.length > 0) {
         try {
-          const rustStatus = await smartProxy.getCertificateStatus(route.name);
+          const rustStatus = await smartProxy.getCertificateStatus(info.routeNames[0]);
           if (rustStatus) {
             if (rustStatus.expiryDate) expiryDate = rustStatus.expiryDate;
             if (rustStatus.issuer) issuer = rustStatus.issuer;
@@ -104,7 +210,38 @@ export class CertificateHandler {
         }
       }
 
-      // Compute status from expiry date if we have one and status is still valid/unknown
+      // Check persisted cert data from smartdata document classes
+      if (status === 'unknown') {
+        const cleanDomain = domain.replace(/^\*\.?/, '');
+        // SmartAcme stores certs under the base domain (e.g. example.com for api.example.com)
+        const parts = cleanDomain.split('.');
+        const baseDomain = parts.length > 2 ? parts.slice(-2).join('.') : cleanDomain;
+        const acmeDoc = await AcmeCertDoc.findByDomain(baseDomain)
+          || (baseDomain !== cleanDomain ? await AcmeCertDoc.findByDomain(cleanDomain) : null);
+        const proxyDoc = !acmeDoc ? await ProxyCertDoc.findByDomain(domain) : null;
+
+        if (acmeDoc?.validUntil) {
+          expiryDate = new Date(acmeDoc.validUntil).toISOString();
+          if (acmeDoc.created) {
+            issuedAt = new Date(acmeDoc.created).toISOString();
+          }
+          issuer = 'smartacme-dns-01';
+        } else if (proxyDoc?.publicKey) {
+          // certStore has the cert — parse PEM for expiry
+          try {
+            const x509 = new plugins.crypto.X509Certificate(proxyDoc.publicKey);
+            expiryDate = new Date(x509.validTo).toISOString();
+            issuedAt = new Date(x509.validFrom).toISOString();
+          } catch { /* PEM parsing failed */ }
+          status = 'valid';
+          issuer = 'cert-store';
+        } else if (acmeDoc || proxyDoc) {
+          status = 'valid';
+          issuer = 'cert-store';
+        }
+      }
+
+      // Compute status from expiry date
       if (expiryDate && (status === 'valid' || status === 'unknown')) {
         const expiry = new Date(expiryDate);
         const now = new Date();
@@ -120,23 +257,36 @@ export class CertificateHandler {
       }
 
       // Static certs with no other info default to 'valid'
-      if (source === 'static' && status === 'unknown') {
+      if (info.source === 'static' && status === 'unknown') {
         status = 'valid';
       }
 
-      const canReprovision = source === 'acme' || source === 'provision-function';
+      // ACME/provision-function routes with no cert data are still provisioning
+      if (status === 'unknown' && (info.source === 'acme' || info.source === 'provision-function')) {
+        status = 'provisioning';
+      }
+
+      // Phase 3: Attach backoff info
+      let backoffInfo: interfaces.requests.ICertificateInfo['backoffInfo'];
+      if (dcRouter.certProvisionScheduler) {
+        const bi = await dcRouter.certProvisionScheduler.getBackoffInfo(domain);
+        if (bi) {
+          backoffInfo = bi;
+        }
+      }
 
       certificates.push({
-        routeName: route.name,
-        domains: routeDomains,
+        domain,
+        routeNames: info.routeNames,
         status,
-        source,
-        tlsMode: tls.mode as 'terminate' | 'terminate-and-reencrypt' | 'passthrough',
+        source: info.source,
+        tlsMode: info.tlsMode,
         expiryDate,
         issuer,
         issuedAt,
         error,
-        canReprovision,
+        canReprovision: info.canReprovision,
+        backoffInfo,
       });
     }
 
@@ -166,7 +316,15 @@ export class CertificateHandler {
     return summary;
   }
 
-  private async reprovisionCertificate(routeName: string): Promise<{ success: boolean; message?: string }> {
+  /**
+   * Legacy route-based reprovisioning. Kept for backward compatibility with
+   * older clients that send `reprovisionCertificate` typed-requests.
+   *
+   * Like reprovisionCertificateDomain, this triggers the full route apply
+   * pipeline rather than smartProxy.provisionCertificate(routeName) — which
+   * is a no-op when certProvisionFunction is set (Rust ACME disabled).
+   */
+  private async reprovisionCertificateByRoute(routeName: string): Promise<{ success: boolean; message?: string }> {
     const dcRouter = this.opsServerRef.dcRouterRef;
     const smartProxy = dcRouter.smartProxy;
 
@@ -174,13 +332,343 @@ export class CertificateHandler {
       return { success: false, message: 'SmartProxy is not running' };
     }
 
+    // Clear event-based status for domains in this route so the
+    // certificate-issued event can refresh them
+    for (const [domain, entry] of dcRouter.certificateStatusMap) {
+      if (entry.routeNames.includes(routeName)) {
+        dcRouter.certificateStatusMap.delete(domain);
+      }
+    }
+
     try {
-      await smartProxy.provisionCertificate(routeName);
-      // Clear event-based status so it gets refreshed
-      dcRouter.certificateStatusMap.delete(routeName);
+      if (dcRouter.routeConfigManager) {
+        await dcRouter.routeConfigManager.applyRoutes();
+      } else {
+        await smartProxy.updateRoutes(smartProxy.routeManager.getRoutes());
+      }
       return { success: true, message: `Certificate reprovisioning triggered for route '${routeName}'` };
-    } catch (err) {
-      return { success: false, message: err.message || 'Failed to reprovision certificate' };
+    } catch (err: unknown) {
+      return { success: false, message: (err as Error).message || 'Failed to reprovision certificate' };
     }
   }
+
+  /**
+   * Domain-based reprovisioning — clears backoff first, refreshes the smartacme
+   * cert (when forceRenew is set), then re-applies routes so the running Rust
+   * proxy actually picks up the new cert.
+   *
+   * Why applyRoutes (not smartProxy.provisionCertificate)?
+   *   smartProxy.provisionCertificate(routeName) routes through the Rust ACME
+   *   path, which is forcibly disabled whenever certProvisionFunction is set
+   *   (smart-proxy.ts:168-171). The only path that re-invokes
+   *   certProvisionFunction → bridge.loadCertificate is updateRoutes(), which
+   *   we trigger via routeConfigManager.applyRoutes().
+   */
+  private async reprovisionCertificateDomain(domain: string, forceRenew?: boolean): Promise<{ success: boolean; message?: string }> {
+    const dcRouter = this.opsServerRef.dcRouterRef;
+    const smartProxy = dcRouter.smartProxy;
+
+    if (!smartProxy) {
+      return { success: false, message: 'SmartProxy is not running' };
+    }
+
+    // Clear backoff for this domain (user override)
+    if (dcRouter.certProvisionScheduler) {
+      await dcRouter.certProvisionScheduler.clearBackoff(domain);
+    }
+
+    // Find routes matching this domain — fail early if none exist
+    const routeNames = dcRouter.findRouteNamesForDomain(domain);
+    if (routeNames.length === 0) {
+      return { success: false, message: `No routes found for domain '${domain}'` };
+    }
+
+    // If forceRenew, order a fresh cert from ACME now so it's already in
+    // AcmeCertDoc by the time certProvisionFunction is invoked below.
+    //
+    // includeWildcard: when forcing a non-wildcard subdomain renewal, we still
+    // want the wildcard SAN in the order so the new cert keeps covering every
+    // sibling. Without this, smartacme defaults to includeWildcard: false and
+    // the re-issued cert would have only the base domain as SAN, breaking every
+    // sibling subdomain that was previously covered by the same wildcard cert.
+    if (forceRenew && dcRouter.smartAcme) {
+      let newCert: plugins.smartacme.Cert;
+      try {
+        newCert = await dcRouter.smartAcme.getCertificateForDomain(domain, {
+          forceRenew: true,
+          includeWildcard: !domain.startsWith('*.'),
+        });
+      } catch (err: unknown) {
+        return { success: false, message: `Failed to renew certificate for ${domain}: ${(err as Error).message}` };
+      }
+
+      // Propagate the freshly-issued cert PEM to every sibling route domain that
+      // shares the same cert identity. Without this, the rust hot-swap (keyed by
+      // exact domain in `loaded_certs`) only fires for the clicked route via the
+      // fire-and-forget cert provisioning path, leaving siblings serving the
+      // stale in-memory cert until the next background reload completes.
+      try {
+        await this.propagateCertToSiblings(domain, newCert);
+      } catch (err: unknown) {
+        // Best-effort: failure here doesn't undo the cert issuance, just log.
+        logger.log('warn', `Failed to propagate force-renewed cert to siblings of ${domain}: ${(err as Error).message}`);
+      }
+    }
+
+    // Clear status map entry so it gets refreshed by the certificate-issued event
+    dcRouter.certificateStatusMap.delete(domain);
+
+    // Trigger the full route apply pipeline:
+    //   applyRoutes → updateRoutes → provisionCertificatesViaCallback →
+    //   certProvisionFunction(domain) → smartAcme.getCertificateForDomain →
+    //   bridge.loadCertificate → Rust hot-swaps `loaded_certs` →
+    //   certificate-issued event → certificateStatusMap updated
+    try {
+      if (dcRouter.routeConfigManager) {
+        await dcRouter.routeConfigManager.applyRoutes();
+      } else {
+        // Fallback when DB is disabled and there is no RouteConfigManager
+        await smartProxy.updateRoutes(smartProxy.routeManager.getRoutes());
+      }
+      return { success: true, message: forceRenew ? `Certificate force-renewed for domain '${domain}'` : `Certificate reprovisioning triggered for domain '${domain}'` };
+    } catch (err: unknown) {
+      return { success: false, message: (err as Error).message || `Failed to reprovision certificate for ${domain}` };
+    }
+  }
+
+  /**
+   * After a force-renew, walk every route in the smartproxy that resolves to
+   * the same cert identity as `forcedDomain` and write the freshly-issued cert
+   * PEM into ProxyCertDoc for each. This guarantees that the next applyRoutes
+   * → provisionCertificatesViaCallback iteration will hot-swap every sibling's
+   * rust loaded_certs entry with the new (correct) PEM, rather than relying on
+   * the in-memory cert returned by smartacme's per-domain cache.
+   *
+   * Why this is necessary:
+   *   Rust's `loaded_certs` is a HashMap<domain, TlsCertConfig>. Each
+   *   bridge.loadCertificate(domain, ...) only swaps that one entry. The
+   *   fire-and-forget cert provisioning path triggered by updateRoutes does
+   *   eventually iterate every auto-cert route, but it returns the cached
+   *   (broken pre-fix) cert from smartacme's per-domain mutex. With this
+   *   helper, ProxyCertDoc is updated synchronously to the correct PEM before
+   *   applyRoutes runs, so even the transient window stays consistent.
+   */
+  private async propagateCertToSiblings(
+    forcedDomain: string,
+    newCert: plugins.smartacme.Cert,
+  ): Promise<void> {
+    const dcRouter = this.opsServerRef.dcRouterRef;
+    const smartProxy = dcRouter.smartProxy;
+    if (!smartProxy) return;
+
+    const certIdentity = deriveCertDomainName(forcedDomain);
+    if (!certIdentity) return;
+
+    // Collect every route domain whose cert identity matches.
+    const affected = new Set<string>();
+    for (const route of smartProxy.routeManager.getRoutes()) {
+      if (!route.match.domains) continue;
+      const routeDomains = Array.isArray(route.match.domains)
+        ? route.match.domains
+        : [route.match.domains];
+      for (const routeDomain of routeDomains) {
+        if (deriveCertDomainName(routeDomain) === certIdentity) {
+          affected.add(routeDomain);
+        }
+      }
+    }
+
+    if (affected.size === 0) return;
+
+    // Parse expiry from PEM (defense-in-depth — same pattern as
+    // ts/classes.dcrouter.ts:988-995 and the existing certStore.save callback).
+    let validUntil = newCert.validUntil;
+    let validFrom: number | undefined;
+    if (newCert.publicKey) {
+      try {
+        const x509 = new plugins.crypto.X509Certificate(newCert.publicKey);
+        validUntil = new Date(x509.validTo).getTime();
+        validFrom = new Date(x509.validFrom).getTime();
+      } catch { /* fall back to smartacme's value */ }
+    }
+
+    // Persist new cert PEM under each affected route domain
+    for (const routeDomain of affected) {
+      let doc = await ProxyCertDoc.findByDomain(routeDomain);
+      if (!doc) {
+        doc = new ProxyCertDoc();
+        doc.domain = routeDomain;
+      }
+      doc.publicKey = newCert.publicKey;
+      doc.privateKey = newCert.privateKey;
+      doc.ca = '';
+      doc.validUntil = validUntil || 0;
+      doc.validFrom = validFrom || 0;
+      await doc.save();
+
+      // Clear status so the next event refresh shows the new cert
+      dcRouter.certificateStatusMap.delete(routeDomain);
+    }
+
+    logger.log(
+      'info',
+      `Propagated force-renewed cert for ${forcedDomain} (cert identity '${certIdentity}') to ${affected.size} sibling route domain(s): ${[...affected].join(', ')}`,
+    );
+  }
+
+  /**
+   * Delete certificate data for a domain from storage
+   */
+  private async deleteCertificate(domain: string): Promise<{ success: boolean; message?: string }> {
+    const dcRouter = this.opsServerRef.dcRouterRef;
+    const cleanDomain = domain.replace(/^\*\.?/, '');
+    const parts = cleanDomain.split('.');
+    const baseDomain = parts.length > 2 ? parts.slice(-2).join('.') : cleanDomain;
+
+    // Delete from smartdata document classes (try base domain first, then exact)
+    const acmeDoc = await AcmeCertDoc.findByDomain(baseDomain)
+      || (baseDomain !== cleanDomain ? await AcmeCertDoc.findByDomain(cleanDomain) : null);
+    if (acmeDoc) {
+      await acmeDoc.delete();
+    }
+
+    // Try both original domain and clean domain for proxy certs
+    for (const d of [domain, cleanDomain]) {
+      const proxyDoc = await ProxyCertDoc.findByDomain(d);
+      if (proxyDoc) {
+        await proxyDoc.delete();
+      }
+    }
+
+    // Clear from in-memory status map
+    dcRouter.certificateStatusMap.delete(domain);
+
+    // Clear backoff info
+    if (dcRouter.certProvisionScheduler) {
+      await dcRouter.certProvisionScheduler.clearBackoff(domain);
+    }
+
+    return { success: true, message: `Certificate data deleted for '${domain}'` };
+  }
+
+  /**
+   * Export certificate data for a domain as ICert-shaped JSON
+   */
+  private async exportCertificate(domain: string): Promise<{
+    success: boolean;
+    cert?: {
+      id: string;
+      domainName: string;
+      created: number;
+      validUntil: number;
+      privateKey: string;
+      publicKey: string;
+      csr: string;
+    };
+    message?: string;
+  }> {
+    const cleanDomain = domain.replace(/^\*\.?/, '');
+
+    // Try AcmeCertDoc first (has full ICert fields)
+    const acmeDoc = await AcmeCertDoc.findByDomain(cleanDomain);
+    if (acmeDoc && acmeDoc.publicKey && acmeDoc.privateKey) {
+      return {
+        success: true,
+        cert: {
+          id: acmeDoc.id || plugins.crypto.randomUUID(),
+          domainName: acmeDoc.domainName || domain,
+          created: acmeDoc.created || Date.now(),
+          validUntil: acmeDoc.validUntil || 0,
+          privateKey: acmeDoc.privateKey,
+          publicKey: acmeDoc.publicKey,
+          csr: acmeDoc.csr || '',
+        },
+      };
+    }
+
+    // Fallback: try ProxyCertDoc with original domain, then clean domain
+    let proxyDoc = await ProxyCertDoc.findByDomain(domain);
+    if (!proxyDoc || !proxyDoc.publicKey) {
+      proxyDoc = await ProxyCertDoc.findByDomain(cleanDomain);
+    }
+
+    if (proxyDoc && proxyDoc.publicKey && proxyDoc.privateKey) {
+      return {
+        success: true,
+        cert: {
+          id: plugins.crypto.randomUUID(),
+          domainName: domain,
+          created: proxyDoc.validFrom || Date.now(),
+          validUntil: proxyDoc.validUntil || 0,
+          privateKey: proxyDoc.privateKey,
+          publicKey: proxyDoc.publicKey,
+          csr: '',
+        },
+      };
+    }
+
+    return { success: false, message: `No certificate data found for '${domain}'` };
+  }
+
+  /**
+   * Import a certificate from ICert-shaped JSON
+   */
+  private async importCertificate(cert: {
+    id: string;
+    domainName: string;
+    created: number;
+    validUntil: number;
+    privateKey: string;
+    publicKey: string;
+    csr: string;
+  }): Promise<{ success: boolean; message?: string }> {
+    // Validate PEM content
+    if (!cert.publicKey || !cert.publicKey.includes('-----BEGIN CERTIFICATE-----')) {
+      return { success: false, message: 'Invalid publicKey: must contain a PEM-encoded certificate' };
+    }
+    if (!cert.privateKey || !cert.privateKey.includes('-----BEGIN')) {
+      return { success: false, message: 'Invalid privateKey: must contain a PEM-encoded key' };
+    }
+
+    const dcRouter = this.opsServerRef.dcRouterRef;
+    const cleanDomain = cert.domainName.replace(/^\*\.?/, '');
+
+    // Save to AcmeCertDoc (SmartAcme-compatible)
+    let acmeDoc = await AcmeCertDoc.findByDomain(cleanDomain);
+    if (!acmeDoc) {
+      acmeDoc = new AcmeCertDoc();
+      acmeDoc.domainName = cleanDomain;
+    }
+    acmeDoc.id = cert.id;
+    acmeDoc.created = cert.created;
+    acmeDoc.validUntil = cert.validUntil;
+    acmeDoc.privateKey = cert.privateKey;
+    acmeDoc.publicKey = cert.publicKey;
+    acmeDoc.csr = cert.csr || '';
+    await acmeDoc.save();
+
+    // Also save to ProxyCertDoc (proxy-cert format)
+    let proxyDoc = await ProxyCertDoc.findByDomain(cert.domainName);
+    if (!proxyDoc) {
+      proxyDoc = new ProxyCertDoc();
+      proxyDoc.domain = cert.domainName;
+    }
+    proxyDoc.publicKey = cert.publicKey;
+    proxyDoc.privateKey = cert.privateKey;
+    proxyDoc.ca = '';
+    proxyDoc.validUntil = cert.validUntil;
+    proxyDoc.validFrom = cert.created;
+    await proxyDoc.save();
+
+    // Update in-memory status map
+    dcRouter.certificateStatusMap.set(cert.domainName, {
+      status: 'valid',
+      source: 'static',
+      expiryDate: cert.validUntil ? new Date(cert.validUntil).toISOString() : undefined,
+      issuedAt: cert.created ? new Date(cert.created).toISOString() : undefined,
+      routeNames: [],
+    });
+
+    return { success: true, message: `Certificate imported for '${cert.domainName}'` };
+  }
 }

ts/opsserver/handlers/config.handler.ts

@@ -1,23 +1,23 @@
 import * as plugins from '../../plugins.js';
+import * as paths from '../../paths.js';
 import type { OpsServer } from '../classes.opsserver.js';
 import * as interfaces from '../../../ts_interfaces/index.js';
 
 export class ConfigHandler {
-  public typedrouter = new plugins.typedrequest.TypedRouter();
-
   constructor(private opsServerRef: OpsServer) {
-    // Add this handler's router to the parent
-    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
     this.registerHandlers();
   }
 
   private registerHandlers(): void {
+    // Config endpoint registers directly on viewRouter (valid identity required via middleware)
+    const router = this.opsServerRef.viewRouter;
+
     // Get Configuration Handler (read-only)
-    this.typedrouter.addTypedHandler(
+    router.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetConfiguration>(
         'getConfiguration',
         async (dataArg, toolsArg) => {
-          const config = await this.getConfiguration(dataArg.section);
+          const config = await this.getConfiguration();
           return {
             config,
             section: dataArg.section,
@@ -26,83 +26,197 @@ export class ConfigHandler {
       )
     );
   }
-  
-  private async getConfiguration(section?: string): Promise<{
-    email: {
-      enabled: boolean;
-      ports: number[];
-      maxMessageSize: number;
-      rateLimits: {
-        perMinute: number;
-        perHour: number;
-        perDay: number;
-      };
-      domains?: string[];
-    };
-    dns: {
-      enabled: boolean;
-      port: number;
-      nameservers: string[];
-      caching: boolean;
-      ttl: number;
-    };
-    proxy: {
-      enabled: boolean;
-      httpPort: number;
-      httpsPort: number;
-      maxConnections: number;
-    };
-    security: {
-      blockList: string[];
-      rateLimit: boolean;
-      spamDetection: boolean;
-      tlsRequired: boolean;
-    };
-  }> {
+
+  private async getConfiguration(): Promise<interfaces.requests.IConfigData> {
     const dcRouter = this.opsServerRef.dcRouterRef;
-    
-    // Get email domains if email server is configured
+    const opts = dcRouter.options;
+    const resolvedPaths = dcRouter.resolvedPaths;
+
+    // --- System ---
+    const storageBackend: 'filesystem' | 'custom' | 'memory' = opts.dbConfig?.mongoDbUrl
+      ? 'custom'
+      : 'filesystem';
+
+    // Resolve proxy IPs: fall back to SmartProxy's runtime proxyIPs if not in opts
+    let proxyIps = opts.proxyIps || [];
+    if (proxyIps.length === 0 && dcRouter.smartProxy) {
+      const spSettings = (dcRouter.smartProxy as any).settings;
+      if (spSettings?.proxyIPs?.length > 0) {
+        proxyIps = spSettings.proxyIPs;
+      }
+    }
+
+    const system: interfaces.requests.IConfigData['system'] = {
+      baseDir: resolvedPaths.dcrouterHomeDir,
+      dataDir: resolvedPaths.dataDir,
+      publicIp: opts.publicIp || dcRouter.detectedPublicIp || null,
+      proxyIps,
+      uptime: Math.floor(process.uptime()),
+      storageBackend,
+      storagePath: opts.dbConfig?.storagePath || resolvedPaths.defaultTsmDbPath,
+    };
+
+    // --- SmartProxy ---
+    let acmeInfo: interfaces.requests.IConfigData['smartProxy']['acme'] = null;
+    if (opts.smartProxyConfig?.acme) {
+      const acme = opts.smartProxyConfig.acme;
+      acmeInfo = {
+        enabled: acme.enabled !== false,
+        accountEmail: acme.accountEmail || '',
+        useProduction: acme.useProduction !== false,
+        autoRenew: acme.autoRenew !== false,
+        renewThresholdDays: acme.renewThresholdDays || 30,
+      };
+    }
+
+    let routeCount = 0;
+    if (dcRouter.routeConfigManager) {
+      try {
+        const merged = await dcRouter.routeConfigManager.getMergedRoutes();
+        routeCount = merged.routes.length;
+      } catch {
+        routeCount = opts.smartProxyConfig?.routes?.length || 0;
+      }
+    } else if (opts.smartProxyConfig?.routes) {
+      routeCount = opts.smartProxyConfig.routes.length;
+    }
+
+    const smartProxy: interfaces.requests.IConfigData['smartProxy'] = {
+      enabled: !!dcRouter.smartProxy,
+      routeCount,
+      acme: acmeInfo,
+    };
+
+    // --- Email ---
     let emailDomains: string[] = [];
-    if (dcRouter.emailServer && dcRouter.emailServer.domainRegistry) {
-      emailDomains = dcRouter.emailServer.domainRegistry.getAllDomains();
-    } else if (dcRouter.options.emailConfig?.domains) {
-      // Fallback: get domains from email config options
-      emailDomains = dcRouter.options.emailConfig.domains.map(d => 
+    if (dcRouter.emailServer && (dcRouter.emailServer as any).domainRegistry) {
+      emailDomains = (dcRouter.emailServer as any).domainRegistry.getAllDomains();
+    } else if (opts.emailConfig?.domains) {
+      emailDomains = opts.emailConfig.domains.map((d: any) =>
         typeof d === 'string' ? d : d.domain
       );
     }
-    
+
+    let portMapping: Record<string, number> | null = null;
+    if (opts.emailPortConfig?.portMapping) {
+      portMapping = {};
+      for (const [ext, int] of Object.entries(opts.emailPortConfig.portMapping)) {
+        portMapping[String(ext)] = int as number;
+      }
+    }
+
+    const email: interfaces.requests.IConfigData['email'] = {
+      enabled: !!dcRouter.emailServer,
+      ports: opts.emailConfig?.ports || [],
+      portMapping,
+      hostname: opts.emailConfig?.hostname || null,
+      domains: emailDomains,
+      emailRouteCount: opts.emailConfig?.routes?.length || 0,
+      receivedEmailsPath: opts.emailPortConfig?.receivedEmailsPath || null,
+    };
+
+    // --- DNS ---
+    const dnsRecords = (opts.dnsRecords || []).map(r => ({
+      name: r.name,
+      type: r.type,
+      value: r.value,
+      ttl: r.ttl,
+    }));
+
+    // dnsChallenge: true when at least one DnsProviderDoc exists in the DB
+    // (replaces the legacy `dnsChallenge.cloudflareApiKey` constructor field).
+    let dnsChallengeEnabled = false;
+    try {
+      dnsChallengeEnabled = (await dcRouter.dnsManager?.hasAcmeCapableProvider()) ?? false;
+    } catch {
+      dnsChallengeEnabled = false;
+    }
+
+    const dns: interfaces.requests.IConfigData['dns'] = {
+      enabled: !!dcRouter.dnsServer,
+      port: 53,
+      nsDomains: opts.dnsNsDomains || [],
+      scopes: opts.dnsScopes || [],
+      recordCount: dnsRecords.length,
+      records: dnsRecords,
+      dnsChallenge: dnsChallengeEnabled,
+    };
+
+    // --- TLS ---
+    let tlsSource: 'acme' | 'static' | 'none' = 'none';
+    if (opts.tls?.certPath && opts.tls?.keyPath) {
+      tlsSource = 'static';
+    } else if (opts.smartProxyConfig?.acme?.enabled !== false && opts.smartProxyConfig?.acme) {
+      tlsSource = 'acme';
+    }
+
+    const tls: interfaces.requests.IConfigData['tls'] = {
+      contactEmail: opts.tls?.contactEmail || opts.smartProxyConfig?.acme?.accountEmail || null,
+      domain: opts.tls?.domain || null,
+      source: tlsSource,
+      certPath: opts.tls?.certPath || null,
+      keyPath: opts.tls?.keyPath || null,
+    };
+
+    // --- Database ---
+    const dbConfig = opts.dbConfig;
+    const cache: interfaces.requests.IConfigData['cache'] = {
+      enabled: dbConfig?.enabled !== false,
+      storagePath: dbConfig?.storagePath || resolvedPaths.defaultTsmDbPath,
+      dbName: dbConfig?.dbName || 'dcrouter',
+      defaultTTLDays: 30,
+      cleanupIntervalHours: dbConfig?.cleanupIntervalHours || 1,
+      ttlConfig: {},
+    };
+
+    // --- RADIUS ---
+    const radiusCfg = opts.radiusConfig;
+    const radius: interfaces.requests.IConfigData['radius'] = {
+      enabled: !!dcRouter.radiusServer,
+      authPort: radiusCfg?.authPort || null,
+      acctPort: radiusCfg?.acctPort || null,
+      bindAddress: radiusCfg?.bindAddress || null,
+      clientCount: radiusCfg?.clients?.length || 0,
+      vlanDefaultVlan: radiusCfg?.vlanAssignment?.defaultVlan ?? null,
+      vlanAllowUnknownMacs: radiusCfg?.vlanAssignment?.allowUnknownMacs ?? null,
+      vlanMappingCount: radiusCfg?.vlanAssignment?.mappings?.length || 0,
+    };
+
+    // --- Remote Ingress ---
+    const riCfg = opts.remoteIngressConfig;
+    const connectedEdgeIps = dcRouter.tunnelManager?.getConnectedEdgeIps() || [];
+
+    // Determine TLS mode: custom certs > ACME from cert store > self-signed fallback
+    let tlsMode: 'custom' | 'acme' | 'self-signed' = 'self-signed';
+    if (riCfg?.tls?.certPath && riCfg?.tls?.keyPath) {
+      tlsMode = 'custom';
+    } else if (riCfg?.hubDomain) {
+      try {
+        const { ProxyCertDoc } = await import('../../db/index.js');
+        const stored = await ProxyCertDoc.findByDomain(riCfg.hubDomain);
+        if (stored?.publicKey && stored?.privateKey) {
+          tlsMode = 'acme';
+        }
+      } catch { /* no stored cert */ }
+    }
+
+    const remoteIngress: interfaces.requests.IConfigData['remoteIngress'] = {
+      enabled: !!dcRouter.remoteIngressManager,
+      tunnelPort: riCfg?.tunnelPort || null,
+      hubDomain: riCfg?.hubDomain || null,
+      tlsMode,
+      connectedEdgeIps,
+    };
+
     return {
-      email: {
-        enabled: !!dcRouter.emailServer,
-        ports: dcRouter.emailServer ? [25, 465, 587, 2525] : [],
-        maxMessageSize: 10 * 1024 * 1024, // 10MB default
-        rateLimits: {
-          perMinute: 10,
-          perHour: 100,
-          perDay: 1000,
-        },
-        domains: emailDomains,
-      },
-      dns: {
-        enabled: !!dcRouter.dnsServer,
-        port: 53,
-        nameservers: dcRouter.options.dnsNsDomains || [],
-        caching: true,
-        ttl: 300,
-      },
-      proxy: {
-        enabled: !!dcRouter.smartProxy,
-        httpPort: 80,
-        httpsPort: 443,
-        maxConnections: 1000,
-      },
-      security: {
-        blockList: [],
-        rateLimit: true,
-        spamDetection: true,
-        tlsRequired: false,
-      },
+      system,
+      smartProxy,
+      email,
+      dns,
+      tls,
+      cache,
+      radius,
+      remoteIngress,
     };
   }
-}
+}

ts/opsserver/handlers/dns-provider.handler.ts

@@ -0,0 +1,197 @@
+import * as plugins from '../../plugins.js';
+import type { OpsServer } from '../classes.opsserver.js';
+import * as interfaces from '../../../ts_interfaces/index.js';
+
+/**
+ * CRUD + connection-test handlers for DnsProviderDoc.
+ *
+ * Auth: same dual-mode pattern as TargetProfileHandler — admin JWT or
+ * API token with the appropriate `dns-providers:read|write` scope.
+ */
+export class DnsProviderHandler {
+  public typedrouter = new plugins.typedrequest.TypedRouter();
+
+  constructor(private opsServerRef: OpsServer) {
+    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
+    this.registerHandlers();
+  }
+
+  private async requireAuth(
+    request: { identity?: interfaces.data.IIdentity; apiToken?: string },
+    requiredScope?: interfaces.data.TApiTokenScope,
+  ): Promise<string> {
+    if (request.identity?.jwt) {
+      try {
+        const isAdmin = await this.opsServerRef.adminHandler.adminIdentityGuard.exec({
+          identity: request.identity,
+        });
+        if (isAdmin) return request.identity.userId;
+      } catch { /* fall through */ }
+    }
+
+    if (request.apiToken) {
+      const tokenManager = this.opsServerRef.dcRouterRef.apiTokenManager;
+      if (tokenManager) {
+        const token = await tokenManager.validateToken(request.apiToken);
+        if (token) {
+          if (!requiredScope || tokenManager.hasScope(token, requiredScope)) {
+            return token.createdBy;
+          }
+          throw new plugins.typedrequest.TypedResponseError('insufficient scope');
+        }
+      }
+    }
+
+    throw new plugins.typedrequest.TypedResponseError('unauthorized');
+  }
+
+  private registerHandlers(): void {
+    // Get all providers — prepends the built-in DcRouter pseudo-provider
+    // so operators see a uniform "who serves this?" list that includes the
+    // authoritative dcrouter alongside external accounts.
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetDnsProviders>(
+        'getDnsProviders',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'dns-providers:read');
+          const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
+          const synthetic: interfaces.data.IDnsProviderPublic = {
+            id: interfaces.data.DCROUTER_BUILTIN_PROVIDER_ID,
+            name: 'DcRouter',
+            type: 'dcrouter',
+            status: 'ok',
+            createdAt: 0,
+            updatedAt: 0,
+            createdBy: 'system',
+            hasCredentials: false,
+            builtIn: true,
+          };
+          const real = dnsManager ? await dnsManager.listProviders() : [];
+          return { providers: [synthetic, ...real] };
+        },
+      ),
+    );
+
+    // Get single provider
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetDnsProvider>(
+        'getDnsProvider',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'dns-providers:read');
+          const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
+          if (!dnsManager) return { provider: null };
+          return { provider: await dnsManager.getProvider(dataArg.id) };
+        },
+      ),
+    );
+
+    // Create provider
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_CreateDnsProvider>(
+        'createDnsProvider',
+        async (dataArg) => {
+          const userId = await this.requireAuth(dataArg, 'dns-providers:write');
+          if (dataArg.type === 'dcrouter') {
+            return {
+              success: false,
+              message: 'cannot create built-in provider',
+            };
+          }
+          const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
+          if (!dnsManager) {
+            return { success: false, message: 'DnsManager not initialized (DB disabled?)' };
+          }
+          const id = await dnsManager.createProvider({
+            name: dataArg.name,
+            type: dataArg.type,
+            credentials: dataArg.credentials,
+            createdBy: userId,
+          });
+          return { success: true, id };
+        },
+      ),
+    );
+
+    // Update provider
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_UpdateDnsProvider>(
+        'updateDnsProvider',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'dns-providers:write');
+          if (dataArg.id === interfaces.data.DCROUTER_BUILTIN_PROVIDER_ID) {
+            return { success: false, message: 'cannot edit built-in provider' };
+          }
+          const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
+          if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
+          const ok = await dnsManager.updateProvider(dataArg.id, {
+            name: dataArg.name,
+            credentials: dataArg.credentials,
+          });
+          return ok ? { success: true } : { success: false, message: 'Provider not found' };
+        },
+      ),
+    );
+
+    // Delete provider
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_DeleteDnsProvider>(
+        'deleteDnsProvider',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'dns-providers:write');
+          if (dataArg.id === interfaces.data.DCROUTER_BUILTIN_PROVIDER_ID) {
+            return { success: false, message: 'cannot delete built-in provider' };
+          }
+          const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
+          if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
+          return await dnsManager.deleteProvider(dataArg.id, dataArg.force ?? false);
+        },
+      ),
+    );
+
+    // Test provider connection
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_TestDnsProvider>(
+        'testDnsProvider',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'dns-providers:read');
+          if (dataArg.id === interfaces.data.DCROUTER_BUILTIN_PROVIDER_ID) {
+            return {
+              ok: false,
+              error: 'built-in provider has no external connection to test',
+              testedAt: Date.now(),
+            };
+          }
+          const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
+          if (!dnsManager) {
+            return { ok: false, error: 'DnsManager not initialized', testedAt: Date.now() };
+          }
+          return await dnsManager.testProvider(dataArg.id);
+        },
+      ),
+    );
+
+    // List domains visible to a provider's account (without importing them)
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ListProviderDomains>(
+        'listProviderDomains',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'dns-providers:read');
+          if (dataArg.providerId === interfaces.data.DCROUTER_BUILTIN_PROVIDER_ID) {
+            return {
+              success: false,
+              message: 'built-in provider has no external domain listing — use "Add DcRouter Domain" instead',
+            };
+          }
+          const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
+          if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
+          try {
+            const domains = await dnsManager.listProviderDomains(dataArg.providerId);
+            return { success: true, domains };
+          } catch (err: unknown) {
+            return { success: false, message: (err as Error).message };
+          }
+        },
+      ),
+    );
+  }
+}

ts/opsserver/handlers/dns-record.handler.ts

@@ -0,0 +1,127 @@
+import * as plugins from '../../plugins.js';
+import type { OpsServer } from '../classes.opsserver.js';
+import * as interfaces from '../../../ts_interfaces/index.js';
+
+/**
+ * CRUD handlers for DnsRecordDoc.
+ */
+export class DnsRecordHandler {
+  public typedrouter = new plugins.typedrequest.TypedRouter();
+
+  constructor(private opsServerRef: OpsServer) {
+    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
+    this.registerHandlers();
+  }
+
+  private async requireAuth(
+    request: { identity?: interfaces.data.IIdentity; apiToken?: string },
+    requiredScope?: interfaces.data.TApiTokenScope,
+  ): Promise<string> {
+    if (request.identity?.jwt) {
+      try {
+        const isAdmin = await this.opsServerRef.adminHandler.adminIdentityGuard.exec({
+          identity: request.identity,
+        });
+        if (isAdmin) return request.identity.userId;
+      } catch { /* fall through */ }
+    }
+
+    if (request.apiToken) {
+      const tokenManager = this.opsServerRef.dcRouterRef.apiTokenManager;
+      if (tokenManager) {
+        const token = await tokenManager.validateToken(request.apiToken);
+        if (token) {
+          if (!requiredScope || tokenManager.hasScope(token, requiredScope)) {
+            return token.createdBy;
+          }
+          throw new plugins.typedrequest.TypedResponseError('insufficient scope');
+        }
+      }
+    }
+
+    throw new plugins.typedrequest.TypedResponseError('unauthorized');
+  }
+
+  private registerHandlers(): void {
+    // Get records by domain
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetDnsRecords>(
+        'getDnsRecords',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'dns-records:read');
+          const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
+          if (!dnsManager) return { records: [] };
+          const docs = await dnsManager.listRecordsForDomain(dataArg.domainId);
+          return { records: docs.map((d) => dnsManager.toPublicRecord(d)) };
+        },
+      ),
+    );
+
+    // Get single record
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetDnsRecord>(
+        'getDnsRecord',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'dns-records:read');
+          const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
+          if (!dnsManager) return { record: null };
+          const doc = await dnsManager.getRecord(dataArg.id);
+          return { record: doc ? dnsManager.toPublicRecord(doc) : null };
+        },
+      ),
+    );
+
+    // Create record
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_CreateDnsRecord>(
+        'createDnsRecord',
+        async (dataArg) => {
+          const userId = await this.requireAuth(dataArg, 'dns-records:write');
+          const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
+          if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
+          return await dnsManager.createRecord({
+            domainId: dataArg.domainId,
+            name: dataArg.name,
+            type: dataArg.type,
+            value: dataArg.value,
+            ttl: dataArg.ttl,
+            proxied: dataArg.proxied,
+            createdBy: userId,
+          });
+        },
+      ),
+    );
+
+    // Update record
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_UpdateDnsRecord>(
+        'updateDnsRecord',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'dns-records:write');
+          const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
+          if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
+          return await dnsManager.updateRecord({
+            id: dataArg.id,
+            name: dataArg.name,
+            value: dataArg.value,
+            ttl: dataArg.ttl,
+            proxied: dataArg.proxied,
+          });
+        },
+      ),
+    );
+
+    // Delete record
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_DeleteDnsRecord>(
+        'deleteDnsRecord',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'dns-records:write');
+          const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
+          if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
+          return await dnsManager.deleteRecord(dataArg.id);
+        },
+      ),
+    );
+  }
+}

ts/opsserver/handlers/domain.handler.ts

@@ -0,0 +1,161 @@
+import * as plugins from '../../plugins.js';
+import type { OpsServer } from '../classes.opsserver.js';
+import * as interfaces from '../../../ts_interfaces/index.js';
+
+/**
+ * CRUD handlers for DomainDoc.
+ */
+export class DomainHandler {
+  public typedrouter = new plugins.typedrequest.TypedRouter();
+
+  constructor(private opsServerRef: OpsServer) {
+    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
+    this.registerHandlers();
+  }
+
+  private async requireAuth(
+    request: { identity?: interfaces.data.IIdentity; apiToken?: string },
+    requiredScope?: interfaces.data.TApiTokenScope,
+  ): Promise<string> {
+    if (request.identity?.jwt) {
+      try {
+        const isAdmin = await this.opsServerRef.adminHandler.adminIdentityGuard.exec({
+          identity: request.identity,
+        });
+        if (isAdmin) return request.identity.userId;
+      } catch { /* fall through */ }
+    }
+
+    if (request.apiToken) {
+      const tokenManager = this.opsServerRef.dcRouterRef.apiTokenManager;
+      if (tokenManager) {
+        const token = await tokenManager.validateToken(request.apiToken);
+        if (token) {
+          if (!requiredScope || tokenManager.hasScope(token, requiredScope)) {
+            return token.createdBy;
+          }
+          throw new plugins.typedrequest.TypedResponseError('insufficient scope');
+        }
+      }
+    }
+
+    throw new plugins.typedrequest.TypedResponseError('unauthorized');
+  }
+
+  private registerHandlers(): void {
+    // Get all domains
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetDomains>(
+        'getDomains',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'domains:read');
+          const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
+          if (!dnsManager) return { domains: [] };
+          const docs = await dnsManager.listDomains();
+          return { domains: docs.map((d) => dnsManager.toPublicDomain(d)) };
+        },
+      ),
+    );
+
+    // Get single domain
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetDomain>(
+        'getDomain',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'domains:read');
+          const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
+          if (!dnsManager) return { domain: null };
+          const doc = await dnsManager.getDomain(dataArg.id);
+          return { domain: doc ? dnsManager.toPublicDomain(doc) : null };
+        },
+      ),
+    );
+
+    // Create dcrouter-hosted domain
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_CreateDomain>(
+        'createDomain',
+        async (dataArg) => {
+          const userId = await this.requireAuth(dataArg, 'domains:write');
+          const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
+          if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
+          try {
+            const id = await dnsManager.createDcrouterDomain({
+              name: dataArg.name,
+              description: dataArg.description,
+              createdBy: userId,
+            });
+            return { success: true, id };
+          } catch (err: unknown) {
+            return { success: false, message: (err as Error).message };
+          }
+        },
+      ),
+    );
+
+    // Import domains from a provider
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ImportDomain>(
+        'importDomain',
+        async (dataArg) => {
+          const userId = await this.requireAuth(dataArg, 'domains:write');
+          const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
+          if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
+          try {
+            const importedIds = await dnsManager.importDomainsFromProvider({
+              providerId: dataArg.providerId,
+              domainNames: dataArg.domainNames,
+              createdBy: userId,
+            });
+            return { success: true, importedIds };
+          } catch (err: unknown) {
+            return { success: false, message: (err as Error).message };
+          }
+        },
+      ),
+    );
+
+    // Update domain metadata
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_UpdateDomain>(
+        'updateDomain',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'domains:write');
+          const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
+          if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
+          const ok = await dnsManager.updateDomain(dataArg.id, {
+            description: dataArg.description,
+          });
+          return ok ? { success: true } : { success: false, message: 'Domain not found' };
+        },
+      ),
+    );
+
+    // Delete domain
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_DeleteDomain>(
+        'deleteDomain',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'domains:write');
+          const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
+          if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
+          const ok = await dnsManager.deleteDomain(dataArg.id);
+          return ok ? { success: true } : { success: false, message: 'Domain not found' };
+        },
+      ),
+    );
+
+    // Force-resync provider domain
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_SyncDomain>(
+        'syncDomain',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'domains:write');
+          const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
+          if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
+          return await dnsManager.syncDomain(dataArg.id);
+        },
+      ),
+    );
+  }
+}

ts/opsserver/handlers/email-ops.handler.ts

@@ -1,86 +1,44 @@
 import * as plugins from '../../plugins.js';
 import type { OpsServer } from '../classes.opsserver.js';
 import * as interfaces from '../../../ts_interfaces/index.js';
-import { SecurityLogger } from '../../security/index.js';
 
 export class EmailOpsHandler {
-  public typedrouter = new plugins.typedrequest.TypedRouter();
-
   constructor(private opsServerRef: OpsServer) {
-    // Add this handler's router to the parent
-    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
     this.registerHandlers();
   }
 
   private registerHandlers(): void {
-    // Get Queued Emails Handler
-    this.typedrouter.addTypedHandler(
-      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetQueuedEmails>(
-        'getQueuedEmails',
+    const viewRouter = this.opsServerRef.viewRouter;
+    const adminRouter = this.opsServerRef.adminRouter;
+
+    // ---- Read endpoints (viewRouter — valid identity required via middleware) ----
+
+    // Get All Emails Handler
+    viewRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetAllEmails>(
+        'getAllEmails',
         async (dataArg) => {
-          const emailServer = this.opsServerRef.dcRouterRef.emailServer;
-          if (!emailServer?.deliveryQueue) {
-            return { items: [], total: 0 };
-          }
-
-          const queue = emailServer.deliveryQueue;
-          const stats = queue.getStats();
-
-          // Get all queue items and filter by status if provided
-          const items = this.getQueueItems(
-            dataArg.status,
-            dataArg.limit || 50,
-            dataArg.offset || 0
-          );
-
-          return {
-            items,
-            total: stats.queueSize,
-          };
+          const emails = this.getAllQueueEmails();
+          return { emails };
         }
       )
     );
 
-    // Get Sent Emails Handler
-    this.typedrouter.addTypedHandler(
-      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetSentEmails>(
-        'getSentEmails',
+    // Get Email Detail Handler
+    viewRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetEmailDetail>(
+        'getEmailDetail',
         async (dataArg) => {
-          const items = this.getQueueItems(
-            'delivered',
-            dataArg.limit || 50,
-            dataArg.offset || 0
-          );
-
-          return {
-            items,
-            total: items.length, // Note: total would ideally come from a counter
-          };
+          const email = this.getEmailDetail(dataArg.emailId);
+          return { email };
         }
       )
     );
 
-    // Get Failed Emails Handler
-    this.typedrouter.addTypedHandler(
-      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetFailedEmails>(
-        'getFailedEmails',
-        async (dataArg) => {
-          const items = this.getQueueItems(
-            'failed',
-            dataArg.limit || 50,
-            dataArg.offset || 0
-          );
-
-          return {
-            items,
-            total: items.length,
-          };
-        }
-      )
-    );
+    // ---- Write endpoints (adminRouter) ----
 
     // Resend Failed Email Handler
-    this.typedrouter.addTypedHandler(
+    adminRouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ResendEmail>(
         'resendEmail',
         async (dataArg) => {
@@ -101,17 +59,12 @@ export class EmailOpsHandler {
           }
 
           try {
-            // Re-enqueue the failed email by creating a new queue entry
-            // with the same data but reset attempt count
             const newQueueId = await queue.enqueue(
               item.processingResult,
               item.processingMode,
               item.route
             );
-
-            // Optionally remove the old failed entry
             await queue.removeItem(dataArg.emailId);
-
             return { success: true, newQueueId };
           } catch (error) {
             return {
@@ -122,197 +75,199 @@ export class EmailOpsHandler {
         }
       )
     );
-
-    // Get Security Incidents Handler
-    this.typedrouter.addTypedHandler(
-      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetSecurityIncidents>(
-        'getSecurityIncidents',
-        async (dataArg) => {
-          const securityLogger = SecurityLogger.getInstance();
-
-          const filter: {
-            level?: any;
-            type?: any;
-          } = {};
-
-          if (dataArg.level) {
-            filter.level = dataArg.level;
-          }
-
-          if (dataArg.type) {
-            filter.type = dataArg.type;
-          }
-
-          const incidents = securityLogger.getRecentEvents(
-            dataArg.limit || 100,
-            Object.keys(filter).length > 0 ? filter : undefined
-          );
-
-          return {
-            incidents: incidents.map(event => ({
-              timestamp: event.timestamp,
-              level: event.level as interfaces.requests.TSecurityLogLevel,
-              type: event.type as interfaces.requests.TSecurityEventType,
-              message: event.message,
-              details: event.details,
-              ipAddress: event.ipAddress,
-              userId: event.userId,
-              sessionId: event.sessionId,
-              emailId: event.emailId,
-              domain: event.domain,
-              action: event.action,
-              result: event.result,
-              success: event.success,
-            })),
-            total: incidents.length,
-          };
-        }
-      )
-    );
-
-    // Get Bounce Records Handler
-    this.typedrouter.addTypedHandler(
-      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetBounceRecords>(
-        'getBounceRecords',
-        async (dataArg) => {
-          const emailServer = this.opsServerRef.dcRouterRef.emailServer;
-
-          if (!emailServer) {
-            return { records: [], suppressionList: [], total: 0 };
-          }
-
-          // Use smartmta's public API for bounce/suppression data
-          const suppressionList = emailServer.getSuppressionList();
-          const hardBouncedAddresses = emailServer.getHardBouncedAddresses();
-
-          // Create bounce records from the available data
-          const records: interfaces.requests.IBounceRecord[] = [];
-
-          for (const email of hardBouncedAddresses) {
-            const bounceInfo = emailServer.getBounceHistory(email);
-            if (bounceInfo) {
-              records.push({
-                id: `bounce-${email}`,
-                recipient: email,
-                sender: '',
-                domain: email.split('@')[1] || '',
-                bounceType: (bounceInfo as any).type as interfaces.requests.TBounceType,
-                bounceCategory: (bounceInfo as any).category as interfaces.requests.TBounceCategory,
-                timestamp: (bounceInfo as any).lastBounce,
-                processed: true,
-              });
-            }
-          }
-
-          // Apply limit and offset
-          const limit = dataArg.limit || 50;
-          const offset = dataArg.offset || 0;
-          const paginatedRecords = records.slice(offset, offset + limit);
-
-          return {
-            records: paginatedRecords,
-            suppressionList,
-            total: records.length,
-          };
-        }
-      )
-    );
-
-    // Remove from Suppression List Handler
-    this.typedrouter.addTypedHandler(
-      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_RemoveFromSuppressionList>(
-        'removeFromSuppressionList',
-        async (dataArg) => {
-          const emailServer = this.opsServerRef.dcRouterRef.emailServer;
-
-          if (!emailServer) {
-            return { success: false, error: 'Email server not available' };
-          }
-
-          try {
-            emailServer.removeFromSuppressionList(dataArg.email);
-            return { success: true };
-          } catch (error) {
-            return {
-              success: false,
-              error: error instanceof Error ? error.message : 'Failed to remove from suppression list'
-            };
-          }
-        }
-      )
-    );
   }
 
   /**
-   * Helper method to get queue items with filtering and pagination
+   * Get all queue items mapped to catalog IEmail format
    */
-  private getQueueItems(
-    status?: interfaces.requests.TEmailQueueStatus,
-    limit: number = 50,
-    offset: number = 0
-  ): interfaces.requests.IEmailQueueItem[] {
+  private getAllQueueEmails(): interfaces.requests.IEmail[] {
     const emailServer = this.opsServerRef.dcRouterRef.emailServer;
     if (!emailServer?.deliveryQueue) {
       return [];
     }
 
     const queue = emailServer.deliveryQueue;
-    const items: interfaces.requests.IEmailQueueItem[] = [];
-
-    // Access the internal queue map via reflection
-    // This is necessary because the queue doesn't expose iteration methods
     const queueMap = (queue as any).queue as Map<string, any>;
 
     if (!queueMap) {
       return [];
     }
 
-    // Filter and convert items
+    const emails: interfaces.requests.IEmail[] = [];
+
     for (const [id, item] of queueMap.entries()) {
-      // Apply status filter if provided
-      if (status && item.status !== status) {
-        continue;
-      }
-
-      // Extract email details from processingResult if available
-      const processingResult = item.processingResult;
-      let from = '';
-      let to: string[] = [];
-      let subject = '';
-
-      if (processingResult) {
-        // Check if it's an Email object or raw email data
-        if (processingResult.email) {
-          from = processingResult.email.from || '';
-          to = processingResult.email.to || [];
-          subject = processingResult.email.subject || '';
-        } else if (processingResult.from) {
-          from = processingResult.from;
-          to = processingResult.to || [];
-          subject = processingResult.subject || '';
-        }
-      }
-
-      items.push({
-        id: item.id,
-        processingMode: item.processingMode,
-        status: item.status,
-        attempts: item.attempts,
-        nextAttempt: item.nextAttempt instanceof Date ? item.nextAttempt.getTime() : item.nextAttempt,
-        lastError: item.lastError,
-        createdAt: item.createdAt instanceof Date ? item.createdAt.getTime() : item.createdAt,
-        updatedAt: item.updatedAt instanceof Date ? item.updatedAt.getTime() : item.updatedAt,
-        deliveredAt: item.deliveredAt instanceof Date ? item.deliveredAt.getTime() : item.deliveredAt,
-        from,
-        to,
-        subject,
-      });
+      emails.push(this.mapQueueItemToEmail(item));
     }
 
     // Sort by createdAt descending (newest first)
-    items.sort((a, b) => b.createdAt - a.createdAt);
+    emails.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
 
-    // Apply pagination
-    return items.slice(offset, offset + limit);
+    return emails;
+  }
+
+  /**
+   * Get a single email detail by ID
+   */
+  private getEmailDetail(emailId: string): interfaces.requests.IEmailDetail | null {
+    const emailServer = this.opsServerRef.dcRouterRef.emailServer;
+    if (!emailServer?.deliveryQueue) {
+      return null;
+    }
+
+    const queue = emailServer.deliveryQueue;
+    const item = queue.getItem(emailId);
+
+    if (!item) {
+      return null;
+    }
+
+    return this.mapQueueItemToEmailDetail(item);
+  }
+
+  /**
+   * Map a queue item to catalog IEmail format
+   */
+  private mapQueueItemToEmail(item: any): interfaces.requests.IEmail {
+    const processingResult = item.processingResult;
+    let from = '';
+    let to = '';
+    let subject = '';
+    let messageId = '';
+    let size = '0 B';
+
+    if (processingResult) {
+      if (processingResult.email) {
+        from = processingResult.email.from || '';
+        to = (processingResult.email.to || [])[0] || '';
+        subject = processingResult.email.subject || '';
+      } else if (processingResult.from) {
+        from = processingResult.from;
+        to = (processingResult.to || [])[0] || '';
+        subject = processingResult.subject || '';
+      }
+
+      // Try to get messageId
+      if (typeof processingResult.getMessageId === 'function') {
+        try {
+          messageId = processingResult.getMessageId() || '';
+        } catch {
+          messageId = '';
+        }
+      }
+
+      // Compute approximate size
+      const textLen = processingResult.text?.length || 0;
+      const htmlLen = processingResult.html?.length || 0;
+      let attachSize = 0;
+      if (typeof processingResult.getAttachmentsSize === 'function') {
+        try {
+          attachSize = processingResult.getAttachmentsSize() || 0;
+        } catch {
+          attachSize = 0;
+        }
+      }
+      size = this.formatSize(textLen + htmlLen + attachSize);
+    }
+
+    // Map queue status to catalog TEmailStatus
+    const status = this.mapStatus(item.status);
+
+    const createdAt = item.createdAt instanceof Date ? item.createdAt.getTime() : item.createdAt;
+
+    return {
+      id: item.id,
+      direction: 'outbound' as interfaces.requests.TEmailDirection,
+      status,
+      from,
+      to,
+      subject,
+      timestamp: new Date(createdAt).toISOString(),
+      messageId,
+      size,
+    };
+  }
+
+  /**
+   * Map a queue item to catalog IEmailDetail format
+   */
+  private mapQueueItemToEmailDetail(item: any): interfaces.requests.IEmailDetail {
+    const base = this.mapQueueItemToEmail(item);
+    const processingResult = item.processingResult;
+
+    let toList: string[] = [];
+    let cc: string[] = [];
+    let headers: Record<string, string> = {};
+    let body = '';
+
+    if (processingResult) {
+      if (processingResult.email) {
+        toList = processingResult.email.to || [];
+        cc = processingResult.email.cc || [];
+      } else {
+        toList = processingResult.to || [];
+        cc = processingResult.cc || [];
+      }
+
+      headers = processingResult.headers || {};
+      body = processingResult.html || processingResult.text || '';
+    }
+
+    return {
+      ...base,
+      toList,
+      cc,
+      smtpLog: [],
+      connectionInfo: {
+        sourceIp: '',
+        sourceHostname: '',
+        destinationIp: '',
+        destinationPort: 0,
+        tlsVersion: '',
+        tlsCipher: '',
+        authenticated: false,
+        authMethod: '',
+        authUser: '',
+      },
+      authenticationResults: {
+        spf: 'none',
+        spfDomain: '',
+        dkim: 'none',
+        dkimDomain: '',
+        dmarc: 'none',
+        dmarcPolicy: '',
+      },
+      rejectionReason: item.status === 'failed' ? item.lastError : undefined,
+      bounceMessage: item.status === 'failed' ? item.lastError : undefined,
+      headers,
+      body,
+    };
+  }
+
+  /**
+   * Map queue status to catalog TEmailStatus
+   */
+  private mapStatus(queueStatus: string): interfaces.requests.TEmailStatus {
+    switch (queueStatus) {
+      case 'pending':
+      case 'processing':
+        return 'pending';
+      case 'delivered':
+        return 'delivered';
+      case 'failed':
+        return 'bounced';
+      case 'deferred':
+        return 'deferred';
+      default:
+        return 'pending';
+    }
+  }
+
+  /**
+   * Format byte size to human-readable string
+   */
+  private formatSize(bytes: number): string {
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
   }
 }

ts/opsserver/handlers/index.ts

@@ -5,4 +5,16 @@ export * from './security.handler.js';
 export * from './stats.handler.js';
 export * from './radius.handler.js';
 export * from './email-ops.handler.js';
-export * from './certificate.handler.js';
+export * from './certificate.handler.js';
+export * from './remoteingress.handler.js';
+export * from './route-management.handler.js';
+export * from './api-token.handler.js';
+export * from './vpn.handler.js';
+export * from './source-profile.handler.js';
+export * from './target-profile.handler.js';
+export * from './network-target.handler.js';
+export * from './users.handler.js';
+export * from './dns-provider.handler.js';
+export * from './domain.handler.js';
+export * from './dns-record.handler.js';
+export * from './acme-config.handler.js';

ts/opsserver/handlers/logs.handler.ts

@@ -1,19 +1,42 @@
 import * as plugins from '../../plugins.js';
 import type { OpsServer } from '../classes.opsserver.js';
 import * as interfaces from '../../../ts_interfaces/index.js';
+import { logBuffer, baseLogger } from '../../logger.js';
+
+// Module-level singleton: the log push destination is added once and reuses
+// the current OpsServer reference so it survives OpsServer restarts without
+// accumulating duplicate destinations.
+let logPushDestinationInstalled = false;
+let currentOpsServerRef: OpsServer | null = null;
 
 export class LogsHandler {
-  public typedrouter = new plugins.typedrequest.TypedRouter();
-  
+  private activeStreamStops: Set<() => void> = new Set();
+
   constructor(private opsServerRef: OpsServer) {
-    // Add this handler's router to the parent
-    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
     this.registerHandlers();
+    this.setupLogPushDestination();
   }
-  
+
+  /**
+   * Clean up all active log streams and deactivate the push destination.
+   * Called when OpsServer stops.
+   */
+  public cleanup(): void {
+    // Stop all active follow-mode log streams
+    for (const stop of this.activeStreamStops) {
+      stop();
+    }
+    this.activeStreamStops.clear();
+    // Deactivate the push destination (it stays registered but becomes a no-op)
+    currentOpsServerRef = null;
+  }
+
   private registerHandlers(): void {
+    // All log endpoints register directly on viewRouter (valid identity required via middleware)
+    const router = this.opsServerRef.viewRouter;
+
     // Get Recent Logs Handler
-    this.typedrouter.addTypedHandler(
+    router.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetRecentLogs>(
         'getRecentLogs',
         async (dataArg, toolsArg) => {
@@ -25,24 +48,24 @@ export class LogsHandler {
             dataArg.search,
             dataArg.timeRange
           );
-          
+
           return {
             logs,
-            total: logs.length, // TODO: Implement proper total count
-            hasMore: false, // TODO: Implement proper pagination
+            total: logs.length,
+            hasMore: false,
           };
         }
       )
     );
-    
+
     // Get Log Stream Handler
-    this.typedrouter.addTypedHandler(
+    router.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetLogStream>(
         'getLogStream',
         async (dataArg, toolsArg) => {
           // Create a virtual stream for log streaming
           const virtualStream = new plugins.typedrequest.VirtualStream<Uint8Array>();
-          
+
           // Set up log streaming
           const streamLogs = this.setupLogStream(
             virtualStream,
@@ -50,20 +73,47 @@ export class LogsHandler {
             dataArg.filters?.category,
             dataArg.follow
           );
-          
+
           // Start streaming
           streamLogs.start();
-          
-          // VirtualStream handles cleanup automatically
-          
+
+          // Track the stop function so we can clean up on shutdown
+          this.activeStreamStops.add(streamLogs.stop);
+
           return {
-            logStream: virtualStream as any, // Cast to IVirtualStream interface
+            logStream: virtualStream as any,
           };
         }
       )
     );
   }
-  
+
+  private static mapLogLevel(smartlogLevel: string): 'debug' | 'info' | 'warn' | 'error' {
+    switch (smartlogLevel) {
+      case 'silly':
+      case 'debug':
+        return 'debug';
+      case 'warn':
+        return 'warn';
+      case 'error':
+        return 'error';
+      default:
+        return 'info';
+    }
+  }
+
+  private static deriveCategory(
+    zone?: string,
+    message?: string
+  ): 'smtp' | 'dns' | 'security' | 'system' | 'email' {
+    const msg = (message || '').toLowerCase();
+    if (msg.includes('[security:') || msg.includes('security')) return 'security';
+    if (zone === 'email' || msg.includes('email') || msg.includes('smtp') || msg.includes('mta')) return 'email';
+    if (zone === 'dns' || msg.includes('dns')) return 'dns';
+    if (msg.includes('smtp')) return 'smtp';
+    return 'system';
+  }
+
   private async getRecentLogs(
     level?: 'error' | 'warn' | 'info' | 'debug',
     category?: 'smtp' | 'dns' | 'security' | 'system' | 'email',
@@ -78,44 +128,122 @@ export class LogsHandler {
     message: string;
     metadata?: any;
   }>> {
-    // TODO: Implement actual log retrieval from storage or logger
-    // For now, return mock data
-    const mockLogs: Array<{
+    // Compute a timestamp cutoff from timeRange
+    let since: number | undefined;
+    if (timeRange) {
+      const rangeMs: Record<string, number> = {
+        '1h': 3600000,
+        '6h': 21600000,
+        '24h': 86400000,
+        '7d': 604800000,
+        '30d': 2592000000,
+      };
+      since = Date.now() - (rangeMs[timeRange] || 86400000);
+    }
+
+    // Map the UI level to smartlog levels for filtering
+    const smartlogLevels: string[] | undefined = level
+      ? level === 'debug'
+        ? ['debug', 'silly']
+        : level === 'info'
+          ? ['info', 'ok', 'success', 'note', 'lifecycle']
+          : [level]
+      : undefined;
+
+    // Fetch a larger batch from buffer, then apply category filter client-side
+    const rawEntries = logBuffer.getEntries({
+      level: smartlogLevels as any,
+      search,
+      since,
+      limit: limit * 3, // over-fetch to compensate for category filtering
+      offset: 0,
+    });
+
+    // Map ILogPackage → UI log format and apply category filter
+    const mapped: Array<{
       timestamp: number;
       level: 'debug' | 'info' | 'warn' | 'error';
       category: 'smtp' | 'dns' | 'security' | 'system' | 'email';
       message: string;
       metadata?: any;
     }> = [];
-    
-    const categories: Array<'smtp' | 'dns' | 'security' | 'system' | 'email'> = ['smtp', 'dns', 'security', 'system', 'email'];
-    const levels: Array<'debug' | 'info' | 'warn' | 'error'> = ['info', 'warn', 'error', 'debug'];
-    const now = Date.now();
-    
-    // Generate some mock log entries
-    for (let i = 0; i < 50; i++) {
-      const mockCategory = categories[Math.floor(Math.random() * categories.length)];
-      const mockLevel = levels[Math.floor(Math.random() * levels.length)];
-      
-      // Filter by requested criteria
-      if (level && mockLevel !== level) continue;
-      if (category && mockCategory !== category) continue;
-      
-      mockLogs.push({
-        timestamp: now - (i * 60000), // 1 minute apart
-        level: mockLevel,
-        category: mockCategory,
-        message: `Sample log message ${i} from ${mockCategory}`,
-        metadata: {
-          requestId: plugins.uuid.v4(),
-        },
+
+    for (const pkg of rawEntries) {
+      const uiLevel = LogsHandler.mapLogLevel(pkg.level);
+      const uiCategory = LogsHandler.deriveCategory(pkg.context?.zone, pkg.message);
+
+      if (category && uiCategory !== category) continue;
+
+      mapped.push({
+        timestamp: pkg.timestamp,
+        level: uiLevel,
+        category: uiCategory,
+        message: pkg.message,
+        metadata: pkg.data,
       });
+
+      if (mapped.length >= limit) break;
     }
-    
-    // Apply pagination
-    return mockLogs.slice(offset, offset + limit);
+
+    return mapped;
   }
-  
+
+  /**
+   * Add a log destination to the base logger that pushes entries
+   * to all connected ops_dashboard TypedSocket clients.
+   *
+   * Uses a module-level singleton so the destination is added only once,
+   * even across OpsServer restart cycles. The destination reads
+   * `currentOpsServerRef` dynamically so it always uses the active server.
+   */
+  private setupLogPushDestination(): void {
+    // Update the module-level reference so the existing destination uses the new server
+    currentOpsServerRef = this.opsServerRef;
+
+    if (logPushDestinationInstalled) {
+      return; // destination already registered — just updated the ref
+    }
+    logPushDestinationInstalled = true;
+
+    baseLogger.addLogDestination({
+      async handleLog(logPackage: any) {
+        const opsServer = currentOpsServerRef;
+        if (!opsServer) return;
+
+        const typedsocket = opsServer.server?.typedserver?.typedsocket;
+        if (!typedsocket) return;
+
+        let connections: any[];
+        try {
+          connections = await typedsocket.findAllTargetConnectionsByTag('role', 'ops_dashboard');
+        } catch {
+          return;
+        }
+        if (connections.length === 0) return;
+
+        const entry: interfaces.data.ILogEntry = {
+          timestamp: logPackage.timestamp || Date.now(),
+          level: LogsHandler.mapLogLevel(logPackage.level),
+          category: LogsHandler.deriveCategory(logPackage.context?.zone, logPackage.message),
+          message: logPackage.message,
+          metadata: logPackage.data,
+        };
+
+        for (const conn of connections) {
+          try {
+            const push = typedsocket.createTypedRequest<interfaces.requests.IReq_PushLogEntry>(
+              'pushLogEntry',
+              conn,
+            );
+            push.fire({ entry }).catch(() => {}); // fire-and-forget
+          } catch {
+            // connection may have closed
+          }
+        }
+      },
+    });
+  }
+
   private setupLogStream(
     virtualStream: plugins.typedrequest.VirtualStream<Uint8Array>,
     levelFilter?: string[],
@@ -126,8 +254,18 @@ export class LogsHandler {
     stop: () => void;
   } {
     let intervalId: NodeJS.Timeout | null = null;
-    let logIndex = 0;
-    
+    let stopped = false;
+    let lastTimestamp = Date.now();
+
+    const stop = () => {
+      stopped = true;
+      if (intervalId) {
+        clearInterval(intervalId);
+        intervalId = null;
+      }
+      this.activeStreamStops.delete(stop);
+    };
+
     const start = () => {
       if (!follow) {
         // Send existing logs and close
@@ -142,54 +280,73 @@ export class LogsHandler {
             const encoder = new TextEncoder();
             virtualStream.sendData(encoder.encode(logData));
           });
-          // VirtualStream doesn't have end() method - it closes automatically
         });
         return;
       }
-      
-      // For follow mode, simulate real-time log streaming
-      intervalId = setInterval(() => {
-        const categories: Array<'smtp' | 'dns' | 'security' | 'system' | 'email'> = ['smtp', 'dns', 'security', 'system', 'email'];
-        const levels: Array<'debug' | 'info' | 'warn' | 'error'> = ['info', 'warn', 'error', 'debug'];
-        
-        const mockCategory = categories[Math.floor(Math.random() * categories.length)];
-        const mockLevel = levels[Math.floor(Math.random() * levels.length)];
-        
-        // Filter by requested criteria
-        if (levelFilter && !levelFilter.includes(mockLevel)) return;
-        if (categoryFilter && !categoryFilter.includes(mockCategory)) return;
-        
-        const logEntry = {
-          timestamp: Date.now(),
-          level: mockLevel,
-          category: mockCategory,
-          message: `Real-time log ${logIndex++} from ${mockCategory}`,
-          metadata: {
-            requestId: plugins.uuid.v4(),
-          },
-        };
-        
-        const logData = JSON.stringify(logEntry);
-        const encoder = new TextEncoder();
-        virtualStream.sendData(encoder.encode(logData));
-      }, 2000); // Send a log every 2 seconds
-      
-      // TODO: Hook into actual logger events
-      // logger.on('log', (logEntry) => {
-      //   if (matchesCriteria(logEntry, level, service)) {
-      //     virtualStream.sendData(formatLogEntry(logEntry));
-      //   }
-      // });
+
+      // For follow mode, tail real log entries from the in-memory buffer
+      intervalId = setInterval(async () => {
+        if (stopped) {
+          clearInterval(intervalId!);
+          intervalId = null;
+          return;
+        }
+
+        // Fetch new entries since last poll
+        const rawEntries = logBuffer.getEntries({
+          since: lastTimestamp,
+          limit: 50,
+        });
+
+        if (rawEntries.length === 0) return;
+
+        for (const raw of rawEntries) {
+          const mappedLevel = LogsHandler.mapLogLevel(raw.level);
+          const mappedCategory = LogsHandler.deriveCategory(
+            (raw as any).context?.zone,
+            raw.message,
+          );
+
+          // Apply filters
+          if (levelFilter && !levelFilter.includes(mappedLevel)) continue;
+          if (categoryFilter && !categoryFilter.includes(mappedCategory)) continue;
+
+          const logEntry = {
+            timestamp: raw.timestamp || Date.now(),
+            level: mappedLevel,
+            category: mappedCategory,
+            message: raw.message,
+            metadata: (raw as any).data,
+          };
+
+          const logData = JSON.stringify(logEntry);
+          const encoder = new TextEncoder();
+          try {
+            let timeoutHandle: ReturnType<typeof setTimeout>;
+            await Promise.race([
+              virtualStream.sendData(encoder.encode(logData)).then((result) => {
+                clearTimeout(timeoutHandle);
+                return result;
+              }),
+              new Promise<never>((_, reject) => {
+                timeoutHandle = setTimeout(() => reject(new Error('stream send timeout')), 10_000);
+              }),
+            ]);
+          } catch {
+            // Stream closed, errored, or timed out — clean up
+            stop();
+            return;
+          }
+        }
+
+        // Advance the watermark past all entries we just processed
+        const newest = rawEntries[rawEntries.length - 1];
+        if (newest.timestamp && newest.timestamp >= lastTimestamp) {
+          lastTimestamp = newest.timestamp + 1;
+        }
+      }, 2000);
     };
-    
-    const stop = () => {
-      if (intervalId) {
-        clearInterval(intervalId);
-        intervalId = null;
-      }
-      // TODO: Unhook from logger events
-    };
-    
+
     return { start, stop };
   }
-}
+}

ts/opsserver/handlers/network-target.handler.ts

@@ -0,0 +1,167 @@
+import * as plugins from '../../plugins.js';
+import type { OpsServer } from '../classes.opsserver.js';
+import * as interfaces from '../../../ts_interfaces/index.js';
+
+export class NetworkTargetHandler {
+  public typedrouter = new plugins.typedrequest.TypedRouter();
+
+  constructor(private opsServerRef: OpsServer) {
+    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
+    this.registerHandlers();
+  }
+
+  private async requireAuth(
+    request: { identity?: interfaces.data.IIdentity; apiToken?: string },
+    requiredScope?: interfaces.data.TApiTokenScope,
+  ): Promise<string> {
+    if (request.identity?.jwt) {
+      try {
+        const isAdmin = await this.opsServerRef.adminHandler.adminIdentityGuard.exec({
+          identity: request.identity,
+        });
+        if (isAdmin) return request.identity.userId;
+      } catch { /* fall through */ }
+    }
+
+    if (request.apiToken) {
+      const tokenManager = this.opsServerRef.dcRouterRef.apiTokenManager;
+      if (tokenManager) {
+        const token = await tokenManager.validateToken(request.apiToken);
+        if (token) {
+          if (!requiredScope || tokenManager.hasScope(token, requiredScope)) {
+            return token.createdBy;
+          }
+          throw new plugins.typedrequest.TypedResponseError('insufficient scope');
+        }
+      }
+    }
+
+    throw new plugins.typedrequest.TypedResponseError('unauthorized');
+  }
+
+  private registerHandlers(): void {
+    // Get all network targets
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetNetworkTargets>(
+        'getNetworkTargets',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'targets:read');
+          const resolver = this.opsServerRef.dcRouterRef.referenceResolver;
+          if (!resolver) {
+            return { targets: [] };
+          }
+          return { targets: resolver.listTargets() };
+        },
+      ),
+    );
+
+    // Get a single network target
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetNetworkTarget>(
+        'getNetworkTarget',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'targets:read');
+          const resolver = this.opsServerRef.dcRouterRef.referenceResolver;
+          if (!resolver) {
+            return { target: null };
+          }
+          return { target: resolver.getTarget(dataArg.id) || null };
+        },
+      ),
+    );
+
+    // Create a network target
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_CreateNetworkTarget>(
+        'createNetworkTarget',
+        async (dataArg) => {
+          const userId = await this.requireAuth(dataArg, 'targets:write');
+          const resolver = this.opsServerRef.dcRouterRef.referenceResolver;
+          if (!resolver) {
+            return { success: false, message: 'Reference resolver not initialized' };
+          }
+          const id = await resolver.createTarget({
+            name: dataArg.name,
+            description: dataArg.description,
+            host: dataArg.host,
+            port: dataArg.port,
+            createdBy: userId,
+          });
+          return { success: true, id };
+        },
+      ),
+    );
+
+    // Update a network target
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_UpdateNetworkTarget>(
+        'updateNetworkTarget',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'targets:write');
+          const resolver = this.opsServerRef.dcRouterRef.referenceResolver;
+          const manager = this.opsServerRef.dcRouterRef.routeConfigManager;
+          if (!resolver || !manager) {
+            return { success: false, message: 'Not initialized' };
+          }
+
+          const { affectedRouteIds } = await resolver.updateTarget(dataArg.id, {
+            name: dataArg.name,
+            description: dataArg.description,
+            host: dataArg.host,
+            port: dataArg.port,
+          });
+
+          if (affectedRouteIds.length > 0) {
+            await manager.reResolveRoutes(affectedRouteIds);
+          }
+
+          return { success: true, affectedRouteCount: affectedRouteIds.length };
+        },
+      ),
+    );
+
+    // Delete a network target
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_DeleteNetworkTarget>(
+        'deleteNetworkTarget',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'targets:write');
+          const resolver = this.opsServerRef.dcRouterRef.referenceResolver;
+          const manager = this.opsServerRef.dcRouterRef.routeConfigManager;
+          if (!resolver || !manager) {
+            return { success: false, message: 'Not initialized' };
+          }
+
+          const result = await resolver.deleteTarget(
+            dataArg.id,
+            dataArg.force ?? false,
+            manager.getStoredRoutes(),
+          );
+
+          if (result.success && dataArg.force) {
+            await manager.applyRoutes();
+          }
+
+          return result;
+        },
+      ),
+    );
+
+    // Get routes using a network target
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetNetworkTargetUsage>(
+        'getNetworkTargetUsage',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'targets:read');
+          const resolver = this.opsServerRef.dcRouterRef.referenceResolver;
+          const manager = this.opsServerRef.dcRouterRef.routeConfigManager;
+          if (!resolver || !manager) {
+            return { routes: [] };
+          }
+          const usage = resolver.getTargetUsageForId(dataArg.id, manager.getStoredRoutes());
+          return { routes: usage.map((u) => ({ id: u.id, name: u.routeName })) };
+        },
+      ),
+    );
+  }
+}

ts/opsserver/handlers/radius.handler.ts

@@ -3,21 +3,19 @@ import type { OpsServer } from '../classes.opsserver.js';
 import * as interfaces from '../../../ts_interfaces/index.js';
 
 export class RadiusHandler {
-  public typedrouter = new plugins.typedrequest.TypedRouter();
-
   constructor(private opsServerRef: OpsServer) {
-    // Add this handler's router to the parent
-    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
     this.registerHandlers();
   }
 
   private registerHandlers(): void {
+    const viewRouter = this.opsServerRef.viewRouter;
+    const adminRouter = this.opsServerRef.adminRouter;
     // ========================================================================
     // RADIUS Client Management
     // ========================================================================
 
-    // Get all RADIUS clients
-    this.typedrouter.addTypedHandler(
+    // Get all RADIUS clients (read)
+    viewRouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetRadiusClients>(
         'getRadiusClients',
         async (dataArg, toolsArg) => {
@@ -40,8 +38,8 @@ export class RadiusHandler {
       )
     );
 
-    // Add or update a RADIUS client
-    this.typedrouter.addTypedHandler(
+    // Add or update a RADIUS client (write)
+    adminRouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_SetRadiusClient>(
         'setRadiusClient',
         async (dataArg, toolsArg) => {
@@ -54,15 +52,15 @@ export class RadiusHandler {
           try {
             await radiusServer.addClient(dataArg.client);
             return { success: true };
-          } catch (error) {
-            return { success: false, message: error.message };
+          } catch (error: unknown) {
+            return { success: false, message: (error as Error).message };
           }
         }
       )
     );
 
-    // Remove a RADIUS client
-    this.typedrouter.addTypedHandler(
+    // Remove a RADIUS client (write)
+    adminRouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_RemoveRadiusClient>(
         'removeRadiusClient',
         async (dataArg, toolsArg) => {
@@ -85,8 +83,8 @@ export class RadiusHandler {
     // VLAN Mapping Management
     // ========================================================================
 
-    // Get all VLAN mappings
-    this.typedrouter.addTypedHandler(
+    // Get all VLAN mappings (read)
+    viewRouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetVlanMappings>(
         'getVlanMappings',
         async (dataArg, toolsArg) => {
@@ -121,8 +119,8 @@ export class RadiusHandler {
       )
     );
 
-    // Add or update a VLAN mapping
-    this.typedrouter.addTypedHandler(
+    // Add or update a VLAN mapping (write)
+    adminRouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_SetVlanMapping>(
         'setVlanMapping',
         async (dataArg, toolsArg) => {
@@ -146,15 +144,15 @@ export class RadiusHandler {
                 updatedAt: mapping.updatedAt,
               },
             };
-          } catch (error) {
-            return { success: false, message: error.message };
+          } catch (error: unknown) {
+            return { success: false, message: (error as Error).message };
           }
         }
       )
     );
 
-    // Remove a VLAN mapping
-    this.typedrouter.addTypedHandler(
+    // Remove a VLAN mapping (write)
+    adminRouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_RemoveVlanMapping>(
         'removeVlanMapping',
         async (dataArg, toolsArg) => {
@@ -174,8 +172,8 @@ export class RadiusHandler {
       )
     );
 
-    // Update VLAN configuration
-    this.typedrouter.addTypedHandler(
+    // Update VLAN configuration (write)
+    adminRouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_UpdateVlanConfig>(
         'updateVlanConfig',
         async (dataArg, toolsArg) => {
@@ -206,8 +204,8 @@ export class RadiusHandler {
       )
     );
 
-    // Test VLAN assignment
-    this.typedrouter.addTypedHandler(
+    // Test VLAN assignment (read)
+    viewRouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_TestVlanAssignment>(
         'testVlanAssignment',
         async (dataArg, toolsArg) => {
@@ -240,8 +238,8 @@ export class RadiusHandler {
     // Accounting / Session Management
     // ========================================================================
 
-    // Get active sessions
-    this.typedrouter.addTypedHandler(
+    // Get active sessions (read)
+    viewRouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetRadiusSessions>(
         'getRadiusSessions',
         async (dataArg, toolsArg) => {
@@ -289,8 +287,8 @@ export class RadiusHandler {
       )
     );
 
-    // Disconnect a session
-    this.typedrouter.addTypedHandler(
+    // Disconnect a session (write)
+    adminRouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_DisconnectRadiusSession>(
         'disconnectRadiusSession',
         async (dataArg, toolsArg) => {
@@ -314,8 +312,8 @@ export class RadiusHandler {
       )
     );
 
-    // Get accounting summary
-    this.typedrouter.addTypedHandler(
+    // Get accounting summary (read)
+    viewRouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetRadiusAccountingSummary>(
         'getRadiusAccountingSummary',
         async (dataArg, toolsArg) => {
@@ -351,8 +349,8 @@ export class RadiusHandler {
     // Statistics
     // ========================================================================
 
-    // Get RADIUS statistics
-    this.typedrouter.addTypedHandler(
+    // Get RADIUS statistics (read)
+    viewRouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetRadiusStatistics>(
         'getRadiusStatistics',
         async (dataArg, toolsArg) => {

ts/opsserver/handlers/remoteingress.handler.ts

@@ -0,0 +1,226 @@
+import * as plugins from '../../plugins.js';
+import type { OpsServer } from '../classes.opsserver.js';
+import * as interfaces from '../../../ts_interfaces/index.js';
+
+export class RemoteIngressHandler {
+  constructor(private opsServerRef: OpsServer) {
+    this.registerHandlers();
+  }
+
+  private registerHandlers(): void {
+    const viewRouter = this.opsServerRef.viewRouter;
+    const adminRouter = this.opsServerRef.adminRouter;
+
+    // ---- Read endpoints (viewRouter — valid identity required via middleware) ----
+
+    // Get all remote ingress edges
+    viewRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetRemoteIngresses>(
+        'getRemoteIngresses',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.remoteIngressManager;
+          if (!manager) {
+            return { edges: [] };
+          }
+          // Return edges without secrets, enriched with effective listen ports and breakdown
+          const edges = manager.getAllEdges().map((e) => {
+            const breakdown = manager.getPortBreakdown(e);
+            return {
+              ...e,
+              secret: '********', // Never expose secrets via API
+              effectiveListenPorts: manager.getEffectiveListenPorts(e),
+              manualPorts: breakdown.manual,
+              derivedPorts: breakdown.derived,
+            };
+          });
+          return { edges };
+        },
+      ),
+    );
+
+    // ---- Write endpoints (adminRouter) ----
+
+    // Create a new remote ingress edge
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_CreateRemoteIngress>(
+        'createRemoteIngress',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.remoteIngressManager;
+          const tunnelManager = this.opsServerRef.dcRouterRef.tunnelManager;
+
+          if (!manager) {
+            return {
+              success: false,
+              edge: null as any,
+            };
+          }
+
+          const edge = await manager.createEdge(
+            dataArg.name,
+            dataArg.listenPorts || [],
+            dataArg.tags,
+            dataArg.autoDerivePorts ?? true,
+          );
+
+          // Sync allowed edges with the hub
+          if (tunnelManager) {
+            await tunnelManager.syncAllowedEdges();
+          }
+
+          return { success: true, edge };
+        },
+      ),
+    );
+
+    // Delete a remote ingress edge
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_DeleteRemoteIngress>(
+        'deleteRemoteIngress',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.remoteIngressManager;
+          const tunnelManager = this.opsServerRef.dcRouterRef.tunnelManager;
+
+          if (!manager) {
+            return { success: false, message: 'RemoteIngress not configured' };
+          }
+
+          const deleted = await manager.deleteEdge(dataArg.id);
+          if (deleted && tunnelManager) {
+            await tunnelManager.syncAllowedEdges();
+          }
+
+          return {
+            success: deleted,
+            message: deleted ? undefined : 'Edge not found',
+          };
+        },
+      ),
+    );
+
+    // Update a remote ingress edge
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_UpdateRemoteIngress>(
+        'updateRemoteIngress',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.remoteIngressManager;
+          const tunnelManager = this.opsServerRef.dcRouterRef.tunnelManager;
+
+          if (!manager) {
+            return { success: false, edge: null as any };
+          }
+
+          const edge = await manager.updateEdge(dataArg.id, {
+            name: dataArg.name,
+            listenPorts: dataArg.listenPorts,
+            autoDerivePorts: dataArg.autoDerivePorts,
+            enabled: dataArg.enabled,
+            tags: dataArg.tags,
+          });
+
+          if (!edge) {
+            return { success: false, edge: null as any };
+          }
+
+          // Sync allowed edges — ports, tags, or enabled may have changed
+          if (tunnelManager) {
+            await tunnelManager.syncAllowedEdges();
+          }
+
+          const breakdown = manager.getPortBreakdown(edge);
+          return {
+            success: true,
+            edge: {
+              ...edge,
+              secret: '********',
+              effectiveListenPorts: manager.getEffectiveListenPorts(edge),
+              manualPorts: breakdown.manual,
+              derivedPorts: breakdown.derived,
+            },
+          };
+        },
+      ),
+    );
+
+    // Regenerate secret for an edge
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_RegenerateRemoteIngressSecret>(
+        'regenerateRemoteIngressSecret',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.remoteIngressManager;
+          const tunnelManager = this.opsServerRef.dcRouterRef.tunnelManager;
+
+          if (!manager) {
+            return { success: false, secret: '' };
+          }
+
+          const secret = await manager.regenerateSecret(dataArg.id);
+          if (!secret) {
+            return { success: false, secret: '' };
+          }
+
+          // Sync allowed edges since secret changed
+          if (tunnelManager) {
+            await tunnelManager.syncAllowedEdges();
+          }
+
+          return { success: true, secret };
+        },
+      ),
+    );
+
+    // Get runtime status of all edges (read)
+    viewRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetRemoteIngressStatus>(
+        'getRemoteIngressStatus',
+        async (dataArg, toolsArg) => {
+          const tunnelManager = this.opsServerRef.dcRouterRef.tunnelManager;
+          if (!tunnelManager) {
+            return { statuses: [] };
+          }
+          return { statuses: tunnelManager.getEdgeStatuses() };
+        },
+      ),
+    );
+
+    // Get a connection token for an edge (write — exposes secret)
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetRemoteIngressConnectionToken>(
+        'getRemoteIngressConnectionToken',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.remoteIngressManager;
+          if (!manager) {
+            return { success: false, message: 'RemoteIngress not configured' };
+          }
+
+          const edge = manager.getEdge(dataArg.edgeId);
+          if (!edge) {
+            return { success: false, message: 'Edge not found' };
+          }
+          if (!edge.enabled) {
+            return { success: false, message: 'Edge is disabled' };
+          }
+
+          const hubHost = dataArg.hubHost
+            || this.opsServerRef.dcRouterRef.options.remoteIngressConfig?.hubDomain;
+          if (!hubHost) {
+            return {
+              success: false,
+              message: 'No hub hostname configured. Set hubDomain in remoteIngressConfig or provide hubHost.',
+            };
+          }
+
+          const hubPort = this.opsServerRef.dcRouterRef.options.remoteIngressConfig?.tunnelPort ?? 8443;
+
+          const token = plugins.remoteingress.encodeConnectionToken({
+            hubHost,
+            hubPort,
+            edgeId: edge.id,
+            secret: edge.secret,
+          });
+
+          return { success: true, token };
+        },
+      ),
+    );
+  }
+}

ts/opsserver/handlers/route-management.handler.ts

@@ -0,0 +1,164 @@
+import * as plugins from '../../plugins.js';
+import type { OpsServer } from '../classes.opsserver.js';
+import * as interfaces from '../../../ts_interfaces/index.js';
+
+export class RouteManagementHandler {
+  public typedrouter = new plugins.typedrequest.TypedRouter();
+
+  constructor(private opsServerRef: OpsServer) {
+    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
+    this.registerHandlers();
+  }
+
+  /**
+   * Validate auth: JWT identity OR API token with required scope.
+   * Returns a userId string on success, throws on failure.
+   */
+  private async requireAuth(
+    request: { identity?: interfaces.data.IIdentity; apiToken?: string },
+    requiredScope?: interfaces.data.TApiTokenScope,
+  ): Promise<string> {
+    // Try JWT identity first
+    if (request.identity?.jwt) {
+      try {
+        const isAdmin = await this.opsServerRef.adminHandler.adminIdentityGuard.exec({
+          identity: request.identity,
+        });
+        if (isAdmin) return request.identity.userId;
+      } catch { /* fall through */ }
+    }
+
+    // Try API token
+    if (request.apiToken) {
+      const tokenManager = this.opsServerRef.dcRouterRef.apiTokenManager;
+      if (tokenManager) {
+        const token = await tokenManager.validateToken(request.apiToken);
+        if (token) {
+          if (!requiredScope || tokenManager.hasScope(token, requiredScope)) {
+            return token.createdBy;
+          }
+          throw new plugins.typedrequest.TypedResponseError('insufficient scope');
+        }
+      }
+    }
+
+    throw new plugins.typedrequest.TypedResponseError('unauthorized');
+  }
+
+  private registerHandlers(): void {
+    // Get merged routes
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetMergedRoutes>(
+        'getMergedRoutes',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'routes:read');
+          const manager = this.opsServerRef.dcRouterRef.routeConfigManager;
+          if (!manager) {
+            return { routes: [], warnings: [] };
+          }
+          return manager.getMergedRoutes();
+        },
+      ),
+    );
+
+    // Create route
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_CreateRoute>(
+        'createRoute',
+        async (dataArg) => {
+          const userId = await this.requireAuth(dataArg, 'routes:write');
+          const manager = this.opsServerRef.dcRouterRef.routeConfigManager;
+          if (!manager) {
+            return { success: false, message: 'Route management not initialized' };
+          }
+          const id = await manager.createRoute(dataArg.route, userId, dataArg.enabled ?? true, dataArg.metadata);
+          return { success: true, storedRouteId: id };
+        },
+      ),
+    );
+
+    // Update route
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_UpdateRoute>(
+        'updateRoute',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'routes:write');
+          const manager = this.opsServerRef.dcRouterRef.routeConfigManager;
+          if (!manager) {
+            return { success: false, message: 'Route management not initialized' };
+          }
+          const ok = await manager.updateRoute(dataArg.id, {
+            route: dataArg.route as any,
+            enabled: dataArg.enabled,
+            metadata: dataArg.metadata,
+          });
+          return { success: ok, message: ok ? undefined : 'Route not found' };
+        },
+      ),
+    );
+
+    // Delete route
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_DeleteRoute>(
+        'deleteRoute',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'routes:write');
+          const manager = this.opsServerRef.dcRouterRef.routeConfigManager;
+          if (!manager) {
+            return { success: false, message: 'Route management not initialized' };
+          }
+          const ok = await manager.deleteRoute(dataArg.id);
+          return { success: ok, message: ok ? undefined : 'Route not found' };
+        },
+      ),
+    );
+
+    // Set override on a hardcoded route
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_SetRouteOverride>(
+        'setRouteOverride',
+        async (dataArg) => {
+          const userId = await this.requireAuth(dataArg, 'routes:write');
+          const manager = this.opsServerRef.dcRouterRef.routeConfigManager;
+          if (!manager) {
+            return { success: false, message: 'Route management not initialized' };
+          }
+          await manager.setOverride(dataArg.routeName, dataArg.enabled, userId);
+          return { success: true };
+        },
+      ),
+    );
+
+    // Remove override from a hardcoded route
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_RemoveRouteOverride>(
+        'removeRouteOverride',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'routes:write');
+          const manager = this.opsServerRef.dcRouterRef.routeConfigManager;
+          if (!manager) {
+            return { success: false, message: 'Route management not initialized' };
+          }
+          const ok = await manager.removeOverride(dataArg.routeName);
+          return { success: ok, message: ok ? undefined : 'Override not found' };
+        },
+      ),
+    );
+
+    // Toggle programmatic route
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ToggleRoute>(
+        'toggleRoute',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'routes:write');
+          const manager = this.opsServerRef.dcRouterRef.routeConfigManager;
+          if (!manager) {
+            return { success: false, message: 'Route management not initialized' };
+          }
+          const ok = await manager.toggleRoute(dataArg.id, dataArg.enabled);
+          return { success: ok, message: ok ? undefined : 'Route not found' };
+        },
+      ),
+    );
+  }
+}

ts/opsserver/handlers/security.handler.ts

@@ -4,17 +4,16 @@ import * as interfaces from '../../../ts_interfaces/index.js';
 import { MetricsManager } from '../../monitoring/index.js';
 
 export class SecurityHandler {
-  public typedrouter = new plugins.typedrequest.TypedRouter();
-  
   constructor(private opsServerRef: OpsServer) {
-    // Add this handler's router to the parent
-    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
     this.registerHandlers();
   }
-  
+
   private registerHandlers(): void {
+    // All security endpoints register directly on viewRouter (valid identity required via middleware)
+    const router = this.opsServerRef.viewRouter;
+
     // Security Metrics Handler
-    this.typedrouter.addTypedHandler(
+    router.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetSecurityMetrics>(
         'getSecurityMetrics',
         async (dataArg, toolsArg) => {
@@ -40,7 +39,7 @@ export class SecurityHandler {
     );
     
     // Active Connections Handler
-    this.typedrouter.addTypedHandler(
+    router.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetActiveConnections>(
         'getActiveConnections',
         async (dataArg, toolsArg) => {
@@ -77,35 +76,53 @@ export class SecurityHandler {
     );
     
     // Network Stats Handler - provides comprehensive network metrics
-    this.typedrouter.addTypedHandler(
-      new plugins.typedrequest.TypedHandler(
+    router.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetNetworkStats>(
         'getNetworkStats',
         async (dataArg, toolsArg) => {
           // Get network stats from MetricsManager if available
           if (this.opsServerRef.dcRouterRef.metricsManager) {
             const networkStats = await this.opsServerRef.dcRouterRef.metricsManager.getNetworkStats();
-            
+
+            // Convert per-IP throughput Map to serializable array
+            const throughputByIP: Array<{ ip: string; in: number; out: number }> = [];
+            if (networkStats.throughputByIP) {
+              for (const [ip, tp] of networkStats.throughputByIP) {
+                throughputByIP.push({ ip, in: tp.in, out: tp.out });
+              }
+            }
+
             return {
               connectionsByIP: Array.from(networkStats.connectionsByIP.entries()).map(([ip, count]) => ({ ip, count })),
               throughputRate: networkStats.throughputRate,
               topIPs: networkStats.topIPs,
               totalDataTransferred: networkStats.totalDataTransferred,
+              throughputHistory: networkStats.throughputHistory || [],
+              throughputByIP,
+              requestsPerSecond: networkStats.requestsPerSecond || 0,
+              requestsTotal: networkStats.requestsTotal || 0,
+              backends: networkStats.backends || [],
             };
           }
-          
+
           // Fallback if MetricsManager not available
           return {
             connectionsByIP: [],
             throughputRate: { bytesInPerSecond: 0, bytesOutPerSecond: 0 },
             topIPs: [],
             totalDataTransferred: { bytesIn: 0, bytesOut: 0 },
+            throughputHistory: [],
+            throughputByIP: [],
+            requestsPerSecond: 0,
+            requestsTotal: 0,
+            backends: [],
           };
         }
       )
     );
     
     // Rate Limit Status Handler
-    this.typedrouter.addTypedHandler(
+    router.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetRateLimitStatus>(
         'getRateLimitStatus',
         async (dataArg, toolsArg) => {

ts/opsserver/handlers/source-profile.handler.ts

@@ -0,0 +1,169 @@
+import * as plugins from '../../plugins.js';
+import type { OpsServer } from '../classes.opsserver.js';
+import * as interfaces from '../../../ts_interfaces/index.js';
+
+export class SourceProfileHandler {
+  public typedrouter = new plugins.typedrequest.TypedRouter();
+
+  constructor(private opsServerRef: OpsServer) {
+    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
+    this.registerHandlers();
+  }
+
+  private async requireAuth(
+    request: { identity?: interfaces.data.IIdentity; apiToken?: string },
+    requiredScope?: interfaces.data.TApiTokenScope,
+  ): Promise<string> {
+    if (request.identity?.jwt) {
+      try {
+        const isAdmin = await this.opsServerRef.adminHandler.adminIdentityGuard.exec({
+          identity: request.identity,
+        });
+        if (isAdmin) return request.identity.userId;
+      } catch { /* fall through */ }
+    }
+
+    if (request.apiToken) {
+      const tokenManager = this.opsServerRef.dcRouterRef.apiTokenManager;
+      if (tokenManager) {
+        const token = await tokenManager.validateToken(request.apiToken);
+        if (token) {
+          if (!requiredScope || tokenManager.hasScope(token, requiredScope)) {
+            return token.createdBy;
+          }
+          throw new plugins.typedrequest.TypedResponseError('insufficient scope');
+        }
+      }
+    }
+
+    throw new plugins.typedrequest.TypedResponseError('unauthorized');
+  }
+
+  private registerHandlers(): void {
+    // Get all source profiles
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetSourceProfiles>(
+        'getSourceProfiles',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'source-profiles:read');
+          const resolver = this.opsServerRef.dcRouterRef.referenceResolver;
+          if (!resolver) {
+            return { profiles: [] };
+          }
+          return { profiles: resolver.listProfiles() };
+        },
+      ),
+    );
+
+    // Get a single source profile
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetSourceProfile>(
+        'getSourceProfile',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'source-profiles:read');
+          const resolver = this.opsServerRef.dcRouterRef.referenceResolver;
+          if (!resolver) {
+            return { profile: null };
+          }
+          return { profile: resolver.getProfile(dataArg.id) || null };
+        },
+      ),
+    );
+
+    // Create a source profile
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_CreateSourceProfile>(
+        'createSourceProfile',
+        async (dataArg) => {
+          const userId = await this.requireAuth(dataArg, 'source-profiles:write');
+          const resolver = this.opsServerRef.dcRouterRef.referenceResolver;
+          if (!resolver) {
+            return { success: false, message: 'Reference resolver not initialized' };
+          }
+          const id = await resolver.createProfile({
+            name: dataArg.name,
+            description: dataArg.description,
+            security: dataArg.security,
+            extendsProfiles: dataArg.extendsProfiles,
+            createdBy: userId,
+          });
+          return { success: true, id };
+        },
+      ),
+    );
+
+    // Update a source profile
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_UpdateSourceProfile>(
+        'updateSourceProfile',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'source-profiles:write');
+          const resolver = this.opsServerRef.dcRouterRef.referenceResolver;
+          const manager = this.opsServerRef.dcRouterRef.routeConfigManager;
+          if (!resolver || !manager) {
+            return { success: false, message: 'Not initialized' };
+          }
+
+          const { affectedRouteIds } = await resolver.updateProfile(dataArg.id, {
+            name: dataArg.name,
+            description: dataArg.description,
+            security: dataArg.security,
+            extendsProfiles: dataArg.extendsProfiles,
+          });
+
+          // Propagate to affected routes
+          if (affectedRouteIds.length > 0) {
+            await manager.reResolveRoutes(affectedRouteIds);
+          }
+
+          return { success: true, affectedRouteCount: affectedRouteIds.length };
+        },
+      ),
+    );
+
+    // Delete a source profile
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_DeleteSourceProfile>(
+        'deleteSourceProfile',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'source-profiles:write');
+          const resolver = this.opsServerRef.dcRouterRef.referenceResolver;
+          const manager = this.opsServerRef.dcRouterRef.routeConfigManager;
+          if (!resolver || !manager) {
+            return { success: false, message: 'Not initialized' };
+          }
+
+          const result = await resolver.deleteProfile(
+            dataArg.id,
+            dataArg.force ?? false,
+            manager.getStoredRoutes(),
+          );
+
+          // If force-deleted with affected routes, re-apply
+          if (result.success && dataArg.force) {
+            await manager.applyRoutes();
+          }
+
+          return result;
+        },
+      ),
+    );
+
+    // Get routes using a source profile
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetSourceProfileUsage>(
+        'getSourceProfileUsage',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'source-profiles:read');
+          const resolver = this.opsServerRef.dcRouterRef.referenceResolver;
+          const manager = this.opsServerRef.dcRouterRef.routeConfigManager;
+          if (!resolver || !manager) {
+            return { routes: [] };
+          }
+          const usage = resolver.getProfileUsageForId(dataArg.id, manager.getStoredRoutes());
+          return { routes: usage.map((u) => ({ id: u.id, name: u.routeName })) };
+        },
+      ),
+    );
+  }
+}

ts/opsserver/handlers/stats.handler.ts

@@ -2,19 +2,20 @@ import * as plugins from '../../plugins.js';
 import type { OpsServer } from '../classes.opsserver.js';
 import * as interfaces from '../../../ts_interfaces/index.js';
 import { MetricsManager } from '../../monitoring/index.js';
+import { SecurityLogger } from '../../security/classes.securitylogger.js';
+import { commitinfo } from '../../00_commitinfo_data.js';
 
 export class StatsHandler {
-  public typedrouter = new plugins.typedrequest.TypedRouter();
-  
   constructor(private opsServerRef: OpsServer) {
-    // Add this handler's router to the parent
-    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
     this.registerHandlers();
   }
-  
+
   private registerHandlers(): void {
+    // All stats endpoints register directly on viewRouter (valid identity required via middleware)
+    const router = this.opsServerRef.viewRouter;
+
     // Server Statistics Handler
-    this.typedrouter.addTypedHandler(
+    router.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetServerStatistics>(
         'getServerStatistics',
         async (dataArg, toolsArg) => {
@@ -37,7 +38,7 @@ export class StatsHandler {
     );
     
     // Email Statistics Handler
-    this.typedrouter.addTypedHandler(
+    router.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetEmailStatistics>(
         'getEmailStatistics',
         async (dataArg, toolsArg) => {
@@ -76,7 +77,7 @@ export class StatsHandler {
     );
     
     // DNS Statistics Handler
-    this.typedrouter.addTypedHandler(
+    router.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetDnsStatistics>(
         'getDnsStatistics',
         async (dataArg, toolsArg) => {
@@ -113,7 +114,7 @@ export class StatsHandler {
     );
     
     // Queue Status Handler
-    this.typedrouter.addTypedHandler(
+    router.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetQueueStatus>(
         'getQueueStatus',
         async (dataArg, toolsArg) => {
@@ -141,7 +142,7 @@ export class StatsHandler {
     );
     
     // Health Status Handler
-    this.typedrouter.addTypedHandler(
+    router.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetHealthStatus>(
         'getHealthStatus',
         async (dataArg, toolsArg) => {
@@ -158,7 +159,7 @@ export class StatsHandler {
                 };
                 return acc;
               }, {} as any),
-              version: '2.12.0', // TODO: Get from package.json
+              version: commitinfo.version,
             },
           };
         }
@@ -166,7 +167,7 @@ export class StatsHandler {
     );
     
     // Combined Metrics Handler - More efficient for frontend polling
-    this.typedrouter.addTypedHandler(
+    router.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetCombinedMetrics>(
         'getCombinedMetrics',
         async (dataArg, toolsArg) => {
@@ -203,6 +204,11 @@ export class StatsHandler {
           if (sections.email) {
             promises.push(
               this.collectEmailStats().then(stats => {
+                // Get time-series data from MetricsManager
+                const timeSeries = this.opsServerRef.dcRouterRef.metricsManager
+                  ? this.opsServerRef.dcRouterRef.metricsManager.getEmailTimeSeries(24)
+                  : undefined;
+
                 metrics.email = {
                   sent: stats.sentToday,
                   received: stats.receivedToday,
@@ -212,6 +218,7 @@ export class StatsHandler {
                   averageDeliveryTime: 0,
                   deliveryRate: stats.deliveryRate,
                   bounceRate: stats.bounceRate,
+                  timeSeries,
                 };
               })
             );
@@ -220,6 +227,11 @@ export class StatsHandler {
           if (sections.dns) {
             promises.push(
               this.collectDnsStats().then(stats => {
+                // Get time-series data from MetricsManager
+                const timeSeries = this.opsServerRef.dcRouterRef.metricsManager
+                  ? this.opsServerRef.dcRouterRef.metricsManager.getDnsTimeSeries(24)
+                  : undefined;
+
                 metrics.dns = {
                   totalQueries: stats.totalQueries,
                   cacheHits: stats.cacheHits,
@@ -228,6 +240,8 @@ export class StatsHandler {
                   activeDomains: stats.topDomains.length,
                   averageResponseTime: 0,
                   queryTypes: stats.queryTypes,
+                  timeSeries,
+                  recentQueries: stats.recentQueries,
                 };
               })
             );
@@ -236,6 +250,19 @@ export class StatsHandler {
           if (sections.security && this.opsServerRef.dcRouterRef.metricsManager) {
             promises.push(
               this.opsServerRef.dcRouterRef.metricsManager.getSecurityStats().then(stats => {
+                // Get recent events from the SecurityLogger singleton
+                const securityLogger = SecurityLogger.getInstance();
+                const recentEvents = securityLogger.getRecentEvents(50).map((evt) => ({
+                  timestamp: evt.timestamp,
+                  level: evt.level,
+                  type: evt.type,
+                  message: evt.message,
+                  details: evt.details,
+                  ipAddress: evt.ipAddress,
+                  domain: evt.domain,
+                  success: evt.success,
+                }));
+
                 metrics.security = {
                   blockedIPs: stats.blockedIPs,
                   reputationScores: {},
@@ -244,6 +271,7 @@ export class StatsHandler {
                   phishingDetected: stats.phishingDetected,
                   authenticationFailures: stats.authFailures,
                   suspiciousActivities: stats.totalThreatsBlocked,
+                  recentEvents,
                 };
               })
             );
@@ -252,9 +280,17 @@ export class StatsHandler {
           if (sections.network && this.opsServerRef.dcRouterRef.metricsManager) {
             promises.push(
               (async () => {
-                const stats = await this.opsServerRef.dcRouterRef.metricsManager.getNetworkStats();
+                const stats = await this.opsServerRef.dcRouterRef.metricsManager!.getNetworkStats();
                 const serverStats = await this.collectServerStats();
 
+                // Build per-IP bandwidth lookup from throughputByIP
+                const ipBandwidth = new Map<string, { in: number; out: number }>();
+                if (stats.throughputByIP) {
+                  for (const [ip, tp] of stats.throughputByIP) {
+                    ipBandwidth.set(ip, { in: tp.in, out: tp.out });
+                  }
+                }
+
                 metrics.network = {
                   totalBandwidth: {
                     in: stats.throughputRate.bytesInPerSecond,
@@ -269,16 +305,59 @@ export class StatsHandler {
                   topEndpoints: stats.topIPs.map(ip => ({
                     endpoint: ip.ip,
                     requests: ip.count,
-                    bandwidth: {
-                      in: 0,
-                      out: 0,
-                    },
+                    bandwidth: ipBandwidth.get(ip.ip) || { in: 0, out: 0 },
                   })),
+                  throughputHistory: stats.throughputHistory || [],
+                  requestsPerSecond: stats.requestsPerSecond || 0,
+                  requestsTotal: stats.requestsTotal || 0,
+                  backends: stats.backends || [],
+                  frontendProtocols: stats.frontendProtocols || null,
+                  backendProtocols: stats.backendProtocols || null,
                 };
               })()
             );
           }
-          
+
+          if (sections.radius) {
+            promises.push(
+              (async () => {
+                const radiusServer = this.opsServerRef.dcRouterRef.radiusServer;
+                if (!radiusServer) return;
+                const stats = radiusServer.getStats();
+                const accountingStats = radiusServer.getAccountingManager().getStats();
+                metrics.radius = {
+                  running: stats.running,
+                  uptime: stats.uptime,
+                  authRequests: stats.authRequests,
+                  authAccepts: stats.authAccepts,
+                  authRejects: stats.authRejects,
+                  accountingRequests: stats.accountingRequests,
+                  activeSessions: stats.activeSessions,
+                  totalInputBytes: accountingStats.totalInputBytes,
+                  totalOutputBytes: accountingStats.totalOutputBytes,
+                };
+              })()
+            );
+          }
+
+          if (sections.vpn) {
+            promises.push(
+              (async () => {
+                const vpnManager = this.opsServerRef.dcRouterRef.vpnManager;
+                const vpnConfig = this.opsServerRef.dcRouterRef.options.vpnConfig;
+                if (!vpnManager) return;
+                const connected = await vpnManager.getConnectedClients();
+                metrics.vpn = {
+                  running: vpnManager.running,
+                  subnet: vpnManager.getSubnet(),
+                  registeredClients: vpnManager.listClients().length,
+                  connectedClients: connected.length,
+                  wgListenPort: vpnConfig?.wgListenPort ?? 51820,
+                };
+              })()
+            );
+          }
+
           await Promise.all(promises);
           
           return {
@@ -387,6 +466,7 @@ export class StatsHandler {
       count: number;
     }>;
     queryTypes: { [key: string]: number };
+    recentQueries?: Array<{ timestamp: number; domain: string; type: string; answered: boolean; responseTimeMs: number }>;
     domainBreakdown?: { [domain: string]: interfaces.data.IDnsStats };
   }> {
     // Get metrics from MetricsManager if available
@@ -400,9 +480,10 @@ export class StatsHandler {
         cacheHitRate: dnsStats.cacheHitRate,
         topDomains: dnsStats.topDomains,
         queryTypes: dnsStats.queryTypes,
+        recentQueries: dnsStats.recentQueries,
       };
     }
-    
+
     // Fallback if MetricsManager not available
     return {
       queriesPerSecond: 0,
@@ -452,44 +533,41 @@ export class StatsHandler {
       message?: string;
     }>;
   }> {
-    const services: Array<{
-      name: string;
-      status: 'healthy' | 'degraded' | 'unhealthy';
-      message?: string;
-    }> = [];
-    
-    // Check HTTP Proxy
-    if (this.opsServerRef.dcRouterRef.smartProxy) {
-      services.push({
-        name: 'HTTP/HTTPS Proxy',
-        status: 'healthy',
-      });
-    }
-    
-    // Check Email Server
-    if (this.opsServerRef.dcRouterRef.emailServer) {
-      services.push({
-        name: 'Email Server',
-        status: 'healthy',
-      });
-    }
-    
-    // Check DNS Server
-    if (this.opsServerRef.dcRouterRef.dnsServer) {
-      services.push({
-        name: 'DNS Server',
-        status: 'healthy',
-      });
-    }
-    
-    // Check OpsServer
-    services.push({
-      name: 'OpsServer',
-      status: 'healthy',
+    const dcRouter = this.opsServerRef.dcRouterRef;
+    const health = dcRouter.serviceManager.getHealth();
+
+    const services = health.services.map((svc) => {
+      let status: 'healthy' | 'degraded' | 'unhealthy';
+      switch (svc.state) {
+        case 'running':
+          status = 'healthy';
+          break;
+        case 'starting':
+        case 'degraded':
+          status = 'degraded';
+          break;
+        case 'failed':
+          status = svc.criticality === 'critical' ? 'unhealthy' : 'degraded';
+          break;
+        case 'stopped':
+        case 'stopping':
+        default:
+          status = 'degraded';
+          break;
+      }
+
+      let message: string | undefined;
+      if (svc.state === 'failed' && svc.lastError) {
+        message = svc.lastError;
+      } else if (svc.retryCount > 0 && svc.state !== 'running') {
+        message = `Retry attempt ${svc.retryCount}`;
+      }
+
+      return { name: svc.name, status, message };
     });
-    
-    const healthy = services.every(s => s.status === 'healthy');
-    
+
+    const healthy = health.overall === 'healthy';
+
     return {
       healthy,
       services,

ts/opsserver/handlers/target-profile.handler.ts

@@ -0,0 +1,157 @@
+import * as plugins from '../../plugins.js';
+import type { OpsServer } from '../classes.opsserver.js';
+import * as interfaces from '../../../ts_interfaces/index.js';
+
+export class TargetProfileHandler {
+  public typedrouter = new plugins.typedrequest.TypedRouter();
+
+  constructor(private opsServerRef: OpsServer) {
+    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
+    this.registerHandlers();
+  }
+
+  private async requireAuth(
+    request: { identity?: interfaces.data.IIdentity; apiToken?: string },
+    requiredScope?: interfaces.data.TApiTokenScope,
+  ): Promise<string> {
+    if (request.identity?.jwt) {
+      try {
+        const isAdmin = await this.opsServerRef.adminHandler.adminIdentityGuard.exec({
+          identity: request.identity,
+        });
+        if (isAdmin) return request.identity.userId;
+      } catch { /* fall through */ }
+    }
+
+    if (request.apiToken) {
+      const tokenManager = this.opsServerRef.dcRouterRef.apiTokenManager;
+      if (tokenManager) {
+        const token = await tokenManager.validateToken(request.apiToken);
+        if (token) {
+          if (!requiredScope || tokenManager.hasScope(token, requiredScope)) {
+            return token.createdBy;
+          }
+          throw new plugins.typedrequest.TypedResponseError('insufficient scope');
+        }
+      }
+    }
+
+    throw new plugins.typedrequest.TypedResponseError('unauthorized');
+  }
+
+  private registerHandlers(): void {
+    // Get all target profiles
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetTargetProfiles>(
+        'getTargetProfiles',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'target-profiles:read');
+          const manager = this.opsServerRef.dcRouterRef.targetProfileManager;
+          if (!manager) {
+            return { profiles: [] };
+          }
+          return { profiles: manager.listProfiles() };
+        },
+      ),
+    );
+
+    // Get a single target profile
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetTargetProfile>(
+        'getTargetProfile',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'target-profiles:read');
+          const manager = this.opsServerRef.dcRouterRef.targetProfileManager;
+          if (!manager) {
+            return { profile: null };
+          }
+          return { profile: manager.getProfile(dataArg.id) || null };
+        },
+      ),
+    );
+
+    // Create a target profile
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_CreateTargetProfile>(
+        'createTargetProfile',
+        async (dataArg) => {
+          const userId = await this.requireAuth(dataArg, 'target-profiles:write');
+          const manager = this.opsServerRef.dcRouterRef.targetProfileManager;
+          if (!manager) {
+            return { success: false, message: 'Target profile manager not initialized' };
+          }
+          const id = await manager.createProfile({
+            name: dataArg.name,
+            description: dataArg.description,
+            domains: dataArg.domains,
+            targets: dataArg.targets,
+            routeRefs: dataArg.routeRefs,
+            createdBy: userId,
+          });
+          return { success: true, id };
+        },
+      ),
+    );
+
+    // Update a target profile
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_UpdateTargetProfile>(
+        'updateTargetProfile',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'target-profiles:write');
+          const manager = this.opsServerRef.dcRouterRef.targetProfileManager;
+          if (!manager) {
+            return { success: false, message: 'Not initialized' };
+          }
+          await manager.updateProfile(dataArg.id, {
+            name: dataArg.name,
+            description: dataArg.description,
+            domains: dataArg.domains,
+            targets: dataArg.targets,
+            routeRefs: dataArg.routeRefs,
+          });
+          // Re-apply routes and refresh VPN client security to update access
+          await this.opsServerRef.dcRouterRef.routeConfigManager?.applyRoutes();
+          await this.opsServerRef.dcRouterRef.vpnManager?.refreshAllClientSecurity();
+          return { success: true };
+        },
+      ),
+    );
+
+    // Delete a target profile
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_DeleteTargetProfile>(
+        'deleteTargetProfile',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'target-profiles:write');
+          const manager = this.opsServerRef.dcRouterRef.targetProfileManager;
+          if (!manager) {
+            return { success: false, message: 'Not initialized' };
+          }
+          const result = await manager.deleteProfile(dataArg.id, dataArg.force);
+          if (result.success) {
+            // Re-apply routes and refresh VPN client security to update access
+            await this.opsServerRef.dcRouterRef.routeConfigManager?.applyRoutes();
+            await this.opsServerRef.dcRouterRef.vpnManager?.refreshAllClientSecurity();
+          }
+          return result;
+        },
+      ),
+    );
+
+    // Get VPN clients using a target profile
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetTargetProfileUsage>(
+        'getTargetProfileUsage',
+        async (dataArg) => {
+          await this.requireAuth(dataArg, 'target-profiles:read');
+          const manager = this.opsServerRef.dcRouterRef.targetProfileManager;
+          if (!manager) {
+            return { clients: [] };
+          }
+          return { clients: await manager.getProfileUsage(dataArg.id) };
+        },
+      ),
+    );
+  }
+}

ts/opsserver/handlers/users.handler.ts

@@ -0,0 +1,30 @@
+import * as plugins from '../../plugins.js';
+import type { OpsServer } from '../classes.opsserver.js';
+import * as interfaces from '../../../ts_interfaces/index.js';
+
+/**
+ * Read-only handler for OpsServer user accounts. Registers on adminRouter,
+ * so admin middleware enforces auth + role check before the handler runs.
+ * User data is owned by AdminHandler; this handler just exposes a safe
+ * projection of it via TypedRequest.
+ */
+export class UsersHandler {
+  constructor(private opsServerRef: OpsServer) {
+    this.registerHandlers();
+  }
+
+  private registerHandlers(): void {
+    const router = this.opsServerRef.adminRouter;
+
+    // List users (admin-only, read-only)
+    router.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ListUsers>(
+        'listUsers',
+        async (_dataArg) => {
+          const users = this.opsServerRef.adminHandler.listUsers();
+          return { users };
+        },
+      ),
+    );
+  }
+}

ts/opsserver/handlers/vpn.handler.ts

@@ -0,0 +1,336 @@
+import * as plugins from '../../plugins.js';
+import type { OpsServer } from '../classes.opsserver.js';
+import * as interfaces from '../../../ts_interfaces/index.js';
+
+export class VpnHandler {
+  constructor(private opsServerRef: OpsServer) {
+    this.registerHandlers();
+  }
+
+  private registerHandlers(): void {
+    const viewRouter = this.opsServerRef.viewRouter;
+    const adminRouter = this.opsServerRef.adminRouter;
+
+    // ---- Read endpoints (viewRouter — valid identity required via middleware) ----
+
+    // Get all registered VPN clients
+    viewRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetVpnClients>(
+        'getVpnClients',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          if (!manager) {
+            return { clients: [] };
+          }
+          const clients = manager.listClients().map((c) => ({
+            clientId: c.clientId,
+            enabled: c.enabled,
+            targetProfileIds: c.targetProfileIds,
+            description: c.description,
+            assignedIp: c.assignedIp,
+            createdAt: c.createdAt,
+            updatedAt: c.updatedAt,
+            expiresAt: c.expiresAt,
+            destinationAllowList: c.destinationAllowList,
+            destinationBlockList: c.destinationBlockList,
+            useHostIp: c.useHostIp,
+            useDhcp: c.useDhcp,
+            staticIp: c.staticIp,
+            forceVlan: c.forceVlan,
+            vlanId: c.vlanId,
+          }));
+          return { clients };
+        },
+      ),
+    );
+
+    // Get VPN server status
+    viewRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetVpnStatus>(
+        'getVpnStatus',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          const vpnConfig = this.opsServerRef.dcRouterRef.options.vpnConfig;
+          if (!manager) {
+            return {
+              status: {
+                running: false,
+                subnet: vpnConfig?.subnet || '10.8.0.0/24',
+                wgListenPort: vpnConfig?.wgListenPort ?? 51820,
+                serverPublicKeys: null,
+                registeredClients: 0,
+                connectedClients: 0,
+              },
+            };
+          }
+
+          const connected = await manager.getConnectedClients();
+          return {
+            status: {
+              running: manager.running,
+              subnet: manager.getSubnet(),
+              wgListenPort: vpnConfig?.wgListenPort ?? 51820,
+              serverPublicKeys: manager.getServerPublicKeys(),
+              registeredClients: manager.listClients().length,
+              connectedClients: connected.length,
+            },
+          };
+        },
+      ),
+    );
+
+    // Get currently connected VPN clients
+    viewRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetVpnConnectedClients>(
+        'getVpnConnectedClients',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          if (!manager) {
+            return { connectedClients: [] };
+          }
+
+          const connected = await manager.getConnectedClients();
+          return {
+            connectedClients: connected.map((c) => ({
+              clientId: c.registeredClientId || c.clientId,
+              assignedIp: c.assignedIp,
+              connectedSince: c.connectedSince,
+              bytesSent: c.bytesSent,
+              bytesReceived: c.bytesReceived,
+              transport: c.transportType,
+            })),
+          };
+        },
+      ),
+    );
+
+    // ---- Write endpoints (adminRouter — admin identity required via middleware) ----
+
+    // Create a new VPN client
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_CreateVpnClient>(
+        'createVpnClient',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          if (!manager) {
+            return { success: false, message: 'VPN not configured' };
+          }
+
+          try {
+            const bundle = await manager.createClient({
+              clientId: dataArg.clientId,
+              targetProfileIds: dataArg.targetProfileIds,
+              description: dataArg.description,
+              destinationAllowList: dataArg.destinationAllowList,
+              destinationBlockList: dataArg.destinationBlockList,
+              useHostIp: dataArg.useHostIp,
+              useDhcp: dataArg.useDhcp,
+              staticIp: dataArg.staticIp,
+              forceVlan: dataArg.forceVlan,
+              vlanId: dataArg.vlanId,
+            });
+
+            // Retrieve the persisted doc to get dcrouter-level fields
+            const persistedClient = manager.listClients().find(
+              (c) => c.clientId === bundle.entry.clientId,
+            );
+
+            return {
+              success: true,
+              client: {
+                clientId: bundle.entry.clientId,
+                enabled: bundle.entry.enabled ?? true,
+                targetProfileIds: persistedClient?.targetProfileIds,
+                description: bundle.entry.description,
+                assignedIp: bundle.entry.assignedIp,
+                createdAt: Date.now(),
+                updatedAt: Date.now(),
+                expiresAt: bundle.entry.expiresAt,
+                destinationAllowList: persistedClient?.destinationAllowList,
+                destinationBlockList: persistedClient?.destinationBlockList,
+                useHostIp: persistedClient?.useHostIp,
+                useDhcp: persistedClient?.useDhcp,
+                staticIp: persistedClient?.staticIp,
+                forceVlan: persistedClient?.forceVlan,
+                vlanId: persistedClient?.vlanId,
+              },
+              wireguardConfig: bundle.wireguardConfig,
+            };
+          } catch (err: unknown) {
+            return { success: false, message: (err as Error).message };
+          }
+        },
+      ),
+    );
+
+    // Update a VPN client's metadata
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_UpdateVpnClient>(
+        'updateVpnClient',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          if (!manager) {
+            return { success: false, message: 'VPN not configured' };
+          }
+
+          try {
+            await manager.updateClient(dataArg.clientId, {
+              description: dataArg.description,
+              targetProfileIds: dataArg.targetProfileIds,
+              destinationAllowList: dataArg.destinationAllowList,
+              destinationBlockList: dataArg.destinationBlockList,
+              useHostIp: dataArg.useHostIp,
+              useDhcp: dataArg.useDhcp,
+              staticIp: dataArg.staticIp,
+              forceVlan: dataArg.forceVlan,
+              vlanId: dataArg.vlanId,
+            });
+            return { success: true };
+          } catch (err: unknown) {
+            return { success: false, message: (err as Error).message };
+          }
+        },
+      ),
+    );
+
+    // Delete a VPN client
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_DeleteVpnClient>(
+        'deleteVpnClient',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          if (!manager) {
+            return { success: false, message: 'VPN not configured' };
+          }
+
+          try {
+            await manager.removeClient(dataArg.clientId);
+            return { success: true };
+          } catch (err: unknown) {
+            return { success: false, message: (err as Error).message };
+          }
+        },
+      ),
+    );
+
+    // Enable a VPN client
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_EnableVpnClient>(
+        'enableVpnClient',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          if (!manager) {
+            return { success: false, message: 'VPN not configured' };
+          }
+
+          try {
+            await manager.enableClient(dataArg.clientId);
+            return { success: true };
+          } catch (err: unknown) {
+            return { success: false, message: (err as Error).message };
+          }
+        },
+      ),
+    );
+
+    // Disable a VPN client
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_DisableVpnClient>(
+        'disableVpnClient',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          if (!manager) {
+            return { success: false, message: 'VPN not configured' };
+          }
+
+          try {
+            await manager.disableClient(dataArg.clientId);
+            return { success: true };
+          } catch (err: unknown) {
+            return { success: false, message: (err as Error).message };
+          }
+        },
+      ),
+    );
+
+    // Rotate a VPN client's keys
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_RotateVpnClientKey>(
+        'rotateVpnClientKey',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          if (!manager) {
+            return { success: false, message: 'VPN not configured' };
+          }
+
+          try {
+            const bundle = await manager.rotateClientKey(dataArg.clientId);
+            return {
+              success: true,
+              wireguardConfig: bundle.wireguardConfig,
+            };
+          } catch (err: unknown) {
+            return { success: false, message: (err as Error).message };
+          }
+        },
+      ),
+    );
+
+    // Export a VPN client config
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ExportVpnClientConfig>(
+        'exportVpnClientConfig',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          if (!manager) {
+            return { success: false, message: 'VPN not configured' };
+          }
+
+          try {
+            const config = await manager.exportClientConfig(dataArg.clientId, dataArg.format);
+            return { success: true, config };
+          } catch (err: unknown) {
+            return { success: false, message: (err as Error).message };
+          }
+        },
+      ),
+    );
+
+    // Get telemetry for a specific VPN client
+    viewRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetVpnClientTelemetry>(
+        'getVpnClientTelemetry',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          if (!manager) {
+            return { success: false, message: 'VPN not configured' };
+          }
+
+          try {
+            const telemetry = await manager.getClientTelemetry(dataArg.clientId);
+            if (!telemetry) {
+              return { success: false, message: 'Client not found or not connected' };
+            }
+            return {
+              success: true,
+              telemetry: {
+                clientId: telemetry.clientId,
+                assignedIp: telemetry.assignedIp,
+                bytesSent: telemetry.bytesSent,
+                bytesReceived: telemetry.bytesReceived,
+                packetsDropped: telemetry.packetsDropped,
+                bytesDropped: telemetry.bytesDropped,
+                lastKeepaliveAt: telemetry.lastKeepaliveAt,
+                keepalivesReceived: telemetry.keepalivesReceived,
+                rateLimitBytesPerSec: telemetry.rateLimitBytesPerSec,
+                burstBytes: telemetry.burstBytes,
+              },
+            };
+          } catch (err: unknown) {
+            return { success: false, message: (err as Error).message };
+          }
+        },
+      ),
+    );
+  }
+}