@serve.zone/dcrouter 2.12.4 → 5.0.2

package/readme.md

@@ -1,8 +1,14 @@
-# dcrouter
+# @serve.zone/dcrouter
 
-**dcrouter: a traffic router intended to be gating your datacenter.**
+![](https://code.foss.global/serve.zone/docs/raw/branch/main/dcrouter.png)
 
-A comprehensive traffic routing solution that provides unified gateway capabilities for HTTP/HTTPS, TCP/SNI, email (SMTP), and DNS protocols. Designed for enterprises requiring robust traffic management, automatic certificate provisioning, and enterprise-grade email infrastructure.
+**dcrouter: The all-in-one gateway for your datacenter.** 🚀
+
+A comprehensive traffic routing solution that provides unified gateway capabilities for HTTP/HTTPS, TCP/SNI, email (SMTP), DNS, and RADIUS protocols. Designed for enterprises requiring robust traffic management, automatic TLS certificate provisioning, and enterprise-grade email infrastructure — all from a single process.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
 
 ## Table of Contents
 
@@ -10,57 +16,79 @@ A comprehensive traffic routing solution that provides unified gateway capabilit
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Architecture](#architecture)
-- [Configuration](#configuration)
+- [Configuration Reference](#configuration-reference)
+- [HTTP/HTTPS & TCP/SNI Routing](#httphttps--tcpsni-routing)
 - [Email System](#email-system)
-- [SmartProxy Routing](#smartproxy-routing)
+- [DNS Server](#dns-server)
+- [RADIUS Server](#radius-server)
+- [Storage & Caching](#storage--caching)
 - [Security Features](#security-features)
+- [OpsServer Dashboard](#opsserver-dashboard)
 - [API Reference](#api-reference)
-- [Examples](#examples)
-- [Troubleshooting](#troubleshooting)
+- [Sub-Modules](#sub-modules)
+- [Testing](#testing)
+- [License and Legal Information](#license-and-legal-information)
 
 ## Features
 
-### 🌐 **Universal Traffic Router**
-- **HTTP/HTTPS routing** with pattern matching and virtual hosts
-- **TCP/SNI proxy** for any protocol with TLS termination/passthrough
-- **DNS server** with authoritative and dynamic record management
-- **Multi-protocol support** on the same infrastructure
+### 🌐 Universal Traffic Router
+- **HTTP/HTTPS routing** with domain matching, path-based forwarding, and automatic TLS
+- **TCP/SNI proxy** for any protocol with TLS termination or passthrough
+- **DNS server** (Rust-powered via [SmartDNS](https://code.foss.global/push.rocks/smartdns)) with authoritative zones, dynamic record management, and DNS-over-HTTPS
+- **Multi-protocol support** on the same infrastructure via [SmartProxy](https://code.foss.global/push.rocks/smartproxy)
 
-### 🔒 **Enterprise Security**
-- **Automatic TLS certificates** via ACME with DNS-01 challenges
-- **IP reputation checking** and real-time threat detection
-- **Content scanning** for spam, viruses, and malicious content
-- **Comprehensive security logging** with correlation tracking
-
-### 📧 **Complete Email Infrastructure**
+### 📧 Complete Email Infrastructure (powered by [smartmta](https://code.foss.global/push.rocks/smartmta))
 - **Multi-domain SMTP server** on standard ports (25, 587, 465)
-- **Pattern-based email routing** with three processing modes
-- **DKIM, SPF, DMARC** authentication and verification
-- **Enterprise deliverability** with IP warmup and reputation management
-
-### ⚡ **High Performance**
-- **Connection pooling** and efficient resource management
-- **Load balancing** with automatic failover
-- **Rate limiting** at multiple levels
-- **Real-time metrics** and monitoring
-
-### 💾 **Flexible Storage System**
-- **Multiple storage backends**: filesystem, custom functions, or memory
-- **Unified storage interface** for all components
-- **Automatic data migration** between backends
-- **Persistent configuration** for domains, routes, and security data
+- **Pattern-based email routing** with four action types: forward, process, deliver, reject
+- **DKIM signing & verification**, SPF, DMARC authentication stack
+- **Enterprise deliverability** with IP warmup schedules and sender reputation tracking
+- **Bounce handling** with automatic suppression lists
+- **Hierarchical rate limiting** — global, per-domain, per-sender
+
+### 🔒 Enterprise Security
+- **Automatic TLS certificates** via ACME with Cloudflare DNS-01 challenges
+- **IP reputation checking** with caching and configurable thresholds
+- **Content scanning** for spam, viruses, and malicious attachments
+- **Security event logging** with structured audit trails
+
+### 📡 RADIUS Server
+- **MAC Authentication Bypass (MAB)** for network device authentication
+- **VLAN assignment** based on exact MAC, OUI prefix, or wildcard patterns
+- **RADIUS accounting** for session tracking, traffic metering, and billing
+- **Real-time management** via OpsServer API
+
+### ⚡ High Performance
+- **Rust-powered proxy engine** via SmartProxy for maximum throughput
+- **Rust-powered MTA engine** via smartmta (TypeScript + Rust hybrid) for reliable email delivery
+- **Rust-powered DNS engine** via SmartDNS for high-performance UDP and DNS-over-HTTPS
+- **Connection pooling** for outbound SMTP and backend services
+- **Socket-handler mode** — direct socket passing eliminates internal port hops
+- **Real-time metrics** via SmartMetrics (CPU, memory, connections, throughput)
+
+### 💾 Persistent Storage & Caching
+- **Multiple storage backends**: filesystem, custom functions, or in-memory
+- **Embedded cache database** via smartdata + LocalTsmDb (MongoDB-compatible)
+- **Automatic TTL-based cleanup** for cached emails and IP reputation data
+
+### 🖥️ OpsServer Dashboard
+- **Web-based management interface** with real-time monitoring
+- **JWT authentication** with session persistence
+- **Live views** for connections, email queues, DNS queries, RADIUS sessions, and security events
+- **Read-only configuration display** — DcRouter is configured through code
 
 ## Installation
 
 ```bash
-npm install @serve.zone/dcrouter --save
+pnpm add @serve.zone/dcrouter
+# or
+npm install @serve.zone/dcrouter
 ```
 
 ### Prerequisites
 
-- Node.js 18+ with ES modules support
-- Valid domain with DNS control (for ACME certificates)
-- Cloudflare API token (for DNS challenges)
+- **Node.js 20+** with ES module support
+- Valid domain with DNS control (for ACME certificate automation)
+- Cloudflare API token (for DNS-01 challenges) — optional
 
 ## Quick Start
 
@@ -73,11 +101,11 @@ const router = new DcRouter({
   smartProxyConfig: {
     routes: [
       {
-        name: 'web-service',
-        match: { domains: ['example.com'], ports: [443] },
+        name: 'web-app',
+        match: { domains: ['example.com', 'www.example.com'], ports: [443] },
         action: {
           type: 'forward',
-          target: { host: '192.168.1.10', port: 8080 },
+          targets: [{ host: '192.168.1.10', port: 8080 }],
           tls: { mode: 'terminate', certificate: 'auto' }
         }
       }
@@ -91,10 +119,9 @@ const router = new DcRouter({
 });
 
 await router.start();
-console.log('DcRouter started successfully');
 ```
 
-### Basic Email Router
+### Basic Email Server
 
 ```typescript
 import { DcRouter } from '@serve.zone/dcrouter';
@@ -103,30 +130,106 @@ const router = new DcRouter({
   emailConfig: {
     ports: [25, 587, 465],
     hostname: 'mail.example.com',
+    domains: [
+      {
+        domain: 'example.com',
+        dnsMode: 'external-dns'
+      }
+    ],
     routes: [
       {
-        name: 'local-mail',
+        name: 'process-all',
         match: { recipients: '*@example.com' },
         action: {
           type: 'process',
-          process: {
-            scan: true,
-            dkim: true,
-            queue: 'normal'
-          }
+          process: { scan: true, dkim: true, queue: 'normal' }
         }
       }
-    ],
-    tls: {
-      keyPath: './certs/key.pem',
-      certPath: './certs/cert.pem'
-    }
+    ]
   }
 });
 
 await router.start();
 ```
 
+### Full Stack with Dashboard
+
+```typescript
+import { DcRouter } from '@serve.zone/dcrouter';
+
+const router = new DcRouter({
+  // HTTP/HTTPS routing
+  smartProxyConfig: {
+    routes: [
+      {
+        name: 'website',
+        match: { domains: ['example.com'], ports: [443] },
+        action: {
+          type: 'forward',
+          targets: [{ host: '192.168.1.10', port: 80 }],
+          tls: { mode: 'terminate', certificate: 'auto' }
+        }
+      }
+    ],
+    acme: { email: 'ssl@example.com', enabled: true, useProduction: true }
+  },
+
+  // Email system (powered by smartmta)
+  emailConfig: {
+    ports: [25, 587, 465],
+    hostname: 'mail.example.com',
+    domains: [{ domain: 'example.com', dnsMode: 'external-dns' }],
+    routes: [
+      {
+        name: 'inbound-mail',
+        match: { recipients: '*@example.com' },
+        action: { type: 'process', process: { scan: true, dkim: true, queue: 'normal' } }
+      }
+    ]
+  },
+
+  // Authoritative DNS
+  dnsNsDomains: ['ns1.example.com', 'ns2.example.com'],
+  dnsScopes: ['example.com'],
+  publicIp: '203.0.113.1',
+  dnsRecords: [
+    { name: 'example.com', type: 'A', value: '203.0.113.1' },
+    { name: 'www.example.com', type: 'CNAME', value: 'example.com' }
+  ],
+
+  // RADIUS authentication
+  radiusConfig: {
+    authPort: 1812,
+    acctPort: 1813,
+    clients: [
+      { name: 'switch-1', ipRange: '192.168.1.0/24', secret: 'radius-secret', enabled: true }
+    ],
+    vlanAssignment: {
+      defaultVlan: 100,
+      allowUnknownMacs: true,
+      mappings: [
+        { mac: 'aa:bb:cc:dd:ee:ff', vlan: 10, enabled: true },
+        { mac: 'aa:bb:cc', vlan: 20, enabled: true }  // OUI prefix
+      ]
+    },
+    accounting: { enabled: true, retentionDays: 30 }
+  },
+
+  // Persistent storage
+  storage: { fsPath: '/var/lib/dcrouter/data' },
+
+  // Cache database
+  cacheConfig: { enabled: true, storagePath: '/etc/dcrouter/tsmdb' },
+
+  // TLS & ACME
+  tls: { contactEmail: 'admin@example.com' },
+  dnsChallenge: { cloudflareApiKey: process.env.CLOUDFLARE_API_KEY }
+});
+
+await router.start();
+// OpsServer dashboard available at http://localhost:3000
+```
+
 ## Architecture
 
 ### System Overview
@@ -138,292 +241,272 @@ graph TB
         SMTP[SMTP Clients]
         TCP[TCP Clients]
         DNS[DNS Queries]
+        RAD[RADIUS Clients]
     end
-    
+
     subgraph "DcRouter Core"
-        DcRouter[DcRouter Orchestrator]
-        SmartProxy[SmartProxy Engine]
-        EmailServer[Unified Email Server]
-        DnsServer[DNS Server]
-        CertManager[Certificate Manager]
+        DC[DcRouter Orchestrator]
+        SP[SmartProxy Engine<br/><i>Rust-powered</i>]
+        ES[smartmta Email Server<br/><i>TypeScript + Rust</i>]
+        DS[SmartDNS Server<br/><i>Rust-powered</i>]
+        RS[SmartRadius Server]
+        CM[Certificate Manager]
+        OS[OpsServer Dashboard]
+        MM[Metrics Manager]
+        SM[Storage Manager]
+        CD[Cache Database]
     end
-    
+
     subgraph "Backend Services"
-        WebServices[Web Services]
-        MailServers[Mail Servers]
-        Databases[Databases]
-        APIs[Internal APIs]
+        WEB[Web Services]
+        MAIL[Mail Servers]
+        DB[Databases]
+        API[Internal APIs]
     end
-    
-    HTTP --> SmartProxy
-    TCP --> SmartProxy
-    SMTP --> EmailServer
-    DNS --> DnsServer
-    
-    DcRouter --> SmartProxy
-    DcRouter --> EmailServer
-    DcRouter --> DnsServer
-    DcRouter --> CertManager
-    
-    SmartProxy --> WebServices
-    SmartProxy --> APIs
-    EmailServer --> MailServers
-    EmailServer --> Databases
-    
-    CertManager -.-> SmartProxy
-    CertManager -.-> EmailServer
+
+    HTTP --> SP
+    TCP --> SP
+    SMTP --> ES
+    DNS --> DS
+    RAD --> RS
+
+    DC --> SP
+    DC --> ES
+    DC --> DS
+    DC --> RS
+    DC --> CM
+    DC --> OS
+    DC --> MM
+    DC --> SM
+    DC --> CD
+
+    SP --> WEB
+    SP --> API
+    ES --> MAIL
+    ES --> DB
+
+    CM -.-> SP
+    CM -.-> ES
 ```
 
 ### Core Components
 
-#### **DcRouter Orchestrator**
-Central coordination engine that manages all services and provides unified configuration.
+| Component | Package | Description |
+|-----------|---------|-------------|
+| **DcRouter** | `@serve.zone/dcrouter` | Central orchestrator — starts, stops, and coordinates all services |
+| **SmartProxy** | `@push.rocks/smartproxy` | High-performance HTTP/HTTPS and TCP/SNI proxy with route-based config (Rust engine) |
+| **UnifiedEmailServer** | `@push.rocks/smartmta` | Full SMTP server with pattern-based routing, DKIM, queue management (TypeScript + Rust) |
+| **DNS Server** | `@push.rocks/smartdns` | Authoritative DNS with dynamic records and DKIM TXT auto-generation (Rust engine) |
+| **RADIUS Server** | `@push.rocks/smartradius` | Network authentication with MAB, VLAN assignment, and accounting |
+| **OpsServer** | `@api.global/typedserver` | Web dashboard + TypedRequest API for monitoring and management |
+| **MetricsManager** | `@push.rocks/smartmetrics` | Real-time metrics collection (CPU, memory, email, DNS, security) |
+| **StorageManager** | built-in | Pluggable key-value storage (filesystem, custom, or in-memory) |
+| **CacheDb** | `@push.rocks/smartdata` | Embedded MongoDB-compatible database (LocalTsmDb) for persistent caching |
+
+### How It Works
 
-#### **SmartProxy Engine**
-High-performance HTTP/HTTPS and TCP/SNI proxy with:
-- Pattern-based routing
-- TLS termination/passthrough
-- Load balancing
-- Connection pooling
+DcRouter acts purely as an **orchestrator** — it doesn't implement protocols itself. Instead, it wires together best-in-class packages for each protocol:
 
-#### **Unified Email Server**
-Enterprise-grade SMTP server with:
-- Multi-domain support
-- Pattern-based routing
-- Three processing modes
-- Complete authentication stack
+1. **On `start()`**: DcRouter initializes OpsServer (port 3000), then spins up SmartProxy, smartmta, SmartDNS, and SmartRadius based on which configs are provided.
+2. **During operation**: Each service handles its own protocol independently. SmartProxy uses a Rust-powered engine for maximum throughput. smartmta uses a hybrid TypeScript + Rust architecture for reliable email delivery.
+3. **On `stop()`**: All services are gracefully shut down in reverse order.
 
-#### **Certificate Manager**
-Automatic TLS certificate provisioning via ACME with DNS-01 challenges.
+### Rust-Powered Architecture
 
-## Configuration
+DcRouter itself is a pure TypeScript orchestrator, but three of its core sub-components ship with **compiled Rust binaries** for performance-critical paths. At runtime each package detects the platform, unpacks the correct binary, and communicates with TypeScript over IPC/FFI — so you get the ergonomics of TypeScript with the throughput of native code.
 
-### Complete Configuration Interface
+| Component | Rust Binary | What It Handles |
+|-----------|-------------|-----------------|
+| **SmartProxy** | `smartproxy-bin` | All TCP/TLS/HTTP proxy networking, NFTables integration, connection metrics |
+| **smartmta** | `mailer-bin` | SMTP server + client, DKIM/SPF/DMARC, content scanning, IP reputation |
+| **SmartDNS** | `smartdns-bin` | DNS server (UDP + DNS-over-HTTPS), DNSSEC, DNS client resolution |
+| **SmartRadius** | — | Pure TypeScript (no Rust component) |
+
+## Configuration Reference
+
+### `IDcRouterOptions`
 
 ```typescript
 interface IDcRouterOptions {
-  // SmartProxy configuration for HTTP/HTTPS/TCP routing
-  smartProxyConfig?: {
-    routes: IRouteConfig[];
-    acme?: IAcmeConfig;
-    allowSessionTicket?: boolean;
+  // ── Traffic Routing ────────────────────────────────────────────
+  /** SmartProxy config for HTTP/HTTPS and TCP/SNI routing */
+  smartProxyConfig?: ISmartProxyOptions;
+
+  // ── Email ──────────────────────────────────────────────────────
+  /** Unified email server configuration (smartmta) */
+  emailConfig?: IUnifiedEmailServerOptions;
+
+  /** Custom email port mapping overrides */
+  emailPortConfig?: {
+    portMapping?: Record<number, number>;
+    portSettings?: Record<number, any>;
+    receivedEmailsPath?: string;
   };
-  
-  // Email system configuration
-  emailConfig?: {
-    ports: number[];
-    hostname: string;
-    domains?: IEmailDomainConfig[];  // Domain infrastructure setup
-    routes: IEmailRoute[];          // Route-based email handling
-    auth?: IAuthConfig;
-    tls?: ITlsConfig;
-    maxMessageSize?: number;
-    rateLimits?: IRateLimitConfig;
-    useSocketHandler?: boolean;     // Enable socket-handler mode (no port binding)
-    defaults?: {                    // Global defaults for all domains
-      dnsMode?: 'forward' | 'internal-dns' | 'external-dns';
-      dkim?: IDkimConfig;
-      rateLimits?: IRateLimitConfig;
-    };
-  };
-  
-  // DNS server configuration
-  dnsServerConfig?: {
-    port?: number;
-    authoritative?: boolean;
-    records?: IDnsRecord[];
+
+  // ── DNS ────────────────────────────────────────────────────────
+  /** Nameserver domains — get A records automatically */
+  dnsNsDomains?: string[];
+  /** Domains this server is authoritative for */
+  dnsScopes?: string[];
+  /** Public IP for NS A records */
+  publicIp?: string;
+  /** Ingress proxy IPs (hides real server IP) */
+  proxyIps?: string[];
+  /** Custom DNS records */
+  dnsRecords?: Array<{
+    name: string;
+    type: 'A' | 'AAAA' | 'CNAME' | 'MX' | 'TXT' | 'NS' | 'SOA';
+    value: string;
+    ttl?: number;
+    useIngressProxy?: boolean;
+  }>;
+
+  // ── RADIUS ─────────────────────────────────────────────────────
+  /** RADIUS server for network authentication */
+  radiusConfig?: {
+    authPort?: number;                   // default: 1812
+    acctPort?: number;                   // default: 1813
+    clients: IRadiusClient[];
+    vlanAssignment?: IVlanManagerConfig;
+    accounting?: { enabled: boolean; retentionDays?: number };
   };
-  
-  // DNS domain for automatic DNS-over-HTTPS setup
-  dnsDomain?: string;               // e.g., 'dns.example.com'
-  
-  // TLS and certificate configuration
+
+  // ── TLS & Certificates ────────────────────────────────────────
   tls?: {
     contactEmail: string;
-    domain: string;
-  };
-  
-  // DNS challenge configuration
-  dnsChallenge?: {
-    cloudflareApiKey: string;
-  };
-  
-  // Storage configuration
-  storage?: {
-    fsPath?: string;                  // Filesystem storage path
-    readFunction?: (key: string) => Promise<string>;    // Custom read function
-    writeFunction?: (key: string, value: string) => Promise<void>;  // Custom write function
+    domain?: string;
+    certPath?: string;
+    keyPath?: string;
   };
-}
-```
+  dnsChallenge?: { cloudflareApiKey?: string };
 
-### Route Configuration
-
-```typescript
-interface IRouteConfig {
-  name: string;
-  priority?: number;
-  match: {
-    domains?: string[];
-    ports?: number | number[] | { from: number; to: number }[];
+  // ── Storage & Caching ─────────────────────────────────────────
+  storage?: {
+    fsPath?: string;
+    readFunction?: (key: string) => Promise<string>;
+    writeFunction?: (key: string, value: string) => Promise<void>;
   };
-  action: {
-    type: 'forward' | 'redirect' | 'serve';
-    target?: {
-      host: string;
-      port: number | 'preserve' | ((context: any) => number);
-    };
-    tls?: {
-      mode: 'terminate' | 'passthrough';
-      certificate?: 'auto' | string;
-    };
-    security?: {
-      ipAllowList?: string[];
-      ipBlockList?: string[];
+  cacheConfig?: {
+    enabled?: boolean;                   // default: true
+    storagePath?: string;                // default: '/etc/dcrouter/tsmdb'
+    dbName?: string;                     // default: 'dcrouter'
+    cleanupIntervalHours?: number;       // default: 1
+    ttlConfig?: {
+      emails?: number;                   // default: 30 days
+      ipReputation?: number;             // default: 1 day
+      bounces?: number;                  // default: 30 days
+      dkimKeys?: number;                 // default: 90 days
+      suppression?: number;              // default: 30 days
     };
   };
 }
 ```
 
-## Socket-Handler Mode
+## HTTP/HTTPS & TCP/SNI Routing
 
-DcRouter supports an advanced socket-handler mode that eliminates internal port binding for both DNS and email services. Instead of services listening on internal ports, SmartProxy passes sockets directly to the services.
+DcRouter uses [SmartProxy](https://code.foss.global/push.rocks/smartproxy) for all HTTP/HTTPS and TCP/SNI routing. Routes are pattern-matched by domain, port, or both.
 
-### DNS Socket-Handler
-
-When `dnsDomain` is configured, DcRouter automatically:
-- Sets up DNS server for UDP on port 53
-- Creates SmartProxy routes for DNS-over-HTTPS (DoH) on the specified domain
-- Uses socket-handler for HTTPS/DoH traffic (no HTTPS port binding)
+### HTTPS with Auto-TLS
 
 ```typescript
-const router = new DcRouter({
-  dnsDomain: 'dns.example.com',    // Enables DNS with DoH
-  smartProxyConfig: {
-    // DNS routes are automatically created
+{
+  name: 'api-gateway',
+  match: { domains: ['api.example.com'], ports: [443] },
+  action: {
+    type: 'forward',
+    targets: [{ host: '192.168.1.20', port: 8080 }],
+    tls: { mode: 'terminate', certificate: 'auto' }
   }
-});
+}
 ```
 
-This creates:
-- UDP DNS service on port 53 (standard DNS queries)
-- HTTPS routes for `dns.example.com/dns-query` and `dns.example.com/resolve`
-- Automatic TLS certificates via Let's Encrypt
-
-### Email Socket-Handler
-
-When `useSocketHandler` is enabled in email config:
-- Email server doesn't bind to any ports
-- SmartProxy passes sockets directly to email handlers
-- Reduces latency and resource usage
+### TLS Passthrough (SNI Routing)
 
 ```typescript
-const router = new DcRouter({
-  emailConfig: {
-    ports: [25, 587, 465],
-    hostname: 'mail.example.com',
-    useSocketHandler: true,         // Enable socket-handler mode
-    routes: [/* email routes */]
+{
+  name: 'secure-backend',
+  match: { domains: ['secure.example.com'], ports: [8443] },
+  action: {
+    type: 'forward',
+    targets: [{ host: '192.168.1.40', port: 8443 }],
+    tls: { mode: 'passthrough' }
   }
-});
+}
 ```
 
-### Benefits of Socket-Handler Mode
-
-1. **Performance**: Eliminates internal port forwarding overhead
-2. **Security**: No exposed internal ports
-3. **Resource Efficiency**: Fewer open ports and listeners
-4. **Simplified Networking**: Direct socket passing
-5. **Automatic Configuration**: Routes created automatically
+### TCP Port Range Forwarding
 
-### Traditional vs Socket-Handler Mode
-
-**Traditional Mode (default):**
-```
-External Port → SmartProxy → Internal Port → Service
-    25             →           10025          → Email
+```typescript
+{
+  name: 'database-cluster',
+  match: { ports: [{ from: 5432, to: 5439 }] },
+  action: {
+    type: 'forward',
+    targets: [{ host: '192.168.1.30', port: 'preserve' }],
+    security: { ipAllowList: ['192.168.1.0/24'] }
+  }
+}
 ```
 
-**Socket-Handler Mode:**
-```
-External Port → SmartProxy → Socket Handler → Service
-    25             →         (direct socket)  → Email
+### HTTP Redirect
+
+```typescript
+{
+  name: 'http-to-https',
+  match: { ports: [80] },
+  action: { type: 'redirect', redirect: { to: 'https://{domain}{path}' } }
+}
 ```
 
 ## Email System
 
-### Email Domain Configuration
+The email system is powered by [`@push.rocks/smartmta`](https://code.foss.global/push.rocks/smartmta), a TypeScript + Rust hybrid MTA. DcRouter configures and orchestrates smartmta's **UnifiedEmailServer**, which handles SMTP sessions, route matching, delivery queuing, DKIM signing, and all email processing.
 
-DcRouter separates email infrastructure (which domains to handle) from routing logic (how to handle emails):
+### Email Domain Configuration
 
-#### **DNS Modes**
+Domains define _infrastructure_ — how DNS and DKIM are handled for each domain:
 
-**Forward Mode** - Simple mail forwarding without local DNS:
+#### Forward Mode
+Simple forwarding without local DNS management:
 ```typescript
 {
   domain: 'forwarded.com',
   dnsMode: 'forward',
-  dns: {
-    forward: {
-      skipDnsValidation: true,
-      targetDomain: 'mail.target.com'
-    }
-  }
+  dns: { forward: { skipDnsValidation: true, targetDomain: 'mail.target.com' } }
 }
 ```
 
-**Internal DNS Mode** - Use built-in DNS server (requires `dnsDomain` in DcRouter config):
+#### Internal DNS Mode
+Uses DcRouter's built-in DNS server (requires `dnsNsDomains` + `dnsScopes`):
 ```typescript
 {
   domain: 'mail.example.com',
   dnsMode: 'internal-dns',
-  dns: {
-    internal: {
-      mxPriority: 10,
-      ttl: 3600
-    }
-  },
-  dkim: {
-    selector: 'mail2024',
-    keySize: 2048,
-    rotateKeys: true,
-    rotationInterval: 90
-  }
+  dns: { internal: { mxPriority: 10, ttl: 3600 } },
+  dkim: { selector: 'mail2024', keySize: 2048, rotateKeys: true, rotationInterval: 90 }
 }
 ```
 
-**External DNS Mode** - Use existing DNS infrastructure:
+#### External DNS Mode
+Uses existing DNS infrastructure with validation:
 ```typescript
 {
   domain: 'mail.external.com',
   dnsMode: 'external-dns',
-  dns: {
-    external: {
-      requiredRecords: ['MX', 'SPF', 'DKIM', 'DMARC']
-    }
-  },
+  dns: { external: { requiredRecords: ['MX', 'SPF', 'DKIM', 'DMARC'] } },
   rateLimits: {
-    inbound: {
-      messagesPerMinute: 100,
-      connectionsPerIp: 10
-    }
+    inbound: { messagesPerMinute: 100, connectionsPerIp: 10 },
+    outbound: { messagesPerMinute: 200 }
   }
 }
 ```
 
-#### **DKIM Management**
-
-DKIM is always enabled for all domains. Keys are automatically:
-- Generated on first use
-- Stored persistently via StorageManager
-- Rotated based on configuration
-- Cleaned up after grace period
-
 ### Email Route Actions
 
-#### **Forward Action**
-Routes emails to external SMTP servers.
+Routes define _behavior_ — what happens when an email matches:
 
+#### Forward 📤
+Routes emails to an external SMTP server:
 ```typescript
 {
   name: 'forward-to-internal',
@@ -433,821 +516,460 @@ Routes emails to external SMTP servers.
     forward: {
       host: 'internal-mail.company.com',
       port: 25,
-      auth: {
-        username: 'relay-user',
-        password: 'relay-pass'
-      },
-      addHeaders: {
-        'X-Forwarded-By': 'dcrouter'
-      }
+      auth: { user: 'relay-user', pass: 'relay-pass' },
+      addHeaders: { 'X-Forwarded-By': 'dcrouter' }
     }
   }
 }
 ```
 
-#### **Process Action**
-Full Mail Transfer Agent functionality with scanning and delivery queues.
-
+#### Process ⚙️
+Full MTA processing with content scanning and delivery queues:
 ```typescript
 {
   name: 'process-notifications',
   match: { recipients: '*@notifications.company.com' },
   action: {
     type: 'process',
-    process: {
-      scan: true,
-      dkim: true,
-      queue: 'priority'
-    }
+    process: { scan: true, dkim: true, queue: 'priority' }
   }
 }
 ```
 
-#### **Deliver Action**
-Local delivery for mailbox storage.
-
+#### Deliver 📥
+Local mailbox delivery:
 ```typescript
 {
   name: 'deliver-local',
-  match: { recipients: '*@marketing.company.com' },
-  action: {
-    type: 'deliver'
-  }
+  match: { recipients: '*@local.company.com' },
+  action: { type: 'deliver' }
 }
 ```
 
-#### **Reject Action**
-Reject emails with custom SMTP responses.
-
+#### Reject 🚫
+Reject with custom SMTP response code:
 ```typescript
 {
-  name: 'reject-spam',
-  match: { 
-    senders: '*@spam-domain.com',
-    sizeRange: { min: 1000000 } // > 1MB
-  },
+  name: 'reject-spam-domain',
+  match: { senders: '*@spam-domain.com', sizeRange: { min: 1000000 } },
   action: {
     type: 'reject',
-    reject: {
-      code: 550,
-      message: 'Message rejected due to policy'
-    }
+    reject: { code: 550, message: 'Message rejected due to policy' }
   }
 }
 ```
 
-### Common Email Routing Patterns
+### Route Matching
 
-#### **IP-Based Relay**
-Allow internal networks to relay through the server:
-```typescript
-{
-  name: 'office-relay',
-  priority: 100,
-  match: { clientIp: ['192.168.0.0/16', '10.0.0.0/8'] },
-  action: {
-    type: 'forward',
-    forward: { host: 'internal-mail.company.com', port: 25 }
-  }
-}
-```
+Routes support powerful matching criteria:
 
-#### **Domain-Based Routing**
-Route different domains to different servers:
 ```typescript
-{
-  name: 'partner-domain',
-  match: { recipients: '*@partner.com' },
-  action: {
-    type: 'forward', 
-    forward: { host: 'partner-mail.com', port: 587 }
-  }
-}
-```
+// Recipient patterns
+match: { recipients: '*@example.com' }           // All addresses at domain
+match: { recipients: 'admin@*' }                 // "admin" at any domain
+match: { senders: ['*@trusted.com', '*@vip.com'] } // Multiple sender patterns
 
-#### **Authentication-Based Processing**
-Different handling for authenticated vs unauthenticated senders:
-```typescript
-{
-  name: 'authenticated-users',
-  match: { authenticated: true },
-  action: {
-    type: 'process',
-    process: { scan: false, dkim: true, queue: 'priority' }
-  }
-},
-{
-  name: 'unauthenticated-reject',
-  match: { authenticated: false },
-  action: {
-    type: 'reject',
-    reject: { code: 550, message: 'Authentication required' }
-  }
-}
-```
+// IP-based matching (CIDR)
+match: { clientIp: '192.168.0.0/16' }
+match: { clientIp: ['10.0.0.0/8', '172.16.0.0/12'] }
 
-#### **Content-Based Filtering**
-Filter based on size, subject, or headers:
-```typescript
-{
-  name: 'large-email-reject',
-  match: { sizeRange: { min: 25000000 } }, // > 25MB
-  action: {
-    type: 'reject',
-    reject: { code: 552, message: 'Message too large' }
-  }
-},
-{
-  name: 'priority-emails',
-  match: { 
-    headers: { 'X-Priority': 'high' },
-    subject: /urgent|emergency/i
-  },
-  action: {
-    type: 'process',
-    process: { queue: 'priority' }
-  }
-}
+// Authentication state
+match: { authenticated: true }
+
+// Header matching
+match: { headers: { 'X-Priority': 'high', 'Subject': /urgent|emergency/i } }
+
+// Size and content
+match: { sizeRange: { min: 1000, max: 5000000 }, hasAttachments: true }
+match: { subject: /invoice|receipt/i }
 ```
 
-### Email Security Features
+### Socket-Handler Mode 🔌
 
-#### **Route Matching Patterns**
+When `useSocketHandler: true` is set, SmartProxy passes sockets directly to the email server — no internal port binding, lower latency, and fewer open ports:
 
-**Glob Pattern Matching**
-```typescript
-// Email address patterns
-match: { recipients: '*@example.com' }        // All addresses at domain
-match: { recipients: 'admin@*' }             // Admin at any domain
-match: { senders: ['*@trusted.com', '*@partner.com'] } // Multiple patterns
+```
+Traditional:  External Port → SmartProxy → Internal Port → Email Server
+Socket Mode:  External Port → SmartProxy → (direct socket) → Email Server
+```
 
-// CIDR IP matching
-match: { clientIp: '192.168.0.0/16' }        // Private subnet
-match: { clientIp: ['10.0.0.0/8', '172.16.0.0/12'] } // Multiple ranges
+### Email Security Stack
 
-// Header matching
-match: { 
-  headers: {
-    'X-Priority': 'high',
-    'Subject': /urgent|emergency/i
-  }
-}
+- **DKIM** — Automatic key generation, signing, and rotation for all domains
+- **SPF** — Sender Policy Framework verification on inbound mail
+- **DMARC** — Domain-based Message Authentication verification
+- **IP Reputation** — Real-time IP reputation checking with caching
+- **Content Scanning** — Spam, virus, and attachment scanning
+- **Rate Limiting** — Hierarchical limits (global → domain → sender)
+- **Bounce Management** — Automatic bounce detection and suppression lists
 
-// Size and content matching
-match: {
-  sizeRange: { min: 1000, max: 5000000 },    // 1KB to 5MB
-  hasAttachments: true,
-  subject: /invoice|receipt/i
-}
-```
+### Email Deliverability
 
-#### **Content Scanning**
-```typescript
-const scanners = [
-  {
-    type: 'spam',
-    threshold: 5.0,
-    action: 'tag',
-    headers: ['X-Spam-Score', 'X-Spam-Status']
-  },
-  {
-    type: 'virus',
-    action: 'reject',
-    quarantine: true
-  },
-  {
-    type: 'attachment',
-    blockedExtensions: ['.exe', '.bat', '.scr'],
-    maxSize: 25 * 1024 * 1024 // 25MB
-  }
-];
-```
+- **IP Warmup Manager** — Multi-stage warmup schedules for new IPs
+- **Sender Reputation Monitor** — Per-domain reputation tracking and scoring
+- **Connection Pooling** — Pooled outbound SMTP connections per destination
 
-## SmartProxy Routing
+## DNS Server
 
-### HTTP/HTTPS Routing
+DcRouter includes an authoritative DNS server built on [smartdns](https://code.foss.global/push.rocks/smartdns). It handles standard UDP DNS on port 53 and DNS-over-HTTPS via SmartProxy socket handler.
 
-```typescript
-const routes = [
-  // API routing with path-based forwarding
-  {
-    name: 'api-gateway',
-    match: {
-      domains: ['api.example.com'],
-      ports: [443]
-    },
-    action: {
-      type: 'forward',
-      target: {
-        host: '192.168.1.20',
-        port: (context) => {
-          // Route based on path
-          if (context.path.startsWith('/v1/')) return 8080;
-          if (context.path.startsWith('/v2/')) return 8081;
-          return 8080;
-        }
-      },
-      tls: {
-        mode: 'terminate',
-        certificate: 'auto'
-      }
-    }
-  },
-  
-  // Static file serving
-  {
-    name: 'static-assets',
-    match: {
-      domains: ['cdn.example.com'],
-      ports: [443]
-    },
-    action: {
-      type: 'serve',
-      root: '/var/www/static',
-      tls: {
-        mode: 'terminate',
-        certificate: 'auto'
-      }
-    }
-  }
-];
-```
+### Enabling DNS
 
-### TCP/SNI Routing
+DNS is activated when both `dnsNsDomains` and `dnsScopes` are configured:
 
 ```typescript
-const tcpRoutes = [
-  // Database connection routing
-  {
-    name: 'database-cluster',
-    match: {
-      ports: [{ from: 5432, to: 5439 }]
-    },
-    action: {
-      type: 'forward',
-      target: {
-        host: '192.168.1.30',
-        port: 'preserve'
-      },
-      security: {
-        ipAllowList: ['192.168.1.0/24']
-      }
-    }
-  },
-  
-  // SNI-based routing for TLS services
-  {
-    name: 'secure-service',
-    match: {
-      domains: ['secure.example.com'],
-      ports: [8443]
-    },
-    action: {
-      type: 'forward',
-      target: {
-        host: '192.168.1.40',
-        port: 8443
-      },
-      tls: {
-        mode: 'passthrough'
-      }
-    }
-  }
-];
+const router = new DcRouter({
+  dnsNsDomains: ['ns1.example.com', 'ns2.example.com'],
+  dnsScopes: ['example.com'],
+  publicIp: '203.0.113.1',
+  dnsRecords: [
+    { name: 'example.com', type: 'A', value: '203.0.113.1' },
+    { name: 'www.example.com', type: 'CNAME', value: 'example.com' },
+    { name: 'example.com', type: 'MX', value: '10:mail.example.com' },
+    { name: 'example.com', type: 'TXT', value: 'v=spf1 a mx ~all' }
+  ]
+});
 ```
 
-## Storage System
+### Automatic DNS Records
 
-### StorageManager
+DcRouter auto-generates:
+- **NS records** for all domains in `dnsScopes`
+- **SOA records** for authoritative zones
+- **A records** for nameserver domains (`dnsNsDomains`)
+- **MX, SPF, DKIM, DMARC records** for email domains with `internal-dns` mode
+- **ACME challenge records** for certificate provisioning
+
+### Ingress Proxy Support
 
-DcRouter includes a flexible storage system that supports multiple backends:
+When `proxyIps` is configured, A records with `useIngressProxy: true` (default) will use the proxy IP instead of the real server IP — hiding your origin:
 
-#### **Filesystem Storage**
 ```typescript
-const router = new DcRouter({
-  storage: {
-    fsPath: '/var/lib/dcrouter/data'
-  }
-});
+{
+  proxyIps: ['198.51.100.1', '198.51.100.2'],
+  dnsRecords: [
+    { name: 'example.com', type: 'A', value: '203.0.113.1' },  // Will resolve to 198.51.100.1
+    { name: 'ns1.example.com', type: 'A', value: '203.0.113.1', useIngressProxy: false }  // Stays real IP
+  ]
+}
 ```
 
-#### **Custom Storage Backend**
+## RADIUS Server
+
+DcRouter includes a RADIUS server for network access control, built on [smartradius](https://code.foss.global/push.rocks/smartradius).
+
+### Configuration
+
 ```typescript
 const router = new DcRouter({
-  storage: {
-    readFunction: async (key) => {
-      // Read from Redis, S3, etc.
-      return await myDatabase.get(key);
+  radiusConfig: {
+    authPort: 1812,
+    acctPort: 1813,
+    clients: [
+      {
+        name: 'core-switch',
+        ipRange: '192.168.1.0/24',
+        secret: 'shared-secret',
+        enabled: true
+      }
+    ],
+    vlanAssignment: {
+      defaultVlan: 100,
+      allowUnknownMacs: true,
+      mappings: [
+        { mac: 'aa:bb:cc:dd:ee:ff', vlan: 10, enabled: true },   // Exact MAC
+        { mac: 'aa:bb:cc', vlan: 20, enabled: true },             // OUI prefix
+      ]
     },
-    writeFunction: async (key, value) => {
-      // Write to Redis, S3, etc.
-      await myDatabase.set(key, value);
+    accounting: {
+      enabled: true,
+      retentionDays: 30
     }
   }
 });
 ```
 
-#### **Memory Storage (Development)**
-```typescript
-const router = new DcRouter({
-  // No storage config = memory storage with warning
-});
-```
-
-### Storage Usage
+### Components
 
-The storage system is used for:
-- **DKIM Keys**: `/email/dkim/{domain}/private.key`, `/email/dkim/{domain}/public.key`
-- **Email Routes**: `/email/routes/{routeId}.json`
-- **Bounce Lists**: `/email/bounces/suppression.json`
-- **IP Reputation**: `/security/ip-reputation/{ip}.json`
-- **Domain Configs**: `/email/domains/{domain}.json`
+| Component | Purpose |
+|-----------|---------|
+| **RadiusServer** | Main RADIUS server handling auth + accounting requests |
+| **VlanManager** | MAC-to-VLAN mapping with exact, OUI, and wildcard patterns |
+| **AccountingManager** | Session tracking, traffic metering, start/stop/interim updates |
 
-### Data Migration
+### OpsServer API
 
-Migrate data between storage backends:
+RADIUS is fully manageable at runtime via the OpsServer API:
+- Client management (add/remove/list NAS devices)
+- VLAN mapping CRUD operations
+- Session monitoring and forced disconnects
+- Accounting summaries and statistics
 
-```typescript
-import { StorageManager } from '@serve.zone/dcrouter';
-
-// Export from filesystem
-const fsStorage = new StorageManager({ fsPath: './data' });
-const keys = await fsStorage.list('/');
-const data = {};
-for (const key of keys) {
-  data[key] = await fsStorage.get(key);
-}
+## Storage & Caching
 
-// Import to cloud storage
-const cloudStorage = new StorageManager({
-  readFunction: cloudRead,
-  writeFunction: cloudWrite
-});
-for (const [key, value] of Object.entries(data)) {
-  await cloudStorage.set(key, value);
-}
-```
-
-## Security Features
+### StorageManager
 
-### IP Reputation Checking
+Provides a unified key-value interface with three backends:
 
 ```typescript
-import { IpReputationChecker } from '@serve.zone/dcrouter';
+// Filesystem backend
+storage: { fsPath: '/var/lib/dcrouter/data' }
 
-const ipChecker = new IpReputationChecker({
-  providers: ['spamhaus', 'barracuda', 'surbl'],
-  cacheTimeout: 3600000, // 1 hour
-  threshold: 0.7
-});
-
-// Check IP reputation
-const result = await ipChecker.checkIp('192.0.2.1');
-if (result.isBlocked) {
-  console.log(`IP blocked: ${result.reason}`);
+// Custom backend (Redis, S3, etc.)
+storage: {
+  readFunction: async (key) => await redis.get(key),
+  writeFunction: async (key, value) => await redis.set(key, value)
 }
-```
-
-### Content Security Scanner
-
-```typescript
-import { ContentScanner } from '@serve.zone/dcrouter';
-
-const scanner = new ContentScanner({
-  spamThreshold: 5.0,
-  virusScanning: true,
-  attachmentFiltering: {
-    maxSize: 25 * 1024 * 1024,
-    blockedTypes: ['.exe', '.bat', '.scr']
-  }
-});
 
-const scanResult = await scanner.scanEmail(email);
+// In-memory (development only — data lost on restart)
+// Simply omit the storage config
 ```
 
-## API Reference
+Used for: DKIM keys, email routes, bounce/suppression lists, IP reputation data, domain configs.
 
-### DcRouter Class
+### Cache Database
+
+An embedded MongoDB-compatible database (via smartdata + LocalTsmDb) for persistent caching with automatic TTL cleanup:
 
-#### Constructor
 ```typescript
-constructor(options: IDcRouterOptions)
+cacheConfig: {
+  enabled: true,
+  storagePath: '/etc/dcrouter/tsmdb',
+  dbName: 'dcrouter',
+  cleanupIntervalHours: 1,
+  ttlConfig: {
+    emails: 30,         // days
+    ipReputation: 1,    // days
+    bounces: 30,        // days
+    dkimKeys: 90,       // days
+    suppression: 30     // days
+  }
+}
 ```
 
-#### Methods
+Cached document types: `CachedEmail`, `CachedIPReputation`.
 
-##### `start(): Promise<void>`
-Starts all configured services (SmartProxy, email server, DNS server).
+## Security Features
 
-##### `stop(): Promise<void>`
-Gracefully stops all services.
+### IP Reputation Checking
 
-##### `updateRoutes(routes: IRouteConfig[]): Promise<void>`
-Updates SmartProxy routes dynamically.
+Automatic IP reputation checks on inbound connections with configurable caching:
 
-##### `updateDomainRules(rules: IDomainRule[]): Promise<void>`
-Updates email domain routing rules.
+```typescript
+// IP reputation is checked automatically for inbound SMTP connections.
+// Results are cached according to cacheConfig.ttlConfig.ipReputation.
+```
 
-##### `getStats(): IStatsResponse`
-Returns real-time statistics for all services.
+### Rate Limiting
 
-### Email Service API
+Hierarchical rate limits with three levels of specificity:
 
-#### `sendEmail(options: IEmailOptions): Promise<string>`
 ```typescript
-const emailId = await router.emailService.sendEmail({
-  from: 'sender@example.com',
-  to: 'recipient@example.com',
-  subject: 'Test Email',
-  html: '<p>Hello World</p>',
-  attachments: []
-});
-```
+// Global defaults (via emailConfig.defaults.rateLimits)
+defaults: {
+  rateLimits: {
+    inbound: { messagesPerMinute: 50, connectionsPerIp: 5, recipientsPerMessage: 50 },
+    outbound: { messagesPerMinute: 100 }
+  }
+}
 
-#### `getEmailStatus(emailId: string): IEmailStatus`
-```typescript
-const status = router.emailService.getEmailStatus(emailId);
-console.log(status.status); // 'pending', 'sent', 'delivered', 'bounced'
+// Per-domain overrides (in domain config)
+{
+  domain: 'high-volume.com',
+  rateLimits: {
+    outbound: { messagesPerMinute: 500 }  // Override for this domain
+  }
+}
 ```
 
-#### `getDeliveryReport(emailId: string): IDeliveryReport`
-Detailed delivery information including bounce reasons and tracking data.
-
-## Examples
+**Precedence**: Domain-specific > Pattern-specific > Global
 
-### Complete Enterprise Setup
+### Content Scanning
 
 ```typescript
-import { DcRouter } from '@serve.zone/dcrouter';
-
-const router = new DcRouter({
-  // HTTP/HTTPS routing
-  smartProxyConfig: {
-    routes: [
-      // Main website
-      {
-        name: 'website',
-        priority: 100,
-        match: { domains: ['example.com', 'www.example.com'], ports: [443] },
-        action: {
-          type: 'forward',
-          target: { host: '192.168.1.10', port: 80 },
-          tls: { mode: 'terminate', certificate: 'auto' }
-        }
-      },
-      
-      // API services
-      {
-        name: 'api',
-        priority: 110,
-        match: { domains: ['api.example.com'], ports: [443] },
-        action: {
-          type: 'forward',
-          target: { host: '192.168.1.20', port: 8080 },
-          tls: { mode: 'terminate', certificate: 'auto' }
-        }
-      },
-      
-      // Internal services
-      {
-        name: 'internal',
-        match: { ports: [{ from: 8000, to: 8999 }] },
-        action: {
-          type: 'forward',
-          target: { host: '192.168.1.30', port: 'preserve' },
-          security: { ipAllowList: ['192.168.0.0/16'] }
-        }
-      }
-    ],
-    
-    // ACME certificate automation
-    acme: {
-      email: 'ssl@example.com',
-      enabled: true,
-      useProduction: true,
-      autoRenew: true
-    }
-  },
-  
-  // Enterprise email system
-  emailConfig: {
-    ports: [25, 587, 465],
-    hostname: 'mail.example.com',
-    
-    // Domain configuration
-    domains: [
-      {
-        domain: 'example.com',
-        dnsMode: 'external-dns',
-        dkim: {
-          selector: 'mail',
-          rotateKeys: true
-        }
-      },
-      {
-        domain: 'notifications.example.com',
-        dnsMode: 'internal-dns',
-        rateLimits: {
-          outbound: { messagesPerHour: 10000 }
-        }
-      }
-    ],
-    
-    // Authentication configuration
-    auth: {
-      required: true,
-      methods: ['PLAIN', 'LOGIN']
-    },
-    
-    // TLS configuration
-    tls: {
-      keyPath: './certs/mail-key.pem',
-      certPath: './certs/mail-cert.pem'
-    },
-    
-    // Email routing rules
-    routes: [
-      // Relay from office network
-      {
-        name: 'office-relay',
-        priority: 100,
-        match: { clientIp: '192.168.0.0/16' },
-        action: {
-          type: 'forward',
-          forward: {
-            host: 'internal-mail.example.com',
-            port: 25
-          }
-        }
-      },
-      
-      // Transactional emails via processing
-      {
-        name: 'notifications',
-        priority: 50,
-        match: { recipients: '*@notifications.example.com' },
-        action: {
-          type: 'process',
-          process: {
-            scan: true,
-            dkim: true,
-            queue: 'priority'
-          }
-        }
-      },
-      
-      // Internal emails forwarded to Exchange
-      {
-        name: 'internal-mail',
-        priority: 25,
-        match: { recipients: '*@example.com' },
-        action: {
-          type: 'forward',
-          forward: {
-            host: 'exchange.internal.example.com',
-            port: 25
-          }
-        }
-      },
-      
-      // Default reject
-      {
-        name: 'default-reject',
-        match: { recipients: '*' },
-        action: {
-          type: 'reject',
-          reject: {
-            code: 550,
-            message: 'Relay denied'
-          }
-        }
-      }
+action: {
+  type: 'process',
+  options: {
+    contentScanning: true,
+    scanners: [
+      { type: 'spam', threshold: 5.0, action: 'tag' },
+      { type: 'virus', action: 'reject' },
+      { type: 'attachment', blockedExtensions: ['.exe', '.bat', '.scr'], action: 'reject' }
     ]
-  },
-  
-  // DNS server for ACME challenges
-  dnsServerConfig: {
-    port: 53,
-    authoritative: true
-  },
-  
-  // Cloudflare DNS challenges
-  dnsChallenge: {
-    cloudflareApiKey: process.env.CLOUDFLARE_API_KEY
-  },
-  
-  // Persistent storage
-  storage: {
-    fsPath: '/var/lib/dcrouter/data'
   }
-});
-
-// Start the router
-await router.start();
-console.log('Enterprise DcRouter started');
-
-// Monitor statistics
-setInterval(() => {
-  const stats = router.getStats();
-  console.log('Active connections:', stats.activeConnections);
-  console.log('Emails processed:', stats.emailsProcessed);
-}, 60000);
+}
 ```
 
-### Email Template System
+## OpsServer Dashboard
 
-```typescript
-import { EmailService, TemplateManager } from '@serve.zone/dcrouter';
-
-// Setup email templates
-const templateManager = new TemplateManager();
-templateManager.addTemplate('welcome', {
-  subject: 'Welcome to {{company}}!',
-  html: `
-    <h1>Welcome {{name}}!</h1>
-    <p>Thank you for joining {{company}}.</p>
-    <p>Your account: {{email}}</p>
-  `,
-  text: 'Welcome {{name}}! Thank you for joining {{company}}.'
-});
+The OpsServer provides a web-based management interface served on port 3000. It's built with modern web components using [@design.estate/dees-catalog](https://code.foss.global/design.estate/dees-catalog).
 
-// Send templated email
-const emailService = new EmailService(router);
-await emailService.sendTemplatedEmail('welcome', {
-  to: 'user@example.com',
-  templateData: {
-    name: 'John Doe',
-    company: 'Example Corp',
-    email: 'user@example.com'
-  }
-});
-```
+### Dashboard Views
 
-## Troubleshooting
+| View | Description |
+|------|-------------|
+| 📊 **Overview** | Real-time server stats, CPU/memory, connection counts, email throughput |
+| 🌐 **Network** | Active connections, top IPs, throughput rates, SmartProxy metrics |
+| 📧 **Email** | Queue monitoring (queued/sent/failed), bounce records, security incidents |
+| 📜 **Logs** | Real-time log viewer with level filtering and search |
+| ⚙️ **Configuration** | Read-only view of current system configuration |
+| 🛡️ **Security** | IP reputation, rate limit status, blocked connections |
 
-### Common Issues
+### API Endpoints
 
-#### Certificate Issues
-```bash
-# Check certificate status
-curl -I https://your-domain.com
+All management is done via TypedRequest over HTTP POST to `/typedrequest`:
 
-# Verify ACME challenge accessibility
-curl http://your-domain.com/.well-known/acme-challenge/test
-```
+```typescript
+// Authentication
+'adminLoginWithUsernameAndPassword'   // Login with credentials → returns JWT identity
+'verifyIdentity'                       // Verify JWT token validity
+'adminLogout'                          // End admin session
 
-#### Email Delivery Issues
-```bash
-# Test SMTP connectivity
-telnet your-server.com 25
+// Statistics & Health
+'getServerStatistics'                  // Uptime, CPU, memory, connections
+'getHealthStatus'                      // System health check
+'getCombinedMetrics'                   // All metrics in one call
+
+// Email Operations
+'getQueuedEmails'                      // Emails pending delivery
+'getSentEmails'                        // Successfully delivered emails
+'getFailedEmails'                      // Failed emails
+'resendEmail'                          // Re-queue a failed email
+'getBounceRecords'                     // Bounce records
+'removeFromSuppressionList'            // Unsuppress an address
+
+// Configuration (read-only)
+'getConfiguration'                     // Current system config
 
-# Check DKIM record
-dig TXT mail._domainkey.your-domain.com
+// Logs
+'getLogs'                              // Retrieve system logs
 
-# Verify SPF record
-dig TXT your-domain.com
+// RADIUS
+'getRadiusSessions'                    // Active RADIUS sessions
+'getRadiusClients'                     // List NAS clients
+'getRadiusStatistics'                  // RADIUS stats
+'setRadiusClient'                      // Add/update NAS client
+'removeRadiusClient'                   // Remove NAS client
+'getVlanMappings'                      // List VLAN mappings
+'setVlanMapping'                       // Add/update VLAN mapping
+'removeVlanMapping'                    // Remove VLAN mapping
+'testVlanAssignment'                   // Test what VLAN a MAC gets
 ```
 
-#### Email Routing Issues
+## API Reference
 
-**Route Not Matching**
-- Check route priority order (higher priority = evaluated first)
-- Verify glob patterns: `*@example.com` matches domain, `admin@*` matches user
-- Test CIDR notation: `192.168.0.0/16` includes all 192.168.x.x addresses
-- Confirm authentication state matches your expectations
+### DcRouter Class
 
-**Common Route Patterns**
 ```typescript
-// Debug route to log all traffic
-{
-  name: 'debug-all',
-  priority: 1000,
-  match: { recipients: '*' },
-  action: { type: 'process', process: { scan: false } }
-}
+import { DcRouter } from '@serve.zone/dcrouter';
 
-// Catch-all reject (should be lowest priority)
-{
-  name: 'default-reject',
-  priority: 0,
-  match: { recipients: '*' },
-  action: { type: 'reject', reject: { code: 550, message: 'No route' } }
-}
+const router = new DcRouter(options: IDcRouterOptions);
 ```
 
-#### DNS Issues
-```bash
-# Test DNS server
-dig @your-server.com your-domain.com
-
-# Check DNS propagation
-dig your-domain.com @8.8.8.8
-```
+#### Methods
 
-### Logging and Monitoring
+| Method | Description |
+|--------|-------------|
+| `start(): Promise<void>` | Start all configured services |
+| `stop(): Promise<void>` | Gracefully stop all services |
+| `updateSmartProxyConfig(config): Promise<void>` | Hot-update SmartProxy routes |
+| `updateEmailConfig(config): Promise<void>` | Hot-update email configuration |
+| `updateEmailRoutes(routes): Promise<void>` | Update email routing rules at runtime |
+| `updateRadiusConfig(config): Promise<void>` | Hot-update RADIUS configuration |
+| `getStats(): any` | Get real-time statistics from all services |
 
-```typescript
-import { SmartLog } from '@push.rocks/smartlog';
+#### Properties
 
-// Configure logging
-const logger = new SmartLog({
-  level: 'info',
-  transport: 'console'
-});
+| Property | Type | Description |
+|----------|------|-------------|
+| `options` | `IDcRouterOptions` | Current configuration |
+| `smartProxy` | `SmartProxy` | SmartProxy instance |
+| `emailServer` | `UnifiedEmailServer` | Email server instance (from smartmta) |
+| `dnsServer` | `DnsServer` | DNS server instance |
+| `radiusServer` | `RadiusServer` | RADIUS server instance |
+| `storageManager` | `StorageManager` | Storage backend |
+| `opsServer` | `OpsServer` | OpsServer/dashboard instance |
+| `metricsManager` | `MetricsManager` | Metrics collector |
+| `cacheDb` | `CacheDb` | Cache database instance |
 
-// Monitor email events
-router.emailServer.on('emailReceived', (email) => {
-  logger.log('info', `Email received: ${email.from} -> ${email.to}`);
-});
+### Re-exported Types
 
-router.emailServer.on('emailSent', (result) => {
-  logger.log('info', `Email sent: ${result.messageId} (${result.status})`);
-});
+DcRouter re-exports key types from smartmta for convenience:
 
-// Monitor proxy events
-router.smartProxy.on('connectionEstablished', (connection) => {
-  logger.log('info', `Connection: ${connection.clientIp} -> ${connection.target}`);
-});
+```typescript
+import {
+  DcRouter,
+  IDcRouterOptions,
+  UnifiedEmailServer,
+  type IUnifiedEmailServerOptions,
+  type IEmailRoute,
+  type IEmailDomainConfig,
+} from '@serve.zone/dcrouter';
 ```
 
-### Performance Tuning
+## Sub-Modules
+
+DcRouter is published as a monorepo with separately-installable interface and web packages:
+
+| Package | Description | Install |
+|---------|-------------|---------|
+| [`@serve.zone/dcrouter`](https://www.npmjs.com/package/@serve.zone/dcrouter) | Main package — the full router | `pnpm add @serve.zone/dcrouter` |
+| [`@serve.zone/dcrouter-interfaces`](https://www.npmjs.com/package/@serve.zone/dcrouter-interfaces) | TypedRequest interfaces for the OpsServer API | `pnpm add @serve.zone/dcrouter-interfaces` |
+| [`@serve.zone/dcrouter-web`](https://www.npmjs.com/package/@serve.zone/dcrouter-web) | Web dashboard components | `pnpm add @serve.zone/dcrouter-web` |
+
+You can also import interfaces directly from the main package:
 
 ```typescript
-const performanceConfig = {
-  // Connection limits
-  maxConnections: 1000,
-  connectionTimeout: 30000,
-  
-  // Email queue settings
-  emailQueue: {
-    concurrency: 10,
-    maxRetries: 3,
-    retryDelay: 300000
-  },
-  
-  // Cache settings
-  cache: {
-    ipReputation: { ttl: 3600000 }, // 1 hour
-    dns: { ttl: 300000 }, // 5 minutes
-    certificates: { ttl: 86400000 } // 24 hours
-  }
-};
+import { data, requests } from '@serve.zone/dcrouter/interfaces';
 ```
 
-## License
+## Testing
 
-MIT License - see LICENSE file for details.
+DcRouter includes a comprehensive test suite covering all system components:
 
-## Testing
+```bash
+# Run all tests (10 files, 73 tests)
+pnpm test
 
-### Comprehensive Test Suite
+# Run a specific test file
+tstest test/test.jwt-auth.ts --verbose
 
-DcRouter includes a comprehensive test suite covering all aspects of the system:
+# Run with extended timeout
+tstest test/test.opsserver-api.ts --verbose --timeout 60
+```
 
-#### SMTP Protocol Tests
-- **Commands**: EHLO, HELO, MAIL FROM, RCPT TO, DATA, RSET, NOOP, QUIT, VRFY, EXPN, HELP
-- **Extensions**: SIZE, PIPELINING, STARTTLS
-- **Connection Management**: TLS/plain connections, timeouts, limits, rejection handling
-- **Error Handling**: Syntax errors, invalid sequences, temporary/permanent failures
-- **Email Processing**: Basic sending, multiple recipients, large emails, invalid addresses
-- **Security**: Authentication, rate limiting
-- **Performance**: Throughput testing
-- **Edge Cases**: Very large emails, special characters
+### Test Coverage
 
-#### Storage and Configuration Tests
-- **Storage Manager**: All backend types (filesystem, custom, memory)
-- **Integration**: Component storage usage and persistence
-- **DNS Validation**: All DNS modes (forward, internal, external)
-- **DNS Mode Switching**: Dynamic configuration changes
-- **Data Migration**: Moving data between storage backends
+| Test File | Area | Tests |
+|-----------|------|-------|
+| `test.contentscanner.ts` | Content scanning (spam, phishing, malware, attachments) | 13 |
+| `test.dcrouter.email.ts` | Email config, domain and route setup | 4 |
+| `test.dns-server-config.ts` | DNS record parsing, grouping, extraction | 5 |
+| `test.dns-socket-handler.ts` | DNS socket handler and route generation | 6 |
+| `test.errors.ts` | Error classes, handler, retry utilities | 5 |
+| `test.ipreputationchecker.ts` | IP reputation, DNSBL, caching, risk classification | 10 |
+| `test.jwt-auth.ts` | JWT login, verification, logout, invalid credentials | 8 |
+| `test.opsserver-api.ts` | Health, statistics, configuration, log APIs | 6 |
+| `test.protected-endpoint.ts` | Admin auth, identity verification, public endpoints | 8 |
+| `test.storagemanager.ts` | Memory, filesystem, custom backends, concurrency | 8 |
 
-#### Running Tests
+## License and Legal Information
 
-```bash
-# Run all tests
-pnpm test
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
 
-# Run specific test categories
-tsx test/suite/commands/test.ehlo-command.ts
-tsx test/suite/connection/test.tls-connection.ts
-tsx test/suite/email-processing/test.basic-email.ts
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
-# Run with verbose output
-tstest test/suite/security/test.authentication.ts --verbose
-```
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
 
-### Test Infrastructure
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
 
-The test suite uses a self-contained pattern where each test:
-1. Starts its own SMTP server instance
-2. Runs comprehensive test scenarios
-3. Cleans up all resources
-4. Provides detailed logging for debugging
+### Company Information
 
-This ensures tests are isolated, reliable, and can run in parallel.
+Task Venture Capital GmbH
+Registered at District Court Bremen HRB 35230 HB, Germany
 
-## Support
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 
-- Documentation: [https://docs.serve.zone/dcrouter](https://docs.serve.zone/dcrouter)
-- Issues: [https://github.com/serve-zone/dcrouter/issues](https://github.com/serve-zone/dcrouter/issues)
-- Community: [https://community.serve.zone](https://community.serve.zone)
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.