@push.rocks/smartdns 7.5.1 → 7.8.0

package/readme.md

@@ -1,218 +1,253 @@
 # @push.rocks/smartdns
 
-A robust TypeScript library providing advanced DNS management and resolution capabilities including support for DNSSEC, custom DNS servers, and integration with various DNS providers.
+A TypeScript-first DNS toolkit powered by high-performance Rust binaries — covering everything from simple record lookups to running a full authoritative DNS server with DNSSEC, DNS-over-HTTPS, and automatic Let's Encrypt certificates.
 
-## Install
+## 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.
 
-To install `@push.rocks/smartdns`, use the following command with pnpm:
+## Install
 
 ```bash
-pnpm install @push.rocks/smartdns --save
+pnpm install @push.rocks/smartdns
 ```
 
-Or with npm:
+## Architecture at a Glance 🏗️
 
-```bash
-npm install @push.rocks/smartdns --save
-```
+smartdns ships as **three entry points** that you can import independently:
 
-Make sure you have a TypeScript environment set up to utilize the library effectively.
+| Entry point | What it does |
+|---|---|
+| `@push.rocks/smartdns/client` | DNS resolution & record queries (UDP, DoH, system resolver) |
+| `@push.rocks/smartdns/server` | Full DNS server — UDP, DoH, DNSSEC, ACME |
+| `@push.rocks/smartdns` | Convenience re-export of both modules |
 
-## Usage
+Both the **client** and the **server** delegate performance-critical work to compiled **Rust binaries** that ship with the package:
 
-`@push.rocks/smartdns` is a comprehensive library that provides both DNS client and server capabilities, leveraging TypeScript for enhanced development experience. The library is organized into three modules:
+- **`rustdns`** — The server binary: network I/O, packet parsing, DNSSEC signing
+- **`rustdns-client`** — The client binary: UDP wire-format queries, RFC 8484 DoH resolution
 
