diff --git a/changelog.md b/changelog.md index a8465c2..6420977 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,14 @@ # Changelog +## 2026-02-12 - 5.0.2 - fix(docs) +update documentation and packaging configuration: document smartmta/smartdns integrations, adjust API method names, and add release registry info + +- README: document SmartDNS as Rust-powered DNS engine and smartmta as TypeScript+Rust MTA; add Rust-powered architecture section and component package table +- README: update Node.js requirement from 18+ to 20+; replace embedded cache DB TsmDb with LocalTsmDb and reduce listed cached document types +- README & ts_interfaces: rename typedrequest API adminLogin -> adminLoginWithUsernameAndPassword and add/clarify several API methods (logout, suppression management, RADIUS client/VLAN helpers) +- README: update test instructions, change test file references and add a test coverage table +- npmextra.json: re-key package configs (@git.zone/cli, @ship.zone/szci), tidy watch array formatting, and add release.registries and accessLevel for publishing + ## 2026-02-11 - 5.0.1 - fix(deps/tests) bump two dependencies and disable cache in tests diff --git a/npmextra.json b/npmextra.json index 61cb9aa..6a1a2a1 100644 --- a/npmextra.json +++ b/npmextra.json @@ -3,7 +3,11 @@ "watchers": [ { "name": "dcrouter-dev", - "watch": ["ts/**/*.ts", "ts_*/**/*.ts", "test_watch/devserver.ts"], + "watch": [ + "ts/**/*.ts", + "ts_*/**/*.ts", + "test_watch/devserver.ts" + ], "command": "pnpm run build && tsrun test_watch/devserver.ts", "restart": true, "debounce": 500, @@ -22,7 +26,7 @@ } ] }, - "gitzone": { + "@git.zone/cli": { "projectType": "service", "module": { "githost": "gitlab.com", @@ -53,9 +57,16 @@ "SMTP STARTTLS", "DNS management" ] + }, + "release": { + "registries": [ + "https://verdaccio.lossless.digital", + "https://registry.npmjs.org" + ], + "accessLevel": "public" } }, - "npmci": { + "@ship.zone/szci": { "npmGlobalTools": [], "dockerRegistryRepoMap": { "registry.gitlab.com": "code.foss.global/serve.zone/dcrouter" diff --git a/readme.md b/readme.md index ded34c3..d8ab042 100644 --- a/readme.md +++ b/readme.md @@ -34,10 +34,10 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community ### 🌐 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** with authoritative zones, dynamic record management, and DNS-over-HTTPS +- **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) -### 📧 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 four action types: forward, process, deliver, reject - **DKIM signing & verification**, SPF, DMARC authentication stack @@ -59,14 +59,16 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community ### ⚡ 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 + TsmDb (MongoDB-compatible) -- **Automatic TTL-based cleanup** for cached emails, IP reputation, DKIM keys, and more +- **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 @@ -84,7 +86,7 @@ npm install @serve.zone/dcrouter ### Prerequisites -- **Node.js 18+** with ES module support +- **Node.js 20+** with ES module support - Valid domain with DNS control (for ACME certificate automation) - Cloudflare API token (for DNS-01 challenges) — optional @@ -172,7 +174,7 @@ const router = new DcRouter({ acme: { email: 'ssl@example.com', enabled: true, useProduction: true } }, - // Email system + // Email system (powered by smartmta) emailConfig: { ports: [25, 587, 465], hostname: 'mail.example.com', @@ -244,10 +246,10 @@ graph TB subgraph "DcRouter Core" DC[DcRouter Orchestrator] - SP[SmartProxy Engine] - ES[Unified Email Server] - DS[DNS Server] - RS[RADIUS Server] + SP[SmartProxy Engine
Rust-powered] + ES[smartmta Email Server
TypeScript + Rust] + DS[SmartDNS Server
Rust-powered] + RS[SmartRadius Server] CM[Certificate Manager] OS[OpsServer Dashboard] MM[Metrics Manager] @@ -289,17 +291,36 @@ graph TB ### Core Components -| Component | Description | -|-----------|-------------| -| **DcRouter** | Central orchestrator — starts, stops, and coordinates all services | -| **SmartProxy** | High-performance HTTP/HTTPS and TCP/SNI proxy with route-based config | -| **UnifiedEmailServer** | Full SMTP server with pattern-based routing, DKIM, queue management | -| **DNS Server** | Authoritative DNS with dynamic records, DKIM TXT auto-generation | -| **RADIUS Server** | Network authentication with MAB, VLAN assignment, and accounting | -| **OpsServer** | Web dashboard + TypedRequest API for monitoring and management | -| **MetricsManager** | Real-time metrics collection (CPU, memory, email, DNS, security) | -| **StorageManager** | Pluggable key-value storage (filesystem, custom, or in-memory) | -| **CacheDb** | Embedded MongoDB-compatible database for persistent caching | +| 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 + +DcRouter acts purely as an **orchestrator** — it doesn't implement protocols itself. Instead, it wires together best-in-class packages for each protocol: + +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. + +### Rust-Powered Architecture + +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. + +| 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 @@ -312,22 +333,8 @@ interface IDcRouterOptions { smartProxyConfig?: ISmartProxyOptions; // ── Email ────────────────────────────────────────────────────── - /** Unified email server configuration */ - emailConfig?: { - ports: number[]; // e.g. [25, 587, 465] - hostname: string; // e.g. 'mail.example.com' - domains: IEmailDomainConfig[]; // Domain infrastructure - routes: IEmailRoute[]; // Routing rules - useSocketHandler?: boolean; // Direct socket passing (no port binding) - auth?: { required?: boolean; methods?: ('PLAIN'|'LOGIN'|'OAUTH2')[]; users?: Array<{username: string; password: string}> }; - tls?: { certPath?: string; keyPath?: string; caPath?: string }; - maxMessageSize?: number; - defaults?: { - dnsMode?: 'forward' | 'internal-dns' | 'external-dns'; - dkim?: IEmailDomainConfig['dkim']; - rateLimits?: IEmailDomainConfig['rateLimits']; - }; - }; + /** Unified email server configuration (smartmta) */ + emailConfig?: IUnifiedEmailServerOptions; /** Custom email port mapping overrides */ emailPortConfig?: { @@ -338,9 +345,9 @@ interface IDcRouterOptions { // ── DNS ──────────────────────────────────────────────────────── /** Nameserver domains — get A records automatically */ - dnsNsDomains?: string[]; // e.g. ['ns1.example.com', 'ns2.example.com'] + dnsNsDomains?: string[]; /** Domains this server is authoritative for */ - dnsScopes?: string[]; // e.g. ['example.com'] + dnsScopes?: string[]; /** Public IP for NS A records */ publicIp?: string; /** Ingress proxy IPs (hides real server IP) */ @@ -453,7 +460,7 @@ DcRouter uses [SmartProxy](https://code.foss.global/push.rocks/smartproxy) for a ## Email System -The email system is built around the **UnifiedEmailServer**, which handles SMTP sessions, route matching, delivery queuing, DKIM signing, and all email processing in a single unified component. +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. ### Email Domain Configuration @@ -722,7 +729,7 @@ Used for: DKIM keys, email routes, bounce/suppression lists, IP reputation data, ### Cache Database -An embedded MongoDB-compatible database (via smartdata + TsmDb) for persistent caching with automatic TTL cleanup: +An embedded MongoDB-compatible database (via smartdata + LocalTsmDb) for persistent caching with automatic TTL cleanup: ```typescript cacheConfig: { @@ -740,7 +747,7 @@ cacheConfig: { } ``` -Cached document types: `CachedEmail`, `CachedIPReputation`, `CachedBounce`, `CachedSuppression`, `CachedDKIMKey`. +Cached document types: `CachedEmail`, `CachedIPReputation`. ## Security Features @@ -814,31 +821,39 @@ All management is done via TypedRequest over HTTP POST to `/typedrequest`: ```typescript // Authentication -{ method: 'adminLogin', data: { username, password } } -{ method: 'verifyIdentity', data: { identity } } +'adminLoginWithUsernameAndPassword' // Login with credentials → returns JWT identity +'verifyIdentity' // Verify JWT token validity +'adminLogout' // End admin session -// Statistics -{ method: 'getServerStatistics', data: { identity } } -{ method: 'getCombinedMetrics', data: { identity } } -{ method: 'getHealthStatus', data: { identity } } +// Statistics & Health +'getServerStatistics' // Uptime, CPU, memory, connections +'getHealthStatus' // System health check +'getCombinedMetrics' // All metrics in one call // Email Operations -{ method: 'getQueuedEmails', data: { identity } } -{ method: 'getSentEmails', data: { identity } } -{ method: 'getFailedEmails', data: { identity } } -{ method: 'resendEmail', data: { identity, emailId } } -{ method: 'getBounceRecords', data: { identity } } +'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) -{ method: 'getConfiguration', data: { identity } } +'getConfiguration' // Current system config // Logs -{ method: 'getLogs', data: { identity, level, limit } } +'getLogs' // Retrieve system logs // RADIUS -{ method: 'getRadiusSessions', data: { identity } } -{ method: 'getRadiusClients', data: { identity } } -{ method: 'getRadiusStatistics', data: { identity } } +'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 ``` ## API Reference @@ -869,7 +884,7 @@ const router = new DcRouter(options: IDcRouterOptions); |----------|------|-------------| | `options` | `IDcRouterOptions` | Current configuration | | `smartProxy` | `SmartProxy` | SmartProxy instance | -| `emailServer` | `UnifiedEmailServer` | Email server instance | +| `emailServer` | `UnifiedEmailServer` | Email server instance (from smartmta) | | `dnsServer` | `DnsServer` | DNS server instance | | `radiusServer` | `RadiusServer` | RADIUS server instance | | `storageManager` | `StorageManager` | Storage backend | @@ -877,6 +892,21 @@ const router = new DcRouter(options: IDcRouterOptions); | `metricsManager` | `MetricsManager` | Metrics collector | | `cacheDb` | `CacheDb` | Cache database instance | +### Re-exported Types + +DcRouter re-exports key types from smartmta for convenience: + +```typescript +import { + DcRouter, + IDcRouterOptions, + UnifiedEmailServer, + type IUnifiedEmailServerOptions, + type IEmailRoute, + type IEmailDomainConfig, +} from '@serve.zone/dcrouter'; +``` + ## Sub-Modules DcRouter is published as a monorepo with separately-installable interface and web packages: @@ -895,31 +925,34 @@ import { data, requests } from '@serve.zone/dcrouter/interfaces'; ## Testing -DcRouter includes a comprehensive test suite with **198 test files** covering all system components: - -- **SMTP Protocol** — EHLO, MAIL FROM, RCPT TO, DATA, STARTTLS, AUTH, pipelining -- **Email Routing** — Pattern matching, route priorities, all action types -- **Email Security** — DKIM, SPF, DMARC, content scanning, rate limiting -- **DNS** — Record management, socket handler, validation, mode switching -- **RADIUS** — Authentication, VLAN assignment, accounting -- **Deliverability** — IP warmup, reputation monitoring, bounce management -- **Storage & Cache** — All backends, TTL cleanup, persistence -- **OpsServer** — API authentication, protected endpoints, statistics -- **Integration** — Full end-to-end workflows - -### Running Tests +DcRouter includes a comprehensive test suite covering all system components: ```bash -# Run all tests +# Run all tests (10 files, 73 tests) pnpm test # Run a specific test file -tstest test/test.email.router.ts --verbose +tstest test/test.jwt-auth.ts --verbose -# Run SMTP protocol suite -tstest test/suite/smtpserver_commands/test.cmd-01.ehlo-command.ts --verbose +# Run with extended timeout +tstest test/test.opsserver-api.ts --verbose --timeout 60 ``` +### Test Coverage + +| 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 | + ## License and Legal Information This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file. diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index 9573a30..e3a6d02 100644 --- a/ts/00_commitinfo_data.ts +++ b/ts/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@serve.zone/dcrouter', - version: '5.0.1', + version: '5.0.2', description: 'A multifaceted routing service handling mail and SMS delivery functions.' } diff --git a/ts_interfaces/readme.md b/ts_interfaces/readme.md index 60f1312..67a6e38 100644 --- a/ts_interfaces/readme.md +++ b/ts_interfaces/readme.md @@ -89,7 +89,7 @@ TypedRequest interfaces for the OpsServer API, organized by domain: #### 🔐 Authentication | Interface | Method | Description | |-----------|--------|-------------| -| `IReq_AdminLoginWithUsernameAndPassword` | `adminLogin` | Authenticate as admin | +| `IReq_AdminLoginWithUsernameAndPassword` | `adminLoginWithUsernameAndPassword` | Authenticate as admin | | `IReq_AdminLogout` | `adminLogout` | End admin session | | `IReq_VerifyIdentity` | `verifyIdentity` | Verify JWT token validity | diff --git a/ts_web/00_commitinfo_data.ts b/ts_web/00_commitinfo_data.ts index 9573a30..e3a6d02 100644 --- a/ts_web/00_commitinfo_data.ts +++ b/ts_web/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@serve.zone/dcrouter', - version: '5.0.1', + version: '5.0.2', description: 'A multifaceted routing service handling mail and SMS delivery functions.' }