v13.7.0

- Added new readme.statsgrid.md outlining the implementation plan for dees-statsgrid component.
- Replaced custom stats cards in ops-view-overview.ts and ops-view-network.ts with dees-statsgrid for better visualization.
- Introduced consistent color scheme for success, warning, error, and info states.
- Enhanced interactive features including click actions, context menus, and real-time updates.
- Developed ops-view-emails.ts for email management with features like composing, searching, and viewing emails.
- Integrated mock data generation for emails and network requests to facilitate testing.
- Added responsive design elements and improved UI consistency across components.

.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

@@ -19,4 +19,6 @@ dist_*/
 
 # custom
 **/.claude/settings.local.json
-data/
+.nogit/data/
+readme.plan.md
+.playwright-mcp/

.smartconfig.json

@@ -0,0 +1,85 @@
+{
+  "@git.zone/tswatch": {
+    "watchers": [
+      {
+        "name": "dcrouter-dev",
+        "watch": [
+          "ts/**/*.ts",
+          "ts_*/**/*.ts",
+          "test_watch/devserver.ts"
+        ],
+        "command": "pnpm run build && tsrun test_watch/devserver.ts",
+        "restart": true,
+        "debounce": 500,
+        "runOnStart": true
+      }
+    ]
+  },
+  "@git.zone/tsbundle": {
+    "bundles": [
+      {
+        "from": "./ts_web/index.ts",
+        "to": "./dist_serve/bundle.js",
+        "outputMode": "bundle",
+        "bundler": "esbuild",
+        "production": true,
+        "includeFiles": ["./html/**/*.html"]
+      }
+    ]
+  },
+  "@git.zone/cli": {
+    "projectType": "service",
+    "module": {
+      "githost": "gitlab.com",
+      "gitscope": "serve.zone",
+      "gitrepo": "dcrouter",
+      "description": "A traffic router intended to be gating your datacenter.",
+      "npmPackagename": "@serve.zone/dcrouter",
+      "license": "MIT",
+      "projectDomain": "serve.zone",
+      "keywords": [
+        "mail service",
+        "SMS",
+        "letter delivery",
+        "AI services",
+        "SMTP server",
+        "mail parsing",
+        "DKIM",
+        "traffic router",
+        "letterXpress",
+        "OpenAI",
+        "Anthropic AI",
+        "DKIM signing",
+        "mail forwarding",
+        "SMTP TLS",
+        "domain management",
+        "email templating",
+        "rule management",
+        "SMTP STARTTLS",
+        "DNS management"
+      ]
+    },
+    "release": {
+      "registries": [
+        "https://verdaccio.lossless.digital",
+        "https://registry.npmjs.org"
+      ],
+      "accessLevel": "public"
+    }
+  },
+  "@ship.zone/szci": {
+    "npmGlobalTools": [],
+    "dockerRegistryRepoMap": {
+      "registry.gitlab.com": "code.foss.global/serve.zone/dcrouter"
+    },
+    "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"]

cli.child.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+process.env.CLI_CALL = 'true';
+import * as cliTool from './ts/index.js';
+cliTool.runCli();

html/index.html

@@ -0,0 +1,121 @@
+<!--gitzone default-->
+<!-- made by Lossless GmbH -->
+<!-- checkout https://maintainedby.lossless.com for awesome OpenSource projects -->
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <!--Lets set some basic meta tags-->
+    <meta
+      name="viewport"
+      content="user-scalable=0, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width, height=device-height"
+    />
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <meta name="theme-color" content="#000000" />
+
+    <!--Lets make sure we recognize this as an PWA-->
+    <link rel="manifest" href="/manifest.json" />
+    <link rel="icon" type="image/png" href="/assetbroker/manifest/favicon.png" />
+
+    <!--Lets load standard fonts-->
+    <link rel="preconnect" href="https://assetbroker.lossless.one/" crossorigin>
+    <link rel="stylesheet" href="https://assetbroker.lossless.one/fonts/fonts.css">
+
+
+    <!--Lets avoid a rescaling flicker due to default body margins-->
+    <style>
+      html {
+        -ms-text-size-adjust: 100%;
+        -webkit-text-size-adjust: 100%;
+      }
+      body {
+        position: relative;
+        background: #000;
+        margin: 0px;
+      }
+    </style>
+    <script>
+      projectVersion = '';
+    </script>
+  </head>
+  <body>
+    <noscript>
+      <style>
+        body {
+          background: #303f9f;
+          font-family: Inter, Roboto, sans-serif;
+          color: #ffffff;
+        }
+
+        a {
+          color: #ffffff;
+          text-decoration: none;
+        }
+
+        .logo {
+          margin-top: 100px;
+          text-align: center;
+        }
+
+        img {
+          width: 130px;
+        }
+
+        .container {
+          width: 600px;
+          margin: auto;
+          margin-top: 20px;
+          box-shadow: 0px 0px 5px rgba(0, 0, 0, 0.3);
+          overflow: hidden;
+          border-radius: 3px;
+          background: #4357d9;
+        }
+        .contentHeader {
+          padding: 20px;
+          text-align: center;
+          font-size: 25px;
+          border-bottom: 1px solid rgba(255, 255, 255, 0.1);
+        }
+        .content {
+          padding: 20px;
+        }
+        .footer {
+          padding: 10px;
+          text-align: center;
+        }
+      </style>
+      <div class="logo">
+        <img src="https://assetbroker.lossless.one/brandfiles/lossless/svg-minimal-bright.svg" />
+      </div>
+      <div class="container">
+        <div class="contentHeader">We need JavaScript to run properly!</div>
+        <div class="content">
+          This site is being built using lit-element (made by Google). This technology works with
+          JavaScript. Subsequently this website does not work as intended by Lossless GmbH without
+          JavaScript.
+        </div>
+      </div>
+      <div class="footer">
+        <a href="https://lossless.gmbh">Legal Info</a> |
+        <a href="https://lossless.gmbh/privacy">Privacy Policy</a>
+      </div>
+    </noscript>
+    <script type="text/javascript" async defer>
+      window.revenueEnabled = true;
+      const runRevenueCheck = async () => {
+        var e = document.createElement('div');
+        e.id = '476kjuhzgtr764';
+        e.style.display = 'none';
+        document.body.appendChild(e);
+        if (document.getElementById('476kjuhzgtr764')) {
+          window.revenueEnabled = true;
+        } else {
+          window.revenueEnabled = false;
+        }
+        console.log(`revenue enabled: ${window.revenueEnabled}`);
+      };
+
+      runRevenueCheck();
+    </script>
+  </body>
+  <script defer type="module" src="/bundle.js"></script>
+</html>

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.

npmextra.json

@@ -1,46 +0,0 @@
-{
-  "gitzone": {
-    "projectType": "service",
-    "module": {
-      "githost": "gitlab.com",
-      "gitscope": "serve.zone",
-      "gitrepo": "platformservice",
-      "description": "A multifaceted platform service handling mail, SMS, letter delivery, and AI services.",
-      "npmPackagename": "@serve.zone/platformservice",
-      "license": "MIT",
-      "projectDomain": "serve.zone",
-      "keywords": [
-        "mail service",
-        "SMS",
-        "letter delivery",
-        "AI services",
-        "SMTP server",
-        "mail parsing",
-        "DKIM",
-        "platform service",
-        "mailgun integration",
-        "letterXpress",
-        "OpenAI",
-        "Anthropic AI",
-        "DKIM signing",
-        "mail forwarding",
-        "SMTP TLS",
-        "domain management",
-        "email templating",
-        "rule management",
-        "SMTP STARTTLS",
-        "DNS management"
-      ]
-    }
-  },
-  "npmci": {
-    "npmGlobalTools": [],
-    "dockerRegistryRepoMap": {
-      "registry.gitlab.com": "code.foss.global/serve.zone/platformservice"
-    },
-    "dockerBuildargEnvMap": {
-      "NPMCI_TOKEN_NPM2": "NPMCI_TOKEN_NPM2"
-    },
-    "npmRegistryUrl": "verdaccio.lossless.digital"
-  }
-}

package.json

@@ -1,56 +1,75 @@
 {
-  "name": "@serve.zone/platformservice",
-  "private": true,
-  "version": "2.5.0",
-  "description": "A multifaceted platform service handling mail, SMS, letter delivery, and AI services.",
-  "main": "dist_ts/index.js",
-  "typings": "dist_ts/index.d.ts",
+  "name": "@serve.zone/dcrouter",
+  "private": false,
+  "version": "13.7.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",
+    "./apiclient": "./dist_ts_apiclient/index.js"
+  },
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "scripts": {
-    "test": "(tstest test/)",
-    "start": "(node --max_old_space_size=250 ./cli.js)",
+    "test": "(tstest test/ --logfile --timeout 60)",
+    "start": "(node ./cli.js)",
     "startTs": "(node cli.ts.js)",
-    "build": "(tsbuild tsfolders --allowimplicitany)",
-    "localPublish": ""
+    "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": "^2.3.2",
-    "@git.zone/tsrun": "^1.2.8",
-    "@git.zone/tstest": "^1.0.88",
-    "@git.zone/tswatch": "^2.0.1",
-    "@push.rocks/tapbundle": "^6.0.3",
-    "@types/node": "^22.15.14"
+    "@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.0.19",
-    "@api.global/typedserver": "^3.0.74",
-    "@api.global/typedsocket": "^3.0.0",
-    "@apiclient.xyz/cloudflare": "^6.4.1",
-    "@push.rocks/projectinfo": "^5.0.1",
-    "@push.rocks/qenv": "^6.1.0",
-    "@push.rocks/smartacme": "^7.3.3",
-    "@push.rocks/smartdata": "^5.15.1",
-    "@push.rocks/smartdns": "^6.2.2",
-    "@push.rocks/smartfile": "^11.0.4",
-    "@push.rocks/smartlog": "^3.0.3",
-    "@push.rocks/smartmail": "^2.1.0",
-    "@push.rocks/smartpath": "^5.0.5",
-    "@push.rocks/smartpromise": "^4.0.3",
-    "@push.rocks/smartproxy": "^10.2.0",
-    "@push.rocks/smartrequest": "^2.1.0",
-    "@push.rocks/smartrule": "^2.0.1",
+    "@api.global/typedrequest": "^3.3.0",
+    "@api.global/typedrequest-interfaces": "^3.0.19",
+    "@api.global/typedserver": "^8.4.6",
+    "@api.global/typedsocket": "^4.1.2",
+    "@apiclient.xyz/cloudflare": "^7.1.0",
+    "@design.estate/dees-catalog": "^3.69.1",
+    "@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": "^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.2.2",
+    "@push.rocks/smartmetrics": "^3.0.3",
+    "@push.rocks/smartmigration": "1.1.1",
+    "@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": "^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.0",
-    "@serve.zone/interfaces": "^5.0.4",
-    "@tsclass/tsclass": "^9.2.0",
-    "@types/mailparser": "^3.4.6",
-    "ip": "^2.0.1",
-    "lru-cache": "^11.1.0",
-    "mailauth": "^4.8.4",
-    "mailparser": "^3.6.9",
-    "uuid": "^11.1.0"
+    "@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",
+    "@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": [
     "mail service",
@@ -60,8 +79,7 @@
     "SMTP server",
     "mail parsing",
     "DKIM",
-    "platform service",
-    "mailgun integration",
+    "mail router",
     "letterXpress",
     "OpenAI",
     "Anthropic AI",
@@ -72,7 +90,12 @@
     "email templating",
     "rule management",
     "SMTP STARTTLS",
-    "DNS management"
+    "DNS management",
+    "RADIUS",
+    "AAA",
+    "network authentication",
+    "VLAN assignment",
+    "MAC authentication"
   ],
   "pnpm": {
     "onlyBuiltDependencies": [
@@ -81,5 +104,19 @@
       "puppeteer"
     ]
   },
-  "packageManager": "pnpm@10.7.0+sha512.6b865ad4b62a1d9842b61d674a393903b871d9244954f652b8842c2b553c72176b278f64c463e52d40fff8aba385c235c8c9ecf5cc7de4fd78b8bb6d49633ab6"
+  "packageManager": "pnpm@10.11.0",
+  "files": [
+    "ts/**/*",
+    "ts_web/**/*",
+    "ts_apiclient/**/*",
+    "dist/**/*",
+    "dist_*/**/*",
+    "dist_ts/**/*",
+    "dist_ts_web/**/*",
+    "dist_ts_apiclient/**/*",
+    "assets/**/*",
+    "cli.js",
+    ".smartconfig.json",
+    "readme.md"
+  ]
 }

readme.hints.md

@@ -1,32 +1,347 @@
 # Implementation Hints and Learnings
 
+## smartmta Migration (2026-02-11)
+
+### Overview
+dcrouter's custom MTA code (~27,149 lines / 68 files in `ts/mail/` + `ts/deliverability/`) has been replaced with `@push.rocks/smartmta` v5.2.1, a TypeScript+Rust hybrid MTA. dcrouter is now an orchestrator that wires together SmartProxy, smartmta, smartdns, smartradius, and OpsServer.
+
+### Architecture
+- **No socket-handler mode** — smartmta's Rust SMTP server binds its own ports directly
+- **SmartProxy forward mode only** — external email ports forwarded to internal ports where smartmta listens
+- Email traffic flow: External Port → SmartProxy → Internal Port → smartmta UnifiedEmailServer
+
+### Key API Differences (smartmta vs old custom MTA)
+- `updateEmailRoutes()` instead of `updateRoutes()`
+- `dkimCreator` is public (no need for `(this.emailServer as any).dkimCreator`)
+- `bounceManager` is private, but exposed via public methods:
+  - `emailServer.getSuppressionList()`
+  - `emailServer.getHardBouncedAddresses()`
+  - `emailServer.getBounceHistory(email)`
+  - `emailServer.removeFromSuppressionList(email)`
+- `Email` class imported from `@push.rocks/smartmta`
+- `IAttachment` type accessed via `Core` namespace: `import { type Core } from '@push.rocks/smartmta'; type IAttachment = Core.IAttachment;`
+
+### Deleted Directories
+- `ts/mail/` (60 files) — replaced by smartmta
+- `ts/deliverability/` (3 files) — IPWarmupManager/SenderReputationMonitor will move to smartmta
+- `ts/errors/email.errors.ts`, `ts/errors/mta.errors.ts` — smartmta has its own errors
+- `ts/cache/documents/classes.cached.bounce.ts`, `classes.cached.suppression.ts`, `classes.cached.dkim.ts` — smartmta handles its own persistence
+
+### Remaining Cache Documents
+- `CachedEmail` — kept (dcrouter-level queue persistence)
+- `CachedIPReputation` — kept (dcrouter-level IP reputation caching)
+
+### Dependencies Removed
+mailauth, mailparser, @types/mailparser, ip, @push.rocks/smartmail, @push.rocks/smartrule, node-forge
+
+### Pre-existing Test Failures (not caused by migration)
+- `test/test.jwt-auth.ts` — `response.text is not a function` (webrequest compatibility issue)
+- `test/test.opsserver-api.ts` — same webrequest issue, timeouts
+
+### smartmta Location
+Source at `../../push.rocks/smartmta`, release with `gitzone commit -ypbrt`
+
+## Dependency Upgrade (2026-02-11)
+
+### SmartProxy v23.1.2 Route Validation
+- SmartProxy 23.1.2 enforces stricter route validation
+- Forward actions MUST use `targets` (array) instead of `target` (singular)
+- Test configurations that call `DcRouter.start()` need `cacheConfig: { enabled: false }` to avoid starting a real MongoDB process in tests
+
+```typescript
+// WRONG - will fail validation
+action: { type: 'forward', target: { host: 'localhost', port: 10025 } }
+
+// CORRECT
+action: { type: 'forward', targets: [{ host: 'localhost', port: 10025 }] }
+```
+
+**Files Fixed:**
+- `ts/classes.dcrouter.ts` - `generateEmailRoutes()` method
+- `test/test.dcrouter.email.ts` - Updated assertions and added `cacheConfig: { enabled: false }`
+
+## Dependency Upgrade (2026-02-10)
+
+### SmartProxy v23.1.0 Upgrade
+- `@push.rocks/smartproxy`: 22.4.2 → 23.1.0
+
+**Key Changes:**
+- Rust-based proxy components for improved performance
+- Rust binary runs as separate process via IPC
+- `getStatistics()` now returns `Promise<any>` (was synchronous)
+- nftables-proxy removed (not used by dcrouter)
+
+**Code Changes Required:**
+```typescript
+// Old (synchronous)
+const proxyStats = this.dcRouter.smartProxy.getStatistics();
+
+// New (async)
+const proxyStats = await this.dcRouter.smartProxy.getStatistics();
+```
+
+**Files Modified:**
+- `ts/monitoring/classes.metricsmanager.ts` - Added `await` to `getStatistics()` call
+
+## Dependency Upgrade (2026-02-01)
+
+### Major Upgrades Completed
+- `@api.global/typedserver`: 3.0.80 → 8.3.0
+- `@api.global/typedsocket`: 3.1.1 → 4.1.0
+- `@apiclient.xyz/cloudflare`: 6.4.3 → 7.1.0
+- `@design.estate/dees-catalog`: 1.12.4 → 3.41.4
+- `@push.rocks/smartpath`: 5.1.0 → 6.0.0
+- `@push.rocks/smartproxy`: 19.6.17 → 22.4.2
+- `@push.rocks/smartrequest`: 2.1.0 → 5.0.1
+- `uuid`: 11.1.0 → 13.0.0
+
+### Breaking Changes Fixed
+
+1. **SmartProxy v22**: `target` → `targets` (array)
+   ```typescript
+   // Old
+   action: { type: 'forward', target: { host: 'x', port: 25 } }
+   // New
+   action: { type: 'forward', targets: [{ host: 'x', port: 25 }] }
+   ```
+
+2. **SmartRequest v5**: `SmartRequestClient` → `SmartRequest`, `.body` → `.json()`
+   ```typescript
+   // Old
+   const resp = await plugins.smartrequest.SmartRequestClient.create()...post();
+   const json = resp.body;
+   // New
+   const resp = await plugins.smartrequest.SmartRequest.create()...post();
+   const json = await resp.json();
+   ```
+
+3. **dees-catalog v3**: Icon naming changed to library-prefixed format
+   ```typescript
+   // Old (deprecated but supported)
+   <dees-icon iconFA="check"></dees-icon>
+   // New
+   <dees-icon icon="fa:check"></dees-icon>
+   <dees-icon icon="lucide:menu"></dees-icon>
+   ```
+
+### TC39 Decorators
+- ts_web components updated to use `accessor` keyword for `@state()` decorators
+- Required for TC39 standard decorator support
+
+### tswatch Configuration
+The project now uses tswatch for development:
+```bash
+pnpm run watch
+```
+Configuration in `.smartconfig.json`:
+```json
+{
+  "@git.zone/tswatch": {
+    "watchers": [{
+      "name": "dcrouter-dev",
+      "watch": ["ts/**/*.ts", "ts_*/**/*.ts", "test_watch/devserver.ts"],
+      "command": "pnpm run build && tsrun test_watch/devserver.ts",
+      "restart": true,
+      "debounce": 500,
+      "runOnStart": true
+    }]
+  }
+}
+```
+
+## RADIUS Server Integration (2026-02-01)
+
+### Overview
+DcRouter now supports RADIUS server functionality for network authentication via `@push.rocks/smartradius`.
+
+### Key Features
+- **MAC Authentication Bypass (MAB)** - Authenticate network devices based on MAC address
+- **VLAN Assignment** - Assign VLANs based on MAC address or OUI patterns
+- **RADIUS Accounting** - Track sessions, data usage, and billing
+
+### Configuration Example
+```typescript
+const dcRouter = new DcRouter({
+  radiusConfig: {
+    authPort: 1812,      // Authentication port (default)
+    acctPort: 1813,      // Accounting port (default)
+    clients: [
+      {
+        name: 'switch-1',
+        ipRange: '192.168.1.0/24',
+        secret: 'shared-secret',
+        enabled: true
+      }
+    ],
+    vlanAssignment: {
+      defaultVlan: 100,   // VLAN for unknown MACs
+      allowUnknownMacs: true,
+      mappings: [
+        { mac: '00:11:22:33:44:55', vlan: 10, enabled: true },
+        { mac: '00:11:22', vlan: 20, enabled: true }  // OUI pattern
+      ]
+    },
+    accounting: {
+      enabled: true,
+      retentionDays: 30
+    }
+  }
+});
+```
+
+### Components
+- `RadiusServer` - Main server wrapping smartradius
+- `VlanManager` - MAC-to-VLAN mapping with OUI pattern support
+- `AccountingManager` - Session tracking and billing data
+
+### OpsServer API Endpoints
+- `getRadiusClients` / `setRadiusClient` / `removeRadiusClient` - Client management
+- `getVlanMappings` / `setVlanMapping` / `removeVlanMapping` - VLAN mappings
+- `testVlanAssignment` - Test what VLAN a MAC would get
+- `getRadiusSessions` / `disconnectRadiusSession` - Session management
+- `getRadiusStatistics` / `getRadiusAccountingSummary` - Statistics
+
+### Files
+- `ts/radius/` - RADIUS module
+- `ts/opsserver/handlers/radius.handler.ts` - OpsServer handler
+- `ts_interfaces/requests/radius.ts` - TypedRequest interfaces
+
+## Test Fix: test.dcrouter.email.ts (2026-02-01)
+
+### Issue
+The test `DcRouter class - Custom email storage path` was failing with "domainConfigs is not iterable".
+
+### Root Cause
+The test was using outdated email config properties:
+- Used `domainRules: []` (non-existent property)
+- Used `defaultMode` (non-existent property)
+- Missing required `domains: []` property
+- Missing required `routes: []` property
+- Referenced `router.unifiedEmailServer` instead of `router.emailServer`
+
+### Fix
+Updated the test to use the correct `IUnifiedEmailServerOptions` interface properties:
+```typescript
+const emailConfig: IEmailConfig = {
+  ports: [2525],
+  hostname: 'mail.example.com',
+  domains: [], // Required: domain configurations
+  routes: []   // Required: email routing rules
+};
+```
+
+And fixed the property name:
+```typescript
+expect(router.emailServer).toBeTruthy();  // Not unifiedEmailServer
+```
+
+### Key Learning
+When using `IUnifiedEmailServerOptions` (aliased as `IEmailConfig` in some tests):
+- `domains: IEmailDomainConfig[]` is required (array of domain configs)
+- `routes: IEmailRoute[]` is required (email routing rules)
+- Access the email server via `dcRouter.emailServer` not `dcRouter.unifiedEmailServer`
+
+## Network Metrics Implementation (2025-06-23)
+
+### SmartProxy Metrics API Integration
+- Updated to use new SmartProxy metrics API (v19.6.7)
+- Use `getMetrics()` for detailed metrics with grouped methods:
+  ```typescript
+  const metrics = smartProxy.getMetrics();
+  metrics.connections.active()      // Current active connections
+  metrics.throughput.instant()      // Real-time throughput {in, out}
+  metrics.connections.topIPs(10)    // Top 10 IPs by connection count
+  ```
+- Use `getStatistics()` for basic stats
+
+### Network Traffic Display
+- All throughput values shown in bits per second (kbit/s, Mbit/s, Gbit/s)
+- Conversion: `bytesPerSecond * 8 / 1000000` for Mbps
+- Network graph shows separate lines for inbound (green) and outbound (purple)
+- Throughput tiles and graph use same data source for consistency
+
+### Requests/sec vs Connections
+- Requests/sec shows HTTP request counts (derived from connections)
+- Single connection can handle multiple requests
+- Current implementation tracks connections, not individual requests
+- Trend line shows historical request counts, not throughput
+
+## DKIM Implementation Status (2025-05-30)
+
+**Note:** DKIM is now handled by `@push.rocks/smartmta`. The `dkimCreator` is a public property on `UnifiedEmailServer`.
+
 ## SmartProxy Usage
 
+### New Route-Based Architecture (v18+)
+- SmartProxy now uses a route-based configuration system
+- Routes define match criteria and actions instead of simple port-to-port forwarding
+- All traffic types (HTTP, HTTPS, TCP, WebSocket) are configured through routes
+
+```typescript
+// NEW: Route-based SmartProxy configuration
+const smartProxy = new plugins.smartproxy.SmartProxy({
+  routes: [
+    {
+      name: 'https-traffic',
+      match: {
+        ports: 443,
+        domains: ['example.com', '*.example.com']
+      },
+      action: {
+        type: 'forward',
+        target: {
+          host: 'backend.server.com',
+          port: 8080
+        }
+      },
+      tls: {
+        mode: 'terminate',
+        certificate: 'auto'
+      }
+    }
+  ],
+  defaults: {
+    target: {
+      host: 'fallback.server.com',
+      port: 8080
+    }
+  },
+  acme: {
+    accountEmail: 'admin@example.com',
+    enabled: true,
+    useProduction: true
+  }
+});
+```
+
+### Migration from Old to New
+```typescript
+// OLD configuration style (deprecated)
+{
+  fromPort: 443,
+  toPort: 8080,
+  targetIP: 'backend.server.com',
+  domainConfigs: [...]
+}
+
+// NEW route-based style
+{
+  routes: [{
+    name: 'main-route',
+    match: { ports: 443 },
+    action: {
+      type: 'forward',
+      target: { host: 'backend.server.com', port: 8080 }
+    }
+  }]
+}
+```
+
 ### Direct Component Usage
 - Use SmartProxy components directly instead of creating your own wrappers
 - SmartProxy already includes Port80Handler and NetworkProxy functionality
 - When using SmartProxy, configure it directly rather than instantiating Port80Handler or NetworkProxy separately
 
-```typescript
-// PREFERRED: Use SmartProxy with built-in ACME support
-const smartProxy = new plugins.smartproxy.SmartProxy({
-  fromPort: 443,
-  toPort: targetPort,
-  targetIP: targetServer,
-  sniEnabled: true,
-  acme: {
-    port: 80,
-    enabled: true,
-    autoRenew: true,
-    useProduction: true,
-    renewThresholdDays: 30,
-    accountEmail: contactEmail
-  },
-  globalPortRanges: [{ from: 443, to: 443 }],
-  domainConfigs: [/* domain configurations */]
-});
-```
-
 ### Certificate Management
 - SmartProxy has built-in ACME certificate management
 - Configure it in the `acme` property of SmartProxy options
@@ -48,15 +363,48 @@ const value = await qenv.getEnvVarOnDemand('ENV_VAR_NAME');
 
 ### SmartProxy Interfaces
 - Always check the interfaces from the node_modules to ensure correct property names
-- Important interfaces:
-  - `ISmartProxyOptions`: Main configuration for SmartProxy
+- Important interfaces for the new architecture:
+  - `ISmartProxyOptions`: Main configuration with `routes` array
+  - `IRouteConfig`: Individual route configuration
+  - `IRouteMatch`: Match criteria for routes
+  - `IRouteTarget`: Target configuration for forwarding
   - `IAcmeOptions`: ACME certificate configuration
-  - `IDomainConfig`: Domain-specific configuration
+  - `TTlsMode`: TLS handling modes ('passthrough' | 'terminate' | 'terminate-and-reencrypt')
+
+### New Route Configuration
+```typescript
+interface IRouteConfig {
+  name: string;
+  match: {
+    ports: number | number[];
+    domains?: string | string[];
+    path?: string;
+    headers?: Record<string, string | RegExp>;
+  };
+  action: {
+    type: 'forward' | 'redirect' | 'block' | 'static';
+    target?: {
+      host: string | string[] | ((context) => string);
+      port: number | 'preserve' | ((context) => number);
+    };
+  };
+  tls?: {
+    mode: TTlsMode;
+    certificate?: 'auto' | { key: string; cert: string; };
+  };
+  security?: {
+    authentication?: IRouteAuthentication;
+    rateLimit?: IRouteRateLimit;
+    ipAllowList?: string[];
+    ipBlockList?: string[];
+  };
+}
+```
 
 ### Required Properties
-- Remember to include all required properties in your interface implementations
-- For `ISmartProxyOptions`, `globalPortRanges` is required
+- For `ISmartProxyOptions`, `routes` array is the main configuration
 - For `IAcmeOptions`, use `accountEmail` for the contact email
+- Routes must have `name`, `match`, and `action` properties
 
 ## Testing
 
@@ -93,4 +441,333 @@ tap.test('stop', async () => {
 ### Component Integration
 - Leverage built-in integrations between components (like SmartProxy's ACME handling)
 - Use parallel operations for performance (like in the `stop()` method)
-- Separate concerns clearly (HTTP handling vs. SMTP handling)
+- Separate concerns clearly (HTTP handling vs. SMTP handling)
+
+## Email Integration with SmartProxy
+
+### Architecture (Post-Migration)
+- Email traffic is routed through SmartProxy using automatic route generation
+- smartmta's UnifiedEmailServer runs on internal ports and receives forwarded traffic from SmartProxy
+- SmartProxy handles external ports (25, 587, 465) and forwards to internal ports
+- smartmta's Rust SMTP bridge handles SMTP protocol processing
+
+### Port Mapping
+- External port 25 → Internal port 10025 (SMTP)
+- External port 587 → Internal port 10587 (Submission)
+- External port 465 → Internal port 10465 (SMTPS)
+
+### TLS Handling
+- Ports 25 and 587: Use 'passthrough' mode (STARTTLS handled by smartmta)
+- Port 465: Use 'terminate' mode (SmartProxy handles TLS termination)
+
+## SmartMetrics Integration (2025-06-12) - COMPLETED
+
+### Overview
+Fixed the UI metrics display to show accurate CPU and memory data from SmartMetrics.
+
+### Key Findings
+1. **CPU Metrics:**
+   - SmartMetrics provides `cpuUsageText` as a string percentage
+   - MetricsManager parses it as `cpuUsage.user` (system is always 0)
+   - UI was incorrectly dividing by 2, showing half the actual CPU usage
+
+2. **Memory Metrics:**
+   - SmartMetrics calculates `maxMemoryMB` as minimum of:
+     - V8 heap size limit
+     - System total memory
+     - Docker memory limit (if available)
+   - Provides `memoryUsageBytes` (total process memory including children)
+   - Provides `memoryPercentage` (pre-calculated percentage)
+   - UI was only showing heap usage, missing actual memory constraints
+
+### Changes Made
+1. **MetricsManager Enhanced:**
+   - Added `maxMemoryMB` from SmartMetrics instance
+   - Added `actualUsageBytes` from SmartMetrics data
+   - Added `actualUsagePercentage` from SmartMetrics data
+   - Kept existing memory fields for compatibility
+
+2. **Interface Updated:**
+   - Added optional fields to `IServerStats.memoryUsage`
+   - Fields are optional to maintain backward compatibility
+
+3. **UI Fixed:**
+   - Removed incorrect CPU division by 2
+   - Uses `actualUsagePercentage` when available (falls back to heap percentage)
+   - Shows actual memory usage vs max memory limit (not just heap)
+
+### Result
+- CPU now shows accurate usage percentage
+- Memory shows percentage of actual constraints (Docker/system/V8 limits)
+- Better monitoring for containerized environments
+
+## Network UI Implementation (2025-06-20) - COMPLETED
+
+### Overview
+Revamped the Network UI to display real network data from SmartProxy instead of mock data.
+
+### Architecture
+1. **MetricsManager Integration:**
+   - Already integrates with SmartProxy via `dcRouter.smartProxy.getStats()`
+   - Extended with `getNetworkStats()` method to expose unused metrics:
+     - `getConnectionsByIP()` - Connection counts by IP address
+     - `getThroughputRate()` - Real-time bandwidth rates (bytes/second)
+     - `getTopIPs()` - Top connecting IPs sorted by connection count
+   - Note: SmartProxy base interface doesn't include all methods, manual implementation required
+
+2. **Existing Infrastructure Leveraged:**
+   - `getActiveConnections` endpoint already exists in security.handler.ts
+   - Enhanced to include real SmartProxy data via MetricsManager
+   - IConnectionInfo interface already supports network data structures
+
+3. **State Management:**
+   - Added `INetworkState` interface following existing patterns
+   - Created `networkStatePart` with connections, throughput, and IP data
+   - Integrated with existing auto-refresh mechanism
+
+4. **UI Changes (Minimal):**
+   - Removed `generateMockData()` method and all mock generation
+   - Connected to real `networkStatePart` state
+   - Added `renderTopIPs()` section to display top connected IPs
+   - Updated traffic chart to show real request data
+   - Kept all existing UI components (DeesTable, DeesChartArea)
+
+### Implementation Details
+1. **Data Transformation:**
+   - Converts IConnectionInfo[] to INetworkRequest[] for table display
+   - Calculates traffic buckets based on selected time range
+   - Maps connection data to chart-compatible format
+
+2. **Real Metrics Displayed:**
+   - Active connections count (from server stats)
+   - Requests per second (calculated from recent connections)
+   - Throughput rates (currently showing 0 until SmartProxy exposes rates)
+   - Top IPs with connection counts and percentages
+
+3. **TypeScript Fixes:**
+   - SmartProxy methods like `getThroughputRate()` not in base interface
+   - Implemented manual fallbacks for missing methods
+   - Fixed `publicIpv4` → `publicIp` property name
+
+### Result
+- Network view now shows real connection activity
+- Auto-refreshes with other stats every second
+- Displays actual IPs and connection counts
+- No more mock/demo data
+- Minimal code changes (streamlined approach)
+
+### Throughput Data Fix (2025-06-20)
+The throughput was showing 0 because:
+1. MetricsManager was hardcoding throughputRate to 0, assuming the method didn't exist
+2. SmartProxy's `getStats()` returns `IProxyStats` interface, but the actual object (`MetricsCollector`) implements `IProxyStatsExtended`
+3. `getThroughputRate()` only exists in the extended interface
+
+**Solution implemented:**
+1. Updated MetricsManager to check if methods exist at runtime and call them
+2. Added property name mapping (`bytesInPerSec` → `bytesInPerSecond`)
+3. Created new `getNetworkStats` endpoint in security.handler.ts
+4. Updated frontend to call the new endpoint for complete network metrics
+
+The throughput data now flows correctly from SmartProxy → MetricsManager → API → UI.
+
+## Email Operations Dashboard (2026-02-01)
+
+### Overview
+Replaced mock data in the email UI with real backend data from the delivery queue and security logger.
+
+### New Files Created
+- `ts_interfaces/requests/email-ops.ts` - TypedRequest interfaces for email operations
+- `ts/opsserver/handlers/email-ops.handler.ts` - Backend handler for email operations
+
+### Key Interfaces
+- `IReq_GetQueuedEmails` - Fetch emails from delivery queue by status
+- `IReq_GetSentEmails` - Fetch delivered emails
+- `IReq_GetFailedEmails` - Fetch failed emails
+- `IReq_ResendEmail` - Re-queue a failed email for retry
+- `IReq_GetSecurityIncidents` - Fetch security events from SecurityLogger
+- `IReq_GetBounceRecords` - Fetch bounce records and suppression list
+- `IReq_RemoveFromSuppressionList` - Remove email from suppression list
+
+### UI Changes (ops-view-emails.ts)
+- Replaced mock folders (inbox/sent/draft/trash) with operations views:
+  - **Queued**: Emails pending delivery
+  - **Sent**: Successfully delivered emails
+  - **Failed**: Failed emails with resend capability
+  - **Security**: Security incidents from SecurityLogger
+- Removed `generateMockEmails()` method
+- Added state management via `emailOpsStatePart` in appstate.ts
+- Added resend button for failed emails
+- Added security incident detail view
+
+### Data Flow
+```
+UnifiedDeliveryQueue → EmailOpsHandler → TypedRequest → Frontend State → UI
+SecurityLogger → EmailOpsHandler → TypedRequest → Frontend State → UI
+BounceManager → EmailOpsHandler → TypedRequest → Frontend State → UI
+```
+
+### Backend Data Access
+The handler accesses data from:
+- `dcRouter.emailServer.deliveryQueue` - Email queue items (IQueueItem)
+- `SecurityLogger.getInstance()` - Security events (ISecurityEvent)
+- `emailServer.bounceManager` - Bounce records and suppression list
+
+## OpsServer UI Fixes (2026-02-02)
+
+### Configuration Page Fix
+The configuration page had field name mismatches between frontend and backend:
+- Frontend expected `server` and `storage` sections
+- Backend returns `proxy` section (not `server`)
+- Backend has no `storage` section
+
+**Fix**: Updated `ops-view-config.ts` to use correct section names:
+- `proxy` instead of `server`
+- Removed non-existent `storage` section
+- Added optional chaining (`?.`) for safety
+
+### Auth Persistence Fix
+Login state was using `'soft'` mode in Smartstate which is memory-only:
+- User login was lost on page refresh
+- State reset to logged out after browser restart
+
+**Changes**:
+1. `ts_web/appstate.ts`: Changed loginStatePart from `'soft'` to `'persistent'`
+   - Now uses IndexedDB to persist across browser sessions
+2. `ts/opsserver/handlers/admin.handler.ts`: JWT expiry changed from 7 days to 24 hours
+3. `ts_web/elements/ops-dashboard.ts`: Added JWT expiry check on session restore
+   - Validates stored JWT hasn't expired before auto-logging in
+   - Clears expired sessions and shows login form
+
+## Config UI Read-Only Conversion (2026-02-03)
+
+### Overview
+The configuration UI has been converted from an editable interface to a read-only display. DcRouter is configured through code or remotely, not through the UI.
+
+### Changes Made
+
+1. **Backend (`ts/opsserver/handlers/config.handler.ts`)**:
+   - Removed `updateConfiguration` handler
+   - Removed `updateConfiguration()` private method
+   - Kept `getConfiguration` handler (read-only)
+
+2. **Interfaces (`ts_interfaces/requests/config.ts`)**:
+   - Removed `IReq_UpdateConfiguration` interface
+   - Kept `IReq_GetConfiguration` interface
+
+3. **Frontend (`ts_web/elements/ops-view-config.ts`)**:
+   - Removed `editingSection` and `editedConfig` state properties
+   - Removed `startEdit()`, `cancelEdit()`, `saveConfig()` methods
+   - Removed Edit/Save/Cancel buttons
+   - Removed warning banner about immediate changes
+   - Enhanced read-only display with:
+     - Status badges for boolean values (enabled/disabled)
+     - Array display as pills/tags with counts
+     - Section icons (mail, globe, network, shield)
+     - Better formatting for numbers and byte sizes
+     - Empty state handling ("Not configured", "None configured")
+     - Info note explaining configuration is read-only
+
+4. **State Management (`ts_web/appstate.ts`)**:
+   - Removed `updateConfigurationAction`
+   - Kept `fetchConfigurationAction` (read-only)
+
+5. **Tests (`test/test.protected-endpoint.ts`)**:
+   - Replaced `updateConfiguration` tests with `verifyIdentity` tests
+   - Added test for read-only config access
+   - Kept auth flow testing with different protected endpoint
+
+6. **Documentation**:
+   - `readme.md`: Updated API endpoints to show config as read-only
+   - `ts_web/readme.md`: Removed `updateConfigurationAction` from actions list
+   - `ts_interfaces/readme.md`: Removed `IReq_UpdateConfiguration` from table
+
+### Visual Display Features
+- Boolean values shown as colored badges (green=enabled, red=disabled)
+- Arrays displayed as pills with count summaries
+- Section headers with relevant Lucide icons
+- Numbers formatted with locale separators
+- Byte sizes auto-formatted (B, KB, MB, GB)
+- Time values shown with "seconds" suffix
+- Nested objects with visual indentation
+
+## Smartdata Cache System (2026-02-03)
+
+### Overview
+DcRouter now uses smartdata + LocalTsmDb for persistent caching. Data is stored at `~/.serve.zone/dcrouter/tsmdb`.
+
+### Technology Stack
+| Layer | Package | Purpose |
+|-------|---------|---------|
+| ORM | `@push.rocks/smartdata` | Document classes, decorators, queries |
+| Database | `@push.rocks/smartmongo` (LocalTsmDb) | Embedded TsmDB via Unix socket |
+
+### TC39 Decorators
+The project uses TC39 Stage 3 decorators (not experimental decorators). The tsconfig was updated:
+- Removed `experimentalDecorators: true`
+- Removed `emitDecoratorMetadata: true`
+
+This is required for smartdata v7+ compatibility.
+
+### Cache Document Classes
+Located in `ts/cache/documents/`:
+
+| Class | Purpose | Default TTL |
+|-------|---------|-------------|
+| `CachedEmail` | Email queue items | 30 days |
+| `CachedIPReputation` | IP reputation lookups | 24 hours |
+
+Note: CachedBounce, CachedSuppression, and CachedDKIMKey were removed in the smartmta migration (smartmta handles its own persistence for those).
+
+### Usage Pattern
+```typescript
+// Document classes use smartdata decorators
+@plugins.smartdata.Collection(() => getDb())
+export class CachedEmail extends CachedDocument<CachedEmail> {
+  @plugins.smartdata.svDb()
+  public createdAt: Date = new Date();
+
+  @plugins.smartdata.svDb()
+  public expiresAt: Date = new Date(Date.now() + TTL.DAYS_30);
+
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public id: string;
+  // ...
+}
+
+// Query examples
+const email = await CachedEmail.getInstance({ id: 'abc123' });
+const pending = await CachedEmail.getInstances({ status: 'pending' });
+await email.save();
+await email.delete();
+```
+
+### Configuration
+```typescript
+const dcRouter = new DcRouter({
+  cacheConfig: {
+    enabled: true,
+    storagePath: '~/.serve.zone/dcrouter/tsmdb',
+    dbName: 'dcrouter',
+    cleanupIntervalHours: 1,
+    ttlConfig: {
+      emails: 30,       // days
+      ipReputation: 1,  // days
+      bounces: 30,      // days
+      dkimKeys: 90,     // days
+      suppression: 30   // days
+    }
+  }
+});
+```
+
+### Cache Cleaner
+- Runs hourly by default (configurable via `cleanupIntervalHours`)
+- Finds and deletes documents where `expiresAt < now()`
+- Uses smartdata's `getInstances()` + `delete()` pattern
+
+### Key Files
+- `ts/cache/classes.cachedb.ts` - CacheDb singleton wrapper
+- `ts/cache/classes.cached.document.ts` - Base class with TTL support
+- `ts/cache/classes.cache.cleaner.ts` - Periodic cleanup service
+- `ts/cache/documents/*.ts` - Document class definitions

readme.plan.md

@@ -1,172 +0,0 @@
-# DcRouter Improvement Plan
-
-## Objective
-Create a new version of DcRouter that doesn't rely on SzPlatformService but instead uses SmartProxy and the complete email stack directly. This will make DcRouter more modular, lightweight, and capable of SMTP forwarding with the email stack.
-
-## 1. Core Architecture Changes
-
-### 1.1 Remove SzPlatformService Dependency
-- [x] Remove the `platformServiceInstance` option from `IDcRouterOptions`
-  - Update `classes.dcrouter.ts` to remove platformServiceInstance from the options interface
-  - Create a new utility class `DcRouterEnvironment` to handle environment variables directly using qenv
-  - Replace all uses of SzDcRouterConnector with direct calls to DcRouterEnvironment
-
-### 1.2 Direct Integration with Email Stack
-- [x] Add options for direct MtaService integration
-  - Enhance the existing mtaConfig/mtaServiceInstance options to include all necessary MTA configuration
-  - Add new options for email forwarding capabilities that will be passed to the MTA service
-  - Implement initializers for setting up MTA with or without existing instances
-- [x] Create a new SMTP forwarding configuration interface
-  - Create `ISmtpForwardingConfig` interface with fields for destination domains, routing rules, and authentication
-  - Implement domain-to-server mapping for routing emails to appropriate SMTP servers
-  - Add options for SMTP authentication methods (PLAIN, LOGIN, OAUTH2)
-- [x] Implement proper connection between SmartProxy and MTA service
-  - Update `configureSmtpProxy()` method to create bidirectional communication with MTA service
-  - Implement proxy protocol support for preserving client IP addresses during SMTP forwarding
-  - Create listener for MTA status changes to adjust proxy settings dynamically
-
-## 2. SmartProxy Configuration
-
-### 2.1 Enhanced SmartProxy Integration
-- [x] Update `SmartProxy` configuration for better TCP/SNI handling
-  - Modify initialization to support more advanced SNI-based routing decisions
-- [x] Add specific configuration for SMTP ports (25, 465, 587)
-  - Create a `SmtpPortConfig` class to manage SMTP-specific port settings
-  - Add TLS termination options specific to SMTP protocols (STARTTLS vs. implicit TLS)
-  - Implement connection rate limiting and concurrent connection management for SMTP ports
-
-### 2.2 Routing Configuration
-- [x] Allow domain-based routing for email traffic
-  - Add domain matching patterns with wildcard support for inbound email routing
-  - Implement sender domain-based routing for outbound emails
-  - Create domain groups for applying consistent rules across related domains
-- [x] Implement IP-based allow/block lists for advanced filtering
-  - Develop IP range and CIDR notation support for filtering
-  - Create separate lists for inbound and outbound connections
-  - Implement geo-based filtering using IP geolocation
-
-## 3. SMTP Forwarding Functionality
-
-### 3.1 SMTP Routing Engine
-- [x] Enhance the SMTP rule engine to support advanced forwarding scenarios
-  - Extend email routing capabilities with SmartProxy configuration
-  - Add context information to routing for making informed routing decisions
-  - Implement domain-based routing for traffic management
-- [x] Create efficient routing for common email patterns
-  - Develop email forwarding configuration for common use cases
-  - Implement domain-to-server mapping for email routing
-  - Create simple but effective routing mechanisms
-- [x] Implement per-domain routing configuration
-  - Create domain configuration support in SmtpForwardingConfig
-  - Implement dynamic updating of domain routes
-  - Add domain-level connection handling
-
-### 3.2 MTA Integration
-- [x] Configure MTA service for use with DcRouter
-  - Extend DcRouter to work with existing MTA configuration
-  - Implement proper MTA service initialization and startup
-  - Create clean integration between DcRouter and MTA
-- [x] Implement SMTP forwarding as alternative to MTA
-  - Add SMTP forwarding configuration for simpler deployments
-  - Implement SmartProxy configuration for SMTP traffic
-  - Create clean separation between MTA and forwarding modes
-- [x] Maintain email traffic integrity
-  - Ensure proper handling of connections between services
-  - Implement source IP preservation for proper tracking
-  - Create configuration options for security settings
-
-## 4. Implementation Tasks
-
-### 4.1 Create New Classes
-- [x] Create utility classes to handle configuration
-  - Implement `DcRouterEnvironment` for environment variable access
-  - Create `SmtpPortConfig` for managing SMTP port settings
-  - Implement `EmailDomainRouter` for email domain routing
-- [x] Develop SMTP-specific functionality
-  - Create specialized configuration for SMTP traffic
-  - Implement port configuration for different SMTP protocols
-  - Add TLS options handling for SMTP ports
-- [x] Implement certificate management
-  - Utilize SmartProxy's Port80Handler for ACME certificate management
-  - Add certificate application to NetworkProxy
-  - Create certificate event handling
-
-### 4.2 Update Existing Components
-- [x] Refactor `DcRouter` class to remove SzPlatformService dependencies
-  - Remove all direct references to SzPlatformService
-  - Update constructor to use new configuration system
-  - Refactor initialization logic to work independently
-- [x] Update certificate handling to use SmartACME directly
-  - Implement Port80Handler for ACME certificate management
-  - Add automatic certificate renewal with event handling
-  - Apply certificates to appropriate services
-- [x] Enhance SmartProxy configuration for better SMTP support
-  - Implement separate SmartProxy instances for different protocols
-  - Add TLS settings for different SMTP ports (STARTTLS vs. implicit TLS)
-  - Create clean service lifecycle management
-
-### 4.3 Configuration Interface
-- [x] Create a clean, declarative configuration interface
-  - Design structured TypeScript interfaces for all configuration options
-  - Implement simple, focused configuration objects
-  - Create clean separation between different component configurations
-- [x] Support environment variables and programmatic configuration
-  - Create DcRouterEnvironment for environment variable access
-  - Implement environment variable caching for better performance
-  - Allow programmatic configuration updates
-- [x] Implement well-defined configuration APIs
-  - Add typed interfaces for all configuration options
-  - Create clear documentation in interface comments
-  - Implement runtime configuration updating
-
-## 5. Testing and Documentation
-
-### 5.1 Code Implementation
-- [x] Implement core components
-  - Create new classes for configuration and domain routing
-  - Update existing DcRouter with new functionality
-  - Implement environment variable handling
-- [x] Implement SMTP functionality
-  - Add SMTP forwarding configuration
-  - Implement port-specific settings
-  - Create domain-based email routing
-- [x] Implement HTTP/HTTPS functionality
-  - Add NetworkProxy integration
-  - Implement certificate management
-  - Create domain-based HTTP routing
-
-### 5.2 Quality and Performance
-- [x] Ensure code quality
-  - Fix all TypeScript errors
-  - Implement clean interfaces
-  - Create well-documented code
-- [x] Optimize for performance
-  - Implement parallel service shutdown
-  - Use environment variable caching
-  - Create efficient routing lookups
-- [x] Maintain compatibility
-  - Ensure backward compatibility where possible
-  - Create clean extension points
-  - Maintain consistent APIs
-
-## 6. Future Enhancements (Pending)
-
-### 6.1 Testing
-- [ ] Create unit tests for all components
-  - Test environment variable handling
-  - Test domain routing logic
-  - Test certificate management
-- [ ] Create integration tests
-  - Test email forwarding between domains
-  - Test HTTP/HTTPS routing
-  - Test TLS connections
-
-### 6.2 Documentation
-- [ ] Create comprehensive user documentation
-  - Add setup guide for common scenarios
-  - Document all configuration options
-  - Provide example configurations
-- [ ] Create API documentation
-  - Document all public interfaces
-  - Add usage examples
-  - Create integration examples

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/readme.md

@@ -0,0 +1,443 @@
+# DCRouter SMTP Test Suite
+
+```
+test/
+├── readme.md                              # This file
+├── helpers/
+│   ├── server.loader.ts                  # SMTP server lifecycle management
+│   ├── utils.ts                          # Common test utilities
+│   └── smtp.client.ts                    # Test SMTP client utilities
+└── suite/
+    ├── smtpserver_commands/              # SMTP command tests (CMD)
+    ├── smtpserver_connection/            # Connection management tests (CM)
+    ├── smtpserver_edge-cases/            # Edge case tests (EDGE)
+    ├── smtpserver_email-processing/      # Email processing tests (EP)
+    ├── smtpserver_error-handling/        # Error handling tests (ERR)
+    ├── smtpserver_performance/           # Performance tests (PERF)
+    ├── smtpserver_reliability/           # Reliability tests (REL)
+    ├── smtpserver_rfc-compliance/        # RFC compliance tests (RFC)
+    └── smtpserver_security/              # Security tests (SEC)
+```
+
+## Test ID Convention
+
+All test files follow a strict naming convention: `test.<category-id>.<description>.ts`
+
+Examples:
+- `test.cmd-01.ehlo-command.ts` - EHLO command test
+- `test.cm-01.tls-connection.ts` - TLS connection test
+- `test.sec-01.authentication.ts` - Authentication test
+
+## Test Categories
+
+### 1. Connection Management (CM)
+
+Tests for validating SMTP connection handling, TLS support, and connection lifecycle management.
+
+| ID    | Test Description                          | Priority | Implementation |
+|-------|-------------------------------------------|----------|----------------|
+| CM-01 | TLS Connection Test                       | High     | `suite/smtpserver_connection/test.cm-01.tls-connection.ts` |
+| CM-02 | Multiple Simultaneous Connections         | High     | `suite/smtpserver_connection/test.cm-02.multiple-connections.ts` |
+| CM-03 | Connection Timeout                        | High     | `suite/smtpserver_connection/test.cm-03.connection-timeout.ts` |
+| CM-04 | Connection Limits                         | Medium   | `suite/smtpserver_connection/test.cm-04.connection-limits.ts` |
+| CM-05 | Connection Rejection                      | Medium   | `suite/smtpserver_connection/test.cm-05.connection-rejection.ts` |
+| CM-06 | STARTTLS Connection Upgrade               | High     | `suite/smtpserver_connection/test.cm-06.starttls-upgrade.ts` |
+| CM-07 | Abrupt Client Disconnection               | Medium   | `suite/smtpserver_connection/test.cm-07.abrupt-disconnection.ts` |
+| CM-08 | TLS Version Compatibility                 | Medium   | `suite/smtpserver_connection/test.cm-08.tls-versions.ts` |
+| CM-09 | TLS Cipher Configuration                  | Medium   | `suite/smtpserver_connection/test.cm-09.tls-ciphers.ts` |
+| CM-10 | Plain Connection Test                     | Low      | `suite/smtpserver_connection/test.cm-10.plain-connection.ts` |
+| CM-11 | TCP Keep-Alive Test                       | Low      | `suite/smtpserver_connection/test.cm-11.keepalive.ts` |
+
+### 2. SMTP Commands (CMD)
+
+Tests for validating proper SMTP protocol command implementation.
+
+| ID     | Test Description                          | Priority | Implementation |
+|--------|-------------------------------------------|----------|----------------|
+| CMD-01 | EHLO Command                              | High     | `suite/smtpserver_commands/test.cmd-01.ehlo-command.ts` |
+| CMD-02 | MAIL FROM Command                         | High     | `suite/smtpserver_commands/test.cmd-02.mail-from.ts` |
+| CMD-03 | RCPT TO Command                           | High     | `suite/smtpserver_commands/test.cmd-03.rcpt-to.ts` |
+| CMD-04 | DATA Command                              | High     | `suite/smtpserver_commands/test.cmd-04.data-command.ts` |
+| CMD-05 | NOOP Command                              | Medium   | `suite/smtpserver_commands/test.cmd-05.noop-command.ts` |
+| CMD-06 | RSET Command                              | Medium   | `suite/smtpserver_commands/test.cmd-06.rset-command.ts` |
+| CMD-07 | VRFY Command                              | Low      | `suite/smtpserver_commands/test.cmd-07.vrfy-command.ts` |
+| CMD-08 | EXPN Command                              | Low      | `suite/smtpserver_commands/test.cmd-08.expn-command.ts` |
+| CMD-09 | SIZE Extension                            | Medium   | `suite/smtpserver_commands/test.cmd-09.size-extension.ts` |
+| CMD-10 | HELP Command                              | Low      | `suite/smtpserver_commands/test.cmd-10.help-command.ts` |
+| CMD-11 | Command Pipelining                        | Medium   | `suite/smtpserver_commands/test.cmd-11.command-pipelining.ts` |
+| CMD-12 | HELO Command                              | Low      | `suite/smtpserver_commands/test.cmd-12.helo-command.ts` |
+| CMD-13 | QUIT Command                              | High     | `suite/smtpserver_commands/test.cmd-13.quit-command.ts` |
+
+### 3. Email Processing (EP)
+
+Tests for validating email content handling, parsing, and delivery.
+
+| ID    | Test Description                          | Priority | Implementation |
+|-------|-------------------------------------------|----------|----------------|
+| EP-01 | Basic Email Sending                       | High     | `suite/smtpserver_email-processing/test.ep-01.basic-email-sending.ts` |
+| EP-02 | Invalid Email Address Handling            | High     | `suite/smtpserver_email-processing/test.ep-02.invalid-email-addresses.ts` |
+| EP-03 | Multiple Recipients                       | Medium   | `suite/smtpserver_email-processing/test.ep-03.multiple-recipients.ts` |
+| EP-04 | Large Email Handling                      | High     | `suite/smtpserver_email-processing/test.ep-04.large-email.ts` |
+| EP-05 | MIME Handling                             | High     | `suite/smtpserver_email-processing/test.ep-05.mime-handling.ts` |
+| EP-06 | Attachment Handling                       | Medium   | `suite/smtpserver_email-processing/test.ep-06.attachment-handling.ts` |
+| EP-07 | Special Character Handling                | Medium   | `suite/smtpserver_email-processing/test.ep-07.special-character-handling.ts` |
+| EP-08 | Email Routing                             | High     | `suite/smtpserver_email-processing/test.ep-08.email-routing.ts` |
+| EP-09 | Delivery Status Notifications             | Medium   | `suite/smtpserver_email-processing/test.ep-09.delivery-status-notifications.ts` |
+
+### 4. Security (SEC)
+
+Tests for validating security features and protections.
+
+| ID     | Test Description                          | Priority | Implementation |
+|--------|-------------------------------------------|----------|----------------|
+| SEC-01 | Authentication                            | High     | `suite/smtpserver_security/test.sec-01.authentication.ts` |
+| SEC-02 | Authorization                             | High     | `suite/smtpserver_security/test.sec-02.authorization.ts` |
+| SEC-03 | DKIM Processing                           | High     | `suite/smtpserver_security/test.sec-03.dkim-processing.ts` |
+| SEC-04 | SPF Checking                              | High     | `suite/smtpserver_security/test.sec-04.spf-checking.ts` |
+| SEC-05 | DMARC Policy Enforcement                  | Medium   | `suite/smtpserver_security/test.sec-05.dmarc-policy.ts` |
+| SEC-06 | IP Reputation Checking                    | High     | `suite/smtpserver_security/test.sec-06.ip-reputation.ts` |
+| SEC-07 | Content Scanning                          | Medium   | `suite/smtpserver_security/test.sec-07.content-scanning.ts` |
+| SEC-08 | Rate Limiting                             | High     | `suite/smtpserver_security/test.sec-08.rate-limiting.ts` |
+| SEC-09 | TLS Certificate Validation                | High     | `suite/smtpserver_security/test.sec-09.tls-certificate-validation.ts` |
+| SEC-10 | Header Injection Prevention               | High     | `suite/smtpserver_security/test.sec-10.header-injection-prevention.ts` |
+| SEC-11 | Bounce Management                         | Medium   | `suite/smtpserver_security/test.sec-11.bounce-management.ts` |
+
+### 5. Error Handling (ERR)
+
+Tests for validating proper error handling and recovery.
+
+| ID     | Test Description                          | Priority | Implementation |
+|--------|-------------------------------------------|----------|----------------|
+| ERR-01 | Syntax Error Handling                     | High     | `suite/smtpserver_error-handling/test.err-01.syntax-errors.ts` |
+| ERR-02 | Invalid Sequence Handling                 | High     | `suite/smtpserver_error-handling/test.err-02.invalid-sequence.ts` |
+| ERR-03 | Temporary Failure Handling                | Medium   | `suite/smtpserver_error-handling/test.err-03.temporary-failures.ts` |
+| ERR-04 | Permanent Failure Handling                | Medium   | `suite/smtpserver_error-handling/test.err-04.permanent-failures.ts` |
+| ERR-05 | Resource Exhaustion Handling              | High     | `suite/smtpserver_error-handling/test.err-05.resource-exhaustion.ts` |
+| ERR-06 | Malformed MIME Handling                   | Medium   | `suite/smtpserver_error-handling/test.err-06.malformed-mime.ts` |
+| ERR-07 | Exception Handling                        | High     | `suite/smtpserver_error-handling/test.err-07.exception-handling.ts` |
+| ERR-08 | Error Logging                             | Medium   | `suite/smtpserver_error-handling/test.err-08.error-logging.ts` |
+
+### 6. Performance (PERF)
+
+Tests for validating performance characteristics and benchmarks.
+
+| ID      | Test Description                         | Priority | Implementation |
+|---------|------------------------------------------|----------|----------------|
+| PERF-01 | Throughput Testing                       | Medium   | `suite/smtpserver_performance/test.perf-01.throughput.ts` |
+| PERF-02 | Concurrency Testing                      | High     | `suite/smtpserver_performance/test.perf-02.concurrency.ts` |
+| PERF-03 | CPU Utilization                          | Medium   | `suite/smtpserver_performance/test.perf-03.cpu-utilization.ts` |
+| PERF-04 | Memory Usage                             | Medium   | `suite/smtpserver_performance/test.perf-04.memory-usage.ts` |
+| PERF-05 | Connection Processing Time               | Medium   | `suite/smtpserver_performance/test.perf-05.connection-processing-time.ts` |
+| PERF-06 | Message Processing Time                  | Medium   | `suite/smtpserver_performance/test.perf-06.message-processing-time.ts` |
+| PERF-07 | Resource Cleanup                         | High     | `suite/smtpserver_performance/test.perf-07.resource-cleanup.ts` |
+
+### 7. Reliability (REL)
+
+Tests for validating system reliability and stability.
+
+| ID     | Test Description                          | Priority | Implementation |
+|--------|-------------------------------------------|----------|----------------|
+| REL-01 | Long-Running Operation                    | High     | `suite/smtpserver_reliability/test.rel-01.long-running-operation.ts` |
+| REL-02 | Restart Recovery                          | High     | `suite/smtpserver_reliability/test.rel-02.restart-recovery.ts` |
+| REL-03 | Resource Leak Detection                   | High     | `suite/smtpserver_reliability/test.rel-03.resource-leak-detection.ts` |
+| REL-04 | Error Recovery                            | High     | `suite/smtpserver_reliability/test.rel-04.error-recovery.ts` |
+| REL-05 | DNS Resolution Failure Handling           | Medium   | `suite/smtpserver_reliability/test.rel-05.dns-resolution-failure.ts` |
+| REL-06 | Network Interruption Handling             | Medium   | `suite/smtpserver_reliability/test.rel-06.network-interruption.ts` |
+
+### 8. Edge Cases (EDGE)
+
+Tests for validating handling of unusual or extreme scenarios.
+
+| ID      | Test Description                          | Priority | Implementation |
+|---------|-------------------------------------------|----------|----------------|
+| EDGE-01 | Very Large Email                          | Low      | `suite/smtpserver_edge-cases/test.edge-01.very-large-email.ts` |
+| EDGE-02 | Very Small Email                          | Low      | `suite/smtpserver_edge-cases/test.edge-02.very-small-email.ts` |
+| EDGE-03 | Invalid Character Handling                | Medium   | `suite/smtpserver_edge-cases/test.edge-03.invalid-character-handling.ts` |
+| EDGE-04 | Empty Commands                            | Low      | `suite/smtpserver_edge-cases/test.edge-04.empty-commands.ts` |
+| EDGE-05 | Extremely Long Lines                      | Medium   | `suite/smtpserver_edge-cases/test.edge-05.extremely-long-lines.ts` |
+| EDGE-06 | Extremely Long Headers                    | Medium   | `suite/smtpserver_edge-cases/test.edge-06.extremely-long-headers.ts` |
+| EDGE-07 | Unusual MIME Types                        | Low      | `suite/smtpserver_edge-cases/test.edge-07.unusual-mime-types.ts` |
+| EDGE-08 | Nested MIME Structures                    | Low      | `suite/smtpserver_edge-cases/test.edge-08.nested-mime-structures.ts` |
+
+### 9. RFC Compliance (RFC)
+
+Tests for validating compliance with SMTP-related RFCs.
+
+| ID     | Test Description                          | Priority | Implementation |
+|--------|-------------------------------------------|----------|----------------|
+| RFC-01 | RFC 5321 Compliance                       | High     | `suite/smtpserver_rfc-compliance/test.rfc-01.rfc5321-compliance.ts` |
+| RFC-02 | RFC 5322 Compliance                       | High     | `suite/smtpserver_rfc-compliance/test.rfc-02.rfc5322-compliance.ts` |
+| RFC-03 | RFC 7208 SPF Compliance                   | Medium   | `suite/smtpserver_rfc-compliance/test.rfc-03.rfc7208-spf-compliance.ts` |
+| RFC-04 | RFC 6376 DKIM Compliance                  | Medium   | `suite/smtpserver_rfc-compliance/test.rfc-04.rfc6376-dkim-compliance.ts` |
+| RFC-05 | RFC 7489 DMARC Compliance                 | Medium   | `suite/smtpserver_rfc-compliance/test.rfc-05.rfc7489-dmarc-compliance.ts` |
+| RFC-06 | RFC 8314 TLS Compliance                   | Medium   | `suite/smtpserver_rfc-compliance/test.rfc-06.rfc8314-tls-compliance.ts` |
+| RFC-07 | RFC 3461 DSN Compliance                   | Low      | `suite/smtpserver_rfc-compliance/test.rfc-07.rfc3461-dsn-compliance.ts` |
+
+## SMTP Client Test Suite
+
+The following test categories ensure our SMTP client is production-ready, RFC-compliant, and handles all real-world scenarios properly.
+
+### Client Test Organization
+
+```
+test/
+└── suite/
+    ├── smtpclient_connection/          # Client connection management tests (CCM)
+    ├── smtpclient_commands/            # Client command execution tests (CCMD)
+    ├── smtpclient_email-composition/   # Email composition tests (CEP)
+    ├── smtpclient_security/            # Client security tests (CSEC)
+    ├── smtpclient_error-handling/      # Client error handling tests (CERR)
+    ├── smtpclient_performance/         # Client performance tests (CPERF)
+    ├── smtpclient_reliability/         # Client reliability tests (CREL)
+    ├── smtpclient_edge-cases/          # Client edge case tests (CEDGE)
+    └── smtpclient_rfc-compliance/      # Client RFC compliance tests (CRFC)
+```
+
+### 10. Client Connection Management (CCM)
+
+Tests for validating how the SMTP client establishes and manages connections to servers.
+
+| ID     | Test Description                          | Priority | Implementation |
+|--------|-------------------------------------------|----------|----------------|
+| CCM-01 | Basic TCP Connection                      | High     | `suite/smtpclient_connection/test.ccm-01.basic-tcp-connection.ts` |
+| CCM-02 | TLS Connection Establishment              | High     | `suite/smtpclient_connection/test.ccm-02.tls-connection.ts` |
+| CCM-03 | STARTTLS Upgrade                          | High     | `suite/smtpclient_connection/test.ccm-03.starttls-upgrade.ts` |
+| CCM-04 | Connection Pooling                        | High     | `suite/smtpclient_connection/test.ccm-04.connection-pooling.ts` |
+| CCM-05 | Connection Reuse                          | Medium   | `suite/smtpclient_connection/test.ccm-05.connection-reuse.ts` |
+| CCM-06 | Connection Timeout Handling               | High     | `suite/smtpclient_connection/test.ccm-06.connection-timeout.ts` |
+| CCM-07 | Automatic Reconnection                    | High     | `suite/smtpclient_connection/test.ccm-07.automatic-reconnection.ts` |
+| CCM-08 | DNS Resolution & MX Records               | High     | `suite/smtpclient_connection/test.ccm-08.dns-mx-resolution.ts` |
+| CCM-09 | IPv4/IPv6 Dual Stack Support             | Medium   | `suite/smtpclient_connection/test.ccm-09.dual-stack-support.ts` |
+| CCM-10 | Proxy Support (SOCKS/HTTP)               | Low      | `suite/smtpclient_connection/test.ccm-10.proxy-support.ts` |
+| CCM-11 | Keep-Alive Management                     | Medium   | `suite/smtpclient_connection/test.ccm-11.keepalive-management.ts` |
+
+### 11. Client Command Execution (CCMD)
+
+Tests for validating how the client sends SMTP commands and processes responses.
+
+| ID      | Test Description                          | Priority | Implementation |
+|---------|-------------------------------------------|----------|----------------|
+| CCMD-01 | EHLO/HELO Command Sending                 | High     | `suite/smtpclient_commands/test.ccmd-01.ehlo-helo-sending.ts` |
+| CCMD-02 | MAIL FROM Command with Parameters        | High     | `suite/smtpclient_commands/test.ccmd-02.mail-from-parameters.ts` |
+| CCMD-03 | RCPT TO Command with Multiple Recipients | High     | `suite/smtpclient_commands/test.ccmd-03.rcpt-to-multiple.ts` |
+| CCMD-04 | DATA Command and Content Transmission    | High     | `suite/smtpclient_commands/test.ccmd-04.data-transmission.ts` |
+| CCMD-05 | AUTH Command (LOGIN, PLAIN, CRAM-MD5)   | High     | `suite/smtpclient_commands/test.ccmd-05.auth-mechanisms.ts` |
+| CCMD-06 | Command Pipelining                       | Medium   | `suite/smtpclient_commands/test.ccmd-06.command-pipelining.ts` |
+| CCMD-07 | Response Code Parsing                    | High     | `suite/smtpclient_commands/test.ccmd-07.response-parsing.ts` |
+| CCMD-08 | Extended Response Handling               | Medium   | `suite/smtpclient_commands/test.ccmd-08.extended-responses.ts` |
+| CCMD-09 | QUIT Command and Graceful Disconnect     | High     | `suite/smtpclient_commands/test.ccmd-09.quit-disconnect.ts` |
+| CCMD-10 | RSET Command Usage                       | Medium   | `suite/smtpclient_commands/test.ccmd-10.rset-usage.ts` |
+| CCMD-11 | NOOP Keep-Alive                          | Low      | `suite/smtpclient_commands/test.ccmd-11.noop-keepalive.ts` |
+
+### 12. Client Email Composition (CEP)
+
+Tests for validating email composition, formatting, and encoding.
+
+| ID     | Test Description                          | Priority | Implementation |
+|--------|-------------------------------------------|----------|----------------|
+| CEP-01 | Basic Email Headers                       | High     | `suite/smtpclient_email-composition/test.cep-01.basic-headers.ts` |
+| CEP-02 | MIME Multipart Messages                   | High     | `suite/smtpclient_email-composition/test.cep-02.mime-multipart.ts` |
+| CEP-03 | Attachment Encoding                       | High     | `suite/smtpclient_email-composition/test.cep-03.attachment-encoding.ts` |
+| CEP-04 | UTF-8 and International Characters       | High     | `suite/smtpclient_email-composition/test.cep-04.utf8-international.ts` |
+| CEP-05 | Base64 and Quoted-Printable Encoding    | Medium   | `suite/smtpclient_email-composition/test.cep-05.content-encoding.ts` |
+| CEP-06 | HTML Email with Inline Images           | Medium   | `suite/smtpclient_email-composition/test.cep-06.html-inline-images.ts` |
+| CEP-07 | Custom Headers                          | Low      | `suite/smtpclient_email-composition/test.cep-07.custom-headers.ts` |
+| CEP-08 | Message-ID Generation                   | Medium   | `suite/smtpclient_email-composition/test.cep-08.message-id.ts` |
+| CEP-09 | Date Header Formatting                  | Medium   | `suite/smtpclient_email-composition/test.cep-09.date-formatting.ts` |
+| CEP-10 | Line Length Limits (RFC 5322)          | High     | `suite/smtpclient_email-composition/test.cep-10.line-length-limits.ts` |
+
+### 13. Client Security (CSEC)
+
+Tests for client-side security features and protections.
+
+| ID      | Test Description                          | Priority | Implementation |
+|---------|-------------------------------------------|----------|----------------|
+| CSEC-01 | TLS Certificate Verification              | High     | `suite/smtpclient_security/test.csec-01.tls-verification.ts` |
+| CSEC-02 | Authentication Mechanisms                 | High     | `suite/smtpclient_security/test.csec-02.auth-mechanisms.ts` |
+| CSEC-03 | OAuth2 Support                           | Medium   | `suite/smtpclient_security/test.csec-03.oauth2-support.ts` |
+| CSEC-04 | Password Security (No Plaintext)         | High     | `suite/smtpclient_security/test.csec-04.password-security.ts` |
+| CSEC-05 | DKIM Signing                             | High     | `suite/smtpclient_security/test.csec-05.dkim-signing.ts` |
+| CSEC-06 | SPF Record Compliance                    | Medium   | `suite/smtpclient_security/test.csec-06.spf-compliance.ts` |
+| CSEC-07 | Secure Credential Storage                | High     | `suite/smtpclient_security/test.csec-07.credential-storage.ts` |
+| CSEC-08 | TLS Version Enforcement                  | High     | `suite/smtpclient_security/test.csec-08.tls-version-enforcement.ts` |
+| CSEC-09 | Certificate Pinning                      | Low      | `suite/smtpclient_security/test.csec-09.certificate-pinning.ts` |
+| CSEC-10 | Injection Attack Prevention              | High     | `suite/smtpclient_security/test.csec-10.injection-prevention.ts` |
+
+### 14. Client Error Handling (CERR)
+
+Tests for how the client handles various error conditions.
+
+| ID      | Test Description                          | Priority | Implementation |
+|---------|-------------------------------------------|----------|----------------|
+| CERR-01 | 4xx Error Response Handling              | High     | `suite/smtpclient_error-handling/test.cerr-01.4xx-errors.ts` |
+| CERR-02 | 5xx Error Response Handling              | High     | `suite/smtpclient_error-handling/test.cerr-02.5xx-errors.ts` |
+| CERR-03 | Network Failure Recovery                 | High     | `suite/smtpclient_error-handling/test.cerr-03.network-failures.ts` |
+| CERR-04 | Timeout Recovery                         | High     | `suite/smtpclient_error-handling/test.cerr-04.timeout-recovery.ts` |
+| CERR-05 | Retry Logic with Backoff                | High     | `suite/smtpclient_error-handling/test.cerr-05.retry-backoff.ts` |
+| CERR-06 | Greylisting Handling                    | Medium   | `suite/smtpclient_error-handling/test.cerr-06.greylisting.ts` |
+| CERR-07 | Rate Limit Response Handling            | High     | `suite/smtpclient_error-handling/test.cerr-07.rate-limits.ts` |
+| CERR-08 | Malformed Server Response               | Medium   | `suite/smtpclient_error-handling/test.cerr-08.malformed-responses.ts` |
+| CERR-09 | Connection Drop During Transfer         | High     | `suite/smtpclient_error-handling/test.cerr-09.connection-drops.ts` |
+| CERR-10 | Authentication Failure Handling         | High     | `suite/smtpclient_error-handling/test.cerr-10.auth-failures.ts` |
+
+### 15. Client Performance (CPERF)
+
+Tests for client performance characteristics and optimization.
+
+| ID       | Test Description                          | Priority | Implementation |
+|----------|-------------------------------------------|----------|----------------|
+| CPERF-01 | Bulk Email Sending                       | High     | `suite/smtpclient_performance/test.cperf-01.bulk-sending.ts` |
+| CPERF-02 | Connection Pool Efficiency               | High     | `suite/smtpclient_performance/test.cperf-02.pool-efficiency.ts` |
+| CPERF-03 | Memory Usage Under Load                  | High     | `suite/smtpclient_performance/test.cperf-03.memory-usage.ts` |
+| CPERF-04 | CPU Usage Optimization                   | Medium   | `suite/smtpclient_performance/test.cperf-04.cpu-optimization.ts` |
+| CPERF-05 | Parallel Sending Performance             | High     | `suite/smtpclient_performance/test.cperf-05.parallel-sending.ts` |
+| CPERF-06 | Large Attachment Handling                | Medium   | `suite/smtpclient_performance/test.cperf-06.large-attachments.ts` |
+| CPERF-07 | Queue Management                         | High     | `suite/smtpclient_performance/test.cperf-07.queue-management.ts` |
+| CPERF-08 | DNS Caching Efficiency                   | Medium   | `suite/smtpclient_performance/test.cperf-08.dns-caching.ts` |
+
+### 16. Client Reliability (CREL)
+
+Tests for client reliability and resilience.
+
+| ID      | Test Description                          | Priority | Implementation |
+|---------|-------------------------------------------|----------|----------------|
+| CREL-01 | Long Running Stability                   | High     | `suite/smtpclient_reliability/test.crel-01.long-running.ts` |
+| CREL-02 | Failover to Backup MX                   | High     | `suite/smtpclient_reliability/test.crel-02.mx-failover.ts` |
+| CREL-03 | Queue Persistence                       | High     | `suite/smtpclient_reliability/test.crel-03.queue-persistence.ts` |
+| CREL-04 | Crash Recovery                          | High     | `suite/smtpclient_reliability/test.crel-04.crash-recovery.ts` |
+| CREL-05 | Memory Leak Prevention                  | High     | `suite/smtpclient_reliability/test.crel-05.memory-leaks.ts` |
+| CREL-06 | Concurrent Operation Safety             | High     | `suite/smtpclient_reliability/test.crel-06.concurrency-safety.ts` |
+| CREL-07 | Resource Cleanup                        | Medium   | `suite/smtpclient_reliability/test.crel-07.resource-cleanup.ts` |
+
+### 17. Client Edge Cases (CEDGE)
+
+Tests for unusual scenarios and edge cases.
+
+| ID       | Test Description                          | Priority | Implementation |
+|----------|-------------------------------------------|----------|----------------|
+| CEDGE-01 | Extremely Slow Server Response           | Medium   | `suite/smtpclient_edge-cases/test.cedge-01.slow-server.ts` |
+| CEDGE-02 | Server Sending Invalid UTF-8             | Low      | `suite/smtpclient_edge-cases/test.cedge-02.invalid-utf8.ts` |
+| CEDGE-03 | Extremely Large Recipients List          | Medium   | `suite/smtpclient_edge-cases/test.cedge-03.large-recipient-list.ts` |
+| CEDGE-04 | Zero-Byte Attachments                    | Low      | `suite/smtpclient_edge-cases/test.cedge-04.zero-byte-attachments.ts` |
+| CEDGE-05 | Server Disconnect Mid-Command            | High     | `suite/smtpclient_edge-cases/test.cedge-05.mid-command-disconnect.ts` |
+| CEDGE-06 | Unusual Server Banners                   | Low      | `suite/smtpclient_edge-cases/test.cedge-06.unusual-banners.ts` |
+| CEDGE-07 | Non-Standard Port Connections            | Medium   | `suite/smtpclient_edge-cases/test.cedge-07.non-standard-ports.ts` |
+
+### 18. Client RFC Compliance (CRFC)
+
+Tests for RFC compliance from the client perspective.
+
+| ID      | Test Description                          | Priority | Implementation |
+|---------|-------------------------------------------|----------|----------------|
+| CRFC-01 | RFC 5321 Client Requirements             | High     | `suite/smtpclient_rfc-compliance/test.crfc-01.rfc5321-client.ts` |
+| CRFC-02 | RFC 5322 Message Format                  | High     | `suite/smtpclient_rfc-compliance/test.crfc-02.rfc5322-format.ts` |
+| CRFC-03 | RFC 2045-2049 MIME Compliance           | High     | `suite/smtpclient_rfc-compliance/test.crfc-03.mime-compliance.ts` |
+| CRFC-04 | RFC 4954 AUTH Extension                 | High     | `suite/smtpclient_rfc-compliance/test.crfc-04.auth-extension.ts` |
+| CRFC-05 | RFC 3207 STARTTLS                      | High     | `suite/smtpclient_rfc-compliance/test.crfc-05.starttls.ts` |
+| CRFC-06 | RFC 1870 SIZE Extension                 | Medium   | `suite/smtpclient_rfc-compliance/test.crfc-06.size-extension.ts` |
+| CRFC-07 | RFC 6152 8BITMIME Extension            | Medium   | `suite/smtpclient_rfc-compliance/test.crfc-07.8bitmime.ts` |
+| CRFC-08 | RFC 2920 Command Pipelining            | Medium   | `suite/smtpclient_rfc-compliance/test.crfc-08.pipelining.ts` |
+
+## Running SMTP Client Tests
+
+### Run All Client Tests
+```bash
+cd dcrouter
+pnpm test test/suite/smtpclient_*
+```
+
+### Run Specific Client Test Category
+```bash
+# Run all client connection tests
+pnpm test test/suite/smtpclient_connection
+
+# Run all client security tests
+pnpm test test/suite/smtpclient_security
+```
+
+### Run Single Client Test File
+```bash
+# Run basic TCP connection test
+tsx test/suite/smtpclient_connection/test.ccm-01.basic-tcp-connection.ts
+
+# Run AUTH mechanisms test
+tsx test/suite/smtpclient_commands/test.ccmd-05.auth-mechanisms.ts
+```
+
+## Client Performance Benchmarks
+
+Expected performance metrics for production-ready SMTP client:
+- **Sending Rate**: >100 emails per second (with connection pooling)
+- **Connection Pool Size**: 10-50 concurrent connections efficiently managed
+- **Memory Usage**: <500MB for 1000 concurrent email operations
+- **DNS Cache Hit Rate**: >90% for repeated domains
+- **Retry Success Rate**: >95% for temporary failures
+- **Large Attachment Support**: Files up to 25MB without performance degradation
+- **Queue Processing**: >1000 emails/minute with persistent queue
+
+## Client Security Requirements
+
+All client security tests must pass for production deployment:
+- **TLS Support**: TLS 1.2+ required, TLS 1.3 preferred
+- **Authentication**: Support for LOGIN, PLAIN, CRAM-MD5, OAuth2
+- **Certificate Validation**: Proper certificate chain validation
+- **DKIM Signing**: Automatic DKIM signature generation
+- **Credential Security**: No plaintext password storage
+- **Injection Prevention**: Protection against header/command injection
+
+## Client Production Readiness Criteria
+
+### Production Gate 1: Core Functionality (>95% tests passing)
+- Basic connection establishment
+- Command execution and response parsing
+- Email composition and sending
+- Error handling and recovery
+
+### Production Gate 2: Advanced Features (>90% tests passing)
+- Connection pooling and reuse
+- Authentication mechanisms
+- TLS/STARTTLS support
+- Retry logic and resilience
+
+### Production Gate 3: Enterprise Ready (>85% tests passing)
+- High-volume sending capabilities
+- Advanced security features
+- Full RFC compliance
+- Performance under load
+
+## Key Differences: Server vs Client Tests
+
+| Aspect | Server Tests | Client Tests |
+|--------|--------------|--------------|
+| **Focus** | Accepting connections, processing commands | Making connections, sending commands |
+| **Security** | Validating incoming data, enforcing policies | Protecting credentials, validating servers |
+| **Performance** | Handling many clients concurrently | Efficient bulk sending, connection reuse |
+| **Reliability** | Staying up under attack/load | Retrying failures, handling timeouts |
+| **RFC Compliance** | Server MUST requirements | Client MUST requirements |
+
+## Test Implementation Priority
+
+1. **Critical** (implement first):
+   - Basic connection and command sending
+   - Authentication mechanisms
+   - Error handling and retry logic
+   - TLS/Security features
+
+2. **High Priority** (implement second):
+   - Connection pooling
+   - Email composition and MIME
+   - Performance optimization
+   - RFC compliance
+
+3. **Medium Priority** (implement third):
+   - Advanced features (OAuth2, etc.)
+   - Edge case handling
+   - Extended performance tests
+   - Additional RFC extensions
+
+4. **Low Priority** (implement last):
+   - Proxy support
+   - Certificate pinning
+   - Unusual scenarios
+   - Optional RFC features
+

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.base.ts

@@ -1,65 +0,0 @@
-import { tap, expect } from '@push.rocks/tapbundle';
-import * as plugins from '../ts/plugins.js';
-import * as paths from '../ts/paths.js';
-import { SenderReputationMonitor } from '../ts/deliverability/classes.senderreputationmonitor.js';
-import { IPWarmupManager } from '../ts/deliverability/classes.ipwarmupmanager.js';
-
-/**
- * Basic test to check if our integrated classes work correctly
- */
-tap.test('verify that SenderReputationMonitor and IPWarmupManager are functioning', async () => {
-  // Create instances of both classes
-  const reputationMonitor = SenderReputationMonitor.getInstance({
-    enabled: true,
-    domains: ['example.com']
-  });
-  
-  const ipWarmupManager = IPWarmupManager.getInstance({
-    enabled: true,
-    ipAddresses: ['192.168.1.1', '192.168.1.2'],
-    targetDomains: ['example.com']
-  });
-  
-  // Test SenderReputationMonitor
-  reputationMonitor.recordSendEvent('example.com', { type: 'sent', count: 100 });
-  reputationMonitor.recordSendEvent('example.com', { type: 'delivered', count: 95 });
-  
-  const reputationData = reputationMonitor.getReputationData('example.com');
-  expect(reputationData).toBeTruthy();
-  
-  const summary = reputationMonitor.getReputationSummary();
-  expect(summary.length).toBeGreaterThan(0);
-  
-  // Add and remove domains
-  reputationMonitor.addDomain('test.com');
-  reputationMonitor.removeDomain('test.com');
-  
-  // Test IPWarmupManager
-  ipWarmupManager.setActiveAllocationPolicy('balanced');
-  
-  const bestIP = ipWarmupManager.getBestIPForSending({
-    from: 'test@example.com',
-    to: ['recipient@test.com'],
-    domain: 'example.com'
-  });
-  
-  if (bestIP) {
-    ipWarmupManager.recordSend(bestIP);
-    const canSendMore = ipWarmupManager.canSendMoreToday(bestIP);
-    expect(typeof canSendMore).toEqual('boolean');
-  }
-  
-  const stageCount = ipWarmupManager.getStageCount();
-  expect(stageCount).toBeGreaterThan(0);
-});
-
-// Final clean-up test
-tap.test('clean up after tests', async () => {
-  // No-op - just to make sure everything is cleaned up properly
-});
-
-tap.test('stop', async () => {
-  await tap.stopForcefully();
-});
-
-export default tap.start();

test/test.bouncemanager.ts

@@ -1,197 +0,0 @@
-import { tap, expect } from '@push.rocks/tapbundle';
-import * as plugins from '../ts/plugins.js';
-import { SzPlatformService } from '../ts/platformservice.js';
-import { BounceManager, BounceType, BounceCategory } from '../ts/email/classes.bouncemanager.js';
-
-/**
- * Test the BounceManager class
- */
-tap.test('BounceManager - should be instantiable', async () => {
-  const bounceManager = new BounceManager();
-  expect(bounceManager).toBeTruthy();
-});
-
-tap.test('BounceManager - should process basic bounce categories', async () => {
-  const bounceManager = new BounceManager();
-  
-  // Test hard bounce detection
-  const hardBounce = await bounceManager.processBounce({
-    recipient: 'invalid@example.com',
-    sender: 'sender@example.com',
-    smtpResponse: 'user unknown',
-    domain: 'example.com'
-  });
-  
-  expect(hardBounce.bounceCategory).toEqual(BounceCategory.HARD);
-  
-  // Test soft bounce detection
-  const softBounce = await bounceManager.processBounce({
-    recipient: 'valid@example.com',
-    sender: 'sender@example.com',
-    smtpResponse: 'server unavailable',
-    domain: 'example.com'
-  });
-  
-  expect(softBounce.bounceCategory).toEqual(BounceCategory.SOFT);
-  
-  // Test auto-response detection
-  const autoResponse = await bounceManager.processBounce({
-    recipient: 'away@example.com',
-    sender: 'sender@example.com',
-    smtpResponse: 'auto-reply: out of office',
-    domain: 'example.com'
-  });
-  
-  expect(autoResponse.bounceCategory).toEqual(BounceCategory.AUTO_RESPONSE);
-});
-
-tap.test('BounceManager - should add and check suppression list entries', async () => {
-  const bounceManager = new BounceManager();
-  
-  // Add to suppression list permanently
-  bounceManager.addToSuppressionList('permanent@example.com', 'Test hard bounce', undefined);
-  
-  // Add to suppression list temporarily (5 seconds)
-  const expireTime = Date.now() + 5000;
-  bounceManager.addToSuppressionList('temporary@example.com', 'Test soft bounce', expireTime);
-  
-  // Check suppression status
-  expect(bounceManager.isEmailSuppressed('permanent@example.com')).toEqual(true);
-  expect(bounceManager.isEmailSuppressed('temporary@example.com')).toEqual(true);
-  expect(bounceManager.isEmailSuppressed('notsuppressed@example.com')).toEqual(false);
-  
-  // Get suppression info
-  const info = bounceManager.getSuppressionInfo('permanent@example.com');
-  expect(info).toBeTruthy();
-  expect(info.reason).toEqual('Test hard bounce');
-  expect(info.expiresAt).toBeUndefined();
-
-  // Verify temporary suppression info
-  const tempInfo = bounceManager.getSuppressionInfo('temporary@example.com');
-  expect(tempInfo).toBeTruthy();
-  expect(tempInfo.reason).toEqual('Test soft bounce');
-  expect(tempInfo.expiresAt).toEqual(expireTime);
-  
-  // Wait for expiration (6 seconds)
-  await new Promise(resolve => setTimeout(resolve, 6000));
-  
-  // Verify permanent suppression is still active
-  expect(bounceManager.isEmailSuppressed('permanent@example.com')).toEqual(true);
-  
-  // Verify temporary suppression has expired
-  expect(bounceManager.isEmailSuppressed('temporary@example.com')).toEqual(false);
-});
-
-tap.test('BounceManager - should process SMTP failures correctly', async () => {
-  const bounceManager = new BounceManager();
-  
-  const result = await bounceManager.processSmtpFailure(
-    'recipient@example.com',
-    '550 5.1.1 User unknown',
-    {
-      sender: 'sender@example.com',
-      statusCode: '550'
-    }
-  );
-  
-  expect(result.bounceType).toEqual(BounceType.INVALID_RECIPIENT);
-  expect(result.bounceCategory).toEqual(BounceCategory.HARD);
-  
-  // Check that the email was added to the suppression list
-  expect(bounceManager.isEmailSuppressed('recipient@example.com')).toEqual(true);
-});
-
-tap.test('BounceManager - should process bounce emails correctly', async () => {
-  const bounceManager = new BounceManager();
-  
-  // Create a mock bounce email as Smartmail
-  const bounceEmail = new plugins.smartmail.Smartmail({
-    from: 'mailer-daemon@example.com',
-    subject: 'Mail delivery failed: returning message to sender',
-    body: `
-      This message was created automatically by mail delivery software.
-      
-      A message that you sent could not be delivered to one or more of its recipients.
-      The following address(es) failed:
-      
-      recipient@example.com
-      mailbox is full
-      
-      ------ This is a copy of the message, including all the headers. ------
-      
-      Original-Recipient: rfc822;recipient@example.com
-      Final-Recipient: rfc822;recipient@example.com
-      Status: 5.2.2
-      diagnostic-code: smtp; 552 5.2.2 Mailbox full
-    `,
-    creationObjectRef: {}
-  });
-  
-  const result = await bounceManager.processBounceEmail(bounceEmail);
-  
-  expect(result).toBeTruthy();
-  expect(result.bounceType).toEqual(BounceType.MAILBOX_FULL);
-  expect(result.bounceCategory).toEqual(BounceCategory.HARD);
-  expect(result.recipient).toEqual('recipient@example.com');
-});
-
-tap.test('BounceManager - should handle retries for soft bounces', async () => {
-  const bounceManager = new BounceManager({
-    retryStrategy: {
-      maxRetries: 2,
-      initialDelay: 100, // 100ms for test
-      maxDelay: 1000,
-      backoffFactor: 2
-    }
-  });
-  
-  // First attempt
-  const result1 = await bounceManager.processBounce({
-    recipient: 'retry@example.com',
-    sender: 'sender@example.com',
-    bounceType: BounceType.SERVER_UNAVAILABLE,
-    bounceCategory: BounceCategory.SOFT,
-    domain: 'example.com'
-  });
-  
-  // Email should be suppressed temporarily
-  expect(bounceManager.isEmailSuppressed('retry@example.com')).toEqual(true);
-  expect(result1.retryCount).toEqual(1);
-  expect(result1.nextRetryTime).toBeGreaterThan(Date.now());
-  
-  // Second attempt
-  const result2 = await bounceManager.processBounce({
-    recipient: 'retry@example.com',
-    sender: 'sender@example.com',
-    bounceType: BounceType.SERVER_UNAVAILABLE,
-    bounceCategory: BounceCategory.SOFT,
-    domain: 'example.com',
-    retryCount: 1
-  });
-  
-  expect(result2.retryCount).toEqual(2);
-  
-  // Third attempt (should convert to hard bounce)
-  const result3 = await bounceManager.processBounce({
-    recipient: 'retry@example.com',
-    sender: 'sender@example.com',
-    bounceType: BounceType.SERVER_UNAVAILABLE,
-    bounceCategory: BounceCategory.SOFT,
-    domain: 'example.com',
-    retryCount: 2
-  });
-  
-  // Should now be a hard bounce after max retries
-  expect(result3.bounceCategory).toEqual(BounceCategory.HARD);
-  
-  // Email should be suppressed permanently
-  expect(bounceManager.isEmailSuppressed('retry@example.com')).toEqual(true);
-  const info = bounceManager.getSuppressionInfo('retry@example.com');
-  expect(info.expiresAt).toBeUndefined(); // Permanent
-});
-
-tap.test('stop', async () => {
-  await tap.stopForcefully();
-});
-
-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.config.md

@@ -0,0 +1,175 @@
+# DCRouter Test Configuration
+
+## Running Tests
+
+### Run All Tests
+```bash
+cd dcrouter
+pnpm test
+```
+
+### Run Specific Category
+```bash
+# Run all connection tests
+tsx test/run-category.ts connection
+
+# Run all security tests  
+tsx test/run-category.ts security
+
+# Run all performance tests
+tsx test/run-category.ts performance
+```
+
+### Run Individual Test File
+```bash
+# Run TLS connection test
+tsx test/suite/connection/test.tls-connection.ts
+
+# Run authentication test
+tsx test/suite/security/test.authentication.ts
+```
+
+### Run Tests with Verbose Output
+```bash
+# All tests with verbose logging
+pnpm test -- --verbose
+
+# Individual test with verbose
+tsx test/suite/connection/test.tls-connection.ts --verbose
+```
+
+## Test Server Configuration
+
+Each test file starts its own SMTP server with specific configuration. Common configurations:
+
+### Basic Server
+```typescript
+const testServer = await startTestServer({
+  port: 2525,
+  hostname: 'localhost'
+});
+```
+
+### TLS-Enabled Server
+```typescript
+const testServer = await startTestServer({
+  port: 2525,
+  hostname: 'localhost',
+  tlsEnabled: true
+});
+```
+
+### Authenticated Server
+```typescript
+const testServer = await startTestServer({
+  port: 2525,
+  hostname: 'localhost',
+  authRequired: true
+});
+```
+
+### High-Performance Server
+```typescript
+const testServer = await startTestServer({
+  port: 2525,
+  hostname: 'localhost',
+  maxConnections: 1000,
+  size: 50 * 1024 * 1024 // 50MB
+});
+```
+
+## Port Allocation
+
+Tests use different ports to avoid conflicts:
+- Connection tests: 2525-2530
+- Command tests: 2531-2540
+- Email processing: 2541-2550
+- Security tests: 2551-2560
+- Performance tests: 2561-2570
+- Edge cases: 2571-2580
+- RFC compliance: 2581-2590
+
+## Test Utilities
+
+### Server Lifecycle
+All tests follow this pattern:
+```typescript
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import { startTestServer, stopTestServer } from '../../helpers/server.loader.js';
+
+let testServer;
+
+tap.test('setup', async () => {
+  testServer = await startTestServer({ port: 2525 });
+});
+
+// Your tests here...
+
+tap.test('cleanup', async () => {
+  await stopTestServer(testServer);
+});
+
+tap.start();
+```
+
+### SMTP Client Testing
+```typescript
+import { createTestSmtpClient } from '../../helpers/smtp.client.js';
+
+const client = createTestSmtpClient({
+  host: 'localhost',
+  port: 2525
+});
+```
+
+### Low-Level SMTP Testing
+```typescript
+import { connectToSmtp, sendSmtpCommand } from '../../helpers/test.utils.js';
+
+const socket = await connectToSmtp('localhost', 2525);
+const response = await sendSmtpCommand(socket, 'EHLO test.example.com', '250');
+```
+
+## Performance Benchmarks
+
+Expected minimums for production:
+- Throughput: >10 emails/second
+- Concurrent connections: >100
+- Memory increase: <2% under load
+- Connection time: <5000ms
+- Error rate: <5%
+
+## Debugging Failed Tests
+
+### Enable Verbose Logging
+```bash
+DEBUG=* tsx test/suite/connection/test.tls-connection.ts
+```
+
+### Check Server Logs
+Tests output server logs to console. Look for:
+- 🚀 Server start messages
+- 📧 Email processing logs
+- ❌ Error messages
+- ✅ Success confirmations
+
+### Common Issues
+
+1. **Port Already in Use**
+   - Tests use unique ports
+   - Check for orphaned processes: `lsof -i :2525`
+   - Kill process: `kill -9 <PID>`
+
+2. **TLS Certificate Errors**
+   - Tests use self-signed certificates
+   - Production should use real certificates
+
+3. **Timeout Errors**
+   - Increase timeout in test configuration
+   - Check network connectivity
+   - Verify server started successfully
+
+4. **Authentication Failures**
+   - Test servers may not validate credentials
+   - Check authRequired configuration
+   - Verify AUTH mechanisms supported

test/test.contentscanner.ts

@@ -1,6 +1,6 @@
-import { tap, expect } from '@push.rocks/tapbundle';
+import { tap, expect } from '@git.zone/tstest/tapbundle';
 import { ContentScanner, ThreatCategory } from '../ts/security/classes.contentscanner.js';
-import { Email } from '../ts/mta/classes.email.js';
+import { Email } from '@push.rocks/smartmta';
 
 // Test instantiation
 tap.test('ContentScanner - should be instantiable', async () => {

test/test.dcrouter.email.ts

@@ -0,0 +1,160 @@
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import * as plugins from '../ts/plugins.js';
+import * as path from 'path';
+import * as fs from 'fs';
+import { DcRouter, type IDcRouterOptions } from '../ts/classes.dcrouter.js';
+import type { IUnifiedEmailServerOptions } from '@push.rocks/smartmta';
+
+
+tap.test('DcRouter class - Custom email port configuration', async () => {
+  // Define custom port mapping
+  const customPortMapping: Record<number, number> = {
+    25: 11025,    // Custom SMTP port mapping
+    587: 11587,   // Custom submission port mapping
+    465: 11465,   // Custom SMTPS port mapping
+    2525: 12525   // Additional custom port
+  };
+
+  // Create a custom email configuration using smartmta interfaces
+  const emailConfig: IUnifiedEmailServerOptions = {
+    ports: [25, 587, 465, 2525],
+    hostname: 'mail.example.com',
+    maxMessageSize: 50 * 1024 * 1024, // 50MB
+    domains: [
+      {
+        domain: 'example.com',
+        dnsMode: 'external-dns',
+      },
+      {
+        domain: 'example.org',
+        dnsMode: 'external-dns',
+      }
+    ],
+    routes: [
+      {
+        name: 'forward-example-com',
+        match: {
+          recipients: '*@example.com',
+        },
+        action: {
+          type: 'forward',
+          forward: {
+            host: 'mail1.example.com',
+            port: 25,
+          }
+        }
+      },
+      {
+        name: 'deliver-example-org',
+        match: {
+          recipients: '*@example.org',
+        },
+        action: {
+          type: 'deliver',
+          process: {
+            dkim: true,
+          }
+        }
+      }
+    ]
+  };
+
+  // Create DcRouter options with custom email port configuration
+  const options: IDcRouterOptions = {
+    emailConfig,
+    emailPortConfig: {
+      portMapping: customPortMapping,
+      portSettings: {
+        2525: {
+          terminateTls: false,
+          routeName: 'custom-smtp-route'
+        }
+      },
+    },
+    tls: {
+      contactEmail: 'test@example.com'
+    }
+  };
+
+  // Create DcRouter instance
+  const router = new DcRouter(options);
+
+  // Verify the options are correctly set
+  expect(router.options.emailPortConfig).toBeTruthy();
+  expect(router.options.emailPortConfig!.portMapping).toEqual(customPortMapping);
+
+  // Test the generateEmailRoutes method
+  if (typeof (router as any)['generateEmailRoutes'] === 'function') {
+    const routes = (router as any)['generateEmailRoutes'](emailConfig);
+
+    // Verify that all ports are configured
+    expect(routes.length).toBeGreaterThan(0);
+
+    // Check the custom port configuration
+    const customPortRoute = routes.find((r: any) => {
+      const ports = r.match.ports;
+      return ports === 2525 || (Array.isArray(ports) && (ports as number[]).includes(2525));
+    });
+    expect(customPortRoute).toBeTruthy();
+    expect(customPortRoute?.name).toEqual('custom-smtp-route');
+    expect(customPortRoute?.action.targets[0].port).toEqual(12525);
+
+    // Check standard port mappings
+    const smtpRoute = routes.find((r: any) => {
+      const ports = r.match.ports;
+      return ports === 25 || (Array.isArray(ports) && (ports as number[]).includes(25));
+    });
+    expect(smtpRoute?.action.targets[0].port).toEqual(11025);
+
+    const submissionRoute = routes.find((r: any) => {
+      const ports = r.match.ports;
+      return ports === 587 || (Array.isArray(ports) && (ports as number[]).includes(587));
+    });
+    expect(submissionRoute?.action.targets[0].port).toEqual(11587);
+  }
+});
+
+tap.test('DcRouter class - Email config with domains and routes', async () => {
+  // Create a basic email configuration
+  const emailConfig: IUnifiedEmailServerOptions = {
+    ports: [2525],
+    hostname: 'mail.example.com',
+    domains: [],
+    routes: []
+  };
+
+  // Create DcRouter options
+  const options: IDcRouterOptions = {
+    emailConfig,
+    tls: {
+      contactEmail: 'test@example.com'
+    },
+    opsServerPort: 3104,
+    dbConfig: {
+      enabled: false,
+    }
+  };
+
+  // Create DcRouter instance
+  const router = new DcRouter(options);
+
+  // Start the router to initialize email services
+  await router.start();
+
+  // Verify unified email server was initialized
+  expect(router.emailServer).toBeTruthy();
+
+  // Stop the router
+  await router.stop();
+});
+
+// Final clean-up test
+tap.test('clean up after tests', async () => {
+  // No-op
+});
+
+tap.test('stop', async () => {
+  await tap.stopForcefully();
+});
+
+export default tap.start();

test/test.dcrouter.ts

@@ -1,119 +0,0 @@
-import { tap, expect } from '@push.rocks/tapbundle';
-import * as plugins from '../ts/plugins.js';
-import { 
-  DcRouter,
-  type IDcRouterOptions, 
-  type ISmtpForwardingConfig, 
-  type IDomainRoutingConfig
-} from '../ts/dcrouter/index.js';
-
-tap.test('DcRouter class - basic functionality', async () => {
-  // Create a simple DcRouter instance
-  const options: IDcRouterOptions = {
-    tls: {
-      contactEmail: 'test@example.com'
-    }
-  };
-
-  const router = new DcRouter(options);
-  expect(router).toBeTruthy();
-  expect(router instanceof DcRouter).toEqual(true);
-  expect(router.options.tls.contactEmail).toEqual('test@example.com');
-});
-
-tap.test('DcRouter class - HTTP routing configuration', async () => {
-  // Create HTTP routing configuration
-  const httpRoutes: IDomainRoutingConfig[] = [
-    {
-      domain: 'example.com',
-      targetServer: '192.168.1.10',
-      targetPort: 8080,
-      useTls: true
-    },
-    {
-      domain: '*.example.org',
-      targetServer: '192.168.1.20',
-      targetPort: 9000,
-      useTls: false
-    }
-  ];
-
-  const options: IDcRouterOptions = {
-    httpDomainRoutes: httpRoutes,
-    tls: {
-      contactEmail: 'test@example.com'
-    }
-  };
-
-  const router = new DcRouter(options);
-  expect(router.options.httpDomainRoutes.length).toEqual(2);
-  expect(router.options.httpDomainRoutes[0].domain).toEqual('example.com');
-  expect(router.options.httpDomainRoutes[1].domain).toEqual('*.example.org');
-});
-
-tap.test('DcRouter class - SMTP forwarding configuration', async () => {
-  // Create SMTP forwarding configuration
-  const smtpForwarding: ISmtpForwardingConfig = {
-    enabled: true,
-    ports: [25, 587, 465],
-    defaultServer: 'mail.example.com',
-    defaultPort: 25,
-    useTls: true,
-    preserveSourceIp: true,
-    domainRoutes: [
-      {
-        domain: 'example.com',
-        server: 'mail1.example.com',
-        port: 25
-      },
-      {
-        domain: 'example.org',
-        server: 'mail2.example.org',
-        port: 587
-      }
-    ]
-  };
-
-  const options: IDcRouterOptions = {
-    smtpForwarding,
-    tls: {
-      contactEmail: 'test@example.com'
-    }
-  };
-
-  const router = new DcRouter(options);
-  expect(router.options.smtpForwarding.enabled).toEqual(true);
-  expect(router.options.smtpForwarding.ports.length).toEqual(3);
-  expect(router.options.smtpForwarding.domainRoutes.length).toEqual(2);
-  expect(router.options.smtpForwarding.domainRoutes[0].domain).toEqual('example.com');
-});
-
-tap.test('DcRouter class - Domain pattern matching', async () => {
-  const router = new DcRouter({});
-  
-  // Use the internal method for testing if accessible
-  // This requires knowledge of the implementation, so it's a bit brittle
-  if (typeof router['isDomainMatch'] === 'function') {
-    // Test exact match
-    expect(router['isDomainMatch']('example.com', 'example.com')).toEqual(true);
-    expect(router['isDomainMatch']('example.com', 'example.org')).toEqual(false);
-    
-    // Test wildcard match
-    expect(router['isDomainMatch']('sub.example.com', '*.example.com')).toEqual(true);
-    expect(router['isDomainMatch']('sub.sub.example.com', '*.example.com')).toEqual(true);
-    expect(router['isDomainMatch']('example.com', '*.example.com')).toEqual(false);
-    expect(router['isDomainMatch']('sub.example.org', '*.example.com')).toEqual(false);
-  }
-});
-
-// Final clean-up test
-tap.test('clean up after tests', async () => {
-  // No-op - just to make sure everything is cleaned up properly
-});
-
-tap.test('stop', async () => {
-  await tap.stopForcefully();
-});
-
-// Export a function to run all tests
-export default tap.start();

test/test.deliverability.ts

@@ -1,55 +0,0 @@
-import { tap, expect } from '@push.rocks/tapbundle';
-import * as plugins from '../ts/plugins.js';
-import * as paths from '../ts/paths.js';
-
-// Import the components we want to test
-import { SenderReputationMonitor } from '../ts/deliverability/classes.senderreputationmonitor.js';
-import { IPWarmupManager } from '../ts/deliverability/classes.ipwarmupmanager.js';
-
-// Ensure test directories exist
-paths.ensureDirectories();
-
-// Test SenderReputationMonitor functionality
-tap.test('SenderReputationMonitor should track sending events', async () => {
-  // Initialize monitor with test domain
-  const monitor = SenderReputationMonitor.getInstance({
-    enabled: true,
-    domains: ['test-domain.com']
-  });
-
-  // Record some events
-  monitor.recordSendEvent('test-domain.com', { type: 'sent', count: 100 });
-  monitor.recordSendEvent('test-domain.com', { type: 'delivered', count: 95 });
-  
-  // Get domain metrics
-  const metrics = monitor.getReputationData('test-domain.com');
-  
-  // Verify metrics were recorded
-  if (metrics) {
-    expect(metrics.volume.sent).toEqual(100);
-    expect(metrics.volume.delivered).toEqual(95);
-  }
-});
-
-// Test IPWarmupManager functionality
-tap.test('IPWarmupManager should handle IP allocation policies', async () => {
-  // Initialize warmup manager
-  const manager = IPWarmupManager.getInstance({
-    enabled: true,
-    ipAddresses: ['192.168.1.1', '192.168.1.2'],
-    targetDomains: ['test-domain.com']
-  });
-  
-  // Set allocation policy
-  manager.setActiveAllocationPolicy('balanced');
-  
-  // Verify allocation methods work
-  const canSend = manager.canSendMoreToday('192.168.1.1');
-  expect(typeof canSend).toEqual('boolean');
-});
-
-tap.test('stop', async () => {
-  await tap.stopForcefully();
-});
-
-export default tap.start();

test/test.dns-server-config.ts

@@ -0,0 +1,140 @@
+#!/usr/bin/env tsx
+
+/**
+ * Test DNS server configuration and record registration
+ */
+
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import * as plugins from '../ts/plugins.js';
+
+// Test DNS configuration
+const testDnsConfig = {
+  udpPort: 5353, // Use non-privileged port for testing
+  httpsPort: 8443,
+  httpsKey: './test/fixtures/test-key.pem',
+  httpsCert: './test/fixtures/test-cert.pem',
+  dnssecZone: 'test.example.com',
+  records: [
+    { name: 'test.example.com', type: 'A', value: '192.168.1.1' },
+    { name: 'mail.test.example.com', type: 'A', value: '192.168.1.2' },
+    { name: 'test.example.com', type: 'MX', value: '10 mail.test.example.com' },
+    { name: 'test.example.com', type: 'TXT', value: 'v=spf1 a:mail.test.example.com ~all' },
+    { name: 'test.example.com', type: 'NS', value: 'ns1.test.example.com' },
+    { name: 'ns1.test.example.com', type: 'A', value: '192.168.1.1' }
+  ]
+};
+
+tap.test('DNS server configuration - should extract records correctly', async () => {
+  const { records, ...dnsServerOptions } = testDnsConfig;
+  
+  expect(dnsServerOptions.udpPort).toEqual(5353);
+  expect(dnsServerOptions.httpsPort).toEqual(8443);
+  expect(dnsServerOptions.dnssecZone).toEqual('test.example.com');
+  expect(records).toBeArray();
+  expect(records.length).toEqual(6);
+});
+
+tap.test('DNS server configuration - should handle record parsing', async () => {
+  const parseDnsRecordData = (type: string, value: string): any => {
+    switch (type) {
+      case 'A':
+        return value;
+      case 'MX':
+        const [priority, exchange] = value.split(' ');
+        return { priority: parseInt(priority), exchange };
+      case 'TXT':
+        return value;
+      case 'NS':
+        return value;
+      default:
+        return value;
+    }
+  };
+  
+  // Test A record parsing
+  const aRecord = parseDnsRecordData('A', '192.168.1.1');
+  expect(aRecord).toEqual('192.168.1.1');
+  
+  // Test MX record parsing
+  const mxRecord = parseDnsRecordData('MX', '10 mail.test.example.com');
+  expect(mxRecord).toHaveProperty('priority', 10);
+  expect(mxRecord).toHaveProperty('exchange', 'mail.test.example.com');
+  
+  // Test TXT record parsing
+  const txtRecord = parseDnsRecordData('TXT', 'v=spf1 a:mail.test.example.com ~all');
+  expect(txtRecord).toEqual('v=spf1 a:mail.test.example.com ~all');
+});
+
+tap.test('DNS server configuration - should group records by domain', async () => {
+  const records = testDnsConfig.records;
+  const recordsByDomain = new Map<string, typeof records>();
+  
+  for (const record of records) {
+    const pattern = record.name.includes('*') ? record.name : `*.${record.name}`;
+    if (!recordsByDomain.has(pattern)) {
+      recordsByDomain.set(pattern, []);
+    }
+    recordsByDomain.get(pattern)!.push(record);
+  }
+  
+  // Check grouping
+  expect(recordsByDomain.size).toBeGreaterThan(0);
+  
+  // Verify each group has records
+  for (const [pattern, domainRecords] of recordsByDomain) {
+    expect(domainRecords.length).toBeGreaterThan(0);
+    console.log(`Pattern: ${pattern}, Records: ${domainRecords.length}`);
+  }
+});
+
+tap.test('DNS server configuration - should extract unique record types', async () => {
+  const records = testDnsConfig.records;
+  const recordTypes = [...new Set(records.map(r => r.type))];
+  
+  expect(recordTypes).toContain('A');
+  expect(recordTypes).toContain('MX');
+  expect(recordTypes).toContain('TXT');
+  expect(recordTypes).toContain('NS');
+  
+  console.log('Unique record types:', recordTypes.join(', '));
+});
+
+tap.test('DNS server - mock handler registration', async () => {
+  // Mock DNS server for testing
+  const mockDnsServer = {
+    handlers: new Map<string, any>(),
+    registerHandler: function(pattern: string, types: string[], handler: Function) {
+      this.handlers.set(pattern, { types, handler });
+      console.log(`Registered handler for pattern: ${pattern}, types: ${types.join(', ')}`);
+    }
+  };
+  
+  // Simulate record registration
+  const records = testDnsConfig.records;
+  const recordsByDomain = new Map<string, typeof records>();
+  
+  for (const record of records) {
+    const pattern = record.name.includes('*') ? record.name : `*.${record.name}`;
+    if (!recordsByDomain.has(pattern)) {
+      recordsByDomain.set(pattern, []);
+    }
+    recordsByDomain.get(pattern)!.push(record);
+  }
+  
+  // Register handlers
+  for (const [domainPattern, domainRecords] of recordsByDomain) {
+    const recordTypes = [...new Set(domainRecords.map(r => r.type))];
+    mockDnsServer.registerHandler(domainPattern, recordTypes, (question: any) => {
+      const matchingRecord = domainRecords.find(
+        r => r.name === question.name && r.type === question.type
+      );
+      return matchingRecord || null;
+    });
+  }
+  
+  expect(mockDnsServer.handlers.size).toBeGreaterThan(0);
+});
+
+tap.start({
+  throwOnError: true
+});

test/test.dns-socket-handler.ts

@@ -0,0 +1,149 @@
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import { DcRouter } from '../ts/classes.dcrouter.js';
+import * as plugins from '../ts/plugins.js';
+
+let dcRouter: DcRouter;
+
+tap.test('should NOT instantiate DNS server when dnsNsDomains is not set', async () => {
+  dcRouter = new DcRouter({
+    smartProxyConfig: {
+      routes: []
+    },
+    opsServerPort: 3100,
+    dbConfig: { enabled: false }
+  });
+
+  await dcRouter.start();
+
+  // Check that DNS server is not created
+  expect((dcRouter as any).dnsServer).toBeUndefined();
+
+  await dcRouter.stop();
+});
+
+tap.test('should generate DNS routes when dnsNsDomains is set', async () => {
+  // This test checks the route generation logic WITHOUT starting the full DcRouter
+  // Starting DcRouter would require DNS port 53 and cause conflicts
+
+  dcRouter = new DcRouter({
+    dnsNsDomains: ['ns1.test.local', 'ns2.test.local'],
+    dnsScopes: ['test.local'],
+    smartProxyConfig: {
+      routes: []
+    }
+  });
+
+  // Check routes are generated correctly (without starting)
+  const generatedRoutes = (dcRouter as any).generateDnsRoutes();
+  expect(generatedRoutes.length).toEqual(2); // /dns-query and /resolve
+
+  // Check that routes have socket-handler action
+  generatedRoutes.forEach((route: any) => {
+    expect(route.action.type).toEqual('socket-handler');
+    expect(route.action.socketHandler).toBeDefined();
+  });
+
+  // Verify routes target the primary nameserver
+  const dnsQueryRoute = generatedRoutes.find((r: any) => r.name === 'dns-over-https-dns-query');
+  expect(dnsQueryRoute).toBeDefined();
+  expect(dnsQueryRoute.match.domains).toContain('ns1.test.local');
+});
+
+tap.test('should create DNS routes with correct configuration', async () => {
+  dcRouter = new DcRouter({
+    dnsNsDomains: ['ns1.example.com', 'ns2.example.com'],
+    dnsScopes: ['example.com'],
+    smartProxyConfig: {
+      routes: []
+    }
+  });
+
+  // Access the private method to generate routes
+  const dnsRoutes = (dcRouter as any).generateDnsRoutes();
+
+  expect(dnsRoutes.length).toEqual(2);
+
+  // Check first route (dns-query) - uses primary nameserver (first in array)
+  const dnsQueryRoute = dnsRoutes.find((r: any) => r.name === 'dns-over-https-dns-query');
+  expect(dnsQueryRoute).toBeDefined();
+  expect(dnsQueryRoute.match.ports).toContain(443);
+  expect(dnsQueryRoute.match.domains).toContain('ns1.example.com');
+  expect(dnsQueryRoute.match.path).toEqual('/dns-query');
+
+  // Check second route (resolve)
+  const resolveRoute = dnsRoutes.find((r: any) => r.name === 'dns-over-https-resolve');
+  expect(resolveRoute).toBeDefined();
+  expect(resolveRoute.match.ports).toContain(443);
+  expect(resolveRoute.match.domains).toContain('ns1.example.com');
+  expect(resolveRoute.match.path).toEqual('/resolve');
+});
+
+tap.test('DNS socket handler should be created correctly', async () => {
+  // This test verifies the socket handler creation WITHOUT starting the full router
+  dcRouter = new DcRouter({
+    dnsNsDomains: ['ns1.test.local', 'ns2.test.local'],
+    dnsScopes: ['test.local'],
+    smartProxyConfig: {
+      routes: []
+    }
+  });
+
+  // Get the socket handler (this doesn't require DNS server to be started)
+  const socketHandler = (dcRouter as any).createDnsSocketHandler();
+  expect(socketHandler).toBeDefined();
+  expect(typeof socketHandler).toEqual('function');
+
+  // Create a mock socket to test the handler behavior without DNS server
+  const mockSocket = new plugins.net.Socket();
+  let socketEnded = false;
+
+  mockSocket.end = () => {
+    socketEnded = true;
+    return mockSocket;
+  };
+
+  // When DNS server is not initialized, the handler should end the socket
+  try {
+    await socketHandler(mockSocket);
+  } catch (error) {
+    // Expected - DNS server not initialized
+  }
+
+  // Socket should be ended because DNS server wasn't started
+  expect(socketEnded).toEqual(true);
+});
+
+tap.test('DNS routes should only be generated when dnsNsDomains is configured', async () => {
+  // Test without DNS configuration - should return empty routes
+  dcRouter = new DcRouter({
+    smartProxyConfig: {
+      routes: []
+    }
+  });
+
+  const routesWithoutDns = (dcRouter as any).generateDnsRoutes();
+  expect(routesWithoutDns.length).toEqual(0);
+
+  // Test with DNS configuration - should return routes
+  const dcRouterWithDns = new DcRouter({
+    dnsNsDomains: ['ns1.example.com'],
+    dnsScopes: ['example.com'],
+    smartProxyConfig: {
+      routes: []
+    }
+  });
+
+  const routesWithDns = (dcRouterWithDns as any).generateDnsRoutes();
+  expect(routesWithDns.length).toEqual(2);
+
+  // Verify socket handler can be created
+  const socketHandler = (dcRouterWithDns as any).createDnsSocketHandler();
+  expect(socketHandler).toBeDefined();
+  expect(typeof socketHandler).toEqual('function');
+});
+
+tap.test('stop', async () => {
+  await tap.stopForcefully();
+});
+
+export default tap.start();

test/test.emailauth.ts

@@ -1,209 +0,0 @@
-import { tap, expect } from '@push.rocks/tapbundle';
-import { SzPlatformService } from '../ts/platformservice.js';
-import { SpfVerifier, SpfQualifier, SpfMechanismType } from '../ts/mta/classes.spfverifier.js';
-import { DmarcVerifier, DmarcPolicy, DmarcAlignment } from '../ts/mta/classes.dmarcverifier.js';
-import { Email } from '../ts/mta/classes.email.js';
-
-/**
- * Test email authentication systems: SPF and DMARC
- */
-
-// Setup platform service for testing
-let platformService: SzPlatformService;
-
-tap.test('Setup test environment', async () => {
-  platformService = new SzPlatformService();
-  // Use start() instead of init() which doesn't exist
-  await platformService.start();
-  expect(platformService.mtaService).toBeTruthy();
-});
-
-// SPF Verifier Tests
-tap.test('SPF Verifier - should parse SPF record', async () => {
-  const spfVerifier = new SpfVerifier(platformService.mtaService);
-  
-  // Test valid SPF record parsing
-  const record = 'v=spf1 a mx ip4:192.168.0.1/24 include:example.org ~all';
-  const parsedRecord = spfVerifier.parseSpfRecord(record);
-  
-  expect(parsedRecord).toBeTruthy();
-  expect(parsedRecord.version).toEqual('spf1');
-  expect(parsedRecord.mechanisms.length).toEqual(5);
-  
-  // Check specific mechanisms
-  expect(parsedRecord.mechanisms[0].type).toEqual(SpfMechanismType.A);
-  expect(parsedRecord.mechanisms[0].qualifier).toEqual(SpfQualifier.PASS);
-  
-  expect(parsedRecord.mechanisms[1].type).toEqual(SpfMechanismType.MX);
-  expect(parsedRecord.mechanisms[1].qualifier).toEqual(SpfQualifier.PASS);
-  
-  expect(parsedRecord.mechanisms[2].type).toEqual(SpfMechanismType.IP4);
-  expect(parsedRecord.mechanisms[2].value).toEqual('192.168.0.1/24');
-  
-  expect(parsedRecord.mechanisms[3].type).toEqual(SpfMechanismType.INCLUDE);
-  expect(parsedRecord.mechanisms[3].value).toEqual('example.org');
-  
-  expect(parsedRecord.mechanisms[4].type).toEqual(SpfMechanismType.ALL);
-  expect(parsedRecord.mechanisms[4].qualifier).toEqual(SpfQualifier.SOFTFAIL);
-  
-  // Test invalid record
-  const invalidRecord = 'not-a-spf-record';
-  const invalidParsed = spfVerifier.parseSpfRecord(invalidRecord);
-  expect(invalidParsed).toBeNull();
-});
-
-// DMARC Verifier Tests
-tap.test('DMARC Verifier - should parse DMARC record', async () => {
-  const dmarcVerifier = new DmarcVerifier(platformService.mtaService);
-  
-  // Test valid DMARC record parsing
-  const record = 'v=DMARC1; p=reject; sp=quarantine; pct=50; adkim=s; aspf=r; rua=mailto:dmarc@example.com';
-  const parsedRecord = dmarcVerifier.parseDmarcRecord(record);
-  
-  expect(parsedRecord).toBeTruthy();
-  expect(parsedRecord.version).toEqual('DMARC1');
-  expect(parsedRecord.policy).toEqual(DmarcPolicy.REJECT);
-  expect(parsedRecord.subdomainPolicy).toEqual(DmarcPolicy.QUARANTINE);
-  expect(parsedRecord.pct).toEqual(50);
-  expect(parsedRecord.adkim).toEqual(DmarcAlignment.STRICT);
-  expect(parsedRecord.aspf).toEqual(DmarcAlignment.RELAXED);
-  expect(parsedRecord.reportUriAggregate).toContain('dmarc@example.com');
-  
-  // Test invalid record
-  const invalidRecord = 'not-a-dmarc-record';
-  const invalidParsed = dmarcVerifier.parseDmarcRecord(invalidRecord);
-  expect(invalidParsed).toBeNull();
-});
-
-tap.test('DMARC Verifier - should verify DMARC alignment', async () => {
-  const dmarcVerifier = new DmarcVerifier(platformService.mtaService);
-  
-  // Test email domains with DMARC alignment
-  const email = new Email({
-    from: 'sender@example.com',
-    to: 'recipient@example.net',
-    subject: 'Test DMARC alignment',
-    text: 'This is a test email'
-  });
-  
-  // Test when both SPF and DKIM pass with alignment
-  const dmarcResult = await dmarcVerifier.verify(
-    email,
-    { domain: 'example.com', result: true },  // SPF - aligned and passed
-    { domain: 'example.com', result: true }   // DKIM - aligned and passed
-  );
-  
-  expect(dmarcResult).toBeTruthy();
-  expect(dmarcResult.spfPassed).toEqual(true);
-  expect(dmarcResult.dkimPassed).toEqual(true);
-  expect(dmarcResult.spfDomainAligned).toEqual(true);
-  expect(dmarcResult.dkimDomainAligned).toEqual(true);
-  expect(dmarcResult.action).toEqual('pass');
-  
-  // Test when neither SPF nor DKIM is aligned
-  const dmarcResult2 = await dmarcVerifier.verify(
-    email,
-    { domain: 'differentdomain.com', result: true },  // SPF - passed but not aligned
-    { domain: 'anotherdomain.com', result: true }     // DKIM - passed but not aligned
-  );
-  
-  // We can now see the actual DMARC result and update our expectations
-  
-  expect(dmarcResult2).toBeTruthy();
-  expect(dmarcResult2.spfPassed).toEqual(true);
-  expect(dmarcResult2.dkimPassed).toEqual(true);
-  expect(dmarcResult2.spfDomainAligned).toEqual(false);
-  expect(dmarcResult2.dkimDomainAligned).toEqual(false);
-  
-  // The test environment is returning a 'reject' policy - we can verify that
-  expect(dmarcResult2.policyEvaluated).toEqual('reject');
-  expect(dmarcResult2.actualPolicy).toEqual('reject');
-  expect(dmarcResult2.action).toEqual('reject');
-});
-
-tap.test('DMARC Verifier - should apply policy correctly', async () => {
-  const dmarcVerifier = new DmarcVerifier(platformService.mtaService);
-  
-  // Create test email
-  const email = new Email({
-    from: 'sender@example.com',
-    to: 'recipient@example.net',
-    subject: 'Test DMARC policy application',
-    text: 'This is a test email'
-  });
-  
-  // Test pass action
-  const passResult: any = {
-    hasDmarc: true,
-    spfDomainAligned: true,
-    dkimDomainAligned: true,
-    spfPassed: true,
-    dkimPassed: true,
-    policyEvaluated: DmarcPolicy.NONE,
-    actualPolicy: DmarcPolicy.NONE,
-    appliedPercentage: 100,
-    action: 'pass',
-    details: 'DMARC passed'
-  };
-  
-  const passApplied = dmarcVerifier.applyPolicy(email, passResult);
-  expect(passApplied).toEqual(true);
-  expect(email.mightBeSpam).toEqual(false);
-  expect(email.headers['X-DMARC-Result']).toEqual('DMARC passed');
-  
-  // Test quarantine action
-  const quarantineResult: any = {
-    hasDmarc: true,
-    spfDomainAligned: false,
-    dkimDomainAligned: false,
-    spfPassed: false,
-    dkimPassed: false,
-    policyEvaluated: DmarcPolicy.QUARANTINE,
-    actualPolicy: DmarcPolicy.QUARANTINE,
-    appliedPercentage: 100,
-    action: 'quarantine',
-    details: 'DMARC failed, policy=quarantine'
-  };
-  
-  // Reset email spam flag
-  email.mightBeSpam = false;
-  email.headers = {};
-  
-  const quarantineApplied = dmarcVerifier.applyPolicy(email, quarantineResult);
-  expect(quarantineApplied).toEqual(true);
-  expect(email.mightBeSpam).toEqual(true);
-  expect(email.headers['X-Spam-Flag']).toEqual('YES');
-  expect(email.headers['X-DMARC-Result']).toEqual('DMARC failed, policy=quarantine');
-  
-  // Test reject action
-  const rejectResult: any = {
-    hasDmarc: true,
-    spfDomainAligned: false,
-    dkimDomainAligned: false,
-    spfPassed: false,
-    dkimPassed: false,
-    policyEvaluated: DmarcPolicy.REJECT,
-    actualPolicy: DmarcPolicy.REJECT,
-    appliedPercentage: 100,
-    action: 'reject',
-    details: 'DMARC failed, policy=reject'
-  };
-  
-  // Reset email spam flag
-  email.mightBeSpam = false;
-  email.headers = {};
-  
-  const rejectApplied = dmarcVerifier.applyPolicy(email, rejectResult);
-  expect(rejectApplied).toEqual(false);
-  expect(email.mightBeSpam).toEqual(true);
-});
-
-tap.test('Cleanup test environment', async () => {
-  await platformService.stop();
-});
-
-tap.test('stop', async () => {
-  await tap.stopForcefully();
-});
-
-export default tap.start();

test/test.errors.ts

@@ -0,0 +1,274 @@
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import * as errors from '../ts/errors/index.js';
+import {
+  PlatformError,
+  ValidationError,
+  NetworkError,
+  ResourceError,
+  OperationError
+} from '../ts/errors/base.errors.js';
+import {
+  ErrorSeverity,
+  ErrorCategory,
+  ErrorRecoverability
+} from '../ts/errors/error.codes.js';
+import {
+  ErrorHandler
+} from '../ts/errors/error-handler.js';
+
+// Test base error classes
+tap.test('Base error classes should set properties correctly', async () => {
+  const message = 'Test error message';
+  const code = 'TEST_ERROR_CODE';
+  const context = {
+    component: 'TestComponent',
+    operation: 'testOperation',
+    data: { foo: 'bar' }
+  };
+
+  // Test PlatformError
+  const platformError = new PlatformError(
+    message,
+    code,
+    ErrorSeverity.MEDIUM,
+    ErrorCategory.OPERATION,
+    ErrorRecoverability.MAYBE_RECOVERABLE,
+    context
+  );
+
+  expect(platformError.message).toEqual(message);
+  expect(platformError.code).toEqual(code);
+  expect(platformError.severity).toEqual(ErrorSeverity.MEDIUM);
+  expect(platformError.category).toEqual(ErrorCategory.OPERATION);
+  expect(platformError.recoverability).toEqual(ErrorRecoverability.MAYBE_RECOVERABLE);
+  expect(platformError.context?.component).toEqual(context.component);
+  expect(platformError.context?.operation).toEqual(context.operation);
+  expect(platformError.context?.data?.foo).toEqual('bar');
+  expect(platformError.name).toEqual('PlatformError');
+
+  // Test ValidationError
+  const validationError = new ValidationError(message, code, context);
+  expect(validationError.category).toEqual(ErrorCategory.VALIDATION);
+  expect(validationError.severity).toEqual(ErrorSeverity.LOW);
+
+  // Test NetworkError
+  const networkError = new NetworkError(message, code, context);
+  expect(networkError.category).toEqual(ErrorCategory.CONNECTIVITY);
+  expect(networkError.severity).toEqual(ErrorSeverity.MEDIUM);
+  expect(networkError.recoverability).toEqual(ErrorRecoverability.MAYBE_RECOVERABLE);
+
+  // Test ResourceError
+  const resourceError = new ResourceError(message, code, context);
+  expect(resourceError.category).toEqual(ErrorCategory.RESOURCE);
+});
+
+// Test error handler utility
+tap.test('ErrorHandler should properly handle and format errors', async () => {
+  // Configure error handler
+  ErrorHandler.configure({
+    logErrors: false, // Disable for testing
+    includeStacksInProd: false,
+    retry: {
+      maxAttempts: 5,
+      baseDelay: 100,
+      maxDelay: 1000,
+      backoffFactor: 2
+    }
+  });
+
+  // Test converting regular Error to PlatformError
+  const regularError = new Error('Something went wrong');
+  const platformError = ErrorHandler.toPlatformError(
+    regularError,
+    'PLATFORM_OPERATION_ERROR',
+    { component: 'TestHandler' }
+  );
+
+  expect(platformError).toBeInstanceOf(PlatformError);
+  expect(platformError.code).toEqual('PLATFORM_OPERATION_ERROR');
+  expect(platformError.context?.component).toEqual('TestHandler');
+
+  // Test formatting error for API response
+  const formattedError = ErrorHandler.formatErrorForResponse(platformError, true);
+  expect(formattedError.code).toEqual('PLATFORM_OPERATION_ERROR');
+  expect(formattedError.message).toEqual('An unexpected error occurred.');
+  expect(formattedError.details?.rawMessage).toEqual('Something went wrong');
+
+  // Test executing a function with error handling
+  let executed = false;
+  try {
+    await ErrorHandler.execute(async () => {
+      executed = true;
+      throw new Error('Execution failed');
+    }, 'TEST_EXECUTION_ERROR', { operation: 'testExecution' });
+  } catch (error) {
+    expect(error).toBeInstanceOf(PlatformError);
+    expect(error.code).toEqual('TEST_EXECUTION_ERROR');
+    expect(error.context.operation).toEqual('testExecution');
+  }
+  expect(executed).toEqual(true);
+
+  // Test executeWithRetry successful after retries
+  let attempts = 0;
+  const result = await ErrorHandler.executeWithRetry(
+    async () => {
+      attempts++;
+      if (attempts < 3) {
+        throw new Error('Temporary failure');
+      }
+      return 'success';
+    },
+    'TEST_RETRY_ERROR',
+    {
+      maxAttempts: 5,
+      baseDelay: 10, // Use small delay for tests
+      retryableErrorPatterns: [/Temporary failure/], // Add pattern to make error retryable
+      onRetry: (error, attempt, delay) => {
+        expect(error).toBeInstanceOf(PlatformError);
+        expect(attempt).toBeGreaterThan(0);
+        expect(delay).toBeGreaterThan(0);
+      }
+    }
+  );
+
+  expect(result).toEqual('success');
+  expect(attempts).toEqual(3);
+
+  // Test executeWithRetry that fails after max attempts
+  attempts = 0;
+  try {
+    await ErrorHandler.executeWithRetry(
+      async () => {
+        attempts++;
+        throw new Error('Persistent failure');
+      },
+      'TEST_RETRY_ERROR',
+      {
+        maxAttempts: 3,
+        baseDelay: 10,
+        retryableErrorPatterns: [/Persistent failure/] // Make error retryable so it tries all attempts
+      }
+    );
+  } catch (error) {
+    expect(error).toBeInstanceOf(PlatformError);
+    expect(attempts).toEqual(3);
+  }
+});
+
+// Test retry utilities
+tap.test('Error retry utilities should work correctly', async () => {
+  let attempts = 0;
+
+  try {
+    await errors.retry(
+      async () => {
+        attempts++;
+        if (attempts < 3) {
+          throw new Error('Temporary error');
+        }
+        return 'success';
+      },
+      {
+        maxRetries: 5,
+        initialDelay: 20,
+        backoffFactor: 1.5,
+        retryableErrors: [/Temporary/]
+      }
+    );
+  } catch (e) {
+    // Should not reach here
+    expect(false).toEqual(true);
+  }
+
+  expect(attempts).toEqual(3);
+
+  // Test retry with non-retryable error
+  attempts = 0;
+  try {
+    await errors.retry(
+      async () => {
+        attempts++;
+        throw new Error('Critical error');
+      },
+      {
+        maxRetries: 3,
+        initialDelay: 10,
+        retryableErrors: [/Temporary/] // Won't match "Critical"
+      }
+    );
+  } catch (error) {
+    expect(error.message).toEqual('Critical error');
+    expect(attempts).toEqual(1); // Should only attempt once
+  }
+});
+
+// Helper function that will reject first n times, then resolve
+interface FlakyFunction {
+  (failTimes: number, result?: any): Promise<any>;
+  counter: number;
+  reset: () => void;
+}
+
+const flaky: FlakyFunction = Object.assign(
+  async function (failTimes: number, result: any = 'success'): Promise<any> {
+    if (flaky.counter < failTimes) {
+      flaky.counter++;
+      throw new Error(`Flaky failure ${flaky.counter}`);
+    }
+    return result;
+  },
+  {
+    counter: 0,
+    reset: () => { flaky.counter = 0; }
+  }
+);
+
+// Test error wrapping and retry combination
+tap.test('Error handling can be combined with retry for robust operations', async () => {
+  // Reset counter for the test
+  flaky.reset();
+
+  // Create a wrapped version of the flaky function
+  const wrapped = errors.withErrorHandling(
+    () => flaky(2, 'wrapped success'),
+    'TEST_WRAPPED_ERROR',
+    { component: 'TestComponent' }
+  );
+
+  // Execute with retry
+  const result = await errors.retry(
+    wrapped,
+    {
+      maxRetries: 3,
+      initialDelay: 10,
+      retryableErrors: [/Flaky failure/]
+    }
+  );
+  expect(result).toEqual('wrapped success');
+  expect(flaky.counter).toEqual(2);
+
+  // Reset and test failure case
+  flaky.reset();
+
+  try {
+    await errors.retry(
+      () => flaky(5, 'never reached'),
+      {
+        maxRetries: 2, // Only retry twice, but we need 5 attempts to succeed
+        initialDelay: 10,
+        retryableErrors: [/Flaky failure/] // Add pattern to make it retry
+      }
+    );
+    // Should not reach here
+    expect(false).toEqual(true);
+  } catch (error) {
+    expect(error.message).toContain('Flaky failure');
+    expect(flaky.counter).toEqual(3); // Initial + 2 retries = 3 attempts
+  }
+});
+
+tap.test('stop', async () => {
+  await tap.stopForcefully();
+});
+
+export default tap.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.integration.ts

@@ -1,100 +0,0 @@
-import { tap, expect } from '@push.rocks/tapbundle';
-import * as plugins from '../ts/plugins.js';
-import { SzPlatformService } from '../ts/platformservice.js';
-import { MtaService } from '../ts/mta/classes.mta.js';
-import { EmailService } from '../ts/email/classes.emailservice.js';
-import { BounceManager } from '../ts/email/classes.bouncemanager.js';
-import DcRouter from '../ts/dcrouter/classes.dcrouter.js';
-
-// Test the new integration architecture
-tap.test('should be able to create an independent MTA service', async (tools) => {
-  // Create an independent MTA service
-  const mta = new MtaService(undefined, {
-    smtp: {
-      port: 10025, // Use a different port for testing
-      hostname: 'test.example.com'
-    }
-  });
-  
-  // Verify it was created properly without a platform service reference
-  expect(mta).toBeTruthy();
-  expect(mta.platformServiceRef).toBeUndefined();
-  
-  // Even without a platform service, it should have its own SMTP rule engine
-  expect(mta.smtpRuleEngine).toBeTruthy();
-});
-
-tap.test('should be able to create an EmailService with an existing MTA', async (tools) => {
-  // Create a platform service first
-  const platformService = new SzPlatformService();
-  
-  // Create a shared bounce manager
-  const bounceManager = new BounceManager();
-  
-  // Create an independent MTA service
-  const mta = new MtaService(undefined, {
-    smtp: {
-      port: 10025, // Use a different port for testing
-    }
-  });
-  
-  // Manually set the bounce manager for testing
-  // @ts-ignore - adding property for testing
-  mta.bounceManager = bounceManager;
-  
-  // Create an email service that uses the independent MTA
-  // @ts-ignore - passing a third argument to the constructor
-  const emailService = new EmailService(platformService, {}, mta);
-  
-  // Manually set the mtaService property
-  emailService.mtaService = mta;
-  
-  // Verify relationships
-  expect(emailService.mtaService === mta).toBeTrue();
-  expect(emailService.bounceManager).toBeTruthy();
-  
-  // MTA should not have a direct platform service reference
-  expect(mta.platformServiceRef).toBeUndefined();
-  
-  // But it should have access to bounce manager
-  // @ts-ignore - accessing property for testing
-  expect(mta.bounceManager === bounceManager).toBeTrue();
-});
-
-tap.test('MTA service should have SMTP rule engine', async (tools) => {
-  // Create an independent MTA service
-  const mta = new MtaService(undefined, {
-    smtp: {
-      port: 10025, // Use a different port for testing
-    }
-  });
-  
-  // Verify the MTA has an SMTP rule engine
-  expect(mta.smtpRuleEngine).toBeTruthy();
-});
-
-tap.test('platform service should support having an MTA service', async (tools) => {
-  // Create a platform service with default config
-  const platformService = new SzPlatformService();
-  
-  // Create MTA - don't await start() to avoid binding to ports
-  platformService.mtaService = new MtaService(platformService, {
-    smtp: {
-      port: 10025, // Use a different port for testing
-    }
-  });
-  
-  // Create email service using the platform
-  platformService.emailService = new EmailService(platformService);
-  
-  // Verify the MTA has a reference to the platform service
-  expect(platformService.mtaService).toBeTruthy();
-  expect(platformService.mtaService.platformServiceRef).toBeTruthy();
-});
-
-tap.test('stop', async () => {
-  await tap.stopForcefully();
-});
-
-// Export for tapbundle execution
-export default tap.start();

test/test.ipreputationchecker.ts

@@ -1,4 +1,4 @@
-import { tap, expect } from '@push.rocks/tapbundle';
+import { tap, expect } from '@git.zone/tstest/tapbundle';
 import { IPReputationChecker, ReputationThreshold, IPType } from '../ts/security/classes.ipreputationchecker.js';
 import * as plugins from '../ts/plugins.js';
 
@@ -6,8 +6,8 @@ import * as plugins from '../ts/plugins.js';
 const originalDnsResolve = plugins.dns.promises.resolve;
 let mockDnsResolveImpl: (hostname: string) => Promise<string[]> = async () => ['127.0.0.1'];
 
-// Setup mock DNS resolver
-plugins.dns.promises.resolve = async (hostname: string) => {
+// Setup mock DNS resolver with proper typing
+(plugins.dns.promises as any).resolve = async (hostname: string) => {
   return mockDnsResolveImpl(hostname);
 };
 

test/test.ipwarmupmanager.ts

@@ -1,323 +0,0 @@
-import { tap, expect } from '@push.rocks/tapbundle';
-import * as plugins from '../ts/plugins.js';
-import * as paths from '../ts/paths.js';
-import { IPWarmupManager } from '../ts/deliverability/classes.ipwarmupmanager.js';
-
-// Cleanup any temporary test data
-const cleanupTestData = () => {
-  const warmupDataPath = plugins.path.join(paths.dataDir, 'warmup');
-  if (plugins.fs.existsSync(warmupDataPath)) {
-    // Remove the directory recursively using fs instead of smartfile
-    plugins.fs.rmSync(warmupDataPath, { recursive: true, force: true });
-  }
-};
-
-// Helper to reset the singleton instance between tests
-const resetSingleton = () => {
-  // @ts-ignore - accessing private static field for testing
-  IPWarmupManager.instance = null;
-};
-
-// Before running any tests
-tap.test('setup', async () => {
-  cleanupTestData();
-});
-
-// Test initialization of IPWarmupManager
-tap.test('should initialize IPWarmupManager with default settings', async () => {
-  resetSingleton();
-  const ipWarmupManager = IPWarmupManager.getInstance();
-  
-  expect(ipWarmupManager).toBeTruthy();
-  expect(typeof ipWarmupManager.getBestIPForSending).toEqual('function');
-  expect(typeof ipWarmupManager.canSendMoreToday).toEqual('function');
-  expect(typeof ipWarmupManager.getStageCount).toEqual('function');
-  expect(typeof ipWarmupManager.setActiveAllocationPolicy).toEqual('function');
-});
-
-// Test initialization with custom settings
-tap.test('should initialize IPWarmupManager with custom settings', async () => {
-  resetSingleton();
-  const ipWarmupManager = IPWarmupManager.getInstance({
-    enabled: true,
-    ipAddresses: ['192.168.1.1', '192.168.1.2'],
-    targetDomains: ['example.com', 'test.com'],
-    fallbackPercentage: 75
-  });
-  
-  // Test setting allocation policy
-  ipWarmupManager.setActiveAllocationPolicy('roundRobin');
-  
-  // Get best IP for sending
-  const bestIP = ipWarmupManager.getBestIPForSending({
-    from: 'test@example.com',
-    to: ['recipient@test.com'],
-    domain: 'example.com'
-  });
-  
-  // Check if we can send more today
-  const canSendMore = ipWarmupManager.canSendMoreToday('192.168.1.1');
-  
-  // Check stage count
-  const stageCount = ipWarmupManager.getStageCount();
-  expect(typeof stageCount).toEqual('number');
-});
-
-// Test IP allocation policies
-tap.test('should allocate IPs using balanced policy', async () => {
-  resetSingleton();
-  const ipWarmupManager = IPWarmupManager.getInstance({
-    enabled: true,
-    ipAddresses: ['192.168.1.1', '192.168.1.2', '192.168.1.3'],
-    targetDomains: ['example.com', 'test.com']
-    // Remove allocationPolicy which is not in the interface
-  });
-  
-  ipWarmupManager.setActiveAllocationPolicy('balanced');
-  
-  // Use getBestIPForSending multiple times and check if all IPs are used
-  const usedIPs = new Set();
-  for (let i = 0; i < 30; i++) {
-    const ip = ipWarmupManager.getBestIPForSending({
-      from: 'test@example.com',
-      to: ['recipient@test.com'],
-      domain: 'example.com'
-    });
-    if (ip) usedIPs.add(ip);
-  }
-  
-  // We should use at least 2 different IPs with balanced policy
-  expect(usedIPs.size >= 2).toBeTrue();
-});
-
-// Test round robin allocation policy
-tap.test('should allocate IPs using round robin policy', async () => {
-  resetSingleton();
-  const ipWarmupManager = IPWarmupManager.getInstance({
-    enabled: true,
-    ipAddresses: ['192.168.1.1', '192.168.1.2', '192.168.1.3'],
-    targetDomains: ['example.com', 'test.com']
-    // Remove allocationPolicy which is not in the interface
-  });
-  
-  ipWarmupManager.setActiveAllocationPolicy('roundRobin');
-  
-  // First few IPs should rotate through the available IPs
-  const firstIP = ipWarmupManager.getBestIPForSending({
-    from: 'test@example.com',
-    to: ['recipient@test.com'],
-    domain: 'example.com'
-  });
-  
-  const secondIP = ipWarmupManager.getBestIPForSending({
-    from: 'test@example.com',
-    to: ['recipient@test.com'],
-    domain: 'example.com'
-  });
-  
-  const thirdIP = ipWarmupManager.getBestIPForSending({
-    from: 'test@example.com',
-    to: ['recipient@test.com'],
-    domain: 'example.com'
-  });
-  
-  // Round robin should give us different IPs for consecutive calls
-  expect(firstIP !== secondIP).toBeTrue();
-  
-  // With 3 IPs, the fourth call should cycle back to one of the IPs
-  const fourthIP = ipWarmupManager.getBestIPForSending({
-    from: 'test@example.com',
-    to: ['recipient@test.com'],
-    domain: 'example.com'
-  });
-  
-  // Check that the fourth IP is one of the 3 valid IPs
-  expect(['192.168.1.1', '192.168.1.2', '192.168.1.3'].includes(fourthIP)).toBeTrue();
-});
-
-// Test dedicated domain allocation policy
-tap.test('should allocate IPs using dedicated domain policy', async () => {
-  resetSingleton();
-  const ipWarmupManager = IPWarmupManager.getInstance({
-    enabled: true,
-    ipAddresses: ['192.168.1.1', '192.168.1.2', '192.168.1.3'],
-    targetDomains: ['example.com', 'test.com', 'other.com']
-    // Remove allocationPolicy which is not in the interface
-  });
-  
-  ipWarmupManager.setActiveAllocationPolicy('dedicated');
-  
-  // Instead of mapDomainToIP which doesn't exist, we'll simulate domain mapping
-  // by making dedicated calls per domain - we can't call the internal method directly
-  
-  // Each domain should get its dedicated IP
-  const exampleIP = ipWarmupManager.getBestIPForSending({
-    from: 'test@example.com',
-    to: ['recipient@gmail.com'],
-    domain: 'example.com'
-  });
-  
-  const testIP = ipWarmupManager.getBestIPForSending({
-    from: 'test@test.com',
-    to: ['recipient@gmail.com'],
-    domain: 'test.com'
-  });
-  
-  const otherIP = ipWarmupManager.getBestIPForSending({
-    from: 'test@other.com',
-    to: ['recipient@gmail.com'],
-    domain: 'other.com'
-  });
-  
-  // Since we're not actually mapping domains to IPs, we can only test if they return valid IPs
-  // The original assertions have been modified since we can't guarantee which IP will be returned
-  expect(exampleIP).toBeTruthy();
-  expect(testIP).toBeTruthy();
-  expect(otherIP).toBeTruthy();
-});
-
-// Test daily sending limits
-tap.test('should enforce daily sending limits', async () => {
-  resetSingleton();
-  const ipWarmupManager = IPWarmupManager.getInstance({
-    enabled: true,
-    ipAddresses: ['192.168.1.1'],
-    targetDomains: ['example.com']
-    // Remove allocationPolicy which is not in the interface
-  });
-  
-  // Override the warmup stage for testing
-  // @ts-ignore - accessing private method for testing
-  ipWarmupManager.warmupStatuses.set('192.168.1.1', {
-    ipAddress: '192.168.1.1',
-    isActive: true,
-    currentStage: 1,
-    startDate: new Date(),
-    currentStageStartDate: new Date(),
-    targetCompletionDate: new Date(),
-    currentDailyAllocation: 5,
-    sentInCurrentStage: 0,
-    totalSent: 0,
-    dailyStats: [],
-    metrics: {
-      openRate: 0,
-      bounceRate: 0,
-      complaintRate: 0
-    }
-  });
-  
-  // Set a very low daily limit for testing 
-  // @ts-ignore - accessing private method for testing
-  ipWarmupManager.config.stages = [
-    { stage: 1, maxDailyVolume: 5, durationDays: 5, targetMetrics: { maxBounceRate: 8, minOpenRate: 15 } }
-  ];
-  
-  // First pass: should be able to get an IP
-  const ip = ipWarmupManager.getBestIPForSending({
-    from: 'test@example.com',
-    to: ['recipient@test.com'],
-    domain: 'example.com'
-  });
-  
-  expect(ip === '192.168.1.1').toBeTrue();
-  
-  // Record 5 sends to reach the daily limit
-  for (let i = 0; i < 5; i++) {
-    ipWarmupManager.recordSend('192.168.1.1');
-  }
-  
-  // Check if we can send more today
-  const canSendMore = ipWarmupManager.canSendMoreToday('192.168.1.1');
-  expect(canSendMore).toEqual(false);
-  
-  // After reaching limit, getBestIPForSending should return null
-  // since there are no available IPs
-  const sixthIP = ipWarmupManager.getBestIPForSending({
-    from: 'test@example.com',
-    to: ['recipient@test.com'],
-    domain: 'example.com'
-  });
-  
-  expect(sixthIP === null).toBeTrue();
-});
-
-// Test recording sends
-tap.test('should record send events correctly', async () => {
-  resetSingleton();
-  const ipWarmupManager = IPWarmupManager.getInstance({
-    enabled: true,
-    ipAddresses: ['192.168.1.1', '192.168.1.2'],
-    targetDomains: ['example.com'],
-  });
-  
-  // Set allocation policy
-  ipWarmupManager.setActiveAllocationPolicy('balanced');
-  
-  // Get an IP for sending
-  const ip = ipWarmupManager.getBestIPForSending({
-    from: 'test@example.com',
-    to: ['recipient@test.com'],
-    domain: 'example.com'
-  });
-  
-  // If we got an IP, record some sends
-  if (ip) {
-    // Record a few sends
-    for (let i = 0; i < 5; i++) {
-      ipWarmupManager.recordSend(ip);
-    }
-    
-    // Check if we can still send more
-    const canSendMore = ipWarmupManager.canSendMoreToday(ip);
-    expect(typeof canSendMore).toEqual('boolean');
-  }
-});
-
-// Test that DedicatedDomainPolicy assigns IPs correctly
-tap.test('should assign IPs using dedicated domain policy', async () => {
-  resetSingleton();
-  const ipWarmupManager = IPWarmupManager.getInstance({
-    enabled: true,
-    ipAddresses: ['192.168.1.1', '192.168.1.2', '192.168.1.3'],
-    targetDomains: ['example.com', 'test.com', 'other.com']
-  });
-  
-  // Set allocation policy to dedicated domains
-  ipWarmupManager.setActiveAllocationPolicy('dedicated');
-  
-  // Check allocation by querying for different domains
-  const ip1 = ipWarmupManager.getBestIPForSending({
-    from: 'test@example.com',
-    to: ['recipient@test.com'],
-    domain: 'example.com'
-  });
-  
-  const ip2 = ipWarmupManager.getBestIPForSending({
-    from: 'test@test.com',
-    to: ['recipient@test.com'],
-    domain: 'test.com'
-  });
-  
-  // If we got IPs, they should be consistently assigned
-  if (ip1 && ip2) {
-    // Requesting the same domain again should return the same IP
-    const ip1again = ipWarmupManager.getBestIPForSending({
-      from: 'another@example.com',
-      to: ['recipient@test.com'],
-      domain: 'example.com'
-    });
-    
-    expect(ip1again === ip1).toBeTrue();
-  }
-});
-
-// After all tests, clean up
-tap.test('cleanup', async () => {
-  cleanupTestData();
-});
-
-tap.test('stop', async () => {
-  await tap.stopForcefully();
-});
-
-export default tap.start();

test/test.jwt-auth.ts

@@ -0,0 +1,132 @@
+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';
+
+let testDcRouter: DcRouter;
+let identity: interfaces.data.IIdentity;
+
+tap.test('should start DCRouter with OpsServer', async () => {
+  testDcRouter = new DcRouter({
+    // Minimal config for testing
+    opsServerPort: 3102,
+    dbConfig: { enabled: false },
+  });
+  
+  await testDcRouter.start();
+  expect(testDcRouter.opsServer).toBeInstanceOf(Object);
+});
+
+tap.test('should login with admin credentials and receive JWT', async () => {
+  const loginRequest = new TypedRequest<interfaces.requests.IReq_AdminLoginWithUsernameAndPassword>(
+    'http://localhost:3102/typedrequest',
+    'adminLoginWithUsernameAndPassword'
+  );
+  
+  const response = await loginRequest.fire({
+    username: 'admin',
+    password: 'admin'
+  });
+  
+  expect(response).toHaveProperty('identity');
+  expect(response.identity).toHaveProperty('jwt');
+  expect(response.identity).toHaveProperty('userId');
+  expect(response.identity).toHaveProperty('name');
+  expect(response.identity).toHaveProperty('expiresAt');
+  expect(response.identity).toHaveProperty('role');
+  expect(response.identity.role).toEqual('admin');
+  
+  identity = response.identity;
+  console.log('JWT:', identity.jwt);
+});
+
+tap.test('should verify valid JWT identity', async () => {
+  const verifyRequest = new TypedRequest<interfaces.requests.IReq_VerifyIdentity>(
+    'http://localhost:3102/typedrequest',
+    'verifyIdentity'
+  );
+  
+  const response = await verifyRequest.fire({
+    identity
+  });
+  
+  expect(response).toHaveProperty('valid');
+  expect(response.valid).toBeTrue();
+  expect(response).toHaveProperty('identity');
+  expect(response.identity.userId).toEqual(identity.userId);
+});
+
+tap.test('should reject invalid JWT', async () => {
+  const verifyRequest = new TypedRequest<interfaces.requests.IReq_VerifyIdentity>(
+    'http://localhost:3102/typedrequest',
+    'verifyIdentity'
+  );
+  
+  const response = await verifyRequest.fire({
+    identity: {
+      ...identity,
+      jwt: 'invalid.jwt.token'
+    }
+  });
+  
+  expect(response).toHaveProperty('valid');
+  expect(response.valid).toBeFalse();
+});
+
+tap.test('should verify JWT matches identity data', async () => {
+  const verifyRequest = new TypedRequest<interfaces.requests.IReq_VerifyIdentity>(
+    'http://localhost:3102/typedrequest',
+    'verifyIdentity'
+  );
+  
+  // The response should contain the same identity data as the JWT
+  const response = await verifyRequest.fire({
+    identity
+  });
+  
+  expect(response).toHaveProperty('valid');
+  expect(response.valid).toBeTrue();
+  expect(response.identity.expiresAt).toEqual(identity.expiresAt);
+  expect(response.identity.userId).toEqual(identity.userId);
+});
+
+tap.test('should handle logout', async () => {
+  const logoutRequest = new TypedRequest<interfaces.requests.IReq_AdminLogout>(
+    'http://localhost:3102/typedrequest',
+    'adminLogout'
+  );
+  
+  const response = await logoutRequest.fire({
+    identity
+  });
+  
+  expect(response).toHaveProperty('success');
+  expect(response.success).toBeTrue();
+});
+
+tap.test('should reject wrong credentials', async () => {
+  const loginRequest = new TypedRequest<interfaces.requests.IReq_AdminLoginWithUsernameAndPassword>(
+    'http://localhost:3102/typedrequest',
+    'adminLoginWithUsernameAndPassword'
+  );
+  
+  let errorOccurred = false;
+  try {
+    await loginRequest.fire({
+      username: 'admin',
+      password: 'wrongpassword'
+    });
+  } catch (error) {
+    errorOccurred = true;
+    // TypedResponseError is thrown
+    expect(error).toBeTruthy();
+  }
+  
+  expect(errorOccurred).toBeTrue();
+});
+
+tap.test('should stop DCRouter', async () => {
+  await testDcRouter.stop();
+});
+
+export default tap.start();

test/test.minimal.ts

@@ -1,66 +0,0 @@
-import { tap, expect } from '@push.rocks/tapbundle';
-import * as plugins from '../ts/plugins.js';
-import * as paths from '../ts/paths.js';
-import { SenderReputationMonitor } from '../ts/deliverability/classes.senderreputationmonitor.js';
-import { IPWarmupManager } from '../ts/deliverability/classes.ipwarmupmanager.js';
-
-/**
- * Basic test to check if our integrated classes work correctly
- */
-tap.test('verify that SenderReputationMonitor and IPWarmupManager are functioning', async (tools) => {
-  // Create instances of both classes
-  const reputationMonitor = SenderReputationMonitor.getInstance({
-    enabled: true,
-    domains: ['example.com']
-  });
-  
-  const ipWarmupManager = IPWarmupManager.getInstance({
-    enabled: true,
-    ipAddresses: ['192.168.1.1', '192.168.1.2'],
-    targetDomains: ['example.com']
-  });
-  
-  // Test SenderReputationMonitor
-  reputationMonitor.recordSendEvent('example.com', { type: 'sent', count: 100 });
-  reputationMonitor.recordSendEvent('example.com', { type: 'delivered', count: 95 });
-  
-  const reputationData = reputationMonitor.getReputationData('example.com');
-  const summary = reputationMonitor.getReputationSummary();
-  
-  // Basic checks
-  expect(reputationData).toBeTruthy();
-  expect(summary.length).toBeGreaterThan(0);
-  
-  // Add and remove domains
-  reputationMonitor.addDomain('test.com');
-  reputationMonitor.removeDomain('test.com');
-  
-  // Test IPWarmupManager
-  ipWarmupManager.setActiveAllocationPolicy('balanced');
-  
-  const bestIP = ipWarmupManager.getBestIPForSending({
-    from: 'test@example.com',
-    to: ['recipient@test.com'],
-    domain: 'example.com'
-  });
-  
-  if (bestIP) {
-    ipWarmupManager.recordSend(bestIP);
-    const canSendMore = ipWarmupManager.canSendMoreToday(bestIP);
-    expect(canSendMore !== undefined).toBeTrue();
-  }
-  
-  const stageCount = ipWarmupManager.getStageCount();
-  expect(stageCount).toBeGreaterThan(0);
-});
-
-// Final clean-up test
-tap.test('clean up after tests', async () => {
-  // No-op - just to make sure everything is cleaned up properly
-});
-
-tap.test('stop', async () => {
-  await tap.stopForcefully();
-});
-
-export default tap.start();

test/test.opsserver-api.ts

@@ -0,0 +1,124 @@
+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';
+
+let testDcRouter: DcRouter;
+let adminIdentity: interfaces.data.IIdentity;
+
+tap.test('should start DCRouter with OpsServer', async () => {
+  testDcRouter = new DcRouter({
+    // Minimal config for testing
+    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:3101/typedrequest',
+    'getHealthStatus'
+  );
+
+  const response = await healthRequest.fire({
+    identity: adminIdentity,
+    detailed: false,
+  });
+
+  expect(response).toHaveProperty('health');
+  expect(response.health.healthy).toBeTrue();
+  expect(response.health.services).toHaveProperty('OpsServer');
+});
+
+tap.test('should respond to server statistics request', async () => {
+  const statsRequest = new TypedRequest<interfaces.requests.IReq_GetServerStatistics>(
+    'http://localhost:3101/typedrequest',
+    'getServerStatistics'
+  );
+
+  const response = await statsRequest.fire({
+    identity: adminIdentity,
+    includeHistory: false,
+  });
+
+  expect(response).toHaveProperty('stats');
+  expect(response.stats).toHaveProperty('uptime');
+  expect(response.stats).toHaveProperty('cpuUsage');
+  expect(response.stats).toHaveProperty('memoryUsage');
+});
+
+tap.test('should respond to configuration request', async () => {
+  const configRequest = new TypedRequest<interfaces.requests.IReq_GetConfiguration>(
+    'http://localhost:3101/typedrequest',
+    'getConfiguration'
+  );
+
+  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('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:3101/typedrequest',
+    'getRecentLogs'
+  );
+
+  const response = await logsRequest.fire({
+    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();

test/test.protected-endpoint.ts

@@ -0,0 +1,128 @@
+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';
+
+let testDcRouter: DcRouter;
+let adminIdentity: interfaces.data.IIdentity;
+
+tap.test('should start DCRouter with OpsServer', async () => {
+  testDcRouter = new DcRouter({
+    // Minimal config for testing
+    opsServerPort: 3103,
+    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:3103/typedrequest',
+    'adminLoginWithUsernameAndPassword'
+  );
+
+  const response = await loginRequest.fire({
+    username: 'admin',
+    password: 'admin'
+  });
+
+  expect(response).toHaveProperty('identity');
+  adminIdentity = response.identity;
+  console.log('Admin logged in with JWT');
+});
+
+tap.test('should allow admin to verify identity', async () => {
+  const verifyRequest = new TypedRequest<interfaces.requests.IReq_VerifyIdentity>(
+    'http://localhost:3103/typedrequest',
+    'verifyIdentity'
+  );
+
+  const response = await verifyRequest.fire({
+    identity: adminIdentity,
+  });
+
+  expect(response).toHaveProperty('valid');
+  expect(response.valid).toBeTrue();
+  console.log('Admin identity verified successfully');
+});
+
+tap.test('should reject verify identity without identity', async () => {
+  const verifyRequest = new TypedRequest<interfaces.requests.IReq_VerifyIdentity>(
+    'http://localhost:3103/typedrequest',
+    'verifyIdentity'
+  );
+
+  try {
+    await verifyRequest.fire({} as any);
+    expect(true).toBeFalse(); // Should not reach here
+  } catch (error) {
+    expect(error).toBeTruthy();
+    console.log('Successfully rejected request without identity');
+  }
+});
+
+tap.test('should reject verify identity with invalid JWT', async () => {
+  const verifyRequest = new TypedRequest<interfaces.requests.IReq_VerifyIdentity>(
+    'http://localhost:3103/typedrequest',
+    'verifyIdentity'
+  );
+
+  try {
+    await verifyRequest.fire({
+      identity: {
+        ...adminIdentity,
+        jwt: 'invalid.jwt.token'
+      },
+    });
+    expect(true).toBeFalse(); // Should not reach here
+  } catch (error) {
+    expect(error).toBeTruthy();
+    console.log('Successfully rejected request with invalid JWT');
+  }
+});
+
+tap.test('should reject protected endpoints without auth', async () => {
+  const healthRequest = new TypedRequest<interfaces.requests.IReq_GetHealthStatus>(
+    'http://localhost:3103/typedrequest',
+    'getHealthStatus'
+  );
+
+  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 authenticated access to protected endpoints', async () => {
+  const configRequest = new TypedRequest<interfaces.requests.IReq_GetConfiguration>(
+    'http://localhost:3103/typedrequest',
+    'getConfiguration'
+  );
+
+  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('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 () => {
+  await testDcRouter.stop();
+});
+
+export default tap.start();

test/test.ratelimiter.ts

@@ -1,141 +0,0 @@
-import { tap, expect } from '@push.rocks/tapbundle';
-import { RateLimiter } from '../ts/mta/classes.ratelimiter.js';
-
-tap.test('RateLimiter - should be instantiable', async () => {
-  const limiter = new RateLimiter({
-    maxPerPeriod: 10,
-    periodMs: 1000,
-    perKey: true
-  });
-  
-  expect(limiter).toBeTruthy();
-});
-
-tap.test('RateLimiter - should allow requests within rate limit', async () => {
-  const limiter = new RateLimiter({
-    maxPerPeriod: 5,
-    periodMs: 1000,
-    perKey: true
-  });
-  
-  // Should allow 5 requests
-  for (let i = 0; i < 5; i++) {
-    expect(limiter.isAllowed('test')).toEqual(true);
-  }
-  
-  // 6th request should be denied
-  expect(limiter.isAllowed('test')).toEqual(false);
-});
-
-tap.test('RateLimiter - should enforce per-key limits', async () => {
-  const limiter = new RateLimiter({
-    maxPerPeriod: 3,
-    periodMs: 1000,
-    perKey: true
-  });
-  
-  // Should allow 3 requests for key1
-  for (let i = 0; i < 3; i++) {
-    expect(limiter.isAllowed('key1')).toEqual(true);
-  }
-  
-  // 4th request for key1 should be denied
-  expect(limiter.isAllowed('key1')).toEqual(false);
-  
-  // But key2 should still be allowed
-  expect(limiter.isAllowed('key2')).toEqual(true);
-});
-
-tap.test('RateLimiter - should refill tokens over time', async () => {
-  const limiter = new RateLimiter({
-    maxPerPeriod: 2,
-    periodMs: 100, // Short period for testing
-    perKey: true
-  });
-  
-  // Use all tokens
-  expect(limiter.isAllowed('test')).toEqual(true);
-  expect(limiter.isAllowed('test')).toEqual(true);
-  expect(limiter.isAllowed('test')).toEqual(false);
-  
-  // Wait for refill
-  await new Promise(resolve => setTimeout(resolve, 150));
-  
-  // Should have tokens again
-  expect(limiter.isAllowed('test')).toEqual(true);
-});
-
-tap.test('RateLimiter - should support burst allowance', async () => {
-  const limiter = new RateLimiter({
-    maxPerPeriod: 2,
-    periodMs: 100,
-    perKey: true,
-    burstTokens: 2, // Allow 2 extra tokens for bursts
-    initialTokens: 4  // Start with max + burst tokens
-  });
-  
-  // Should allow 4 requests (2 regular + 2 burst)
-  for (let i = 0; i < 4; i++) {
-    expect(limiter.isAllowed('test')).toEqual(true);
-  }
-  
-  // 5th request should be denied
-  expect(limiter.isAllowed('test')).toEqual(false);
-  
-  // Wait for refill
-  await new Promise(resolve => setTimeout(resolve, 150));
-  
-  // Should have 2 tokens again (rate-limited to normal max, not burst)
-  expect(limiter.isAllowed('test')).toEqual(true);
-  expect(limiter.isAllowed('test')).toEqual(true);
-  
-  // 3rd request after refill should fail (only normal max is refilled, not burst)
-  expect(limiter.isAllowed('test')).toEqual(false);
-});
-
-tap.test('RateLimiter - should return correct stats', async () => {
-  const limiter = new RateLimiter({
-    maxPerPeriod: 10,
-    periodMs: 1000,
-    perKey: true
-  });
-  
-  // Make some requests
-  limiter.isAllowed('test');
-  limiter.isAllowed('test');
-  limiter.isAllowed('test');
-  
-  // Get stats
-  const stats = limiter.getStats('test');
-  
-  expect(stats.remaining).toEqual(7);
-  expect(stats.limit).toEqual(10);
-  expect(stats.allowed).toEqual(3);
-  expect(stats.denied).toEqual(0);
-});
-
-tap.test('RateLimiter - should reset limits', async () => {
-  const limiter = new RateLimiter({
-    maxPerPeriod: 3,
-    periodMs: 1000,
-    perKey: true
-  });
-  
-  // Use all tokens
-  expect(limiter.isAllowed('test')).toEqual(true);
-  expect(limiter.isAllowed('test')).toEqual(true);
-  expect(limiter.isAllowed('test')).toEqual(true);
-  expect(limiter.isAllowed('test')).toEqual(false);
-  
-  // Reset
-  limiter.reset('test');
-  
-  // Should have tokens again
-  expect(limiter.isAllowed('test')).toEqual(true);
-});
-
-tap.test('stop', async () => {
-  await tap.stopForcefully();
-});
-
-export default tap.start();

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.reputationmonitor.ts

@@ -1,243 +0,0 @@
-import { tap, expect } from '@push.rocks/tapbundle';
-import * as plugins from '../ts/plugins.js';
-import * as paths from '../ts/paths.js';
-import { SenderReputationMonitor } from '../ts/deliverability/classes.senderreputationmonitor.js';
-
-// Cleanup any temporary test data
-const cleanupTestData = () => {
-  const reputationDataPath = plugins.path.join(paths.dataDir, 'reputation');
-  if (plugins.fs.existsSync(reputationDataPath)) {
-    // Remove the directory recursively using fs instead of smartfile
-    plugins.fs.rmSync(reputationDataPath, { recursive: true, force: true });
-  }
-};
-
-// Helper to reset the singleton instance between tests
-const resetSingleton = () => {
-  // @ts-ignore - accessing private static field for testing
-  SenderReputationMonitor.instance = null;
-};
-
-// Before running any tests
-tap.test('setup', async () => {
-  cleanupTestData();
-});
-
-// Test initialization of SenderReputationMonitor
-tap.test('should initialize SenderReputationMonitor with default settings', async () => {
-  resetSingleton();
-  const reputationMonitor = SenderReputationMonitor.getInstance();
-  
-  expect(reputationMonitor).toBeTruthy();
-  // Check if the object has the expected methods
-  expect(typeof reputationMonitor.recordSendEvent).toEqual('function');
-  expect(typeof reputationMonitor.getReputationData).toEqual('function');
-  expect(typeof reputationMonitor.getReputationSummary).toEqual('function');
-});
-
-// Test initialization with custom settings
-tap.test('should initialize SenderReputationMonitor with custom settings', async () => {
-  resetSingleton();
-  const reputationMonitor = SenderReputationMonitor.getInstance({
-    enabled: true,
-    domains: ['example.com', 'test.com'],
-    updateFrequency: 12 * 60 * 60 * 1000, // 12 hours
-    alertThresholds: {
-      minReputationScore: 80,
-      maxComplaintRate: 0.05
-    }
-  });
-  
-  // Test adding domains
-  reputationMonitor.addDomain('newdomain.com');
-  
-  // Test retrieving reputation data
-  const data = reputationMonitor.getReputationData('example.com');
-  expect(data).toBeTruthy();
-  expect(data.domain).toEqual('example.com');
-});
-
-// Test recording and tracking send events
-tap.test('should record send events and update metrics', async () => {
-  resetSingleton();
-  const reputationMonitor = SenderReputationMonitor.getInstance({
-    enabled: true,
-    domains: ['example.com']
-  });
-  
-  // Record a series of events
-  reputationMonitor.recordSendEvent('example.com', { type: 'sent', count: 100 });
-  reputationMonitor.recordSendEvent('example.com', { type: 'delivered', count: 95 });
-  reputationMonitor.recordSendEvent('example.com', { type: 'bounce', hardBounce: true, count: 3 });
-  reputationMonitor.recordSendEvent('example.com', { type: 'bounce', hardBounce: false, count: 2 });
-  reputationMonitor.recordSendEvent('example.com', { type: 'complaint', count: 1 });
-  
-  // Check metrics
-  const metrics = reputationMonitor.getReputationData('example.com');
-  
-  expect(metrics).toBeTruthy();
-  expect(metrics.volume.sent).toEqual(100);
-  expect(metrics.volume.delivered).toEqual(95);
-  expect(metrics.volume.hardBounces).toEqual(3);
-  expect(metrics.volume.softBounces).toEqual(2);
-  expect(metrics.complaints.total).toEqual(1);
-});
-
-// Test reputation score calculation
-tap.test('should calculate reputation scores correctly', async () => {
-  resetSingleton();
-  const reputationMonitor = SenderReputationMonitor.getInstance({
-    enabled: true,
-    domains: ['high.com', 'medium.com', 'low.com']
-  });
-  
-  // Record events for different domains
-  reputationMonitor.recordSendEvent('high.com', { type: 'sent', count: 1000 });
-  reputationMonitor.recordSendEvent('high.com', { type: 'delivered', count: 990 });
-  reputationMonitor.recordSendEvent('high.com', { type: 'open', count: 500 });
-  
-  reputationMonitor.recordSendEvent('medium.com', { type: 'sent', count: 1000 });
-  reputationMonitor.recordSendEvent('medium.com', { type: 'delivered', count: 950 });
-  reputationMonitor.recordSendEvent('medium.com', { type: 'open', count: 300 });
-  
-  reputationMonitor.recordSendEvent('low.com', { type: 'sent', count: 1000 });
-  reputationMonitor.recordSendEvent('low.com', { type: 'delivered', count: 850 });
-  reputationMonitor.recordSendEvent('low.com', { type: 'open', count: 100 });
-  
-  // Get reputation summary
-  const summary = reputationMonitor.getReputationSummary();
-  expect(Array.isArray(summary)).toBeTrue();
-  expect(summary.length >= 3).toBeTrue();
-  
-  // Check that domains are included in the summary
-  const domains = summary.map(item => item.domain);
-  expect(domains.includes('high.com')).toBeTrue();
-  expect(domains.includes('medium.com')).toBeTrue();
-  expect(domains.includes('low.com')).toBeTrue();
-});
-
-// Test adding and removing domains
-tap.test('should add and remove domains for monitoring', async () => {
-  resetSingleton();
-  const reputationMonitor = SenderReputationMonitor.getInstance({
-    enabled: true,
-    domains: ['example.com']
-  });
-  
-  // Add a new domain
-  reputationMonitor.addDomain('newdomain.com');
-  
-  // Record data for the new domain
-  reputationMonitor.recordSendEvent('newdomain.com', { type: 'sent', count: 50 });
-  
-  // Check that data was recorded for the new domain
-  const metrics = reputationMonitor.getReputationData('newdomain.com');
-  expect(metrics).toBeTruthy();
-  expect(metrics.volume.sent).toEqual(50);
-  
-  // Remove a domain
-  reputationMonitor.removeDomain('newdomain.com');
-  
-  // Check that data is no longer available
-  const removedMetrics = reputationMonitor.getReputationData('newdomain.com');
-  expect(removedMetrics === null).toBeTrue();
-});
-
-// Test handling open and click events
-tap.test('should track engagement metrics correctly', async () => {
-  resetSingleton();
-  const reputationMonitor = SenderReputationMonitor.getInstance({
-    enabled: true,
-    domains: ['example.com']
-  });
-  
-  // Record basic sending metrics
-  reputationMonitor.recordSendEvent('example.com', { type: 'sent', count: 1000 });
-  reputationMonitor.recordSendEvent('example.com', { type: 'delivered', count: 950 });
-  
-  // Record engagement events
-  reputationMonitor.recordSendEvent('example.com', { type: 'open', count: 500 });
-  reputationMonitor.recordSendEvent('example.com', { type: 'click', count: 250 });
-  
-  // Check engagement metrics
-  const metrics = reputationMonitor.getReputationData('example.com');
-  expect(metrics).toBeTruthy();
-  expect(metrics.engagement.opens).toEqual(500);
-  expect(metrics.engagement.clicks).toEqual(250);
-  expect(typeof metrics.engagement.openRate).toEqual('number');
-  expect(typeof metrics.engagement.clickRate).toEqual('number');
-});
-
-// Test historical data tracking
-tap.test('should store historical reputation data', async () => {
-  resetSingleton();
-  const reputationMonitor = SenderReputationMonitor.getInstance({
-    enabled: true,
-    domains: ['example.com']
-  });
-  
-  // Record events over multiple days
-  const today = new Date();
-  
-  // Record data
-  reputationMonitor.recordSendEvent('example.com', { type: 'sent', count: 1000 });
-  reputationMonitor.recordSendEvent('example.com', { type: 'delivered', count: 950 });
-  
-  // Get metrics data
-  const metrics = reputationMonitor.getReputationData('example.com');
-  
-  // Check that historical data exists
-  expect(metrics.historical).toBeTruthy();
-  expect(metrics.historical.reputationScores).toBeTruthy();
-  
-  // Check that daily send volume is tracked
-  expect(metrics.volume.dailySendVolume).toBeTruthy();
-  const todayStr = today.toISOString().split('T')[0];
-  expect(metrics.volume.dailySendVolume[todayStr]).toEqual(1000);
-});
-
-// Test event recording for different event types
-tap.test('should correctly handle different event types', async () => {
-  resetSingleton();
-  const reputationMonitor = SenderReputationMonitor.getInstance({
-    enabled: true,
-    domains: ['example.com']
-  });
-  
-  // Record different types of events
-  reputationMonitor.recordSendEvent('example.com', { type: 'sent', count: 100 });
-  reputationMonitor.recordSendEvent('example.com', { type: 'delivered', count: 95 });
-  reputationMonitor.recordSendEvent('example.com', { type: 'bounce', hardBounce: true, count: 3 });
-  reputationMonitor.recordSendEvent('example.com', { type: 'bounce', hardBounce: false, count: 2 });
-  reputationMonitor.recordSendEvent('example.com', { type: 'complaint', receivingDomain: 'gmail.com', count: 1 });
-  reputationMonitor.recordSendEvent('example.com', { type: 'open', count: 50 });
-  reputationMonitor.recordSendEvent('example.com', { type: 'click', count: 25 });
-  
-  // Check metrics for different event types
-  const metrics = reputationMonitor.getReputationData('example.com');
-  
-  // Check volume metrics
-  expect(metrics.volume.sent).toEqual(100);
-  expect(metrics.volume.delivered).toEqual(95);
-  expect(metrics.volume.hardBounces).toEqual(3);
-  expect(metrics.volume.softBounces).toEqual(2);
-  
-  // Check complaint metrics
-  expect(metrics.complaints.total).toEqual(1);
-  expect(metrics.complaints.topDomains[0].domain).toEqual('gmail.com');
-  
-  // Check engagement metrics
-  expect(metrics.engagement.opens).toEqual(50);
-  expect(metrics.engagement.clicks).toEqual(25);
-});
-
-// After all tests, clean up
-tap.test('cleanup', async () => {
-  cleanupTestData();
-});
-
-tap.test('stop', async () => {
-  await tap.stopForcefully();
-});
-
-export default tap.start();

test/test.smartmail.ts

@@ -1,248 +0,0 @@
-import { tap, expect } from '@push.rocks/tapbundle';
-import * as plugins from '../ts/plugins.js';
-import * as paths from '../ts/paths.js';
-
-// Import the components we want to test
-import { EmailValidator } from '../ts/email/classes.emailvalidator.js';
-import { TemplateManager } from '../ts/email/classes.templatemanager.js';
-import { Email } from '../ts/mta/classes.email.js';
-
-// Ensure test directories exist
-paths.ensureDirectories();
-
-tap.test('EmailValidator - should validate email formats correctly', async (tools) => {
-  const validator = new EmailValidator();
-  
-  // Test valid email formats
-  expect(validator.isValidFormat('user@example.com')).toBeTrue();
-  expect(validator.isValidFormat('firstname.lastname@example.com')).toBeTrue();
-  expect(validator.isValidFormat('user+tag@example.com')).toBeTrue();
-  
-  // Test invalid email formats
-  expect(validator.isValidFormat('user@')).toBeFalse();
-  expect(validator.isValidFormat('@example.com')).toBeFalse();
-  expect(validator.isValidFormat('user@example')).toBeFalse();
-  expect(validator.isValidFormat('user.example.com')).toBeFalse();
-});
-
-tap.test('EmailValidator - should perform comprehensive validation', async (tools) => {
-  const validator = new EmailValidator();
-  
-  // Test basic validation (syntax-only)
-  const basicResult = await validator.validate('user@example.com', { checkSyntaxOnly: true });
-  expect(basicResult.isValid).toBeTrue();
-  expect(basicResult.details.formatValid).toBeTrue();
-  
-  // We can't reliably test MX validation in all environments, but the function should run
-  const mxResult = await validator.validate('user@example.com', { checkMx: true });
-  expect(typeof mxResult.isValid).toEqual('boolean');
-  expect(typeof mxResult.hasMx).toEqual('boolean');
-});
-
-tap.test('EmailValidator - should detect invalid emails', async (tools) => {
-  const validator = new EmailValidator();
-  
-  const invalidResult = await validator.validate('invalid@@example.com', { checkSyntaxOnly: true });
-  expect(invalidResult.isValid).toBeFalse();
-  expect(invalidResult.details.formatValid).toBeFalse();
-});
-
-tap.test('TemplateManager - should register and retrieve templates', async (tools) => {
-  const templateManager = new TemplateManager({
-    from: 'test@example.com'
-  });
-  
-  // Register a custom template
-  templateManager.registerTemplate({
-    id: 'test-template',
-    name: 'Test Template',
-    description: 'A test template',
-    from: 'test@example.com',
-    subject: 'Test Subject: {{name}}',
-    bodyHtml: '<p>Hello, {{name}}!</p>',
-    bodyText: 'Hello, {{name}}!',
-    category: 'test'
-  });
-  
-  // Get the template back
-  const template = templateManager.getTemplate('test-template');
-  expect(template).toBeTruthy();
-  expect(template.id).toEqual('test-template');
-  expect(template.subject).toEqual('Test Subject: {{name}}');
-  
-  // List templates
-  const templates = templateManager.listTemplates();
-  expect(templates.length > 0).toBeTrue();
-  expect(templates.some(t => t.id === 'test-template')).toBeTrue();
-});
-
-tap.test('TemplateManager - should create smartmail from template', async (tools) => {
-  const templateManager = new TemplateManager({
-    from: 'test@example.com'
-  });
-  
-  // Register a template
-  templateManager.registerTemplate({
-    id: 'welcome-test',
-    name: 'Welcome Test',
-    description: 'A welcome test template',
-    from: 'welcome@example.com',
-    subject: 'Welcome, {{name}}!',
-    bodyHtml: '<p>Hello, {{name}}! Welcome to our service.</p>',
-    bodyText: 'Hello, {{name}}! Welcome to our service.',
-    category: 'test'
-  });
-  
-  // Create smartmail from template
-  const smartmail = await templateManager.createSmartmail('welcome-test', {
-    name: 'John Doe'
-  });
-  
-  expect(smartmail).toBeTruthy();
-  expect(smartmail.options.from).toEqual('welcome@example.com');
-  expect(smartmail.getSubject()).toEqual('Welcome, John Doe!');
-  expect(smartmail.getBody(true).indexOf('Hello, John Doe!') > -1).toBeTrue();
-});
-
-tap.test('Email - should handle template variables', async (tools) => {
-  // Create email with variables
-  const email = new Email({
-    from: 'sender@example.com',
-    to: 'recipient@example.com',
-    subject: 'Hello {{name}}!',
-    text: 'Welcome, {{name}}! Your order #{{orderId}} has been processed.',
-    html: '<p>Welcome, <strong>{{name}}</strong>! Your order #{{orderId}} has been processed.</p>',
-    variables: {
-      name: 'John Doe',
-      orderId: '12345'
-    }
-  });
-  
-  // Test variable substitution
-  expect(email.getSubjectWithVariables()).toEqual('Hello John Doe!');
-  expect(email.getTextWithVariables()).toEqual('Welcome, John Doe! Your order #12345 has been processed.');
-  expect(email.getHtmlWithVariables().indexOf('<strong>John Doe</strong>') > -1).toBeTrue();
-  
-  // Test with additional variables
-  const additionalVars = {
-    name: 'Jane Smith', // Override existing variable
-    status: 'shipped'   // Add new variable
-  };
-  
-  expect(email.getSubjectWithVariables(additionalVars)).toEqual('Hello Jane Smith!');
-  
-  // Add a new variable
-  email.setVariable('trackingNumber', 'TRK123456');
-  expect(email.getTextWithVariables().indexOf('12345') > -1).toBeTrue();
-  
-  // Update multiple variables at once
-  email.setVariables({
-    orderId: '67890',
-    status: 'delivered'
-  });
-  
-  expect(email.getTextWithVariables().indexOf('67890') > -1).toBeTrue();
-});
-
-tap.test('Email and Smartmail compatibility - should convert between formats', async (tools) => {
-  // Create a Smartmail instance
-  const smartmail = new plugins.smartmail.Smartmail({
-    from: 'smartmail@example.com',
-    subject: 'Test Subject',
-    body: '<p>This is a test email.</p>',
-    creationObjectRef: {
-      orderId: '12345'
-    }
-  });
-  
-  // Add recipient and attachment
-  smartmail.addRecipient('recipient@example.com');
-  
-  const attachment = await plugins.smartfile.SmartFile.fromString(
-    'test.txt',
-    'This is a test attachment',
-    'utf8',
-  );
-  
-  smartmail.addAttachment(attachment);
-  
-  // Convert to Email
-  const resolvedSmartmail = await smartmail;
-  const email = Email.fromSmartmail(resolvedSmartmail);
-  
-  // Verify first conversion (Smartmail to Email)
-  expect(email.from).toEqual('smartmail@example.com');
-  expect(email.to.indexOf('recipient@example.com') > -1).toBeTrue();
-  expect(email.subject).toEqual('Test Subject');
-  expect(email.html?.indexOf('This is a test email') > -1).toBeTrue();
-  expect(email.attachments.length).toEqual(1);
-  
-  // Convert back to Smartmail
-  const convertedSmartmail = await email.toSmartmail();
-  
-  // Verify second conversion (Email back to Smartmail) with simplified assertions
-  expect(convertedSmartmail.options.from).toEqual('smartmail@example.com');
-  expect(Array.isArray(convertedSmartmail.options.to)).toBeTrue();
-  expect(convertedSmartmail.options.to.length).toEqual(1);
-  expect(convertedSmartmail.getSubject()).toEqual('Test Subject');
-  expect(convertedSmartmail.getBody(true).indexOf('This is a test email') > -1).toBeTrue();
-  expect(convertedSmartmail.attachments.length).toEqual(1);
-});
-
-tap.test('Email - should validate email addresses', async (tools) => {
-  // Attempt to create an email with invalid addresses
-  let errorThrown = false;
-  
-  try {
-    const email = new Email({
-      from: 'invalid-email',
-      to: 'recipient@example.com',
-      subject: 'Test',
-      text: 'Test'
-    });
-  } catch (error) {
-    errorThrown = true;
-    expect(error.message.indexOf('Invalid sender email address') > -1).toBeTrue();
-  }
-  
-  expect(errorThrown).toBeTrue();
-  
-  // Attempt with invalid recipient
-  errorThrown = false;
-  
-  try {
-    const email = new Email({
-      from: 'sender@example.com',
-      to: 'invalid-recipient',
-      subject: 'Test',
-      text: 'Test'
-    });
-  } catch (error) {
-    errorThrown = true;
-    expect(error.message.indexOf('Invalid recipient email address') > -1).toBeTrue();
-  }
-  
-  expect(errorThrown).toBeTrue();
-  
-  // Valid email should not throw
-  let validEmail: Email;
-  try {
-    validEmail = new Email({
-      from: 'sender@example.com',
-      to: 'recipient@example.com',
-      subject: 'Test',
-      text: 'Test'
-    });
-    
-    expect(validEmail).toBeTruthy();
-    expect(validEmail.from).toEqual('sender@example.com');
-  } catch (error) {
-    expect(error === undefined).toBeTrue(); // This should not happen
-  }
-});
-
-tap.test('stop', async () => {
-  tap.stopForcefully();
-})
-
-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.ts

@@ -1,9 +0,0 @@
-import { tap, expect } from '@push.rocks/tapbundle';
-
-tap.test('should create a platform service', async () => {});
-
-tap.test('stop', async () => {
-  await tap.stopForcefully();
-});
-
-export default tap.start();

test_watch/devserver.ts

@@ -0,0 +1,69 @@
+import { DcRouter } from '../ts/index.js';
+
+const devRouter = new DcRouter({
+  // 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...');
+
+await devRouter.start();
+
+// Graceful shutdown handlers
+const shutdown = async () => {
+  console.log('\nShutting down...');
+  await devRouter.stop();
+  process.exit(0);
+};
+
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);
+
+console.log('DcRouter dev server running. Press Ctrl+C to stop.');

ts/00_commitinfo_data.ts

@@ -2,7 +2,7 @@
  * autocreated commitinfo by @push.rocks/commitinfo
  */
 export const commitinfo = {
-  name: '@serve.zone/platformservice',
-  version: '2.5.0',
-  description: 'A multifaceted platform service handling mail, SMS, letter delivery, and AI services.'
+  name: '@serve.zone/dcrouter',
+  version: '13.7.0',
+  description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 }

ts/aibridge/classes.aibridge.ts

@@ -1,3 +0,0 @@
-export class AIBridge {
-  
-}

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.platformservicedb.ts

@@ -1,27 +0,0 @@
-import * as plugins from './plugins.js';
-import { SzPlatformService } from './platformservice.js';
-
-
-
-export class PlatformServiceDb {
-  public smartdataDb: plugins.smartdata.SmartdataDb;
-  public platformserviceRef: SzPlatformService;
-
-  constructor(platformserviceRefArg: SzPlatformService) {
-    this.platformserviceRef = platformserviceRefArg;
-  }
-
-  public async start() {
-    this.smartdataDb = new plugins.smartdata.SmartdataDb({
-      mongoDbUser: await this.platformserviceRef.serviceQenv.getEnvVarOnDemand('MONGO_DB_USER'),
-      mongoDbName: await this.platformserviceRef.serviceQenv.getEnvVarOnDemand('MONGO_DB_NAME'),
-      mongoDbPass: await this.platformserviceRef.serviceQenv.getEnvVarOnDemand('MONGO_DB_PASS'),
-      mongoDbUrl: await this.platformserviceRef.serviceQenv.getEnvVarOnDemand('MONGO_DB_URL'),
-    });
-    await this.smartdataDb.init();
-  }
-
-  public async stop() {
-    await this.smartdataDb.close();
-  }
-}

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

@@ -0,0 +1,7 @@
+// Export validation tools only
+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

@@ -0,0 +1,266 @@
+import * as plugins from '../plugins.js';
+import { ValidationError } from '../errors/base.errors.js';
+
+/**
+ * Validation result
+ */
+export interface IValidationResult {
+  /**
+   * Whether the validation passed
+   */
+  valid: boolean;
+  
+  /**
+   * Validation errors if any
+   */
+  errors?: string[];
+  
+  /**
+   * Validated configuration (may include defaults)
+   */
+  config?: any;
+}
+
+/**
+ * Validation schema types
+ */
+export type ValidationSchema = Record<string, {
+  /**
+   * Type of the value
+   */
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  
+  /**
+   * Whether the field is required
+   */
+  required?: boolean;
+  
+  /**
+   * Default value if not specified
+   */
+  default?: any;
+  
+  /**
+   * Minimum value (for numbers)
+   */
+  min?: number;
+  
+  /**
+   * Maximum value (for numbers)
+   */
+  max?: number;
+  
+  /**
+   * Minimum length (for strings or arrays)
+   */
+  minLength?: number;
+  
+  /**
+   * Maximum length (for strings or arrays)
+   */
+  maxLength?: number;
+  
+  /**
+   * Pattern to match (for strings)
+   */
+  pattern?: RegExp;
+  
+  /**
+   * Allowed values (for strings, numbers)
+   */
+  enum?: any[];
+  
+  /**
+   * Nested schema (for objects)
+   */
+  schema?: ValidationSchema;
+  
+  /**
+   * Item schema (for arrays)
+   */
+  items?: {
+    type: 'string' | 'number' | 'boolean' | 'object';
+    schema?: ValidationSchema;
+  };
+  
+  /**
+   * Custom validation function
+   */
+  validate?: (value: any) => boolean | string;
+}>;
+
+/**
+ * Configuration validator
+ * Validates configuration objects against schemas and provides default values
+ */
+export class ConfigValidator {
+
+  /**
+   * Validate a configuration object against a schema
+   * 
+   * @param config Configuration object to validate
+   * @param schema Validation schema
+   * @returns Validation result
+   */
+  public static validate<T>(config: T, schema: ValidationSchema): IValidationResult {
+    const errors: string[] = [];
+    const validatedConfig = { ...config };
+
+    // Validate each field against the schema
+    for (const [key, rules] of Object.entries(schema)) {
+      const value = config[key];
+
+      // Check if required
+      if (rules.required && (value === undefined || value === null)) {
+        errors.push(`${key} is required`);
+        continue;
+      }
+
+      // If not present and not required, apply default if available
+      if ((value === undefined || value === null)) {
+        if (rules.default !== undefined) {
+          validatedConfig[key] = rules.default;
+        }
+        continue;
+      }
+
+      // Type validation
+      if (value !== undefined && value !== null) {
+        const valueType = Array.isArray(value) ? 'array' : typeof value;
+        if (valueType !== rules.type) {
+          errors.push(`${key} must be of type ${rules.type}, got ${valueType}`);
+          continue;
+        }
+
+        // Type-specific validations
+        switch (rules.type) {
+          case 'number':
+            if (rules.min !== undefined && value < rules.min) {
+              errors.push(`${key} must be at least ${rules.min}`);
+            }
+            if (rules.max !== undefined && value > rules.max) {
+              errors.push(`${key} must be at most ${rules.max}`);
+            }
+            break;
+
+          case 'string':
+            if (rules.minLength !== undefined && value.length < rules.minLength) {
+              errors.push(`${key} must be at least ${rules.minLength} characters`);
+            }
+            if (rules.maxLength !== undefined && value.length > rules.maxLength) {
+              errors.push(`${key} must be at most ${rules.maxLength} characters`);
+            }
+            if (rules.pattern && !rules.pattern.test(value)) {
+              errors.push(`${key} must match pattern ${rules.pattern}`);
+            }
+            break;
+
+          case 'array':
+            if (rules.minLength !== undefined && value.length < rules.minLength) {
+              errors.push(`${key} must have at least ${rules.minLength} items`);
+            }
+            if (rules.maxLength !== undefined && value.length > rules.maxLength) {
+              errors.push(`${key} must have at most ${rules.maxLength} items`);
+            }
+            if (rules.items && value.length > 0) {
+              for (let i = 0; i < value.length; i++) {
+                const itemType = Array.isArray(value[i]) ? 'array' : typeof value[i];
+                if (itemType !== rules.items.type) {
+                  errors.push(`${key}[${i}] must be of type ${rules.items.type}, got ${itemType}`);
+                } 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}`));
+                  }
+                }
+              }
+            }
+            break;
+
+          case 'object':
+            if (rules.schema) {
+              const nestedResult = this.validate(value, rules.schema);
+              if (!nestedResult.valid) {
+                errors.push(...nestedResult.errors!.map(err => `${key}.${err}`));
+              }
+              validatedConfig[key] = nestedResult.config;
+            }
+            break;
+        }
+
+        // Enum validation
+        if (rules.enum && !rules.enum.includes(value)) {
+          errors.push(`${key} must be one of [${rules.enum.join(', ')}]`);
+        }
+
+        // Custom validation
+        if (rules.validate) {
+          const result = rules.validate(value);
+          if (result !== true) {
+            errors.push(typeof result === 'string' ? result : `${key} failed custom validation`);
+          }
+        }
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors: errors.length > 0 ? errors : undefined,
+      config: validatedConfig
+    };
+  }
+
+
+  /**
+   * Apply defaults to a configuration object based on a schema
+   * 
+   * @param config Configuration object to apply defaults to
+   * @param schema Validation schema with defaults
+   * @returns Configuration with defaults applied
+   */
+  public static applyDefaults<T>(config: T, schema: ValidationSchema): T {
+    const result = { ...config };
+
+    for (const [key, rules] of Object.entries(schema)) {
+      if (result[key] === undefined && rules.default !== undefined) {
+        result[key] = rules.default;
+      }
+
+      // Apply defaults to nested objects
+      if (result[key] && rules.type === 'object' && rules.schema) {
+        result[key] = this.applyDefaults(result[key], rules.schema);
+      }
+
+      // 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
+        );
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Throw a validation error if the configuration is invalid
+   * 
+   * @param config Configuration to validate
+   * @param schema Validation schema
+   * @returns Validated configuration with defaults
+   * @throws ValidationError if validation fails
+   */
+  public static validateOrThrow<T>(config: T, schema: ValidationSchema): T {
+    const result = this.validate(config, schema);
+    
+    if (!result.valid) {
+      throw new ValidationError(
+        `Configuration validation failed: ${result.errors!.join(', ')}`,
+        'CONFIG_VALIDATION_ERROR',
+        { data: { errors: result.errors } }
+      );
+    }
+    
+    return result.config;
+  }
+}

ts/db/classes.cache.cleaner.ts

@@ -0,0 +1,166 @@
+import * as plugins from '../plugins.js';
+import { logger } from '../logger.js';
+import { DcRouterDb } from './classes.dcrouter-db.js';
+
+// Import document classes for cleanup
+import { CachedEmail } from './documents/classes.cached.email.js';
+import { CachedIPReputation } from './documents/classes.cached.ip.reputation.js';
+
+/**
+ * Configuration for the cache cleaner
+ */
+export interface ICacheCleanerOptions {
+  /** Cleanup interval in milliseconds (default: 1 hour) */
+  intervalMs?: number;
+  /** Enable verbose logging */
+  verbose?: boolean;
+}
+
+/**
+ * CacheCleaner - Periodically removes expired documents from the cache
+ *
+ * Runs on a configurable interval (default: hourly) and queries each
+ * collection for documents where expiresAt < now(), then deletes them.
+ */
+export class CacheCleaner {
+  private cleanupInterval: ReturnType<typeof setInterval> | null = null;
+  private isRunning: boolean = false;
+  private options: Required<ICacheCleanerOptions>;
+  private dcRouterDb: DcRouterDb;
+
+  constructor(dcRouterDb: DcRouterDb, options: ICacheCleanerOptions = {}) {
+    this.dcRouterDb = dcRouterDb;
+    this.options = {
+      intervalMs: options.intervalMs || 60 * 60 * 1000, // 1 hour default
+      verbose: options.verbose || false,
+    };
+  }
+
+  /**
+   * Start the periodic cleanup process
+   */
+  public start(): void {
+    if (this.isRunning) {
+      logger.log('warn', 'CacheCleaner already running');
+      return;
+    }
+
+    this.isRunning = true;
+
+    // Run cleanup immediately on start
+    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: unknown) => {
+        logger.log('error', `Cache cleanup failed: ${(error as Error).message}`);
+      });
+    }, this.options.intervalMs);
+
+    logger.log(
+      'info',
+      `CacheCleaner started with interval: ${this.options.intervalMs / 1000 / 60} minutes`
+    );
+  }
+
+  /**
+   * Stop the periodic cleanup process
+   */
+  public stop(): void {
+    if (!this.isRunning) {
+      return;
+    }
+
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+
+    this.isRunning = false;
+    logger.log('info', 'CacheCleaner stopped');
+  }
+
+  /**
+   * Run a single cleanup cycle
+   */
+  public async runCleanup(): Promise<void> {
+    if (!this.dcRouterDb.isReady()) {
+      logger.log('warn', 'DcRouterDb not ready, skipping cleanup');
+      return;
+    }
+
+    const now = new Date();
+    const results: { collection: string; deleted: number }[] = [];
+
+    try {
+      const emailsDeleted = await this.cleanExpiredDocuments(CachedEmail, now);
+      results.push({ collection: 'CachedEmail', deleted: emailsDeleted });
+
+      const ipReputationDeleted = await this.cleanExpiredDocuments(CachedIPReputation, now);
+      results.push({ collection: 'CachedIPReputation', deleted: ipReputationDeleted });
+
+      // Log results
+      const totalDeleted = results.reduce((sum, r) => sum + r.deleted, 0);
+      if (totalDeleted > 0 || this.options.verbose) {
+        const summary = results
+          .filter((r) => r.deleted > 0)
+          .map((r) => `${r.collection}: ${r.deleted}`)
+          .join(', ');
+        logger.log(
+          'info',
+          `Cache cleanup completed. Deleted ${totalDeleted} expired documents. ${summary || 'No deletions.'}`
+        );
+      }
+    } catch (error: unknown) {
+      logger.log('error', `Cache cleanup error: ${(error as Error).message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Clean expired documents from a specific collection using smartdata API
+   */
+  private async cleanExpiredDocuments<T extends { delete: () => Promise<void> }>(
+    documentClass: { getInstances: (filter: any) => Promise<T[]> },
+    now: Date
+  ): Promise<number> {
+    try {
+      // Find all expired documents
+      const expiredDocs = await documentClass.getInstances({
+        expiresAt: { $lt: now },
+      });
+
+      // Delete each expired document
+      let deletedCount = 0;
+      for (const doc of expiredDocs) {
+        try {
+          await doc.delete();
+          deletedCount++;
+        } catch (deleteError: unknown) {
+          logger.log('warn', `Failed to delete expired document: ${(deleteError as Error).message}`);
+        }
+      }
+
+      return deletedCount;
+    } catch (error: unknown) {
+      logger.log('error', `Error cleaning collection: ${(error as Error).message}`);
+      return 0;
+    }
+  }
+
+  /**
+   * Check if the cleaner is running
+   */
+  public isActive(): boolean {
+    return this.isRunning;
+  }
+
+  /**
+   * Get the cleanup interval in milliseconds
+   */
+  public getIntervalMs(): number {
+    return this.options.intervalMs;
+  }
+}

ts/db/classes.cached.document.ts

@@ -0,0 +1,111 @@
+import * as plugins from '../plugins.js';
+
+/**
+ * Base class for all cached documents with TTL support
+ *
+ * Extends smartdata's SmartDataDbDoc to add:
+ * - Automatic timestamps (createdAt, lastAccessedAt)
+ * - TTL/expiration support (expiresAt)
+ * - Helper methods for TTL management
+ *
+ * NOTE: Subclasses MUST add @svDb() decorators to createdAt, expiresAt, and lastAccessedAt
+ * since decorators on abstract classes don't propagate correctly.
+ */
+export abstract class CachedDocument<T extends CachedDocument<T>> extends plugins.smartdata.SmartDataDbDoc<T, T> {
+  /**
+   * Timestamp when the document was created
+   * NOTE: Subclasses must add @svDb() decorator
+   */
+  public createdAt: Date = new Date();
+
+  /**
+   * Timestamp when the document expires and should be cleaned up
+   * NOTE: Subclasses must add @svDb() decorator
+   */
+  public expiresAt!: Date;
+
+  /**
+   * Timestamp of last access (for LRU-style eviction if needed)
+   * NOTE: Subclasses must add @svDb() decorator
+   */
+  public lastAccessedAt: Date = new Date();
+
+  /**
+   * Set the TTL (time to live) for this document
+   * @param ttlMs Time to live in milliseconds
+   */
+  public setTTL(ttlMs: number): void {
+    this.expiresAt = new Date(Date.now() + ttlMs);
+  }
+
+  /**
+   * Set TTL using days
+   * @param days Number of days until expiration
+   */
+  public setTTLDays(days: number): void {
+    this.setTTL(days * 24 * 60 * 60 * 1000);
+  }
+
+  /**
+   * Set TTL using hours
+   * @param hours Number of hours until expiration
+   */
+  public setTTLHours(hours: number): void {
+    this.setTTL(hours * 60 * 60 * 1000);
+  }
+
+  /**
+   * Check if this document has expired
+   */
+  public isExpired(): boolean {
+    if (!this.expiresAt) {
+      return false; // No expiration set
+    }
+    return new Date() > this.expiresAt;
+  }
+
+  /**
+   * Update the lastAccessedAt timestamp
+   */
+  public touch(): void {
+    this.lastAccessedAt = new Date();
+  }
+
+  /**
+   * Get remaining TTL in milliseconds
+   * Returns 0 if expired, -1 if no expiration set
+   */
+  public getRemainingTTL(): number {
+    if (!this.expiresAt) {
+      return -1;
+    }
+    const remaining = this.expiresAt.getTime() - Date.now();
+    return remaining > 0 ? remaining : 0;
+  }
+
+  /**
+   * Extend the TTL by the specified milliseconds from now
+   * @param ttlMs Additional time to live in milliseconds
+   */
+  public extendTTL(ttlMs: number): void {
+    this.expiresAt = new Date(Date.now() + ttlMs);
+  }
+
+  /**
+   * Set the document to never expire (100 years in the future)
+   */
+  public setNeverExpires(): void {
+    this.expiresAt = new Date(Date.now() + 100 * 365 * 24 * 60 * 60 * 1000);
+  }
+}
+
+/**
+ * TTL constants in milliseconds
+ */
+export const TTL = {
+  HOURS_1: 1 * 60 * 60 * 1000,
+  HOURS_24: 24 * 60 * 60 * 1000,
+  DAYS_7: 7 * 24 * 60 * 60 * 1000,
+  DAYS_30: 30 * 24 * 60 * 60 * 1000,
+  DAYS_90: 90 * 24 * 60 * 60 * 1000,
+} as const;

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.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

@@ -0,0 +1,240 @@
+import * as plugins from '../../plugins.js';
+import { CachedDocument, TTL } from '../classes.cached.document.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+
+/**
+ * Email status in the cache
+ */
+export type TCachedEmailStatus = 'pending' | 'processing' | 'delivered' | 'failed' | 'deferred';
+
+/**
+ * Helper to get the smartdata database instance
+ */
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+/**
+ * CachedEmail - Stores email queue items in the cache
+ *
+ * Used for persistent email queue storage, tracking delivery status,
+ * and maintaining email history for the configured TTL period.
+ */
+@plugins.smartdata.Collection(() => getDb())
+export class CachedEmail extends CachedDocument<CachedEmail> {
+  // TTL fields from base class (decorators required on concrete class)
+  @plugins.smartdata.svDb()
+  public createdAt: Date = new Date();
+
+  @plugins.smartdata.svDb()
+  public expiresAt: Date = new Date(Date.now() + TTL.DAYS_30);
+
+  @plugins.smartdata.svDb()
+  public lastAccessedAt: Date = new Date();
+
+  /**
+   * Unique identifier for this email
+   */
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public id!: string;
+
+  /**
+   * Email message ID (RFC 822 Message-ID header)
+   */
+  @plugins.smartdata.svDb()
+  public messageId!: string;
+
+  /**
+   * Sender email address (envelope from)
+   */
+  @plugins.smartdata.svDb()
+  public from!: string;
+
+  /**
+   * Recipient email addresses
+   */
+  @plugins.smartdata.svDb()
+  public to!: string[];
+
+  /**
+   * CC recipients
+   */
+  @plugins.smartdata.svDb()
+  public cc!: string[];
+
+  /**
+   * BCC recipients
+   */
+  @plugins.smartdata.svDb()
+  public bcc!: string[];
+
+  /**
+   * Email subject
+   */
+  @plugins.smartdata.svDb()
+  public subject!: string;
+
+  /**
+   * Raw RFC822 email content
+   */
+  @plugins.smartdata.svDb()
+  public rawContent!: string;
+
+  /**
+   * Current status of the email
+   */
+  @plugins.smartdata.svDb()
+  public status!: TCachedEmailStatus;
+
+  /**
+   * Number of delivery attempts
+   */
+  @plugins.smartdata.svDb()
+  public attempts: number = 0;
+
+  /**
+   * Maximum number of delivery attempts
+   */
+  @plugins.smartdata.svDb()
+  public maxAttempts: number = 3;
+
+  /**
+   * Timestamp for next delivery attempt
+   */
+  @plugins.smartdata.svDb()
+  public nextAttempt!: Date;
+
+  /**
+   * Last error message if delivery failed
+   */
+  @plugins.smartdata.svDb()
+  public lastError!: string;
+
+  /**
+   * Timestamp when the email was successfully delivered
+   */
+  @plugins.smartdata.svDb()
+  public deliveredAt!: Date;
+
+  /**
+   * Sender domain (for querying/filtering)
+   */
+  @plugins.smartdata.svDb()
+  public senderDomain!: string;
+
+  /**
+   * Priority level (higher = more important)
+   */
+  @plugins.smartdata.svDb()
+  public priority: number = 0;
+
+  /**
+   * JSON-serialized route data
+   */
+  @plugins.smartdata.svDb()
+  public routeData!: string;
+
+  /**
+   * DKIM signature status
+   */
+  @plugins.smartdata.svDb()
+  public dkimSigned: boolean = false;
+
+  constructor() {
+    super();
+    this.setTTL(TTL.DAYS_30); // Default 30-day TTL
+    this.status = 'pending';
+    this.to = [];
+    this.cc = [];
+    this.bcc = [];
+  }
+
+  /**
+   * Create a new CachedEmail with a unique ID
+   */
+  public static createNew(): CachedEmail {
+    const email = new CachedEmail();
+    email.id = plugins.uuid.v4();
+    return email;
+  }
+
+  /**
+   * Find an email by ID
+   */
+  public static async findById(id: string): Promise<CachedEmail | null> {
+    return await CachedEmail.getInstance({
+      id,
+    });
+  }
+
+  /**
+   * Find all emails with a specific status
+   */
+  public static async findByStatus(status: TCachedEmailStatus): Promise<CachedEmail[]> {
+    return await CachedEmail.getInstances({
+      status,
+    });
+  }
+
+  /**
+   * Find all emails pending delivery (status = pending and nextAttempt <= now)
+   */
+  public static async findPendingForDelivery(): Promise<CachedEmail[]> {
+    const now = new Date();
+    return await CachedEmail.getInstances({
+      status: 'pending',
+      nextAttempt: { $lte: now },
+    });
+  }
+
+  /**
+   * Find emails by sender domain
+   */
+  public static async findBySenderDomain(domain: string): Promise<CachedEmail[]> {
+    return await CachedEmail.getInstances({
+      senderDomain: domain,
+    });
+  }
+
+  /**
+   * Mark as delivered
+   */
+  public markDelivered(): void {
+    this.status = 'delivered';
+    this.deliveredAt = new Date();
+  }
+
+  /**
+   * Mark as failed with error
+   */
+  public markFailed(error: string): void {
+    this.status = 'failed';
+    this.lastError = error;
+  }
+
+  /**
+   * Increment attempt counter and schedule next attempt
+   */
+  public scheduleRetry(delayMs: number = 5 * 60 * 1000): void {
+    this.attempts++;
+    this.status = 'deferred';
+    this.nextAttempt = new Date(Date.now() + delayMs);
+
+    // If max attempts reached, mark as failed
+    if (this.attempts >= this.maxAttempts) {
+      this.status = 'failed';
+      this.lastError = `Max attempts (${this.maxAttempts}) reached`;
+    }
+  }
+
+  /**
+   * Extract sender domain from email address
+   */
+  public updateSenderDomain(): void {
+    if (this.from) {
+      const match = this.from.match(/@([^>]+)>?$/);
+      if (match) {
+        this.senderDomain = match[1].toLowerCase();
+      }
+    }
+  }
+}

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

@@ -0,0 +1,247 @@
+import * as plugins from '../../plugins.js';
+import { CachedDocument, TTL } from '../classes.cached.document.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+
+/**
+ * Helper to get the smartdata database instance
+ */
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+/**
+ * IP reputation result data
+ */
+export interface IIPReputationData {
+  score: number;
+  isSpam: boolean;
+  isProxy: boolean;
+  isTor: boolean;
+  isVPN: boolean;
+  country?: string;
+  asn?: string;
+  org?: string;
+  blacklists?: string[];
+}
+
+/**
+ * CachedIPReputation - Stores IP reputation lookup results
+ *
+ * Caches the results of IP reputation checks to avoid repeated
+ * external API calls. Default TTL is 24 hours.
+ */
+@plugins.smartdata.Collection(() => getDb())
+export class CachedIPReputation extends CachedDocument<CachedIPReputation> {
+  // TTL fields from base class (decorators required on concrete class)
+  @plugins.smartdata.svDb()
+  public createdAt: Date = new Date();
+
+  @plugins.smartdata.svDb()
+  public expiresAt: Date = new Date(Date.now() + TTL.HOURS_24);
+
+  @plugins.smartdata.svDb()
+  public lastAccessedAt: Date = new Date();
+
+  /**
+   * IP address (unique identifier)
+   */
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public ipAddress!: string;
+
+  /**
+   * Reputation score (0-100, higher = better)
+   */
+  @plugins.smartdata.svDb()
+  public score!: number;
+
+  /**
+   * Whether the IP is flagged as spam source
+   */
+  @plugins.smartdata.svDb()
+  public isSpam!: boolean;
+
+  /**
+   * Whether the IP is a known proxy
+   */
+  @plugins.smartdata.svDb()
+  public isProxy!: boolean;
+
+  /**
+   * Whether the IP is a Tor exit node
+   */
+  @plugins.smartdata.svDb()
+  public isTor!: boolean;
+
+  /**
+   * Whether the IP is a VPN endpoint
+   */
+  @plugins.smartdata.svDb()
+  public isVPN!: boolean;
+
+  /**
+   * Country code (ISO 3166-1 alpha-2)
+   */
+  @plugins.smartdata.svDb()
+  public country!: string;
+
+  /**
+   * Autonomous System Number
+   */
+  @plugins.smartdata.svDb()
+  public asn!: string;
+
+  /**
+   * Organization name
+   */
+  @plugins.smartdata.svDb()
+  public org!: string;
+
+  /**
+   * List of blacklists the IP appears on
+   */
+  @plugins.smartdata.svDb()
+  public blacklists!: string[];
+
+  /**
+   * Number of times this IP has been checked
+   */
+  @plugins.smartdata.svDb()
+  public checkCount: number = 0;
+
+  /**
+   * Number of connections from this IP
+   */
+  @plugins.smartdata.svDb()
+  public connectionCount: number = 0;
+
+  /**
+   * Number of emails received from this IP
+   */
+  @plugins.smartdata.svDb()
+  public emailCount: number = 0;
+
+  /**
+   * Number of spam emails from this IP
+   */
+  @plugins.smartdata.svDb()
+  public spamCount: number = 0;
+
+  constructor() {
+    super();
+    this.setTTL(TTL.HOURS_24); // Default 24-hour TTL
+    this.blacklists = [];
+    this.score = 50; // Default neutral score
+    this.isSpam = false;
+    this.isProxy = false;
+    this.isTor = false;
+    this.isVPN = false;
+  }
+
+  /**
+   * Create from reputation data
+   */
+  public static fromReputationData(ipAddress: string, data: IIPReputationData): CachedIPReputation {
+    const cached = new CachedIPReputation();
+    cached.ipAddress = ipAddress;
+    cached.score = data.score;
+    cached.isSpam = data.isSpam;
+    cached.isProxy = data.isProxy;
+    cached.isTor = data.isTor;
+    cached.isVPN = data.isVPN;
+    cached.country = data.country || '';
+    cached.asn = data.asn || '';
+    cached.org = data.org || '';
+    cached.blacklists = data.blacklists || [];
+    cached.checkCount = 1;
+    return cached;
+  }
+
+  /**
+   * Convert to reputation data object
+   */
+  public toReputationData(): IIPReputationData {
+    this.touch();
+    return {
+      score: this.score,
+      isSpam: this.isSpam,
+      isProxy: this.isProxy,
+      isTor: this.isTor,
+      isVPN: this.isVPN,
+      country: this.country,
+      asn: this.asn,
+      org: this.org,
+      blacklists: this.blacklists,
+    };
+  }
+
+  /**
+   * Find by IP address
+   */
+  public static async findByIP(ipAddress: string): Promise<CachedIPReputation | null> {
+    return await CachedIPReputation.getInstance({
+      ipAddress,
+    });
+  }
+
+  /**
+   * Find all IPs flagged as spam
+   */
+  public static async findSpamIPs(): Promise<CachedIPReputation[]> {
+    return await CachedIPReputation.getInstances({
+      isSpam: true,
+    });
+  }
+
+  /**
+   * Find IPs with score below threshold
+   */
+  public static async findLowScoreIPs(threshold: number): Promise<CachedIPReputation[]> {
+    return await CachedIPReputation.getInstances({
+      score: { $lt: threshold },
+    });
+  }
+
+  /**
+   * Record a connection from this IP
+   */
+  public recordConnection(): void {
+    this.connectionCount++;
+    this.touch();
+  }
+
+  /**
+   * Record an email from this IP
+   */
+  public recordEmail(isSpam: boolean = false): void {
+    this.emailCount++;
+    if (isSpam) {
+      this.spamCount++;
+    }
+    this.touch();
+  }
+
+  /**
+   * Update the reputation data
+   */
+  public updateReputation(data: IIPReputationData): void {
+    this.score = data.score;
+    this.isSpam = data.isSpam;
+    this.isProxy = data.isProxy;
+    this.isTor = data.isTor;
+    this.isVPN = data.isVPN;
+    this.country = data.country || this.country;
+    this.asn = data.asn || this.asn;
+    this.org = data.org || this.org;
+    this.blacklists = data.blacklists || this.blacklists;
+    this.checkCount++;
+    this.touch();
+    // Refresh TTL on update
+    this.setTTL(TTL.HOURS_24);
+  }
+
+  /**
+   * Check if this IP should be blocked
+   */
+  public shouldBlock(): boolean {
+    return this.isSpam || this.score < 20 || this.blacklists.length > 2;
+  }
+}

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,32 @@
+// 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';

ts/db/index.ts

@@ -0,0 +1,11 @@
+// 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
+export * from './documents/index.js';

ts/dcrouter/classes.dcr.sz.connector.ts

@@ -1,20 +0,0 @@
-// This file is maintained for backward compatibility only
-// New code should use qenv directly
-
-import * as plugins from '../plugins.js';
-import type DcRouter from './classes.dcrouter.js';
-
-export class SzDcRouterConnector {
-  public qenv: plugins.qenv.Qenv;
-  public dcRouterRef: DcRouter;
-  
-  constructor(dcRouterRef: DcRouter) {
-    this.dcRouterRef = dcRouterRef;
-    // Initialize qenv directly
-    this.qenv = new plugins.qenv.Qenv('./', '.nogit/');
-  }
-
-  public async getEnvVarOnDemand(varName: string): Promise<string> {
-    return this.qenv.getEnvVarOnDemand(varName) || '';
-  }
-}

ts/dcrouter/classes.dcrouter.ts

@@ -1,357 +0,0 @@
-import * as plugins from '../plugins.js';
-import * as paths from '../paths.js';
-import { SmtpPortConfig, type ISmtpPortSettings } from './classes.smtp.portconfig.js';
-import { EmailDomainRouter, type IEmailDomainRoutingConfig } from './classes.email.domainrouter.js';
-
-import { type IMtaConfig, MtaService } from '../mta/classes.mta.js';
-
-// Certificate types are available via plugins.tsclass
-
-/**
- * Configuration for SMTP forwarding functionality
- */
-export interface ISmtpForwardingConfig {
-  /** Whether SMTP forwarding is enabled */
-  enabled?: boolean;
-  /** SMTP ports to listen on */
-  ports?: number[];
-  /** Default SMTP server hostname */
-  defaultServer: string;
-  /** Default SMTP server port */
-  defaultPort?: number;
-  /** Whether to use TLS when connecting to the default server */
-  useTls?: boolean;
-  /** Preserve source IP address when forwarding */
-  preserveSourceIp?: boolean;
-  /** Domain-specific routing rules */
-  domainRoutes?: Array<{
-    domain: string;
-    server: string;
-    port?: number;
-  }>;
-}
-
-/**
- * Simple domain-based routing configuration
- */
-export interface IDomainRoutingConfig {
-  /** The domain name or pattern (e.g., example.com or *.example.com) */
-  domain: string;
-  /** Target server hostname or IP */
-  targetServer: string;
-  /** Target port */
-  targetPort: number;
-  /** Enable HTTPS/TLS for this route */
-  useTls?: boolean;
-  /** Allow incoming connections from these IP ranges (default: all) */
-  allowedIps?: string[];
-}
-
-export interface IDcRouterOptions {
-  /** HTTP/HTTPS domain-based routing */
-  httpDomainRoutes?: IDomainRoutingConfig[];
-  
-  /** SMTP forwarding configuration */
-  smtpForwarding?: ISmtpForwardingConfig;
-  
-  /** MTA service configuration (if not using SMTP forwarding) */
-  mtaConfig?: IMtaConfig;
-  
-  /** Existing MTA service instance to use (if not using SMTP forwarding) */
-  mtaServiceInstance?: MtaService;
-  
-  /** TLS/certificate configuration */
-  tls?: {
-    /** Contact email for ACME certificates */
-    contactEmail: string;
-    /** Domain for main certificate */
-    domain?: string;
-    /** Path to certificate file (if not using auto-provisioning) */
-    certPath?: string;
-    /** Path to key file (if not using auto-provisioning) */
-    keyPath?: string;
-  };
-  
-  /** DNS server configuration */
-  dnsServerConfig?: plugins.smartdns.IDnsServerOptions;
-}
-
-/**
- * DcRouter can be run on ingress and egress to and from a datacenter site.
- */
-/**
- * Context passed to HTTP routing rules
- */
-/**
- * Context passed to port proxy (SmartProxy) routing rules
- */
-export interface PortProxyRuleContext {
-  proxy: plugins.smartproxy.SmartProxy;
-  configs: plugins.smartproxy.IPortProxySettings['domainConfigs'];
-}
-export class DcRouter {
-  public options: IDcRouterOptions;
-  
-  // Core services
-  public smartProxy?: plugins.smartproxy.SmartProxy;
-  public smtpProxy?: plugins.smartproxy.SmartProxy;
-  public mta?: MtaService;
-  public dnsServer?: plugins.smartdns.DnsServer;
-  
-  // Environment access 
-  private qenv = new plugins.qenv.Qenv('./', '.nogit/');
-  
-  constructor(optionsArg: IDcRouterOptions) {
-    // Set defaults in options
-    this.options = {
-      ...optionsArg
-    };
-  }
-
-  public async start() {
-    console.log('Starting DcRouter services...');
-    
-    try {
-      // 1. Set up HTTP/HTTPS traffic handling with SmartProxy
-      await this.setupHttpProxy();
-      
-      // 2. Set up MTA or SMTP forwarding
-      if (this.options.smtpForwarding?.enabled) {
-        await this.setupSmtpForwarding();
-      } else {
-        await this.setupMtaService();
-      }
-      
-      // 3. Set up DNS server if configured
-      if (this.options.dnsServerConfig) {
-        this.dnsServer = new plugins.smartdns.DnsServer(this.options.dnsServerConfig);
-        await this.dnsServer.start();
-        console.log('DNS server started');
-      }
-      
-      console.log('DcRouter started successfully');
-    } catch (error) {
-      console.error('Error starting DcRouter:', error);
-      // Try to clean up any services that may have started
-      await this.stop();
-      throw error;
-    }
-  }
-  
-  /**
-   * Set up SmartProxy for HTTP/HTTPS traffic
-   */
-  private async setupHttpProxy() {
-    if (!this.options.httpDomainRoutes || this.options.httpDomainRoutes.length === 0) {
-      console.log('No HTTP domain routes configured, skipping HTTP proxy setup');
-      return;
-    }
-    
-    console.log('Setting up SmartProxy for HTTP/HTTPS traffic');
-    
-    // Prepare SmartProxy configuration
-    const smartProxyConfig: plugins.smartproxy.ISmartProxyOptions = {
-      fromPort: 443,
-      toPort: this.options.httpDomainRoutes[0].targetPort,
-      targetIP: this.options.httpDomainRoutes[0].targetServer,
-      sniEnabled: true,
-      acme: {
-        port: 80,
-        enabled: true,
-        autoRenew: true,
-        useProduction: true,
-        renewThresholdDays: 30,
-        accountEmail: this.options.tls?.contactEmail || 'admin@example.com' // ACME requires an email
-      },
-      globalPortRanges: [{ from: 443, to: 443 }],
-      domainConfigs: []
-    };
-    
-    // Create domain configs from the HTTP routes
-    smartProxyConfig.domainConfigs = this.options.httpDomainRoutes.map(route => ({
-      domains: [route.domain],
-      targetIPs: [route.targetServer],
-      allowedIPs: route.allowedIps || ['0.0.0.0/0'],
-      // Skip certificate management for wildcard domains as it's not supported by HTTP-01 challenges
-      certificateManagement: !route.domain.includes('*')
-    }));
-    
-    // Create and start the SmartProxy instance
-    this.smartProxy = new plugins.smartproxy.SmartProxy(smartProxyConfig);
-    
-    // Listen for certificate events
-    this.smartProxy.on('certificate-issued', event => {
-      console.log(`Certificate issued for ${event.domain}, expires ${event.expiryDate}`);
-    });
-    
-    this.smartProxy.on('certificate-renewed', event => {
-      console.log(`Certificate renewed for ${event.domain}, expires ${event.expiryDate}`);
-    });
-    
-    await this.smartProxy.start();
-    
-    console.log(`HTTP/HTTPS proxy configured with ${smartProxyConfig.domainConfigs.length} domain routes`);
-  }
-  
-  /**
-   * Set up the MTA service
-   */
-  private async setupMtaService() {
-    // Use existing MTA service if provided
-    if (this.options.mtaServiceInstance) {
-      this.mta = this.options.mtaServiceInstance;
-      console.log('Using provided MTA service instance');
-    } else if (this.options.mtaConfig) {
-      // Create new MTA service with the provided configuration
-      this.mta = new MtaService(undefined, this.options.mtaConfig);
-      console.log('Created new MTA service instance');
-      
-      // Start the MTA service
-      await this.mta.start();
-      console.log('MTA service started');
-    }
-  }
-  
-  /**
-   * Set up SMTP forwarding with SmartProxy
-   */
-  private async setupSmtpForwarding() {
-    if (!this.options.smtpForwarding) {
-      return;
-    }
-    
-    const forwarding = this.options.smtpForwarding;
-    console.log('Setting up SMTP forwarding');
-    
-    // Determine which ports to listen on
-    const smtpPorts = forwarding.ports || [25, 587, 465];
-    
-    // Create SmartProxy instance for SMTP forwarding
-    this.smtpProxy = new plugins.smartproxy.SmartProxy({
-      // Listen on the first SMTP port
-      fromPort: smtpPorts[0],
-      // Forward to the default server
-      toPort: forwarding.defaultPort || 25,
-      targetIP: forwarding.defaultServer,
-      // Enable SNI if port 465 is included (implicit TLS)
-      sniEnabled: smtpPorts.includes(465),
-      // Preserve source IP if requested
-      preserveSourceIP: forwarding.preserveSourceIp || false,
-      // Create domain configs for SMTP routing
-      domainConfigs: forwarding.domainRoutes?.map(route => ({
-        domains: [route.domain],
-        allowedIPs: ['0.0.0.0/0'], // Allow from anywhere by default
-        targetIPs: [route.server]
-      })) || [],
-      // Include all SMTP ports in the global port ranges
-      globalPortRanges: smtpPorts.map(port => ({ from: port, to: port }))
-    });
-    
-    // Start the SMTP proxy
-    await this.smtpProxy.start();
-    
-    console.log(`SMTP forwarding configured on ports ${smtpPorts.join(', ')}`);
-  }
-
-  /**
-   * Check if a domain matches a pattern (including wildcard support)
-   * @param domain The domain to check
-   * @param pattern The pattern to match against (e.g., "*.example.com")
-   * @returns Whether the domain matches the pattern
-   */
-  private isDomainMatch(domain: string, pattern: string): boolean {
-    // Normalize inputs
-    domain = domain.toLowerCase();
-    pattern = pattern.toLowerCase();
-    
-    // Check for exact match
-    if (domain === pattern) {
-      return true;
-    }
-    
-    // Check for wildcard match (*.example.com)
-    if (pattern.startsWith('*.')) {
-      const patternSuffix = pattern.slice(2); // Remove the "*." prefix
-      
-      // Check if domain ends with the pattern suffix and has at least one character before it
-      return domain.endsWith(patternSuffix) && domain.length > patternSuffix.length;
-    }
-    
-    // No match
-    return false;
-  }
-
-  public async stop() {
-    console.log('Stopping DcRouter services...');
-    
-    try {
-      // Stop all services in parallel for faster shutdown
-      await Promise.all([
-        // Stop HTTP SmartProxy if running
-        this.smartProxy ? this.smartProxy.stop().catch(err => console.error('Error stopping HTTP SmartProxy:', err)) : Promise.resolve(),
-        
-        // Stop SMTP SmartProxy if running
-        this.smtpProxy ? this.smtpProxy.stop().catch(err => console.error('Error stopping SMTP SmartProxy:', err)) : Promise.resolve(),
-        
-        // Stop MTA service if it's our own (not an external instance)
-        (this.mta && !this.options.mtaServiceInstance) ? 
-          this.mta.stop().catch(err => console.error('Error stopping MTA service:', err)) : 
-          Promise.resolve(),
-        
-        // Stop DNS server if running
-        this.dnsServer ? 
-          this.dnsServer.stop().catch(err => console.error('Error stopping DNS server:', err)) : 
-          Promise.resolve()
-      ]);
-      
-      console.log('All DcRouter services stopped');
-    } catch (error) {
-      console.error('Error during DcRouter shutdown:', error);
-      throw error;
-    }
-  }
-
-  /**
-   * Update HTTP domain routes
-   * @param routes New HTTP domain routes
-   */
-  public async updateHttpRoutes(routes: IDomainRoutingConfig[]): Promise<void> {
-    this.options.httpDomainRoutes = routes;
-    
-    // If SmartProxy is already running, we need to restart it with the new configuration
-    if (this.smartProxy) {
-      // Stop the existing SmartProxy
-      await this.smartProxy.stop();
-      this.smartProxy = undefined;
-      
-      // Start a new SmartProxy with the updated configuration
-      await this.setupHttpProxy();
-    }
-    
-    console.log(`Updated HTTP routes with ${routes.length} domains`);
-  }
-  
-  /**
-   * Update SMTP forwarding configuration
-   * @param config New SMTP forwarding configuration
-   */
-  public async updateSmtpForwarding(config: ISmtpForwardingConfig): Promise<void> {
-    // Stop existing SMTP proxy if running
-    if (this.smtpProxy) {
-      await this.smtpProxy.stop();
-      this.smtpProxy = undefined;
-    }
-    
-    // Update configuration
-    this.options.smtpForwarding = config;
-    
-    // Restart SMTP forwarding if enabled
-    if (config.enabled) {
-      await this.setupSmtpForwarding();
-    }
-    
-    console.log('SMTP forwarding configuration updated');
-  }
-}
-
-export default DcRouter;

ts/dcrouter/classes.email.domainrouter.ts

@@ -1,431 +0,0 @@
-import * as plugins from '../plugins.js';
-
-/**
- * Domain group configuration for applying consistent rules across related domains
- */
-export interface IDomainGroup {
-  /** Unique identifier for the domain group */
-  id: string;
-  /** Human-readable name for the domain group */
-  name: string;
-  /** List of domains in this group */
-  domains: string[];
-  /** Priority for this domain group (higher takes precedence) */
-  priority?: number;
-  /** Description of this domain group */
-  description?: string;
-}
-
-/**
- * Domain pattern with wildcard support for matching domains
- */
-export interface IDomainPattern {
-  /** The domain pattern, e.g. "example.com" or "*.example.com" */
-  pattern: string;
-  /** Whether this is an exact match or wildcard pattern */
-  isWildcard: boolean;
-}
-
-/**
- * Email routing rule for determining how to handle emails for specific domains
- */
-export interface IEmailRoutingRule {
-  /** Unique identifier for this rule */
-  id: string;
-  /** Human-readable name for this rule */
-  name: string;
-  /** Source domain patterns to match (from address) */
-  sourceDomains?: IDomainPattern[];
-  /** Destination domain patterns to match (to address) */
-  destinationDomains?: IDomainPattern[];
-  /** Domain groups this rule applies to */
-  domainGroups?: string[];
-  /** Priority of this rule (higher takes precedence) */
-  priority: number;
-  /** Action to take when rule matches */
-  action: 'route' | 'block' | 'tag' | 'filter';
-  /** Target server for routing */
-  targetServer?: string;
-  /** Target port for routing */
-  targetPort?: number;
-  /** Whether to use TLS when routing */
-  useTls?: boolean;
-  /** Authentication details for routing */
-  auth?: {
-    /** Username for authentication */
-    username?: string;
-    /** Password for authentication */
-    password?: string;
-    /** Authentication type */
-    type?: 'PLAIN' | 'LOGIN' | 'OAUTH2';
-  };
-  /** Headers to add or modify when rule matches */
-  headers?: {
-    /** Header name */
-    name: string;
-    /** Header value */
-    value: string;
-    /** Whether to append to existing header or replace */
-    append?: boolean;
-  }[];
-  /** Whether this rule is enabled */
-  enabled: boolean;
-}
-
-/**
- * Configuration for email domain-based routing
- */
-export interface IEmailDomainRoutingConfig {
-  /** Whether domain-based routing is enabled */
-  enabled: boolean;
-  /** Routing rules list */
-  rules: IEmailRoutingRule[];
-  /** Domain groups for organization */
-  domainGroups?: IDomainGroup[];
-  /** Default target server for unmatched domains */
-  defaultTargetServer?: string;
-  /** Default target port for unmatched domains */
-  defaultTargetPort?: number;
-  /** Whether to use TLS for the default route */
-  defaultUseTls?: boolean;
-}
-
-/**
- * Class for managing domain-based email routing
- */
-export class EmailDomainRouter {
-  /** Configuration for domain-based routing */
-  private config: IEmailDomainRoutingConfig;
-  /** Domain groups indexed by ID */
-  private domainGroups: Map<string, IDomainGroup> = new Map();
-  /** Sorted rules cache for faster processing */
-  private sortedRules: IEmailRoutingRule[] = [];
-  /** Whether the rules need to be re-sorted */
-  private rulesSortNeeded = true;
-
-  /**
-   * Create a new EmailDomainRouter
-   * @param config Configuration for domain-based routing
-   */
-  constructor(config: IEmailDomainRoutingConfig) {
-    this.config = config;
-    this.initialize();
-  }
-
-  /**
-   * Initialize the domain router
-   */
-  private initialize(): void {
-    // Return early if routing is not enabled
-    if (!this.config.enabled) {
-      return;
-    }
-
-    // Initialize domain groups
-    if (this.config.domainGroups) {
-      for (const group of this.config.domainGroups) {
-        this.domainGroups.set(group.id, group);
-      }
-    }
-
-    // Sort rules by priority
-    this.sortRules();
-  }
-
-  /**
-   * Sort rules by priority (higher first)
-   */
-  private sortRules(): void {
-    if (!this.config.rules || !this.config.enabled) {
-      this.sortedRules = [];
-      this.rulesSortNeeded = false;
-      return;
-    }
-
-    this.sortedRules = [...this.config.rules]
-      .filter(rule => rule.enabled)
-      .sort((a, b) => b.priority - a.priority);
-
-    this.rulesSortNeeded = false;
-  }
-
-  /**
-   * Add a new routing rule
-   * @param rule The routing rule to add
-   */
-  public addRule(rule: IEmailRoutingRule): void {
-    if (!this.config.rules) {
-      this.config.rules = [];
-    }
-
-    // Check if rule already exists
-    const existingIndex = this.config.rules.findIndex(r => r.id === rule.id);
-    if (existingIndex >= 0) {
-      // Update existing rule
-      this.config.rules[existingIndex] = rule;
-    } else {
-      // Add new rule
-      this.config.rules.push(rule);
-    }
-
-    this.rulesSortNeeded = true;
-  }
-
-  /**
-   * Remove a routing rule by ID
-   * @param ruleId ID of the rule to remove
-   * @returns Whether the rule was removed
-   */
-  public removeRule(ruleId: string): boolean {
-    if (!this.config.rules) {
-      return false;
-    }
-
-    const initialLength = this.config.rules.length;
-    this.config.rules = this.config.rules.filter(rule => rule.id !== ruleId);
-    
-    if (initialLength !== this.config.rules.length) {
-      this.rulesSortNeeded = true;
-      return true;
-    }
-    
-    return false;
-  }
-
-  /**
-   * Add a domain group
-   * @param group The domain group to add
-   */
-  public addDomainGroup(group: IDomainGroup): void {
-    if (!this.config.domainGroups) {
-      this.config.domainGroups = [];
-    }
-
-    // Check if group already exists
-    const existingIndex = this.config.domainGroups.findIndex(g => g.id === group.id);
-    if (existingIndex >= 0) {
-      // Update existing group
-      this.config.domainGroups[existingIndex] = group;
-    } else {
-      // Add new group
-      this.config.domainGroups.push(group);
-    }
-
-    // Update domain groups map
-    this.domainGroups.set(group.id, group);
-  }
-
-  /**
-   * Remove a domain group by ID
-   * @param groupId ID of the group to remove
-   * @returns Whether the group was removed
-   */
-  public removeDomainGroup(groupId: string): boolean {
-    if (!this.config.domainGroups) {
-      return false;
-    }
-
-    const initialLength = this.config.domainGroups.length;
-    this.config.domainGroups = this.config.domainGroups.filter(group => group.id !== groupId);
-    
-    if (initialLength !== this.config.domainGroups.length) {
-      this.domainGroups.delete(groupId);
-      return true;
-    }
-    
-    return false;
-  }
-
-  /**
-   * Determine routing for an email
-   * @param fromDomain The sender domain
-   * @param toDomain The recipient domain
-   * @returns Routing decision or null if no matching rule
-   */
-  public getRoutingForEmail(fromDomain: string, toDomain: string): {
-    targetServer: string;
-    targetPort: number;
-    useTls: boolean;
-    auth?: {
-      username?: string;
-      password?: string;
-      type?: 'PLAIN' | 'LOGIN' | 'OAUTH2';
-    };
-    headers?: {
-      name: string;
-      value: string;
-      append?: boolean;
-    }[];
-  } | null {
-    // Return default routing if routing is not enabled
-    if (!this.config.enabled) {
-      return this.getDefaultRouting();
-    }
-
-    // Sort rules if needed
-    if (this.rulesSortNeeded) {
-      this.sortRules();
-    }
-
-    // Normalize domains
-    fromDomain = fromDomain.toLowerCase();
-    toDomain = toDomain.toLowerCase();
-
-    // Check each rule in priority order
-    for (const rule of this.sortedRules) {
-      if (!rule.enabled) continue;
-
-      // Check if rule applies to this email
-      if (this.ruleMatchesEmail(rule, fromDomain, toDomain)) {
-        // Handle different actions
-        switch (rule.action) {
-          case 'route':
-            // Return routing information
-            return {
-              targetServer: rule.targetServer || this.config.defaultTargetServer || 'localhost',
-              targetPort: rule.targetPort || this.config.defaultTargetPort || 25,
-              useTls: rule.useTls ?? this.config.defaultUseTls ?? false,
-              auth: rule.auth,
-              headers: rule.headers
-            };
-          case 'block':
-            // Return null to indicate email should be blocked
-            return null;
-          case 'tag':
-          case 'filter':
-            // For tagging/filtering, we need to apply headers but continue checking rules
-            // This is simplified for now, in a real implementation we'd aggregate headers
-            continue;
-        }
-      }
-    }
-
-    // No rule matched, use default routing
-    return this.getDefaultRouting();
-  }
-
-  /**
-   * Check if a rule matches an email
-   * @param rule The routing rule to check
-   * @param fromDomain The sender domain
-   * @param toDomain The recipient domain
-   * @returns Whether the rule matches the email
-   */
-  private ruleMatchesEmail(rule: IEmailRoutingRule, fromDomain: string, toDomain: string): boolean {
-    // Check source domains
-    if (rule.sourceDomains && rule.sourceDomains.length > 0) {
-      const matchesSourceDomain = rule.sourceDomains.some(
-        pattern => this.domainMatchesPattern(fromDomain, pattern)
-      );
-      if (!matchesSourceDomain) {
-        return false;
-      }
-    }
-
-    // Check destination domains
-    if (rule.destinationDomains && rule.destinationDomains.length > 0) {
-      const matchesDestinationDomain = rule.destinationDomains.some(
-        pattern => this.domainMatchesPattern(toDomain, pattern)
-      );
-      if (!matchesDestinationDomain) {
-        return false;
-      }
-    }
-
-    // Check domain groups
-    if (rule.domainGroups && rule.domainGroups.length > 0) {
-      // Check if either domain is in any of the specified groups
-      const domainsInGroups = rule.domainGroups
-        .map(groupId => this.domainGroups.get(groupId))
-        .filter(Boolean)
-        .some(group => 
-          group.domains.includes(fromDomain) || 
-          group.domains.includes(toDomain)
-        );
-      
-      if (!domainsInGroups) {
-        return false;
-      }
-    }
-
-    // If we got here, all checks passed
-    return true;
-  }
-
-  /**
-   * Check if a domain matches a pattern
-   * @param domain The domain to check
-   * @param pattern The pattern to match against
-   * @returns Whether the domain matches the pattern
-   */
-  private domainMatchesPattern(domain: string, pattern: IDomainPattern): boolean {
-    domain = domain.toLowerCase();
-    const patternStr = pattern.pattern.toLowerCase();
-
-    // Exact match
-    if (!pattern.isWildcard) {
-      return domain === patternStr;
-    }
-
-    // Wildcard match (*.example.com)
-    if (patternStr.startsWith('*.')) {
-      const suffix = patternStr.substring(2);
-      return domain.endsWith(suffix) && domain.length > suffix.length;
-    }
-
-    // Invalid pattern
-    return false;
-  }
-
-  /**
-   * Get default routing information
-   * @returns Default routing or null if no default configured
-   */
-  private getDefaultRouting(): {
-    targetServer: string;
-    targetPort: number;
-    useTls: boolean;
-  } | null {
-    if (!this.config.defaultTargetServer) {
-      return null;
-    }
-
-    return {
-      targetServer: this.config.defaultTargetServer,
-      targetPort: this.config.defaultTargetPort || 25,
-      useTls: this.config.defaultUseTls || false
-    };
-  }
-
-  /**
-   * Get the current configuration
-   * @returns Current domain routing configuration
-   */
-  public getConfig(): IEmailDomainRoutingConfig {
-    return this.config;
-  }
-
-  /**
-   * Update the configuration
-   * @param config New domain routing configuration
-   */
-  public updateConfig(config: IEmailDomainRoutingConfig): void {
-    this.config = config;
-    this.rulesSortNeeded = true;
-    this.initialize();
-  }
-
-  /**
-   * Enable domain routing
-   */
-  public enable(): void {
-    this.config.enabled = true;
-  }
-
-  /**
-   * Disable domain routing
-   */
-  public disable(): void {
-    this.config.enabled = false;
-  }
-}

ts/dcrouter/classes.smtp.portconfig.ts

@@ -1,311 +0,0 @@
-import * as plugins from '../plugins.js';
-
-/**
- * Configuration options for TLS in SMTP connections
- */
-export interface ISmtpTlsOptions {
-  /** Enable TLS for this SMTP port */
-  enabled: boolean;
-  /** Whether to use STARTTLS (upgrade plain connection) or implicit TLS */
-  useStartTls?: boolean;
-  /** Required TLS protocol version (defaults to TLSv1.2) */
-  minTlsVersion?: 'TLSv1.0' | 'TLSv1.1' | 'TLSv1.2' | 'TLSv1.3';
-  /** TLS ciphers to allow (comma-separated list) */
-  allowedCiphers?: string;
-  /** Whether to require client certificate for authentication */
-  requireClientCert?: boolean;
-  /** Whether to verify client certificate if provided */
-  verifyClientCert?: boolean;
-}
-
-/**
- * Rate limiting options for SMTP connections
- */
-export interface ISmtpRateLimitOptions {
-  /** Maximum connections per minute from a single IP */
-  maxConnectionsPerMinute?: number;
-  /** Maximum concurrent connections from a single IP */
-  maxConcurrentConnections?: number;
-  /** Maximum emails per minute from a single IP */
-  maxEmailsPerMinute?: number;
-  /** Maximum recipients per email */
-  maxRecipientsPerEmail?: number;
-  /** Maximum email size in bytes */
-  maxEmailSize?: number;
-  /** Action to take when rate limit is exceeded (default: 'tempfail') */
-  rateLimitAction?: 'tempfail' | 'drop' | 'delay';
-}
-
-/**
- * Configuration for a specific SMTP port
- */
-export interface ISmtpPortSettings {
-  /** The port number to listen on */
-  port: number;
-  /** Whether this port is enabled */
-  enabled?: boolean;
-  /** Port description (e.g., "Submission Port") */
-  description?: string;
-  /** Whether to require authentication for this port */
-  requireAuth?: boolean;
-  /** TLS options for this port */
-  tls?: ISmtpTlsOptions;
-  /** Rate limiting settings for this port */
-  rateLimit?: ISmtpRateLimitOptions;
-  /** Maximum message size in bytes for this port */
-  maxMessageSize?: number;
-  /** Whether to enable SMTP extensions like PIPELINING, 8BITMIME, etc. */
-  smtpExtensions?: {
-    /** Enable PIPELINING extension */
-    pipelining?: boolean;
-    /** Enable 8BITMIME extension */
-    eightBitMime?: boolean;
-    /** Enable SIZE extension */
-    size?: boolean;
-    /** Enable ENHANCEDSTATUSCODES extension */
-    enhancedStatusCodes?: boolean;
-    /** Enable DSN extension */
-    dsn?: boolean;
-  };
-  /** Custom SMTP greeting banner */
-  banner?: string;
-}
-
-/**
- * Configuration manager for SMTP ports
- */
-export class SmtpPortConfig {
-  /** Port configurations */
-  private portConfigs: Map<number, ISmtpPortSettings> = new Map();
-
-  /** Default port configurations */
-  private static readonly DEFAULT_CONFIGS: Record<number, Partial<ISmtpPortSettings>> = {
-    // Port 25: Standard SMTP
-    25: {
-      description: 'Standard SMTP',
-      requireAuth: false,
-      tls: {
-        enabled: true,
-        useStartTls: true,
-        minTlsVersion: 'TLSv1.2'
-      },
-      rateLimit: {
-        maxConnectionsPerMinute: 60,
-        maxConcurrentConnections: 10,
-        maxEmailsPerMinute: 30
-      },
-      maxMessageSize: 20 * 1024 * 1024 // 20MB
-    },
-    // Port 587: Submission
-    587: {
-      description: 'Submission Port',
-      requireAuth: true,
-      tls: {
-        enabled: true,
-        useStartTls: true,
-        minTlsVersion: 'TLSv1.2'
-      },
-      rateLimit: {
-        maxConnectionsPerMinute: 100,
-        maxConcurrentConnections: 20,
-        maxEmailsPerMinute: 60
-      },
-      maxMessageSize: 50 * 1024 * 1024 // 50MB
-    },
-    // Port 465: SMTPS (Legacy Implicit TLS)
-    465: {
-      description: 'SMTPS (Implicit TLS)',
-      requireAuth: true,
-      tls: {
-        enabled: true,
-        useStartTls: false,
-        minTlsVersion: 'TLSv1.2'
-      },
-      rateLimit: {
-        maxConnectionsPerMinute: 100,
-        maxConcurrentConnections: 20,
-        maxEmailsPerMinute: 60
-      },
-      maxMessageSize: 50 * 1024 * 1024 // 50MB
-    }
-  };
-
-  /**
-   * Create a new SmtpPortConfig
-   * @param initialConfigs Optional initial port configurations
-   */
-  constructor(initialConfigs?: ISmtpPortSettings[]) {
-    // Initialize with default configurations for standard SMTP ports
-    this.initializeDefaults();
-
-    // Apply custom configurations if provided
-    if (initialConfigs) {
-      for (const config of initialConfigs) {
-        this.setPortConfig(config);
-      }
-    }
-  }
-
-  /**
-   * Initialize port configurations with defaults
-   */
-  private initializeDefaults(): void {
-    // Set up default configurations for standard SMTP ports: 25, 587, 465
-    Object.entries(SmtpPortConfig.DEFAULT_CONFIGS).forEach(([portStr, defaults]) => {
-      const port = parseInt(portStr, 10);
-      this.portConfigs.set(port, {
-        port,
-        enabled: true,
-        ...defaults
-      });
-    });
-  }
-
-  /**
-   * Get configuration for a specific port
-   * @param port Port number
-   * @returns Port configuration or null if not found
-   */
-  public getPortConfig(port: number): ISmtpPortSettings | null {
-    return this.portConfigs.get(port) || null;
-  }
-
-  /**
-   * Get all configured ports
-   * @returns Array of port configurations
-   */
-  public getAllPortConfigs(): ISmtpPortSettings[] {
-    return Array.from(this.portConfigs.values());
-  }
-
-  /**
-   * Get only enabled port configurations
-   * @returns Array of enabled port configurations
-   */
-  public getEnabledPortConfigs(): ISmtpPortSettings[] {
-    return this.getAllPortConfigs().filter(config => config.enabled !== false);
-  }
-
-  /**
-   * Set configuration for a specific port
-   * @param config Port configuration
-   */
-  public setPortConfig(config: ISmtpPortSettings): void {
-    // Get existing config if any
-    const existingConfig = this.portConfigs.get(config.port) || { port: config.port };
-
-    // Merge with new configuration
-    this.portConfigs.set(config.port, {
-      ...existingConfig,
-      ...config
-    });
-  }
-
-  /**
-   * Remove configuration for a specific port
-   * @param port Port number
-   * @returns Whether the configuration was removed
-   */
-  public removePortConfig(port: number): boolean {
-    return this.portConfigs.delete(port);
-  }
-
-  /**
-   * Disable a specific port
-   * @param port Port number
-   * @returns Whether the port was disabled
-   */
-  public disablePort(port: number): boolean {
-    const config = this.portConfigs.get(port);
-    if (config) {
-      config.enabled = false;
-      return true;
-    }
-    return false;
-  }
-
-  /**
-   * Enable a specific port
-   * @param port Port number
-   * @returns Whether the port was enabled
-   */
-  public enablePort(port: number): boolean {
-    const config = this.portConfigs.get(port);
-    if (config) {
-      config.enabled = true;
-      return true;
-    }
-    return false;
-  }
-
-  /**
-   * Apply port configurations to SmartProxy settings
-   * @param smartProxy SmartProxy instance
-   */
-  public applyToSmartProxy(smartProxy: plugins.smartproxy.SmartProxy): void {
-    if (!smartProxy) return;
-
-    const enabledPorts = this.getEnabledPortConfigs();
-    const settings = smartProxy.settings;
-
-    // Initialize globalPortRanges if needed
-    if (!settings.globalPortRanges) {
-      settings.globalPortRanges = [];
-    }
-
-    // Add configured ports to globalPortRanges
-    for (const portConfig of enabledPorts) {
-      // Add port to global port ranges if not already present
-      if (!settings.globalPortRanges.some((r) => r.from <= portConfig.port && portConfig.port <= r.to)) {
-        settings.globalPortRanges.push({ from: portConfig.port, to: portConfig.port });
-      }
-      
-      // Apply TLS settings at SmartProxy level
-      if (portConfig.port === 465 && portConfig.tls?.enabled) {
-        // For implicit TLS on port 465
-        settings.sniEnabled = true;
-      }
-    }
-
-    // Group ports by TLS configuration to log them
-    const starttlsPorts = enabledPorts
-      .filter(p => p.tls?.enabled && p.tls?.useStartTls)
-      .map(p => p.port);
-
-    const implicitTlsPorts = enabledPorts
-      .filter(p => p.tls?.enabled && !p.tls?.useStartTls)
-      .map(p => p.port);
-
-    const nonTlsPorts = enabledPorts
-      .filter(p => !p.tls?.enabled)
-      .map(p => p.port);
-
-    if (starttlsPorts.length > 0) {
-      console.log(`Configured STARTTLS SMTP ports: ${starttlsPorts.join(', ')}`);
-    }
-
-    if (implicitTlsPorts.length > 0) {
-      console.log(`Configured Implicit TLS SMTP ports: ${implicitTlsPorts.join(', ')}`);
-    }
-
-    if (nonTlsPorts.length > 0) {
-      console.log(`Configured Plain SMTP ports: ${nonTlsPorts.join(', ')}`);
-    }
-
-    // Setup connection listeners for different port types
-    smartProxy.on('connection', (connection) => {
-      const port = connection.localPort;
-      
-      // Check which type of port this is
-      if (implicitTlsPorts.includes(port)) {
-        console.log(`Implicit TLS SMTP connection on port ${port} from ${connection.remoteIP}`);
-      } else if (starttlsPorts.includes(port)) {
-        console.log(`STARTTLS SMTP connection on port ${port} from ${connection.remoteIP}`);
-      } else if (nonTlsPorts.includes(port)) {
-        console.log(`Plain SMTP connection on port ${port} from ${connection.remoteIP}`);
-      }
-    });
-
-    console.log(`Applied SMTP port configurations to SmartProxy: ${enabledPorts.map(p => p.port).join(', ')}`);
-  }
-}

ts/dcrouter/index.ts

@@ -1,3 +0,0 @@
-export * from './classes.dcrouter.js';
-export * from './classes.smtp.portconfig.js';
-export * from './classes.email.domainrouter.js';

ts/deliverability/classes.ipwarmupmanager.ts

@@ -1,896 +0,0 @@
-import * as plugins from '../plugins.js';
-import * as paths from '../paths.js';
-import { logger } from '../logger.js';
-import { LRUCache } from 'lru-cache';
-
-/**
- * Represents a single stage in the warmup process
- */
-export interface IWarmupStage {
-  /** Stage number (1-based) */
-  stage: number;
-  /** Maximum daily email volume for this stage */
-  maxDailyVolume: number;
-  /** Duration of this stage in days */
-  durationDays: number;
-  /** Target engagement metrics for this stage */
-  targetMetrics?: {
-    /** Minimum open rate (percentage) */
-    minOpenRate?: number;
-    /** Maximum bounce rate (percentage) */
-    maxBounceRate?: number;
-    /** Maximum spam complaint rate (percentage) */
-    maxComplaintRate?: number;
-  };
-}
-
-/**
- * Configuration for IP warmup process
- */
-export interface IIPWarmupConfig {
-  /** Whether the warmup is enabled */
-  enabled?: boolean;
-  /** List of IP addresses to warm up */
-  ipAddresses?: string[];
-  /** Target domains to warm up (e.g. your sending domains) */
-  targetDomains?: string[];
-  /** Warmup stages defining volume and duration */
-  stages?: IWarmupStage[];
-  /** Date when warmup process started */
-  startDate?: Date;
-  /** Default hourly distribution for sending (percentage of daily volume per hour) */
-  hourlyDistribution?: number[];
-  /** Whether to automatically advance stages based on metrics */
-  autoAdvanceStages?: boolean;
-  /** Whether to suspend warmup if metrics decline */
-  suspendOnMetricDecline?: boolean;
-  /** Percentage of traffic to send through fallback provider during warmup */
-  fallbackPercentage?: number;
-  /** Whether to prioritize engaged subscribers during warmup */
-  prioritizeEngagedSubscribers?: boolean;
-}
-
-/**
- * Status for a specific IP's warmup process
- */
-export interface IIPWarmupStatus {
-  /** IP address being warmed up */
-  ipAddress: string;
-  /** Current warmup stage */
-  currentStage: number;
-  /** Start date of the warmup process */
-  startDate: Date;
-  /** Start date of the current stage */
-  currentStageStartDate: Date;
-  /** Target completion date for entire warmup */
-  targetCompletionDate: Date;
-  /** Daily volume allocation for current stage */
-  currentDailyAllocation: number;
-  /** Emails sent in current stage */
-  sentInCurrentStage: number;
-  /** Total emails sent during warmup process */
-  totalSent: number;
-  /** Whether the warmup is currently active */
-  isActive: boolean;
-  /** Daily statistics for the past week */
-  dailyStats: Array<{
-    /** Date of the statistics */
-    date: string;
-    /** Number of emails sent */
-    sent: number;
-    /** Number of emails opened */
-    opened: number;
-    /** Number of bounces */
-    bounces: number;
-    /** Number of spam complaints */
-    complaints: number;
-  }>;
-  /** Current metrics */
-  metrics: {
-    /** Open rate percentage */
-    openRate: number;
-    /** Bounce rate percentage */
-    bounceRate: number;
-    /** Complaint rate percentage */
-    complaintRate: number;
-  };
-}
-
-/**
- * Defines methods for a policy used to allocate emails to different IPs
- */
-export interface IIPAllocationPolicy {
-  /** Name of the policy */
-  name: string;
-  
-  /**
-   * Allocate an IP address for sending an email
-   * @param availableIPs List of available IP addresses
-   * @param emailInfo Information about the email being sent
-   * @returns The IP to use, or null if no IP is available
-   */
-  allocateIP(
-    availableIPs: Array<{ ip: string; priority: number; capacity: number }>,
-    emailInfo: {
-      from: string;
-      to: string[];
-      domain: string;
-      isTransactional: boolean;
-      isWarmup: boolean;
-    }
-  ): string | null;
-}
-
-/**
- * Default IP warmup configuration with industry standard stages
- */
-const DEFAULT_WARMUP_CONFIG: Required<IIPWarmupConfig> = {
-  enabled: true,
-  ipAddresses: [],
-  targetDomains: [],
-  stages: [
-    { stage: 1, maxDailyVolume: 50, durationDays: 2, targetMetrics: { maxBounceRate: 8, minOpenRate: 15 } },
-    { stage: 2, maxDailyVolume: 100, durationDays: 2, targetMetrics: { maxBounceRate: 7, minOpenRate: 18 } },
-    { stage: 3, maxDailyVolume: 500, durationDays: 3, targetMetrics: { maxBounceRate: 6, minOpenRate: 20 } },
-    { stage: 4, maxDailyVolume: 1000, durationDays: 3, targetMetrics: { maxBounceRate: 5, minOpenRate: 20 } },
-    { stage: 5, maxDailyVolume: 5000, durationDays: 5, targetMetrics: { maxBounceRate: 3, minOpenRate: 22 } },
-    { stage: 6, maxDailyVolume: 10000, durationDays: 5, targetMetrics: { maxBounceRate: 2, minOpenRate: 25 } },
-    { stage: 7, maxDailyVolume: 20000, durationDays: 5, targetMetrics: { maxBounceRate: 1, minOpenRate: 25 } },
-    { stage: 8, maxDailyVolume: 50000, durationDays: 5, targetMetrics: { maxBounceRate: 1, minOpenRate: 25 } },
-  ],
-  startDate: new Date(),
-  // Default hourly distribution (percentage per hour, sums to 100%)
-  hourlyDistribution: [
-    1, 1, 1, 1, 1, 2, 3, 5, 7, 8, 10, 11, 
-    10, 9, 8, 6, 5, 4, 3, 2, 1, 1, 1, 0
-  ],
-  autoAdvanceStages: true,
-  suspendOnMetricDecline: true,
-  fallbackPercentage: 50,
-  prioritizeEngagedSubscribers: true
-};
-
-/**
- * Manages the IP warming process for new sending IPs
- */
-export class IPWarmupManager {
-  private static instance: IPWarmupManager;
-  private config: Required<IIPWarmupConfig>;
-  private warmupStatuses: Map<string, IIPWarmupStatus> = new Map();
-  private dailySendCounts: Map<string, number> = new Map();
-  private hourlySendCounts: Map<string, number[]> = new Map();
-  private isInitialized: boolean = false;
-  private allocationPolicies: Map<string, IIPAllocationPolicy> = new Map();
-  private activePolicy: string = 'balanced';
-  
-  /**
-   * Constructor for IPWarmupManager
-   * @param config Warmup configuration
-   */
-  constructor(config: IIPWarmupConfig = {}) {
-    this.config = {
-      ...DEFAULT_WARMUP_CONFIG,
-      ...config,
-      stages: config.stages || [...DEFAULT_WARMUP_CONFIG.stages]
-    };
-    
-    // Register default allocation policies
-    this.registerAllocationPolicy('balanced', new BalancedAllocationPolicy());
-    this.registerAllocationPolicy('roundRobin', new RoundRobinAllocationPolicy());
-    this.registerAllocationPolicy('dedicated', new DedicatedDomainPolicy());
-    
-    this.initialize();
-  }
-  
-  /**
-   * Get the singleton instance of IPWarmupManager
-   * @param config Warmup configuration
-   * @returns Singleton instance
-   */
-  public static getInstance(config: IIPWarmupConfig = {}): IPWarmupManager {
-    if (!IPWarmupManager.instance) {
-      IPWarmupManager.instance = new IPWarmupManager(config);
-    }
-    return IPWarmupManager.instance;
-  }
-  
-  /**
-   * Initialize the warmup manager
-   */
-  private initialize(): void {
-    if (this.isInitialized) return;
-    
-    try {
-      // Load warmup statuses from storage
-      this.loadWarmupStatuses();
-      
-      // Initialize any new IPs that might have been added to config
-      for (const ip of this.config.ipAddresses) {
-        if (!this.warmupStatuses.has(ip)) {
-          this.initializeIPWarmup(ip);
-        }
-      }
-      
-      // Initialize daily and hourly counters
-      const today = new Date().toISOString().split('T')[0];
-      for (const ip of this.config.ipAddresses) {
-        this.dailySendCounts.set(ip, 0);
-        this.hourlySendCounts.set(ip, Array(24).fill(0));
-      }
-      
-      // Schedule daily reset of counters
-      this.scheduleDailyReset();
-      
-      // Schedule daily evaluation of warmup progress
-      this.scheduleDailyEvaluation();
-      
-      this.isInitialized = true;
-      logger.log('info', `IP Warmup Manager initialized with ${this.config.ipAddresses.length} IPs`);
-    } catch (error) {
-      logger.log('error', `Failed to initialize IP Warmup Manager: ${error.message}`, {
-        stack: error.stack
-      });
-    }
-  }
-  
-  /**
-   * Initialize warmup status for a new IP address
-   * @param ipAddress IP address to initialize
-   */
-  private initializeIPWarmup(ipAddress: string): void {
-    const startDate = new Date();
-    let targetCompletionDate = new Date(startDate);
-    
-    // Calculate target completion date based on stages
-    let totalDays = 0;
-    for (const stage of this.config.stages) {
-      totalDays += stage.durationDays;
-    }
-    
-    targetCompletionDate.setDate(targetCompletionDate.getDate() + totalDays);
-    
-    const warmupStatus: IIPWarmupStatus = {
-      ipAddress,
-      currentStage: 1,
-      startDate,
-      currentStageStartDate: new Date(),
-      targetCompletionDate,
-      currentDailyAllocation: this.config.stages[0].maxDailyVolume,
-      sentInCurrentStage: 0,
-      totalSent: 0,
-      isActive: true,
-      dailyStats: [],
-      metrics: {
-        openRate: 0,
-        bounceRate: 0,
-        complaintRate: 0
-      }
-    };
-    
-    this.warmupStatuses.set(ipAddress, warmupStatus);
-    this.saveWarmupStatuses();
-    
-    logger.log('info', `Initialized warmup for IP ${ipAddress}`, {
-      currentStage: 1,
-      targetCompletion: targetCompletionDate.toISOString().split('T')[0]
-    });
-  }
-  
-  /**
-   * Schedule daily reset of send counters
-   */
-  private scheduleDailyReset(): void {
-    // Calculate time until midnight
-    const now = new Date();
-    const tomorrow = new Date(now);
-    tomorrow.setDate(tomorrow.getDate() + 1);
-    tomorrow.setHours(0, 0, 0, 0);
-    
-    const timeUntilMidnight = tomorrow.getTime() - now.getTime();
-    
-    // Schedule reset
-    setTimeout(() => {
-      this.resetDailyCounts();
-      // Reschedule for next day
-      this.scheduleDailyReset();
-    }, timeUntilMidnight);
-    
-    logger.log('info', `Scheduled daily counter reset in ${Math.floor(timeUntilMidnight / 60000)} minutes`);
-  }
-  
-  /**
-   * Reset daily send counters
-   */
-  private resetDailyCounts(): void {
-    for (const ip of this.config.ipAddresses) {
-      // Save yesterday's count to history before resetting
-      const status = this.warmupStatuses.get(ip);
-      if (status) {
-        const yesterday = new Date();
-        yesterday.setDate(yesterday.getDate() - 1);
-        
-        // Update daily stats with yesterday's data
-        const sentCount = this.dailySendCounts.get(ip) || 0;
-        status.dailyStats.push({
-          date: yesterday.toISOString().split('T')[0],
-          sent: sentCount,
-          opened: Math.floor(sentCount * status.metrics.openRate / 100),
-          bounces: Math.floor(sentCount * status.metrics.bounceRate / 100),
-          complaints: Math.floor(sentCount * status.metrics.complaintRate / 100)
-        });
-        
-        // Keep only the last 7 days of stats
-        if (status.dailyStats.length > 7) {
-          status.dailyStats.shift();
-        }
-      }
-      
-      // Reset counters for today
-      this.dailySendCounts.set(ip, 0);
-      this.hourlySendCounts.set(ip, Array(24).fill(0));
-    }
-    
-    // Save updated statuses
-    this.saveWarmupStatuses();
-    
-    logger.log('info', 'Daily send counters reset');
-  }
-  
-  /**
-   * Schedule daily evaluation of warmup progress
-   */
-  private scheduleDailyEvaluation(): void {
-    // Calculate time until 1 AM (do evaluation after midnight)
-    const now = new Date();
-    const evaluationTime = new Date(now);
-    evaluationTime.setDate(evaluationTime.getDate() + 1);
-    evaluationTime.setHours(1, 0, 0, 0);
-    
-    const timeUntilEvaluation = evaluationTime.getTime() - now.getTime();
-    
-    // Schedule evaluation
-    setTimeout(() => {
-      this.evaluateWarmupProgress();
-      // Reschedule for next day
-      this.scheduleDailyEvaluation();
-    }, timeUntilEvaluation);
-    
-    logger.log('info', `Scheduled daily warmup evaluation in ${Math.floor(timeUntilEvaluation / 60000)} minutes`);
-  }
-  
-  /**
-   * Evaluate warmup progress and possibly advance stages
-   */
-  private evaluateWarmupProgress(): void {
-    if (!this.config.autoAdvanceStages) {
-      logger.log('info', 'Auto-advance stages is disabled, skipping evaluation');
-      return;
-    }
-    
-    // Convert entries to array for compatibility with older JS versions
-    Array.from(this.warmupStatuses.entries()).forEach(([ip, status]) => {
-      if (!status.isActive) return;
-      
-      // Check if current stage duration has elapsed
-      const currentStage = this.config.stages[status.currentStage - 1];
-      const now = new Date();
-      const daysSinceStageStart = Math.floor(
-        (now.getTime() - status.currentStageStartDate.getTime()) / (24 * 60 * 60 * 1000)
-      );
-      
-      if (daysSinceStageStart >= currentStage.durationDays) {
-        // Check if metrics meet requirements for advancing
-        const metricsOK = this.checkStageMetrics(status, currentStage);
-        
-        if (metricsOK) {
-          // Advance to next stage if not at the final stage
-          if (status.currentStage < this.config.stages.length) {
-            this.advanceToNextStage(ip);
-          } else {
-            logger.log('info', `IP ${ip} has completed the warmup process`);
-          }
-        } else if (this.config.suspendOnMetricDecline) {
-          // Suspend warmup if metrics don't meet requirements
-          status.isActive = false;
-          logger.log('warn', `Suspended warmup for IP ${ip} due to poor metrics`, {
-            openRate: status.metrics.openRate,
-            bounceRate: status.metrics.bounceRate,
-            complaintRate: status.metrics.complaintRate
-          });
-        } else {
-          // Extend current stage if metrics don't meet requirements
-          logger.log('info', `Extending stage ${status.currentStage} for IP ${ip} due to metrics not meeting requirements`);
-        }
-      }
-    });
-    
-    // Save updated statuses
-    this.saveWarmupStatuses();
-  }
-  
-  /**
-   * Check if the current metrics meet the requirements for the stage
-   * @param status Warmup status to check
-   * @param stage Stage to check against
-   * @returns Whether metrics meet requirements
-   */
-  private checkStageMetrics(status: IIPWarmupStatus, stage: IWarmupStage): boolean {
-    // If no target metrics specified, assume met
-    if (!stage.targetMetrics) return true;
-    
-    const metrics = status.metrics;
-    let meetsRequirements = true;
-    
-    // Check each metric against requirements
-    if (stage.targetMetrics.minOpenRate !== undefined && 
-        metrics.openRate < stage.targetMetrics.minOpenRate) {
-      meetsRequirements = false;
-      logger.log('info', `Open rate ${metrics.openRate}% below target ${stage.targetMetrics.minOpenRate}% for IP ${status.ipAddress}`);
-    }
-    
-    if (stage.targetMetrics.maxBounceRate !== undefined && 
-        metrics.bounceRate > stage.targetMetrics.maxBounceRate) {
-      meetsRequirements = false;
-      logger.log('info', `Bounce rate ${metrics.bounceRate}% above target ${stage.targetMetrics.maxBounceRate}% for IP ${status.ipAddress}`);
-    }
-    
-    if (stage.targetMetrics.maxComplaintRate !== undefined && 
-        metrics.complaintRate > stage.targetMetrics.maxComplaintRate) {
-      meetsRequirements = false;
-      logger.log('info', `Complaint rate ${metrics.complaintRate}% above target ${stage.targetMetrics.maxComplaintRate}% for IP ${status.ipAddress}`);
-    }
-    
-    return meetsRequirements;
-  }
-  
-  /**
-   * Advance IP to the next warmup stage
-   * @param ipAddress IP address to advance
-   */
-  private advanceToNextStage(ipAddress: string): void {
-    const status = this.warmupStatuses.get(ipAddress);
-    if (!status) return;
-    
-    // Store metrics for the completed stage
-    const completedStage = status.currentStage;
-    
-    // Advance to next stage
-    status.currentStage++;
-    status.currentStageStartDate = new Date();
-    status.sentInCurrentStage = 0;
-    
-    // Update allocation
-    const newStage = this.config.stages[status.currentStage - 1];
-    status.currentDailyAllocation = newStage.maxDailyVolume;
-    
-    logger.log('info', `Advanced IP ${ipAddress} to warmup stage ${status.currentStage}`, {
-      previousStage: completedStage,
-      newDailyLimit: status.currentDailyAllocation,
-      durationDays: newStage.durationDays
-    });
-  }
-  
-  /**
-   * Get warmup status for all IPs or a specific IP
-   * @param ipAddress Optional specific IP to get status for
-   * @returns Warmup status information
-   */
-  public getWarmupStatus(ipAddress?: string): IIPWarmupStatus | Map<string, IIPWarmupStatus> {
-    if (ipAddress) {
-      return this.warmupStatuses.get(ipAddress);
-    }
-    return this.warmupStatuses;
-  }
-  
-  /**
-   * Add a new IP address to the warmup process
-   * @param ipAddress IP address to add
-   */
-  public addIPToWarmup(ipAddress: string): void {
-    if (this.config.ipAddresses.includes(ipAddress)) {
-      logger.log('info', `IP ${ipAddress} is already in warmup`);
-      return;
-    }
-    
-    // Add to configuration
-    this.config.ipAddresses.push(ipAddress);
-    
-    // Initialize warmup
-    this.initializeIPWarmup(ipAddress);
-    
-    // Initialize counters
-    this.dailySendCounts.set(ipAddress, 0);
-    this.hourlySendCounts.set(ipAddress, Array(24).fill(0));
-    
-    logger.log('info', `Added IP ${ipAddress} to warmup process`);
-  }
-  
-  /**
-   * Remove an IP address from the warmup process
-   * @param ipAddress IP address to remove
-   */
-  public removeIPFromWarmup(ipAddress: string): void {
-    const index = this.config.ipAddresses.indexOf(ipAddress);
-    if (index === -1) {
-      logger.log('info', `IP ${ipAddress} is not in warmup`);
-      return;
-    }
-    
-    // Remove from configuration
-    this.config.ipAddresses.splice(index, 1);
-    
-    // Remove from statuses and counters
-    this.warmupStatuses.delete(ipAddress);
-    this.dailySendCounts.delete(ipAddress);
-    this.hourlySendCounts.delete(ipAddress);
-    
-    this.saveWarmupStatuses();
-    
-    logger.log('info', `Removed IP ${ipAddress} from warmup process`);
-  }
-  
-  /**
-   * Update metrics for an IP address
-   * @param ipAddress IP address to update
-   * @param metrics New metrics
-   */
-  public updateMetrics(
-    ipAddress: string, 
-    metrics: { openRate?: number; bounceRate?: number; complaintRate?: number }
-  ): void {
-    const status = this.warmupStatuses.get(ipAddress);
-    if (!status) {
-      logger.log('warn', `Cannot update metrics for IP ${ipAddress} - not in warmup`);
-      return;
-    }
-    
-    // Update metrics
-    if (metrics.openRate !== undefined) {
-      status.metrics.openRate = metrics.openRate;
-    }
-    
-    if (metrics.bounceRate !== undefined) {
-      status.metrics.bounceRate = metrics.bounceRate;
-    }
-    
-    if (metrics.complaintRate !== undefined) {
-      status.metrics.complaintRate = metrics.complaintRate;
-    }
-    
-    this.saveWarmupStatuses();
-    
-    logger.log('info', `Updated metrics for IP ${ipAddress}`, {
-      openRate: status.metrics.openRate,
-      bounceRate: status.metrics.bounceRate,
-      complaintRate: status.metrics.complaintRate
-    });
-  }
-  
-  /**
-   * Record a send event for an IP address
-   * @param ipAddress IP address used for sending
-   */
-  public recordSend(ipAddress: string): void {
-    if (!this.config.ipAddresses.includes(ipAddress)) {
-      logger.log('warn', `Cannot record send for IP ${ipAddress} - not in warmup`);
-      return;
-    }
-    
-    // Increment daily counter
-    const currentCount = this.dailySendCounts.get(ipAddress) || 0;
-    this.dailySendCounts.set(ipAddress, currentCount + 1);
-    
-    // Increment hourly counter
-    const hourlyCount = this.hourlySendCounts.get(ipAddress) || Array(24).fill(0);
-    const currentHour = new Date().getHours();
-    hourlyCount[currentHour]++;
-    this.hourlySendCounts.set(ipAddress, hourlyCount);
-    
-    // Update warmup status
-    const status = this.warmupStatuses.get(ipAddress);
-    if (status) {
-      status.sentInCurrentStage++;
-      status.totalSent++;
-    }
-  }
-  
-  /**
-   * Check if an IP can send more emails today
-   * @param ipAddress IP address to check
-   * @returns Whether the IP can send more emails
-   */
-  public canSendMoreToday(ipAddress: string): boolean {
-    if (!this.config.enabled) return true;
-    
-    if (!this.config.ipAddresses.includes(ipAddress)) {
-      // If not in warmup, assume it can send
-      return true;
-    }
-    
-    const status = this.warmupStatuses.get(ipAddress);
-    if (!status || !status.isActive) {
-      return false;
-    }
-    
-    const currentCount = this.dailySendCounts.get(ipAddress) || 0;
-    return currentCount < status.currentDailyAllocation;
-  }
-  
-  /**
-   * Check if an IP can send more emails in the current hour
-   * @param ipAddress IP address to check
-   * @returns Whether the IP can send more emails this hour
-   */
-  public canSendMoreThisHour(ipAddress: string): boolean {
-    if (!this.config.enabled) return true;
-    
-    if (!this.config.ipAddresses.includes(ipAddress)) {
-      // If not in warmup, assume it can send
-      return true;
-    }
-    
-    const status = this.warmupStatuses.get(ipAddress);
-    if (!status || !status.isActive) {
-      return false;
-    }
-    
-    const currentDailyLimit = status.currentDailyAllocation;
-    const currentHour = new Date().getHours();
-    const hourlyAllocation = Math.ceil((currentDailyLimit * this.config.hourlyDistribution[currentHour]) / 100);
-    
-    const hourlyCount = this.hourlySendCounts.get(ipAddress) || Array(24).fill(0);
-    const currentHourCount = hourlyCount[currentHour];
-    
-    return currentHourCount < hourlyAllocation;
-  }
-  
-  /**
-   * Get the best IP to use for sending an email
-   * @param emailInfo Information about the email being sent
-   * @returns The best IP to use, or null if no suitable IP is available
-   */
-  public getBestIPForSending(emailInfo: {
-    from: string;
-    to: string[];
-    domain: string;
-    isTransactional?: boolean;
-  }): string | null {
-    // If warmup is disabled, return null (caller will use default IP)
-    if (!this.config.enabled || this.config.ipAddresses.length === 0) {
-      return null;
-    }
-    
-    // Prepare information for allocation policy
-    const availableIPs = this.config.ipAddresses
-      .filter(ip => this.canSendMoreToday(ip) && this.canSendMoreThisHour(ip))
-      .map(ip => {
-        const status = this.warmupStatuses.get(ip);
-        return {
-          ip,
-          priority: status ? status.currentStage : 1,
-          capacity: status ? (status.currentDailyAllocation - (this.dailySendCounts.get(ip) || 0)) : 0
-        };
-      });
-    
-    // Use the active allocation policy to determine the best IP
-    const policy = this.allocationPolicies.get(this.activePolicy);
-    if (!policy) {
-      logger.log('warn', `No allocation policy named ${this.activePolicy} found`);
-      return null;
-    }
-    
-    return policy.allocateIP(availableIPs, {
-      ...emailInfo,
-      isTransactional: emailInfo.isTransactional || false,
-      isWarmup: true
-    });
-  }
-  
-  /**
-   * Register a new IP allocation policy
-   * @param name Policy name
-   * @param policy Policy implementation
-   */
-  public registerAllocationPolicy(name: string, policy: IIPAllocationPolicy): void {
-    this.allocationPolicies.set(name, policy);
-    logger.log('info', `Registered IP allocation policy: ${name}`);
-  }
-  
-  /**
-   * Set the active IP allocation policy
-   * @param name Policy name
-   */
-  public setActiveAllocationPolicy(name: string): void {
-    if (!this.allocationPolicies.has(name)) {
-      logger.log('warn', `No allocation policy named ${name} found`);
-      return;
-    }
-    
-    this.activePolicy = name;
-    logger.log('info', `Set active IP allocation policy to ${name}`);
-  }
-  
-  /**
-   * Get the total number of stages in the warmup process
-   * @returns Number of stages
-   */
-  public getStageCount(): number {
-    return this.config.stages.length;
-  }
-  
-  /**
-   * Load warmup statuses from storage
-   */
-  private loadWarmupStatuses(): void {
-    try {
-      const warmupDir = plugins.path.join(paths.dataDir, 'warmup');
-      plugins.smartfile.fs.ensureDirSync(warmupDir);
-      
-      const statusFile = plugins.path.join(warmupDir, 'ip_warmup_status.json');
-      
-      if (plugins.fs.existsSync(statusFile)) {
-        const data = plugins.fs.readFileSync(statusFile, 'utf8');
-        const statuses = JSON.parse(data);
-        
-        for (const status of statuses) {
-          // Restore date objects
-          status.startDate = new Date(status.startDate);
-          status.currentStageStartDate = new Date(status.currentStageStartDate);
-          status.targetCompletionDate = new Date(status.targetCompletionDate);
-          
-          this.warmupStatuses.set(status.ipAddress, status);
-        }
-        
-        logger.log('info', `Loaded ${this.warmupStatuses.size} IP warmup statuses from storage`);
-      }
-    } catch (error) {
-      logger.log('error', `Failed to load warmup statuses: ${error.message}`, {
-        stack: error.stack
-      });
-    }
-  }
-  
-  /**
-   * Save warmup statuses to storage
-   */
-  private saveWarmupStatuses(): void {
-    try {
-      const warmupDir = plugins.path.join(paths.dataDir, 'warmup');
-      plugins.smartfile.fs.ensureDirSync(warmupDir);
-      
-      const statusFile = plugins.path.join(warmupDir, 'ip_warmup_status.json');
-      const statuses = Array.from(this.warmupStatuses.values());
-      
-      plugins.smartfile.memory.toFsSync(
-        JSON.stringify(statuses, null, 2),
-        statusFile
-      );
-      
-      logger.log('debug', `Saved ${statuses.length} IP warmup statuses to storage`);
-    } catch (error) {
-      logger.log('error', `Failed to save warmup statuses: ${error.message}`, {
-        stack: error.stack
-      });
-    }
-  }
-}
-
-/**
- * Policy that balances traffic across IPs based on stage and capacity
- */
-class BalancedAllocationPolicy implements IIPAllocationPolicy {
-  name = 'balanced';
-  
-  allocateIP(
-    availableIPs: Array<{ ip: string; priority: number; capacity: number }>,
-    emailInfo: {
-      from: string;
-      to: string[];
-      domain: string;
-      isTransactional: boolean;
-      isWarmup: boolean;
-    }
-  ): string | null {
-    if (availableIPs.length === 0) return null;
-    
-    // Sort IPs by priority (prefer higher stage IPs) and capacity
-    const sortedIPs = [...availableIPs].sort((a, b) => {
-      // First by priority (descending)
-      if (b.priority !== a.priority) {
-        return b.priority - a.priority;
-      }
-      // Then by remaining capacity (descending)
-      return b.capacity - a.capacity;
-    });
-    
-    // Prioritize higher-stage IPs for transactional emails
-    if (emailInfo.isTransactional) {
-      return sortedIPs[0].ip;
-    }
-    
-    // For marketing emails, spread across IPs with preference for higher stages
-    // Use weighted random selection based on stage
-    const totalWeight = sortedIPs.reduce((sum, ip) => sum + ip.priority, 0);
-    let randomPoint = Math.random() * totalWeight;
-    
-    for (const ip of sortedIPs) {
-      randomPoint -= ip.priority;
-      if (randomPoint <= 0) {
-        return ip.ip;
-      }
-    }
-    
-    // Fallback to the highest priority IP
-    return sortedIPs[0].ip;
-  }
-}
-
-/**
- * Policy that rotates through IPs in a round-robin fashion
- */
-class RoundRobinAllocationPolicy implements IIPAllocationPolicy {
-  name = 'roundRobin';
-  private lastIndex = -1;
-  
-  allocateIP(
-    availableIPs: Array<{ ip: string; priority: number; capacity: number }>,
-    emailInfo: {
-      from: string;
-      to: string[];
-      domain: string;
-      isTransactional: boolean;
-      isWarmup: boolean;
-    }
-  ): string | null {
-    if (availableIPs.length === 0) return null;
-    
-    // Sort by capacity to ensure even distribution
-    const sortedIPs = [...availableIPs].sort((a, b) => b.capacity - a.capacity);
-    
-    // Move to next IP
-    this.lastIndex = (this.lastIndex + 1) % sortedIPs.length;
-    
-    return sortedIPs[this.lastIndex].ip;
-  }
-}
-
-/**
- * Policy that dedicates specific IPs to specific domains
- */
-class DedicatedDomainPolicy implements IIPAllocationPolicy {
-  name = 'dedicated';
-  private domainAssignments: Map<string, string> = new Map();
-  
-  allocateIP(
-    availableIPs: Array<{ ip: string; priority: number; capacity: number }>,
-    emailInfo: {
-      from: string;
-      to: string[];
-      domain: string;
-      isTransactional: boolean;
-      isWarmup: boolean;
-    }
-  ): string | null {
-    if (availableIPs.length === 0) return null;
-    
-    // Check if we have a dedicated IP for this domain
-    if (this.domainAssignments.has(emailInfo.domain)) {
-      const dedicatedIP = this.domainAssignments.get(emailInfo.domain);
-      
-      // Check if the dedicated IP is in the available list
-      const isAvailable = availableIPs.some(ip => ip.ip === dedicatedIP);
-      
-      if (isAvailable) {
-        return dedicatedIP;
-      }
-    }
-    
-    // If not, assign one and save the assignment
-    const sortedIPs = [...availableIPs].sort((a, b) => b.capacity - a.capacity);
-    const assignedIP = sortedIPs[0].ip;
-    
-    this.domainAssignments.set(emailInfo.domain, assignedIP);
-    
-    return assignedIP;
-  }
-}

ts/deliverability/index.ts

@@ -1,13 +0,0 @@
-export {
-  IPWarmupManager,
-  type IIPWarmupConfig,
-  type IWarmupStage,
-  type IIPWarmupStatus,
-  type IIPAllocationPolicy
-} from './classes.ipwarmupmanager.js';
-
-export {
-  SenderReputationMonitor,
-  type IDomainReputationMetrics,
-  type IReputationMonitorConfig
-} from './classes.senderreputationmonitor.js';

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,869 @@
+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 manual-domain records with smartdns.DnsServer at startup
+ *  - Provide CRUD methods used by OpsServer handlers (manual 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, manual records loaded
+   * from the DB are registered with the server.
+   */
+  public async attachDnsServer(dnsServer: plugins.smartdns.dnsServerMod.DnsServer): Promise<void> {
+    this.dnsServer = dnsServer;
+    await this.applyManualDomainsToDnsServer();
+  }
+
+  // ==========================================================================
+  // First-boot seeding
+  // ==========================================================================
+
+  /**
+   * If no DomainDocs exist yet but the constructor has legacy DNS fields,
+   * seed them as `source: 'manual'` 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 = 'manual';
+      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 = 'manual';
+      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;
+  }
+
+  // ==========================================================================
+  // Manual-domain DnsServer wiring
+  // ==========================================================================
+
+  /**
+   * Register all manual-domain records from the DB with the embedded DnsServer.
+   * Called once after attachDnsServer().
+   */
+  private async applyManualDomainsToDnsServer(): Promise<void> {
+    if (!this.dnsServer) {
+      return;
+    }
+    const allDomains = await DomainDoc.findAll();
+    const manualDomains = allDomains.filter((d) => d.source === 'manual');
+    let registered = 0;
+    for (const domain of manualDomains) {
+      const records = await DnsRecordDoc.findByDomainId(domain.id);
+      for (const rec of records) {
+        this.registerRecordWithDnsServer(rec);
+        registered++;
+      }
+    }
+    logger.log('info', `DnsManager: registered ${registered} manual 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> {
+    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 manual (authoritative) domain. dcrouter will serve DNS records
+   * for this domain via the embedded smartdns.DnsServer.
+   */
+  public async createManualDomain(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 = 'manual';
+    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 manual domains, also unregisters records from the embedded DnsServer.
+   *
+   * Note: smartdns has no public unregister-by-name API in the version pinned
+   * here, so manual 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 = 'manual';
+    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 {
+      // Manual / 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 manual 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 manual 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: 'manual' | '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,48 @@
+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);
+    }
+    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/email/classes.apimanager.ts

@@ -1,87 +0,0 @@
-import * as plugins from '../plugins.js';
-import { EmailService } from './classes.emailservice.js';
-import { logger } from '../logger.js';
-
-export class ApiManager {
-  public emailRef: EmailService;
-  public typedRouter = new plugins.typedrequest.TypedRouter();
-
-  constructor(emailRefArg: EmailService) {
-    this.emailRef = emailRefArg;
-    this.emailRef.typedrouter.addTypedRouter(this.typedRouter);
-
-    // Register API endpoints
-    this.registerApiEndpoints();
-  }
-
-  /**
-   * Register API endpoints for email functionality
-   */
-  private registerApiEndpoints() {
-    // Register the SendEmail endpoint
-    this.typedRouter.addTypedHandler<plugins.servezoneInterfaces.platformservice.mta.IReq_SendEmail>(
-      new plugins.typedrequest.TypedHandler('sendEmail', async (requestData) => {
-        const mailToSend = new plugins.smartmail.Smartmail({
-          body: requestData.body,
-          from: requestData.from,
-          subject: requestData.title,
-        });
-
-        if (requestData.attachments) {
-          for (const attachment of requestData.attachments) {
-            mailToSend.addAttachment(
-              await plugins.smartfile.SmartFile.fromString(
-                attachment.name,
-                attachment.binaryAttachmentString,
-                'binary'
-              )
-            );
-          }
-        }
-
-        // Send email through the service which will route to the appropriate connector
-        const emailId = await this.emailRef.sendEmail(mailToSend, requestData.to, {});
-        
-        logger.log(
-          'info',
-          `sent an email to ${requestData.to} with subject '${mailToSend.getSubject()}'`,
-          {
-            eventType: 'sentEmail',
-            email: {
-              to: requestData.to,
-              subject: mailToSend.getSubject(),
-            },
-          }
-        );
-        
-        return {
-          responseId: emailId,
-        };
-      })
-    );
-
-    // Add endpoint to check email status
-    this.typedRouter.addTypedHandler<plugins.servezoneInterfaces.platformservice.mta.IReq_CheckEmailStatus>(
-      new plugins.typedrequest.TypedHandler('checkEmailStatus', async (requestData) => {
-        // If MTA is enabled, use it to check status
-        if (this.emailRef.mtaConnector) {
-          const status = await this.emailRef.mtaConnector.checkEmailStatus(requestData.emailId);
-          return status;
-        }
-        
-        // For Mailgun, we don't have a status check implementation currently
-        return {
-          status: 'unknown',
-          details: { message: 'Status tracking not available for current provider' }
-        };
-      })
-    );
-
-    // Add statistics endpoint
-    this.typedRouter.addTypedHandler<plugins.servezoneInterfaces.platformservice.mta.IReq_GetEMailStats>(
-      new plugins.typedrequest.TypedHandler('getEmailStats', async () => {
-        return this.emailRef.getStats();
-      })
-    );
-  }
-}

ts/email/classes.bouncemanager.ts

@@ -1,902 +0,0 @@
-import * as plugins from '../plugins.js';
-import * as paths from '../paths.js';
-import { logger } from '../logger.js';
-import { SecurityLogger, SecurityLogLevel, SecurityEventType } from '../security/index.js';
-import { LRUCache } from 'lru-cache';
-
-/**
- * Bounce types for categorizing the reasons for bounces
- */
-export enum BounceType {
-  // Hard bounces (permanent failures)
-  INVALID_RECIPIENT = 'invalid_recipient',
-  DOMAIN_NOT_FOUND = 'domain_not_found',
-  MAILBOX_FULL = 'mailbox_full',
-  MAILBOX_INACTIVE = 'mailbox_inactive',
-  BLOCKED = 'blocked',
-  SPAM_RELATED = 'spam_related',
-  POLICY_RELATED = 'policy_related',
-  
-  // Soft bounces (temporary failures)
-  SERVER_UNAVAILABLE = 'server_unavailable',
-  TEMPORARY_FAILURE = 'temporary_failure',
-  QUOTA_EXCEEDED = 'quota_exceeded',
-  NETWORK_ERROR = 'network_error',
-  TIMEOUT = 'timeout',
-  
-  // Special cases
-  AUTO_RESPONSE = 'auto_response',
-  CHALLENGE_RESPONSE = 'challenge_response',
-  UNKNOWN = 'unknown'
-}
-
-/**
- * Hard vs soft bounce classification
- */
-export enum BounceCategory {
-  HARD = 'hard',
-  SOFT = 'soft',
-  AUTO_RESPONSE = 'auto_response',
-  UNKNOWN = 'unknown'
-}
-
-/**
- * Bounce data structure
- */
-export interface BounceRecord {
-  id: string;
-  originalEmailId?: string;
-  recipient: string;
-  sender: string;
-  domain: string;
-  subject?: string;
-  bounceType: BounceType;
-  bounceCategory: BounceCategory;
-  timestamp: number;
-  smtpResponse?: string;
-  diagnosticCode?: string;
-  statusCode?: string;
-  headers?: Record<string, string>;
-  processed: boolean;
-  retryCount?: number;
-  nextRetryTime?: number;
-}
-
-/**
- * Email bounce patterns to identify bounce types in SMTP responses and bounce messages
- */
-const BOUNCE_PATTERNS = {
-  // Hard bounce patterns
-  [BounceType.INVALID_RECIPIENT]: [
-    /no such user/i,
-    /user unknown/i,
-    /does not exist/i,
-    /invalid recipient/i,
-    /unknown recipient/i,
-    /no mailbox/i,
-    /user not found/i,
-    /recipient address rejected/i,
-    /550 5\.1\.1/i
-  ],
-  [BounceType.DOMAIN_NOT_FOUND]: [
-    /domain not found/i,
-    /unknown domain/i,
-    /no such domain/i,
-    /host not found/i,
-    /domain invalid/i,
-    /550 5\.1\.2/i
-  ],
-  [BounceType.MAILBOX_FULL]: [
-    /mailbox full/i,
-    /over quota/i,
-    /quota exceeded/i,
-    /552 5\.2\.2/i
-  ],
-  [BounceType.MAILBOX_INACTIVE]: [
-    /mailbox disabled/i,
-    /mailbox inactive/i,
-    /account disabled/i,
-    /mailbox not active/i,
-    /account suspended/i
-  ],
-  [BounceType.BLOCKED]: [
-    /blocked/i,
-    /rejected/i,
-    /denied/i,
-    /blacklisted/i,
-    /prohibited/i,
-    /refused/i,
-    /550 5\.7\./i
-  ],
-  [BounceType.SPAM_RELATED]: [
-    /spam/i,
-    /bulk mail/i,
-    /content rejected/i,
-    /message rejected/i,
-    /550 5\.7\.1/i
-  ],
-  
-  // Soft bounce patterns
-  [BounceType.SERVER_UNAVAILABLE]: [
-    /server unavailable/i,
-    /service unavailable/i,
-    /try again later/i,
-    /try later/i,
-    /451 4\.3\./i,
-    /421 4\.3\./i
-  ],
-  [BounceType.TEMPORARY_FAILURE]: [
-    /temporary failure/i,
-    /temporary error/i,
-    /temporary problem/i,
-    /try again/i,
-    /451 4\./i
-  ],
-  [BounceType.QUOTA_EXCEEDED]: [
-    /quota temporarily exceeded/i,
-    /mailbox temporarily full/i,
-    /452 4\.2\.2/i
-  ],
-  [BounceType.NETWORK_ERROR]: [
-    /network error/i,
-    /connection error/i,
-    /connection timed out/i,
-    /routing error/i,
-    /421 4\.4\./i
-  ],
-  [BounceType.TIMEOUT]: [
-    /timed out/i,
-    /timeout/i,
-    /450 4\.4\.2/i
-  ],
-  
-  // Auto-responses
-  [BounceType.AUTO_RESPONSE]: [
-    /auto[- ]reply/i,
-    /auto[- ]response/i,
-    /vacation/i,
-    /out of office/i,
-    /away from office/i,
-    /on vacation/i,
-    /automatic reply/i
-  ],
-  [BounceType.CHALLENGE_RESPONSE]: [
-    /challenge[- ]response/i,
-    /verify your email/i,
-    /confirm your email/i,
-    /email verification/i
-  ]
-};
-
-/**
- * Retry strategy configuration for soft bounces
- */
-interface RetryStrategy {
-  maxRetries: number;
-  initialDelay: number; // milliseconds
-  maxDelay: number; // milliseconds
-  backoffFactor: number;
-}
-
-/**
- * Manager for handling email bounces
- */
-export class BounceManager {
-  // Retry strategy with exponential backoff
-  private retryStrategy: RetryStrategy = {
-    maxRetries: 5,
-    initialDelay: 15 * 60 * 1000, // 15 minutes
-    maxDelay: 24 * 60 * 60 * 1000, // 24 hours
-    backoffFactor: 2
-  };
-  
-  // Store of bounced emails
-  private bounceStore: BounceRecord[] = [];
-  
-  // Cache of recently bounced email addresses to avoid sending to known bad addresses
-  private bounceCache: LRUCache<string, {
-    lastBounce: number;
-    count: number;
-    type: BounceType;
-    category: BounceCategory;
-  }>;
-  
-  // Suppression list for addresses that should not receive emails
-  private suppressionList: Map<string, {
-    reason: string;
-    timestamp: number;
-    expiresAt?: number; // undefined means permanent
-  }> = new Map();
-  
-  constructor(options?: {
-    retryStrategy?: Partial<RetryStrategy>;
-    maxCacheSize?: number;
-    cacheTTL?: number;
-  }) {
-    // Set retry strategy with defaults
-    if (options?.retryStrategy) {
-      this.retryStrategy = {
-        ...this.retryStrategy,
-        ...options.retryStrategy
-      };
-    }
-    
-    // Initialize bounce cache with LRU (least recently used) caching
-    this.bounceCache = new LRUCache<string, any>({
-      max: options?.maxCacheSize || 10000,
-      ttl: options?.cacheTTL || 30 * 24 * 60 * 60 * 1000, // 30 days default
-    });
-    
-    // Load suppression list from storage
-    this.loadSuppressionList();
-  }
-  
-  /**
-   * Process a bounce notification
-   * @param bounceData Bounce data to process
-   * @returns Processed bounce record
-   */
-  public async processBounce(bounceData: Partial<BounceRecord>): Promise<BounceRecord> {
-    try {
-      // Add required fields if missing
-      const bounce: BounceRecord = {
-        id: bounceData.id || plugins.uuid.v4(),
-        recipient: bounceData.recipient,
-        sender: bounceData.sender,
-        domain: bounceData.domain || bounceData.recipient.split('@')[1],
-        subject: bounceData.subject,
-        bounceType: bounceData.bounceType || BounceType.UNKNOWN,
-        bounceCategory: bounceData.bounceCategory || BounceCategory.UNKNOWN,
-        timestamp: bounceData.timestamp || Date.now(),
-        smtpResponse: bounceData.smtpResponse,
-        diagnosticCode: bounceData.diagnosticCode,
-        statusCode: bounceData.statusCode,
-        headers: bounceData.headers,
-        processed: false,
-        originalEmailId: bounceData.originalEmailId,
-        retryCount: bounceData.retryCount || 0,
-        nextRetryTime: bounceData.nextRetryTime
-      };
-      
-      // Determine bounce type and category if not provided
-      if (!bounceData.bounceType || bounceData.bounceType === BounceType.UNKNOWN) {
-        const bounceInfo = this.detectBounceType(
-          bounce.smtpResponse || '',
-          bounce.diagnosticCode || '',
-          bounce.statusCode || ''
-        );
-        
-        bounce.bounceType = bounceInfo.type;
-        bounce.bounceCategory = bounceInfo.category;
-      }
-      
-      // Process the bounce based on category
-      switch (bounce.bounceCategory) {
-        case BounceCategory.HARD:
-          // Handle hard bounce - add to suppression list
-          await this.handleHardBounce(bounce);
-          break;
-          
-        case BounceCategory.SOFT:
-          // Handle soft bounce - schedule retry if eligible
-          await this.handleSoftBounce(bounce);
-          break;
-          
-        case BounceCategory.AUTO_RESPONSE:
-          // Handle auto-response - typically no action needed
-          logger.log('info', `Auto-response detected for ${bounce.recipient}`);
-          break;
-          
-        default:
-          // Unknown bounce type - log for investigation
-          logger.log('warn', `Unknown bounce type for ${bounce.recipient}`, {
-            bounceType: bounce.bounceType,
-            smtpResponse: bounce.smtpResponse
-          });
-          break;
-      }
-      
-      // Store the bounce record
-      bounce.processed = true;
-      this.bounceStore.push(bounce);
-      
-      // Update the bounce cache
-      this.updateBounceCache(bounce);
-      
-      // Log the bounce
-      logger.log(
-        bounce.bounceCategory === BounceCategory.HARD ? 'warn' : 'info',
-        `Email bounce processed: ${bounce.bounceCategory} bounce for ${bounce.recipient}`,
-        {
-          bounceType: bounce.bounceType,
-          domain: bounce.domain,
-          category: bounce.bounceCategory
-        }
-      );
-      
-      // Enhanced security logging
-      SecurityLogger.getInstance().logEvent({
-        level: bounce.bounceCategory === BounceCategory.HARD 
-          ? SecurityLogLevel.WARN 
-          : SecurityLogLevel.INFO,
-        type: SecurityEventType.EMAIL_VALIDATION,
-        message: `Email bounce detected: ${bounce.bounceCategory} bounce for recipient`,
-        domain: bounce.domain,
-        details: {
-          recipient: bounce.recipient,
-          bounceType: bounce.bounceType,
-          smtpResponse: bounce.smtpResponse,
-          diagnosticCode: bounce.diagnosticCode,
-          statusCode: bounce.statusCode
-        },
-        success: false
-      });
-      
-      return bounce;
-    } catch (error) {
-      logger.log('error', `Error processing bounce: ${error.message}`, {
-        error: error.message,
-        bounceData
-      });
-      throw error;
-    }
-  }
-  
-  /**
-   * Process an SMTP failure as a bounce
-   * @param recipient Recipient email
-   * @param smtpResponse SMTP error response
-   * @param options Additional options
-   * @returns Processed bounce record
-   */
-  public async processSmtpFailure(
-    recipient: string,
-    smtpResponse: string,
-    options: {
-      sender?: string;
-      originalEmailId?: string;
-      statusCode?: string;
-      headers?: Record<string, string>;
-    } = {}
-  ): Promise<BounceRecord> {
-    // Create bounce data from SMTP failure
-    const bounceData: Partial<BounceRecord> = {
-      recipient,
-      sender: options.sender || '',
-      domain: recipient.split('@')[1],
-      smtpResponse,
-      statusCode: options.statusCode,
-      headers: options.headers,
-      originalEmailId: options.originalEmailId,
-      timestamp: Date.now()
-    };
-    
-    // Process as a regular bounce
-    return this.processBounce(bounceData);
-  }
-  
-  /**
-   * Process a bounce notification email
-   * @param bounceEmail The email containing bounce information
-   * @returns Processed bounce record or null if not a bounce
-   */
-  public async processBounceEmail(bounceEmail: plugins.smartmail.Smartmail<any>): Promise<BounceRecord | null> {
-    try {
-      // Check if this is a bounce notification
-      const subject = bounceEmail.getSubject();
-      const body = bounceEmail.getBody();
-      
-      // Check for common bounce notification subject patterns
-      const isBounceSubject = /mail delivery|delivery (failed|status|notification)|failure notice|returned mail|undeliverable|delivery problem/i.test(subject);
-      
-      if (!isBounceSubject) {
-        // Not a bounce notification based on subject
-        return null;
-      }
-      
-      // Extract original recipient from the body or headers
-      let recipient = '';
-      let originalMessageId = '';
-      
-      // Extract recipient from common bounce formats
-      const recipientMatch = body.match(/(?:failed recipient|to[:=]\s*|recipient:|delivery failed:)\s*<?([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})>?/i);
-      if (recipientMatch && recipientMatch[1]) {
-        recipient = recipientMatch[1];
-      }
-      
-      // Extract diagnostic code
-      let diagnosticCode = '';
-      const diagnosticMatch = body.match(/diagnostic(?:-|\\s+)code:\s*(.+)(?:\n|$)/i);
-      if (diagnosticMatch && diagnosticMatch[1]) {
-        diagnosticCode = diagnosticMatch[1].trim();
-      }
-      
-      // Extract SMTP status code
-      let statusCode = '';
-      const statusMatch = body.match(/status(?:-|\\s+)code:\s*([0-9.]+)/i);
-      if (statusMatch && statusMatch[1]) {
-        statusCode = statusMatch[1].trim();
-      }
-      
-      // If recipient not found in standard patterns, try DSN (Delivery Status Notification) format
-      if (!recipient) {
-        // Look for DSN format with Original-Recipient or Final-Recipient fields
-        const originalRecipientMatch = body.match(/original-recipient:.*?([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})/i);
-        const finalRecipientMatch = body.match(/final-recipient:.*?([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})/i);
-        
-        if (originalRecipientMatch && originalRecipientMatch[1]) {
-          recipient = originalRecipientMatch[1];
-        } else if (finalRecipientMatch && finalRecipientMatch[1]) {
-          recipient = finalRecipientMatch[1];
-        }
-      }
-      
-      // If still no recipient, can't process as bounce
-      if (!recipient) {
-        logger.log('warn', 'Could not extract recipient from bounce notification', {
-          subject,
-          sender: bounceEmail.options.from
-        });
-        return null;
-      }
-      
-      // Extract original message ID if available
-      const messageIdMatch = body.match(/original[ -]message[ -]id:[ \t]*<?([^>]+)>?/i);
-      if (messageIdMatch && messageIdMatch[1]) {
-        originalMessageId = messageIdMatch[1].trim();
-      }
-      
-      // Create bounce data
-      const bounceData: Partial<BounceRecord> = {
-        recipient,
-        sender: bounceEmail.options.from,
-        domain: recipient.split('@')[1],
-        subject: bounceEmail.getSubject(),
-        diagnosticCode,
-        statusCode,
-        timestamp: Date.now(),
-        headers: {}
-      };
-      
-      // Process as a regular bounce
-      return this.processBounce(bounceData);
-    } catch (error) {
-      logger.log('error', `Error processing bounce email: ${error.message}`);
-      return null;
-    }
-  }
-  
-  /**
-   * Handle a hard bounce by adding to suppression list
-   * @param bounce The bounce record
-   */
-  private async handleHardBounce(bounce: BounceRecord): Promise<void> {
-    // Add to suppression list permanently (no expiry)
-    this.addToSuppressionList(bounce.recipient, `Hard bounce: ${bounce.bounceType}`, undefined);
-    
-    // Increment bounce count in cache
-    this.updateBounceCache(bounce);
-    
-    // Save to permanent storage
-    this.saveBounceRecord(bounce);
-    
-    // Log hard bounce for monitoring
-    logger.log('warn', `Hard bounce for ${bounce.recipient}: ${bounce.bounceType}`, {
-      domain: bounce.domain,
-      smtpResponse: bounce.smtpResponse,
-      diagnosticCode: bounce.diagnosticCode
-    });
-  }
-  
-  /**
-   * Handle a soft bounce by scheduling a retry if eligible
-   * @param bounce The bounce record
-   */
-  private async handleSoftBounce(bounce: BounceRecord): Promise<void> {
-    // Check if we've exceeded max retries
-    if (bounce.retryCount >= this.retryStrategy.maxRetries) {
-      logger.log('warn', `Max retries exceeded for ${bounce.recipient}, treating as hard bounce`);
-      
-      // Convert to hard bounce after max retries
-      bounce.bounceCategory = BounceCategory.HARD;
-      await this.handleHardBounce(bounce);
-      return;
-    }
-    
-    // Calculate next retry time with exponential backoff
-    const delay = Math.min(
-      this.retryStrategy.initialDelay * Math.pow(this.retryStrategy.backoffFactor, bounce.retryCount),
-      this.retryStrategy.maxDelay
-    );
-    
-    bounce.retryCount++;
-    bounce.nextRetryTime = Date.now() + delay;
-    
-    // Add to suppression list temporarily (with expiry)
-    this.addToSuppressionList(
-      bounce.recipient,
-      `Soft bounce: ${bounce.bounceType}`,
-      bounce.nextRetryTime
-    );
-    
-    // Log the retry schedule
-    logger.log('info', `Scheduled retry ${bounce.retryCount} for ${bounce.recipient} at ${new Date(bounce.nextRetryTime).toISOString()}`, {
-      bounceType: bounce.bounceType,
-      retryCount: bounce.retryCount,
-      nextRetry: bounce.nextRetryTime
-    });
-  }
-  
-  /**
-   * Add an email address to the suppression list
-   * @param email Email address to suppress
-   * @param reason Reason for suppression
-   * @param expiresAt Expiration timestamp (undefined for permanent)
-   */
-  public addToSuppressionList(
-    email: string,
-    reason: string,
-    expiresAt?: number
-  ): void {
-    this.suppressionList.set(email.toLowerCase(), {
-      reason,
-      timestamp: Date.now(),
-      expiresAt
-    });
-    
-    this.saveSuppressionList();
-    
-    logger.log('info', `Added ${email} to suppression list`, {
-      reason,
-      expiresAt: expiresAt ? new Date(expiresAt).toISOString() : 'permanent'
-    });
-  }
-  
-  /**
-   * Remove an email address from the suppression list
-   * @param email Email address to remove
-   */
-  public removeFromSuppressionList(email: string): void {
-    const wasRemoved = this.suppressionList.delete(email.toLowerCase());
-    
-    if (wasRemoved) {
-      this.saveSuppressionList();
-      logger.log('info', `Removed ${email} from suppression list`);
-    }
-  }
-  
-  /**
-   * Check if an email is on the suppression list
-   * @param email Email address to check
-   * @returns Whether the email is suppressed
-   */
-  public isEmailSuppressed(email: string): boolean {
-    const lowercaseEmail = email.toLowerCase();
-    const suppression = this.suppressionList.get(lowercaseEmail);
-    
-    if (!suppression) {
-      return false;
-    }
-    
-    // Check if suppression has expired
-    if (suppression.expiresAt && Date.now() > suppression.expiresAt) {
-      this.suppressionList.delete(lowercaseEmail);
-      this.saveSuppressionList();
-      return false;
-    }
-    
-    return true;
-  }
-  
-  /**
-   * Get suppression information for an email
-   * @param email Email address to check
-   * @returns Suppression information or null if not suppressed
-   */
-  public getSuppressionInfo(email: string): {
-    reason: string;
-    timestamp: number;
-    expiresAt?: number;
-  } | null {
-    const lowercaseEmail = email.toLowerCase();
-    const suppression = this.suppressionList.get(lowercaseEmail);
-    
-    if (!suppression) {
-      return null;
-    }
-    
-    // Check if suppression has expired
-    if (suppression.expiresAt && Date.now() > suppression.expiresAt) {
-      this.suppressionList.delete(lowercaseEmail);
-      this.saveSuppressionList();
-      return null;
-    }
-    
-    return suppression;
-  }
-  
-  /**
-   * Save suppression list to disk
-   */
-  private saveSuppressionList(): void {
-    try {
-      const suppressionData = JSON.stringify(Array.from(this.suppressionList.entries()));
-      plugins.smartfile.memory.toFsSync(
-        suppressionData,
-        plugins.path.join(paths.dataDir, 'emails', 'suppression_list.json')
-      );
-    } catch (error) {
-      logger.log('error', `Failed to save suppression list: ${error.message}`);
-    }
-  }
-  
-  /**
-   * Load suppression list from disk
-   */
-  private loadSuppressionList(): void {
-    try {
-      const suppressionPath = plugins.path.join(paths.dataDir, 'emails', 'suppression_list.json');
-      
-      if (plugins.fs.existsSync(suppressionPath)) {
-        const data = plugins.fs.readFileSync(suppressionPath, 'utf8');
-        const entries = JSON.parse(data);
-        
-        this.suppressionList = new Map(entries);
-        
-        // Clean expired entries
-        const now = Date.now();
-        let expiredCount = 0;
-        
-        for (const [email, info] of this.suppressionList.entries()) {
-          if (info.expiresAt && now > info.expiresAt) {
-            this.suppressionList.delete(email);
-            expiredCount++;
-          }
-        }
-        
-        if (expiredCount > 0) {
-          logger.log('info', `Cleaned ${expiredCount} expired entries from suppression list`);
-          this.saveSuppressionList();
-        }
-        
-        logger.log('info', `Loaded ${this.suppressionList.size} entries from suppression list`);
-      }
-    } catch (error) {
-      logger.log('error', `Failed to load suppression list: ${error.message}`);
-    }
-  }
-  
-  /**
-   * Save bounce record to disk
-   * @param bounce Bounce record to save
-   */
-  private saveBounceRecord(bounce: BounceRecord): void {
-    try {
-      const bounceData = JSON.stringify(bounce);
-      const bouncePath = plugins.path.join(
-        paths.dataDir,
-        'emails',
-        'bounces',
-        `${bounce.id}.json`
-      );
-      
-      // Ensure directory exists
-      const bounceDir = plugins.path.join(paths.dataDir, 'emails', 'bounces');
-      plugins.smartfile.fs.ensureDirSync(bounceDir);
-      
-      plugins.smartfile.memory.toFsSync(bounceData, bouncePath);
-    } catch (error) {
-      logger.log('error', `Failed to save bounce record: ${error.message}`);
-    }
-  }
-  
-  /**
-   * Update bounce cache with new bounce information
-   * @param bounce Bounce record to update cache with
-   */
-  private updateBounceCache(bounce: BounceRecord): void {
-    const email = bounce.recipient.toLowerCase();
-    const existing = this.bounceCache.get(email);
-    
-    if (existing) {
-      // Update existing cache entry
-      existing.lastBounce = bounce.timestamp;
-      existing.count++;
-      existing.type = bounce.bounceType;
-      existing.category = bounce.bounceCategory;
-    } else {
-      // Create new cache entry
-      this.bounceCache.set(email, {
-        lastBounce: bounce.timestamp,
-        count: 1,
-        type: bounce.bounceType,
-        category: bounce.bounceCategory
-      });
-    }
-  }
-  
-  /**
-   * Check bounce history for an email address
-   * @param email Email address to check
-   * @returns Bounce information or null if no bounces
-   */
-  public getBounceInfo(email: string): {
-    lastBounce: number;
-    count: number;
-    type: BounceType;
-    category: BounceCategory;
-  } | null {
-    return this.bounceCache.get(email.toLowerCase()) || null;
-  }
-  
-  /**
-   * Analyze SMTP response and diagnostic codes to determine bounce type
-   * @param smtpResponse SMTP response string
-   * @param diagnosticCode Diagnostic code from bounce
-   * @param statusCode Status code from bounce
-   * @returns Detected bounce type and category
-   */
-  private detectBounceType(
-    smtpResponse: string,
-    diagnosticCode: string,
-    statusCode: string
-  ): {
-    type: BounceType;
-    category: BounceCategory;
-  } {
-    // Combine all text for comprehensive pattern matching
-    const fullText = `${smtpResponse} ${diagnosticCode} ${statusCode}`.toLowerCase();
-    
-    // Check for auto-responses first
-    if (this.matchesPattern(fullText, BounceType.AUTO_RESPONSE) || 
-        this.matchesPattern(fullText, BounceType.CHALLENGE_RESPONSE)) {
-      return {
-        type: BounceType.AUTO_RESPONSE,
-        category: BounceCategory.AUTO_RESPONSE
-      };
-    }
-    
-    // Check for hard bounces
-    for (const bounceType of [
-      BounceType.INVALID_RECIPIENT,
-      BounceType.DOMAIN_NOT_FOUND,
-      BounceType.MAILBOX_FULL,
-      BounceType.MAILBOX_INACTIVE,
-      BounceType.BLOCKED,
-      BounceType.SPAM_RELATED,
-      BounceType.POLICY_RELATED
-    ]) {
-      if (this.matchesPattern(fullText, bounceType)) {
-        return {
-          type: bounceType,
-          category: BounceCategory.HARD
-        };
-      }
-    }
-    
-    // Check for soft bounces
-    for (const bounceType of [
-      BounceType.SERVER_UNAVAILABLE,
-      BounceType.TEMPORARY_FAILURE,
-      BounceType.QUOTA_EXCEEDED,
-      BounceType.NETWORK_ERROR,
-      BounceType.TIMEOUT
-    ]) {
-      if (this.matchesPattern(fullText, bounceType)) {
-        return {
-          type: bounceType,
-          category: BounceCategory.SOFT
-        };
-      }
-    }
-    
-    // Handle DSN (Delivery Status Notification) status codes
-    if (statusCode) {
-      // Format: class.subject.detail
-      const parts = statusCode.split('.');
-      if (parts.length >= 2) {
-        const statusClass = parts[0];
-        const statusSubject = parts[1];
-        
-        // 5.X.X is permanent failure (hard bounce)
-        if (statusClass === '5') {
-          // Try to determine specific type based on subject
-          if (statusSubject === '1') {
-            return { type: BounceType.INVALID_RECIPIENT, category: BounceCategory.HARD };
-          } else if (statusSubject === '2') {
-            return { type: BounceType.MAILBOX_FULL, category: BounceCategory.HARD };
-          } else if (statusSubject === '7') {
-            return { type: BounceType.BLOCKED, category: BounceCategory.HARD };
-          } else {
-            return { type: BounceType.UNKNOWN, category: BounceCategory.HARD };
-          }
-        }
-        
-        // 4.X.X is temporary failure (soft bounce)
-        if (statusClass === '4') {
-          // Try to determine specific type based on subject
-          if (statusSubject === '2') {
-            return { type: BounceType.QUOTA_EXCEEDED, category: BounceCategory.SOFT };
-          } else if (statusSubject === '3') {
-            return { type: BounceType.SERVER_UNAVAILABLE, category: BounceCategory.SOFT };
-          } else if (statusSubject === '4') {
-            return { type: BounceType.NETWORK_ERROR, category: BounceCategory.SOFT };
-          } else {
-            return { type: BounceType.TEMPORARY_FAILURE, category: BounceCategory.SOFT };
-          }
-        }
-      }
-    }
-    
-    // Default to unknown
-    return {
-      type: BounceType.UNKNOWN,
-      category: BounceCategory.UNKNOWN
-    };
-  }
-  
-  /**
-   * Check if text matches any pattern for a bounce type
-   * @param text Text to check against patterns
-   * @param bounceType Bounce type to get patterns for
-   * @returns Whether the text matches any pattern
-   */
-  private matchesPattern(text: string, bounceType: BounceType): boolean {
-    const patterns = BOUNCE_PATTERNS[bounceType];
-    
-    if (!patterns) {
-      return false;
-    }
-    
-    for (const pattern of patterns) {
-      if (pattern.test(text)) {
-        return true;
-      }
-    }
-    
-    return false;
-  }
-  
-  /**
-   * Get all known hard bounced addresses
-   * @returns Array of hard bounced email addresses
-   */
-  public getHardBouncedAddresses(): string[] {
-    const hardBounced: string[] = [];
-    
-    for (const [email, info] of this.bounceCache.entries()) {
-      if (info.category === BounceCategory.HARD) {
-        hardBounced.push(email);
-      }
-    }
-    
-    return hardBounced;
-  }
-  
-  /**
-   * Get suppression list
-   * @returns Array of suppressed email addresses
-   */
-  public getSuppressionList(): string[] {
-    return Array.from(this.suppressionList.keys());
-  }
-  
-  /**
-   * Clear old bounce records (for maintenance)
-   * @param olderThan Timestamp to remove records older than
-   * @returns Number of records removed
-   */
-  public clearOldBounceRecords(olderThan: number): number {
-    let removed = 0;
-    
-    this.bounceStore = this.bounceStore.filter(bounce => {
-      if (bounce.timestamp < olderThan) {
-        removed++;
-        return false;
-      }
-      return true;
-    });
-    
-    return removed;
-  }
-}