-- **Client Module** (`@push.rocks/smartdns/client`): DNS resolution and record queries
-- **Server Module** (`@push.rocks/smartdns/server`): Full DNS server implementation with DNSSEC
-- **Main Module** (`@push.rocks/smartdns`): Convenience exports for both client and server
+TypeScript retains the public API, handler registration, ACME orchestration, and strategy routing. Communication between TypeScript and Rust happens over stdin/stdout JSON IPC via [`@push.rocks/smartrust`](https://code.foss.global/push.rocks/smartrust).
 
-### Getting Started
+```
+                          ┌─────────────────────────┐
+                          │    Your Application      │
+                          └────────┬────────────────┘
+                                   │
+              ┌────────────────────┼─────────────────────┐
+              ▼                                          ▼
+   ┌──────────────────┐                      ┌──────────────────┐
+   │  Smartdns Client  │                      │    DnsServer      │
+   │  (TypeScript API) │                      │  (TypeScript API) │
+   └────────┬─────────┘                      └────────┬─────────┘
+            │                                          │
+    ┌───────┼────────┐                     ┌───────────┤
+    ▼       ▼        ▼                     ▼           ▼
+ system   Rust     Rust              Rust binary    TS Handlers
+ (Node)   UDP      DoH              (rustdns)      (minimatch)
+           │        │                    │
+           ▼        ▼                    ▼
+      rustdns-client              UDP / HTTPS listeners
+      (IPC binary)               DNSSEC signing
+```
 
-You can import the modules based on your needs:
+## Usage
+
+### Quick Start
 
 ```typescript
-// For DNS client operations
+// DNS client — resolve records
 import { Smartdns } from '@push.rocks/smartdns/client';
 
-// For DNS server operations
-import { DnsServer } from '@push.rocks/smartdns/server';
+const dns = new Smartdns({});
+const records = await dns.getRecordsA('example.com');
+console.log(records);
 
-// Or import from the main module (note the different syntax)
-import { dnsClientMod, dnsServerMod } from '@push.rocks/smartdns';
-const dnsClient = new dnsClientMod.Smartdns({});
-const dnsServer = new dnsServerMod.DnsServer({ /* options */ });
-```
+// DNS server — serve records
+import { DnsServer } from '@push.rocks/smartdns/server';
 
-### DNS Client Operations
+const server = new DnsServer({
+  udpPort: 5333,
+  httpsPort: 8443,
+  httpsKey: '...pem...',
+  httpsCert: '...pem...',
+  dnssecZone: 'example.com',
+});
 
-The DNS client (`Smartdns` class) provides methods to query various DNS record types using DNS-over-HTTPS (DoH) with Cloudflare as the primary provider, with fallback to Node.js DNS resolver.
+server.registerHandler('*.example.com', ['A'], (question) => ({
+  name: question.name,
+  type: 'A',
+  class: 'IN',
+  ttl: 300,
+  data: '192.168.1.100',
+}));
 
-#### Fetching A Records
+await server.start();
+```
 
-To fetch "A" records (IPv4 addresses) for a domain:
+Or import from the unified entry point:
 
 ```typescript
-import { Smartdns } from '@push.rocks/smartdns/client';
+import { dnsClientMod, dnsServerMod } from '@push.rocks/smartdns';
 
-const dnsClient = new Smartdns({});
-const aRecords = await dnsClient.getRecordsA('example.com');
-console.log(aRecords);
-// Output: [{ name: 'example.com', type: 'A', dnsSecEnabled: false, value: '93.184.215.14' }]
+const client = new dnsClientMod.Smartdns({});
+const server = new dnsServerMod.DnsServer({ /* ... */ });
 ```
 
-#### Fetching AAAA Records
-
-For resolving a domain to IPv6 addresses:
+---
 
-```typescript
-const aaaaRecords = await dnsClient.getRecordsAAAA('example.com');
-console.log(aaaaRecords);
-// Output: [{ name: 'example.com', type: 'AAAA', dnsSecEnabled: false, value: '2606:2800:21f:cb07:6820:80da:af6b:8b2c' }]
-```
+## 🔍 DNS Client
 
-#### Fetching TXT Records
+The `Smartdns` class resolves DNS records using a configurable strategy that combines the system resolver, raw UDP queries, and DNS-over-HTTPS — all backed by a Rust binary for the wire-format transports.
 
-TXT records store text data, commonly used for domain verification, SPF records, and other metadata:
+### Constructor Options
 
 ```typescript
-const txtRecords = await dnsClient.getRecordsTxt('example.com');
-console.log(txtRecords);
-// Output: [{ name: 'example.com', type: 'TXT', dnsSecEnabled: false, value: 'v=spf1 -all' }]
+interface ISmartDnsConstructorOptions {
+  strategy?: 'doh' | 'udp' | 'system' | 'prefer-system' | 'prefer-udp'; // default: 'prefer-system'
+  allowDohFallback?: boolean; // fallback to DoH when system fails (default: true)
+  timeoutMs?: number; // per-query timeout in milliseconds
+}
 ```
 
-#### Other Record Types
+### Resolution Strategies
+
+| Strategy | Behavior |
+|---|---|
+| `prefer-system` | 🏠 Try the OS resolver first, fall back to Rust DoH. Honors `/etc/hosts`. |
+| `system` | 🏠 Use only the Node.js system resolver. No Rust binary needed. |
+| `doh` | 🌐 Use only DNS-over-HTTPS (RFC 8484 wire format via Cloudflare). Rust-powered. |
+| `udp` | ⚡ Use only raw UDP queries to upstream resolver (Cloudflare 1.1.1.1). Rust-powered. |
+| `prefer-udp` | ⚡ Try Rust UDP first, fall back to Rust DoH if UDP fails. |
 
-The client supports various other DNS record types:
+The Rust binary (`rustdns-client`) is spawned **lazily** — only on the first query that needs it. This means `system`-only usage incurs zero Rust overhead.
+
+### Querying Records
 
 ```typescript
-// MX records for mail servers
-const mxRecords = await dnsClient.getRecords('example.com', 'MX');
+const dns = new Smartdns({ strategy: 'prefer-udp' });
+
+// Type-specific helpers
+const aRecords    = await dns.getRecordsA('example.com');
+const aaaaRecords = await dns.getRecordsAAAA('example.com');
+const txtRecords  = await dns.getRecordsTxt('example.com');
 
-// NS records for nameservers
-const nsRecords = await dnsClient.getNameServers('example.com');
+// Generic query — supports A, AAAA, CNAME, MX, TXT, NS, SOA, PTR, SRV
+const mxRecords = await dns.getRecords('example.com', 'MX');
 
-// Generic query method with retry support
-const records = await dnsClient.getRecords('example.com', 'CNAME', { retryCount: 3 });
+// Nameserver lookup
+const nameservers = await dns.getNameServers('example.com');
 ```
 
-### Advanced DNS Features
+Every query returns an array of `IDnsRecord`:
 
-#### Checking DNS Propagation
+```typescript
+interface IDnsRecord {
+  name: string;
+  type: string;          // 'A', 'AAAA', 'TXT', 'MX', etc.
+  dnsSecEnabled: boolean; // true if upstream AD flag was set
+  value: string;
+}
+```
 
-The client provides a powerful method to verify DNS propagation globally, essential when making DNS changes:
+### DNSSEC Detection 🔐
+
+When using `doh`, `udp`, or `prefer-udp` strategies, the Rust binary sends queries with the EDNS0 DO (DNSSEC OK) bit set and reports the AD (Authenticated Data) flag from the upstream response:
 
 ```typescript
-// Check if a specific DNS record has propagated
-const recordType = 'TXT';
-const expectedValue = 'verification=abc123';
+const dns = new Smartdns({ strategy: 'udp' });
+const records = await dns.getRecordsA('cloudflare.com');
+console.log(records[0].dnsSecEnabled); // true — upstream validated DNSSEC
+```
 
-const isAvailable = await dnsClient.checkUntilAvailable(
+### Checking DNS Propagation
+
+Wait for a specific record to appear — essential after making DNS changes:
+
+```typescript
+const propagated = await dns.checkUntilAvailable(
   'example.com',
-  recordType,
-  expectedValue,
-  50,    // Number of check cycles (default: 50)
-  500    // Interval between checks in ms (default: 500)
+  'TXT',
+  'verification=abc123',
+  50,   // max check cycles (default: 50)
+  500   // interval in ms (default: 500)
 );
 
-if (isAvailable) {
-  console.log('DNS record has propagated successfully!');
-} else {
-  console.log('DNS propagation timeout - record not found.');
+if (propagated) {
+  console.log('Record is live!');
 }
 ```
 
-#### Configuring System DNS Provider
+The method alternates between system resolver and the configured strategy on each cycle for maximum coverage.
+
+### Configuring the System DNS Provider
 
-You can configure Node.js to use a specific DNS provider for all DNS queries:
+Override the global Node.js DNS resolver for all subsequent lookups:
 
 ```typescript
-// Import the standalone function
 import { makeNodeProcessUseDnsProvider } from '@push.rocks/smartdns/client';
 
-// Use Cloudflare DNS for all Node.js DNS operations
-makeNodeProcessUseDnsProvider('cloudflare');
-
-// Or use Google DNS
-makeNodeProcessUseDnsProvider('google');
+makeNodeProcessUseDnsProvider('cloudflare'); // 1.1.1.1 / 1.0.0.1
+makeNodeProcessUseDnsProvider('google');     // 8.8.8.8 / 8.8.4.4
 ```
 
-### Real-World Use Cases
-
-#### DNS-Based Feature Flagging
+### Cleanup
 
-Use TXT records for dynamic feature toggles without redeployment:
+When you're done with a `Smartdns` instance (especially one using Rust strategies), call `destroy()` to kill the Rust child process:
 
 ```typescript
-const txtRecords = await dnsClient.getRecordsTxt('features.example.com');
-const featureFlags = {};
+const dns = new Smartdns({ strategy: 'udp' });
+// ... do queries ...
+dns.destroy(); // kills rustdns-client process
+```
 
-txtRecords.forEach(record => {
-  // Parse TXT records like "feature-dark-mode=true"
-  const [feature, enabled] = record.value.split('=');
-  featureFlags[feature] = enabled === 'true';
-});
+---
 
-if (featureFlags['feature-dark-mode']) {
-  console.log('Dark mode is enabled!');
-}
-```
+## 🖥️ DNS Server
 
-#### Service Discovery
+The `DnsServer` class runs a production-capable authoritative DNS server backed by a Rust binary. It supports standard UDP DNS (port 53), DNS-over-HTTPS, DNSSEC signing, and automated Let's Encrypt certificates.
 
-Use DNS for service endpoint discovery:
+### Server Options
 
 ```typescript
-// Discover API endpoints via TXT records
-const serviceRecords = await dnsClient.getRecordsTxt('_services.example.com');
-
-// Discover mail servers
-const mxRecords = await dnsClient.getRecords('example.com', 'MX');
-const primaryMailServer = mxRecords
-  .sort((a, b) => a.priority - b.priority)[0]?.exchange;
+interface IDnsServerOptions {
+  udpPort: number;               // Port for UDP DNS queries
+  httpsPort: number;             // Port for DNS-over-HTTPS
+  httpsKey: string;              // PEM private key (path or content)
+  httpsCert: string;             // PEM certificate (path or content)
+  dnssecZone: string;            // Zone for DNSSEC signing
+  primaryNameserver?: string;    // SOA mname field (default: 'ns1.{dnssecZone}')
+  udpBindInterface?: string;     // IP to bind UDP (default: '0.0.0.0')
+  httpsBindInterface?: string;   // IP to bind HTTPS (default: '0.0.0.0')
+  manualUdpMode?: boolean;       // Don't auto-bind UDP socket
+  manualHttpsMode?: boolean;     // Don't auto-bind HTTPS server
+  enableLocalhostHandling?: boolean; // RFC 6761 localhost (default: true)
+}
 ```
 
-### DNS Server Implementation
-
-The `DnsServer` class provides a full-featured DNS server with support for UDP, DNS-over-HTTPS (DoH), DNSSEC, and automatic SSL certificate management via Let's Encrypt.
-
-#### Basic DNS Server Setup
-
-Create a simple DNS server that responds to queries:
+### Basic Server
 
 ```typescript
 import { DnsServer } from '@push.rocks/smartdns/server';
 
-const dnsServer = new DnsServer({
-  udpPort: 5333,      // UDP port for DNS queries
-  httpsPort: 8443,    // HTTPS port for DNS-over-HTTPS
-  httpsKey: 'path/to/key.pem',   // Required for HTTPS
-  httpsCert: 'path/to/cert.pem', // Required for HTTPS
-  dnssecZone: 'example.com'      // Optional: enable DNSSEC for this zone
-});
-
-// For enhanced security, bind to specific interfaces
-const secureServer = new DnsServer({
-  udpPort: 53,
-  httpsPort: 443,
-  httpsKey: 'path/to/key.pem',
-  httpsCert: 'path/to/cert.pem',
+const server = new DnsServer({
+  udpPort: 5333,
+  httpsPort: 8443,
+  httpsKey: '...pem...',
+  httpsCert: '...pem...',
   dnssecZone: 'example.com',
-  udpBindInterface: '127.0.0.1',    // Bind UDP to localhost only
-  httpsBindInterface: '127.0.0.1',  // Bind HTTPS to localhost only
-  primaryNameserver: 'ns1.example.com' // Optional: primary nameserver for SOA records (defaults to ns1.{dnssecZone})
 });
 
-// Register a handler for all subdomains of example.com
-dnsServer.registerHandler('*.example.com', ['A'], (question) => ({
+// Register handlers
+server.registerHandler('example.com', ['A'], (question) => ({
   name: question.name,
   type: 'A',
   class: 'IN',
   ttl: 300,
-  data: '192.168.1.100',
+  data: '93.184.215.14',
 }));
 
-// Register a handler for TXT records
-dnsServer.registerHandler('example.com', ['TXT'], (question) => ({
+server.registerHandler('example.com', ['TXT'], (question) => ({
   name: question.name,
   type: 'TXT',
   class: 'IN',
@@ -220,643 +255,308 @@ dnsServer.registerHandler('example.com', ['TXT'], (question) => ({
   data: 'v=spf1 include:_spf.example.com ~all',
 }));
 
-// Start the server
-await dnsServer.start();
-console.log('DNS Server started!');
+await server.start();
+// DNS Server started (UDP: 0.0.0.0:5333, HTTPS: 0.0.0.0:8443)
 ```
 
-### SOA Records and Primary Nameserver
+### Handler System 🎯
 
-The DNS server automatically generates SOA (Start of Authority) records for zones when no specific handler matches a query. The SOA record contains important zone metadata including the primary nameserver.
+Handlers use **glob patterns** (via `minimatch`) to match incoming query names. Multiple handlers can contribute records to the same response.
 
 ```typescript
-const dnsServer = new DnsServer({
-  udpPort: 53,
-  httpsPort: 443,
-  httpsKey: 'path/to/key.pem',
-  httpsCert: 'path/to/cert.pem',
-  dnssecZone: 'example.com',
-  primaryNameserver: 'ns1.example.com'  // Specify your actual primary nameserver
-});
-
-// Without primaryNameserver, the SOA mname defaults to 'ns1.{dnssecZone}'
-// In this case, it would be 'ns1.example.com'
-
-// The automatic SOA record includes:
-// - mname: Primary nameserver (from primaryNameserver option)
-// - rname: Responsible person email (hostmaster.{dnssecZone})
-// - serial: Unix timestamp
-// - refresh: 3600 (1 hour)
-// - retry: 600 (10 minutes)
-// - expire: 604800 (7 days)
-// - minimum: 86400 (1 day)
-```
+// Exact domain
+server.registerHandler('example.com', ['A'], handler);
 
-**Important**: Even if you have multiple nameservers (NS records), only one is designated as the primary in the SOA record. All authoritative nameservers should return the same SOA record.
+// All subdomains
+server.registerHandler('*.example.com', ['A'], handler);
 
-### DNSSEC Support
-
-The DNS server includes comprehensive DNSSEC support with automatic key generation and record signing:
-
-```typescript
-import { DnsServer } from '@push.rocks/smartdns/server';
-
-const dnsServer = new DnsServer({
-  udpPort: 53,
-  httpsPort: 443,
-  dnssecZone: 'secure.example.com',  // Enable DNSSEC for this zone
+// Specific pattern
+server.registerHandler('db-*.internal.example.com', ['A'], (question) => {
+  const id = question.name.match(/db-(\d+)/)?.[1];
+  return {
+    name: question.name,
+    type: 'A',
+    class: 'IN',
+    ttl: 60,
+    data: `10.0.1.${id}`,
+  };
 });
 
-// The server automatically:
-// 1. Generates DNSKEY records with ECDSA (algorithm 13)
-// 2. Creates DS records for parent zone delegation
-// 3. Signs all responses with RRSIG records
-// 4. Provides NSEC records for authenticated denial of existence
-
-// Register your handlers as normal - DNSSEC signing is automatic
-dnsServer.registerHandler('secure.example.com', ['A'], (question) => ({
+// Catch-all
+server.registerHandler('*', ['A'], (question) => ({
   name: question.name,
   type: 'A',
   class: 'IN',
   ttl: 300,
-  data: '192.168.1.1',
+  data: '127.0.0.1',
 }));
 
-await dnsServer.start();
+// Multiple record types
+server.registerHandler('example.com', ['MX'], (question) => ({
+  name: question.name,
+  type: 'MX',
+  class: 'IN',
+  ttl: 300,
+  data: { preference: 10, exchange: 'mail.example.com' },
+}));
 
-// Query for DNSSEC records
-import { Smartdns } from '@push.rocks/smartdns/client';
-const client = new Smartdns({});
-const dnskeyRecords = await client.getRecords('secure.example.com', 'DNSKEY');
-const dsRecords = await client.getRecords('secure.example.com', 'DS');
+// Unregister a handler
+server.unregisterHandler('example.com', ['A']);
 ```
 
-#### Supported DNSSEC Algorithms
+When no handler matches, the server automatically returns an **SOA record** for the zone.
 
-The server supports multiple DNSSEC algorithms:
-- **ECDSAP256SHA256** (Algorithm 13) - Default, using P-256 curve
-- **ED25519** (Algorithm 15) - Modern elliptic curve algorithm
-- **RSASHA256** (Algorithm 8) - RSA-based signatures
+### DNSSEC ✅
 
-### Let's Encrypt Integration
+DNSSEC is enabled automatically when you set the `dnssecZone` option. The Rust backend handles:
 
-The DNS server includes built-in Let's Encrypt support for automatic SSL certificate management:
+- **Key generation** — ECDSA P-256 (algorithm 13) by default
+- **DNSKEY / DS record** generation
+- **RRSIG signing** for all responses
+- **NSEC records** for authenticated denial of existence
 
 ```typescript
-import { DnsServer } from '@push.rocks/smartdns/server';
-
-const dnsServer = new DnsServer({
+const server = new DnsServer({
   udpPort: 53,
   httpsPort: 443,
-  httpsKey: '/path/to/letsencrypt/key.pem',   // Will be auto-generated
-  httpsCert: '/path/to/letsencrypt/cert.pem', // Will be auto-generated
+  httpsKey: '...',
+  httpsCert: '...',
+  dnssecZone: 'secure.example.com',
 });
 
-// Retrieve Let's Encrypt certificate for your domain
-const result = await dnsServer.retrieveSslCertificate(
-  ['secure.example.com', 'www.secure.example.com'],
-  {
-    email: 'admin@example.com',
-    staging: false,  // Use production Let's Encrypt
-    certDir: './certs'
-  }
-);
-
-if (result.success) {
-  console.log('Certificate retrieved successfully!');
-}
-
-// The server automatically:
-// 1. Handles ACME DNS-01 challenges
-// 2. Creates temporary TXT records for domain validation  
-// 3. Retrieves and installs the certificate
-// 4. Restarts the HTTPS server with the new certificate
+// Just register handlers as usual — signing is automatic
+server.registerHandler('secure.example.com', ['A'], (q) => ({
+  name: q.name,
+  type: 'A',
+  class: 'IN',
+  ttl: 300,
+  data: '10.0.0.1',
+}));
 
-await dnsServer.start();
-console.log('DNS Server with Let\'s Encrypt SSL started!');
+await server.start();
 ```
 
-### Manual Socket Handling
+Supported algorithms: **ECDSAP256SHA256** (13), **ED25519** (15), **RSASHA256** (8).
 
-The DNS server supports manual socket handling for advanced use cases like clustering, load balancing, and custom transport implementations. You can control UDP and HTTPS socket handling independently.
-
-#### Configuration Options
-
-```typescript
-export interface IDnsServerOptions {
-  httpsKey: string;              // Path or content of HTTPS private key
-  httpsCert: string;             // Path or content of HTTPS certificate
-  httpsPort: number;             // Port for DNS-over-HTTPS
-  udpPort: number;               // Port for standard UDP DNS
-  dnssecZone: string;            // Zone name for DNSSEC signing
-  udpBindInterface?: string;     // IP address to bind UDP socket (default: '0.0.0.0')
-  httpsBindInterface?: string;   // IP address to bind HTTPS server (default: '0.0.0.0')
-  manualUdpMode?: boolean;       // Handle UDP sockets manually
-  manualHttpsMode?: boolean;     // Handle HTTPS sockets manually
-  primaryNameserver?: string;    // Primary nameserver for SOA records (default: 'ns1.{dnssecZone}')
-}
-```
+### SOA Records
 
-#### Basic Manual Socket Usage
+The server auto-generates SOA records for zones when no specific handler matches. Customize the primary nameserver:
 
 ```typescript
-import { DnsServer } from '@push.rocks/smartdns/server';
-import * as dgram from 'dgram';
-import * as net from 'net';
-
-// Create server with manual UDP mode
-const dnsServer = new DnsServer({
-  httpsKey: '...',
-  httpsCert: '...',
-  httpsPort: 853,
-  udpPort: 53,
+const server = new DnsServer({
+  // ...
   dnssecZone: 'example.com',
-  manualUdpMode: true  // UDP manual, HTTPS automatic
+  primaryNameserver: 'ns1.example.com', // defaults to 'ns1.{dnssecZone}'
 });
 
-await dnsServer.start(); // HTTPS binds, UDP doesn't
-
-// Create your own UDP socket
-const udpSocket = dgram.createSocket('udp4');
-
-// Handle incoming UDP messages
-udpSocket.on('message', (msg, rinfo) => {
-  dnsServer.handleUdpMessage(msg, rinfo, (response, responseRinfo) => {
-    // Send response using your socket
-    udpSocket.send(response, responseRinfo.port, responseRinfo.address);
-  });
-});
-
-// Bind to custom port or multiple interfaces
-udpSocket.bind(5353, '0.0.0.0');
+// Generated SOA includes:
+// mname:   ns1.example.com
+// rname:   hostmaster.example.com
+// serial:  Unix timestamp
+// refresh: 3600, retry: 600, expire: 604800, minimum: 86400
 ```
 
-#### Manual HTTPS Socket Handling
+### Let's Encrypt Integration 🔒
+
+Built-in ACME DNS-01 challenge support for automatic SSL certificates:
 
 ```typescript
-// Create server with manual HTTPS mode
-const dnsServer = new DnsServer({
-  httpsKey: '...',
-  httpsCert: '...',
-  httpsPort: 853,
+const server = new DnsServer({
   udpPort: 53,
+  httpsPort: 443,
+  httpsKey: '/path/to/key.pem',
+  httpsCert: '/path/to/cert.pem',
   dnssecZone: 'example.com',
-  manualHttpsMode: true  // HTTPS manual, UDP automatic
 });
 
-await dnsServer.start(); // UDP binds, HTTPS doesn't
+await server.start();
 
-// Create your own TCP server
-const tcpServer = net.createServer((socket) => {
-  // Pass TCP sockets to DNS server
-  dnsServer.handleHttpsSocket(socket);
-});
+const result = await server.retrieveSslCertificate(
+  ['example.com', 'www.example.com'],
+  {
+    email: 'admin@example.com',
+    staging: false,
+    certDir: './certs',
+  }
+);
 
-tcpServer.listen(8853, '0.0.0.0');
+if (result.success) {
+  console.log('Certificate installed!');
+  // The server automatically:
+  // 1. Registers temporary _acme-challenge TXT handlers
+  // 2. Completes DNS-01 validation
+  // 3. Updates the HTTPS server with the new cert
+  // 4. Cleans up challenge handlers
+}
 ```
 
-#### Full Manual Mode
+### Interface Binding
 
-Control both protocols manually for complete flexibility:
+Restrict the server to specific network interfaces:
 
 ```typescript
-const dnsServer = new DnsServer({
-  httpsKey: '...',
-  httpsCert: '...',
-  httpsPort: 853,
-  udpPort: 53,
-  dnssecZone: 'example.com',
-  manualUdpMode: true,
-  manualHttpsMode: true
+// Localhost only — great for development
+const server = new DnsServer({
+  // ...
+  udpBindInterface: '127.0.0.1',
+  httpsBindInterface: '127.0.0.1',
 });
 
-await dnsServer.start(); // Neither protocol binds
-
-// Set up your own socket handling for both protocols
-// Perfect for custom routing, load balancing, or clustering
+// Different interfaces per protocol
+const server = new DnsServer({
+  // ...
+  udpBindInterface: '192.168.1.100',
+  httpsBindInterface: '10.0.0.50',
+});
 ```
 
-#### Advanced Use Cases
+### Manual Socket Handling 🔧
 
-##### Load Balancing Across Multiple UDP Sockets
+For clustering, load balancing, or custom transports, take control of socket management:
 
 ```typescript
-// Create multiple UDP sockets for different CPU cores
-const sockets = [];
-const numCPUs = require('os').cpus().length;
-
-for (let i = 0; i < numCPUs; i++) {
-  const socket = dgram.createSocket({ 
-    type: 'udp4', 
-    reuseAddr: true  // Allow multiple sockets on same port
-  });
-  
-  socket.on('message', (msg, rinfo) => {
-    dnsServer.handleUdpMessage(msg, rinfo, (response, rinfo) => {
-      socket.send(response, rinfo.port, rinfo.address);
-    });
-  });
-  
-  socket.bind(53);
-  sockets.push(socket);
-}
-```
-
-##### Clustering with Worker Processes
-
-```typescript
-import cluster from 'cluster';
 import { DnsServer } from '@push.rocks/smartdns/server';
+import * as dgram from 'dgram';
 
-if (cluster.isPrimary) {
-  // Master process accepts connections
-  const server = net.createServer({ pauseOnConnect: true });
-  
-  // Distribute connections to workers
-  server.on('connection', (socket) => {
-    const worker = getNextWorker(); // Round-robin or custom logic
-    worker.send('socket', socket);
-  });
-  
-  server.listen(853);
-} else {
-  // Worker process handles DNS
-  const dnsServer = new DnsServer({
-    httpsKey: '...',
-    httpsCert: '...',
-    httpsPort: 853,
-    udpPort: 53,
-    dnssecZone: 'example.com',
-    manualHttpsMode: true
-  });
-  
-  process.on('message', (msg, socket) => {
-    if (msg === 'socket') {
-      dnsServer.handleHttpsSocket(socket);
-    }
-  });
-  
-  await dnsServer.start();
-}
-```
-
-##### Custom Transport Protocol
-
-```typescript
-// Use DNS server with custom transport (e.g., WebSocket)
-import WebSocket from 'ws';
-
-const wss = new WebSocket.Server({ port: 8080 });
-const dnsServer = new DnsServer({
-  httpsKey: '...',
-  httpsCert: '...',
-  httpsPort: 853,
-  udpPort: 53,
-  dnssecZone: 'example.com',
+// Manual UDP mode — you control the socket
+const server = new DnsServer({
+  // ...
   manualUdpMode: true,
-  manualHttpsMode: true
 });
 
-await dnsServer.start();
+await server.start(); // HTTPS auto-binds, UDP does not
 
-wss.on('connection', (ws) => {
-  ws.on('message', (data) => {
-    // Process DNS query from WebSocket
-    const response = dnsServer.processRawDnsPacket(Buffer.from(data));
-    ws.send(response);
+const socket = dgram.createSocket('udp4');
+socket.on('message', (msg, rinfo) => {
+  server.handleUdpMessage(msg, rinfo, (response, responseRinfo) => {
+    socket.send(response, responseRinfo.port, responseRinfo.address);
   });
 });
+socket.bind(5353);
 ```
 
-##### Multi-Interface Binding
+Full manual mode (both protocols):
 
 ```typescript
-// Bind to multiple network interfaces manually
-const interfaces = [
-  { address: '192.168.1.100', type: 'udp4' },
-  { address: '10.0.0.50', type: 'udp4' },
-  { address: '::1', type: 'udp6' }
-];
-
-interfaces.forEach(({ address, type }) => {
-  const socket = dgram.createSocket(type);
-  
-  socket.on('message', (msg, rinfo) => {
-    console.log(`Query received on ${address}`);
-    dnsServer.handleUdpMessage(msg, rinfo, (response, rinfo) => {
-      socket.send(response, rinfo.port, rinfo.address);
-    });
-  });
-  
-  socket.bind(53, address);
+const server = new DnsServer({
+  // ...
+  manualUdpMode: true,
+  manualHttpsMode: true,
 });
-```
-
-### Handling Different Protocols
 
-#### UDP DNS Server
+await server.start(); // Neither protocol binds automatically
+```
 
-Traditional DNS queries over UDP (port 53):
+Process individual DNS packets directly:
 
 ```typescript
-import { DnsServer } from '@push.rocks/smartdns/server';
-import * as plugins from '@push.rocks/smartdns/server/plugins';
-
-const dnsServer = new DnsServer({
-  udpPort: 5353,  // Using alternate port for testing
-  httpsPort: 8443,
-  httpsKey: fs.readFileSync('/path/to/key.pem', 'utf8'),
-  httpsCert: fs.readFileSync('/path/to/cert.pem', 'utf8'),
-  dnssecZone: 'test.local' // Optional
-});
+// Synchronous (TypeScript fallback)
+const response = server.processRawDnsPacket(packetBuffer);
 
-// The UDP server automatically handles DNS packet parsing and encoding
-dnsServer.registerHandler('test.local', ['A'], (question) => ({
-  name: question.name,
-  type: 'A', 
-  class: 'IN',
-  ttl: 60,
-  data: '127.0.0.1',
-}));
-
-await dnsServer.start();
-
-// Test with dig or nslookup:
-// dig @localhost -p 5353 test.local
+// Asynchronous (via Rust bridge — includes DNSSEC signing)
+const response = await server.processRawDnsPacketAsync(packetBuffer);
 ```
 
-#### DNS-over-HTTPS (DoH) Server
-
-Provide encrypted DNS queries over HTTPS:
+#### Load Balancing Example
 
 ```typescript
-import { DnsServer } from '@push.rocks/smartdns/server';
-import * as fs from 'fs';
-
-const dnsServer = new DnsServer({
-  httpsPort: 8443,
-  httpsKey: fs.readFileSync('/path/to/key.pem', 'utf8'),
-  httpsCert: fs.readFileSync('/path/to/cert.pem', 'utf8'),
-});
+import * as dgram from 'dgram';
+import * as os from 'os';
 
-// The HTTPS server automatically handles:
-// - DNS wire format in POST body
-// - Proper Content-Type headers (application/dns-message)
-// - Base64url encoding for GET requests
+const numCPUs = os.cpus().length;
 
-dnsServer.registerHandler('secure.local', ['A'], (question) => ({
-  name: question.name,
-  type: 'A',
-  class: 'IN', 
-  ttl: 300,
-  data: '10.0.0.1',
-}));
+for (let i = 0; i < numCPUs; i++) {
+  const socket = dgram.createSocket({ type: 'udp4', reuseAddr: true });
 
-await dnsServer.start();
+  socket.on('message', (msg, rinfo) => {
+    server.handleUdpMessage(msg, rinfo, (response, rinfo) => {
+      socket.send(response, rinfo.port, rinfo.address);
+    });
+  });
 
-// Test with curl:
-// curl -H "Content-Type: application/dns-message" \
-//      --data-binary @query.bin \
-//      https://localhost:8443/dns-query
+  socket.bind(53);
+}
 ```
 
-### Interface Binding
-
-For enhanced security and network isolation, you can bind the DNS server to specific network interfaces instead of all available interfaces.
-
-#### Localhost-Only Binding
-
-Bind to localhost for development or local-only DNS services:
+### Stopping the Server
 
 ```typescript
-const localServer = new DnsServer({
-  udpPort: 5353,
-  httpsPort: 8443,
-  httpsKey: cert.key,
-  httpsCert: cert.cert,
-  dnssecZone: 'local.test',
-  udpBindInterface: '127.0.0.1',     // IPv4 localhost
-  httpsBindInterface: '127.0.0.1'
-});
-
-// Or use IPv6 localhost
-const ipv6LocalServer = new DnsServer({
-  // ... other options
-  udpBindInterface: '::1',           // IPv6 localhost
-  httpsBindInterface: '::1'
-});
+await server.stop();
 ```
 
-#### Specific Interface Binding
+This gracefully shuts down the Rust process and releases all bound sockets.
 
-Bind to a specific network interface in multi-homed servers:
+---
 
-```typescript
-const interfaceServer = new DnsServer({
-  udpPort: 53,
-  httpsPort: 443,
-  httpsKey: cert.key,
-  httpsCert: cert.cert,
-  dnssecZone: 'example.com',
-  udpBindInterface: '192.168.1.100',  // Specific internal interface
-  httpsBindInterface: '10.0.0.50'    // Different interface for HTTPS
-});
-```
+## 🦀 Rust Crate Structure
 
-#### Security Considerations
+The Rust workspace (`rust/crates/`) contains five crates:
 
-- **Default Behavior**: If not specified, servers bind to all interfaces (`0.0.0.0`)
-- **Localhost Binding**: Use `127.0.0.1` or `::1` for development and testing
-- **Production**: Consider binding to specific internal interfaces for security
-- **Validation**: Invalid IP addresses will throw an error during server startup
+| Crate | Purpose |
+|---|---|
+| `rustdns` | Server binary — IPC management loop, handler callback routing |
+| `rustdns-client` | Client binary — stateless UDP/DoH query proxy |
+| `rustdns-protocol` | DNS wire format parsing, encoding, and RDATA decode/encode |
+| `rustdns-server` | Async UDP + HTTPS servers (tokio, hyper, rustls) |
+| `rustdns-dnssec` | ECDSA/ED25519 key generation and RRset signing |
 
-### Advanced Handler Patterns
+Pre-compiled binaries for `linux_amd64` and `linux_arm64` are included in `dist_rust/`. Cross-compilation is handled by [`@git.zone/tsrust`](https://code.foss.global/git.zone/tsrust).
 
-#### Pattern-Based Routing
+---
 
-Use glob patterns for flexible domain matching:
-
-```typescript
-// Match all subdomains
-dnsServer.registerHandler('*.example.com', ['A'], (question) => {
-  // Extract subdomain
-  const subdomain = question.name.replace('.example.com', '');
-  
-  // Dynamic response based on subdomain
-  return {
-    name: question.name,
-    type: 'A',
-    class: 'IN',
-    ttl: 300,
-    data: subdomain === 'api' ? '10.0.0.10' : '10.0.0.1',
-  };
-});
+## 🧪 Testing
 
-// Match specific patterns
-dnsServer.registerHandler('db-*.service.local', ['A'], (question) => {
-  const instanceId = question.name.match(/db-(\d+)/)?.[1];
-  return {
-    name: question.name,
-    type: 'A',
-    class: 'IN',
-    ttl: 60,
-    data: `10.0.1.${instanceId}`,
-  };
-});
+```bash
+# Run all tests
+pnpm test
 
-// Catch-all handler
-dnsServer.registerHandler('*', ['A'], (question) => ({
-  name: question.name,
-  type: 'A', 
-  class: 'IN',
-  ttl: 300,
-  data: '127.0.0.1',
-}));
+# Run specific test file
+tstest test/test.client.ts --verbose
+tstest test/test.server.ts --verbose
 ```
 
-### Testing
-
-The library uses `@git.zone/tstest` for testing. Here's an example of comprehensive tests:
+Example test:
 
 ```typescript
 import { expect, tap } from '@git.zone/tstest/tapbundle';
 import { Smartdns } from '@push.rocks/smartdns/client';
-import { DnsServer } from '@push.rocks/smartdns/server';
-
-// Test DNS Client
-tap.test('DNS Client - Query Records', async () => {
-  const dnsClient = new Smartdns({});
-  
-  // Test A record query
-  const aRecords = await dnsClient.getRecordsA('google.com');
-  expect(aRecords).toBeArray();
-  expect(aRecords[0]).toHaveProperty('type', 'A');
-  expect(aRecords[0].data).toMatch(/^\d+\.\d+\.\d+\.\d+$/);
-  
-  // Test TXT record query
-  const txtRecords = await dnsClient.getRecordsTxt('google.com');
-  expect(txtRecords).toBeArray();
-  expect(txtRecords[0]).toHaveProperty('type', 'TXT');
-});
-
-// Test DNS Server
-let dnsServer: DnsServer;
-
-tap.test('DNS Server - Setup and Start', async () => {
-  dnsServer = new DnsServer({
-    udpPort: 5353,
-    httpsPort: 8443,
-    httpsKey: 'test-key',   // Use test certificates
-    httpsCert: 'test-cert',
-    dnssecZone: 'test.local'
-  });
-  
-  expect(dnsServer).toBeInstanceOf(DnsServer);
-  await dnsServer.start();
-});
-
-tap.test('DNS Server - Register Handlers', async () => {
-  // Register multiple handlers
-  dnsServer.registerHandler('test.local', ['A'], () => ({
-    name: 'test.local',
-    type: 'A',
-    class: 'IN',
-    ttl: 300,
-    data: '127.0.0.1',
-  }));
-  
-  dnsServer.registerHandler('*.test.local', ['A'], (question) => ({
-    name: question.name,
-    type: 'A', 
-    class: 'IN',
-    ttl: 60,
-    data: '127.0.0.2',
-  }));
-});
 
-tap.test('DNS Server - Query via UDP', async (tools) => {
-  const dnsPacket = (await import('dns-packet')).default;
-  const dgram = await import('dgram');
-  
-  const query = dnsPacket.encode({
-    type: 'query',
-    id: 1234,
-    questions: [{
-      type: 'A',
-      class: 'IN', 
-      name: 'test.local',
-    }],
-  });
-  
-  const client = dgram.createSocket('udp4');
-  const done = tools.defer();
-  
-  client.on('message', (msg) => {
-    const response = dnsPacket.decode(msg);
-    expect(response.answers[0].data).toEqual('127.0.0.1');
-    client.close();
-    done.resolve();
-  });
-  
-  client.send(query, 5353, 'localhost'); // Use the port specified during server creation
-  await done.promise;
+tap.test('resolve A records via UDP', async () => {
+  const dns = new Smartdns({ strategy: 'udp' });
+  const records = await dns.getRecordsA('google.com');
+  expect(records).toBeArray();
+  expect(records[0]).toHaveProperty('type', 'A');
+  expect(records[0]).toHaveProperty('value');
+  dns.destroy();
 });
 
-tap.test('DNS Server - Cleanup', async () => {
-  await dnsServer.stop();
+tap.test('detect DNSSEC via DoH', async () => {
+  const dns = new Smartdns({ strategy: 'doh' });
+  const records = await dns.getRecordsA('cloudflare.com');
+  expect(records[0].dnsSecEnabled).toBeTrue();
+  dns.destroy();
 });
 
-// Run tests
-await tap.start();
+export default tap.start();
 ```
 
-### Best Practices
-
-1. **Port Selection**: Use non-privileged ports (>1024) during development
-2. **Handler Organization**: Group related handlers together
-3. **Error Handling**: Always handle DNS query errors gracefully
-4. **DNSSEC**: Enable DNSSEC for production deployments
-5. **Monitoring**: Log DNS queries for debugging and analytics
-6. **Rate Limiting**: Implement rate limiting for public DNS servers
-7. **Caching**: Respect TTL values and implement proper caching
-8. **Manual Sockets**: Use manual socket handling for clustering and load balancing
-
-### Performance Considerations
-
-- The DNS client uses HTTP keep-alive for connection reuse
-- The DNS server handles concurrent UDP and HTTPS requests efficiently
-- DNSSEC signatures are generated on-demand to reduce memory usage
-- Pattern matching uses caching for improved performance
-- Manual socket handling enables horizontal scaling across CPU cores
-
-### Security Considerations
-
-- Always use DNSSEC for authenticated responses
-- Enable DoH for encrypted DNS queries
-- Validate and sanitize all DNS inputs
-- Implement access controls for DNS server handlers
-- Use Let's Encrypt for automatic SSL certificate management
-- Never expose internal network information through DNS
-- Bind to specific interfaces in production environments
-- Use manual socket handling for custom security layers
-
-This comprehensive library provides everything needed for both DNS client operations and running production-grade DNS servers with modern security features in TypeScript.
-
 ## License and Legal Information
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license.md) file within this repository. 
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
 ### 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 and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+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.
+
+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.
 
 ### Company Information
 
-Task Venture Capital GmbH  
-Registered at District court Bremen HRB 35230 HB, Germany
+Task Venture Capital GmbH
+Registered at District Court Bremen HRB 35230 HB, Germany
 
-For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 
-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.
+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.