smartdns/readme.hints.md

# smartdns - Implementation Hints

## Architecture Overview

The smartdns library is structured into three main modules:

1. **Client Module** (`ts_client/`) - DNS client functionality
2. **Server Module** (`ts_server/`) - DNS server implementation
3. **Main Module** (`ts/`) - Re-exports both client and server

## Client Module (Smartdns class)

### Key Features:
- DNS record queries (A, AAAA, TXT, MX, etc.)
- Support for multiple DNS providers (Google DNS, Cloudflare)
- DNS propagation checking with retry logic
- DNSSEC verification support
- Both HTTP-based (DoH) and Node.js DNS resolver fallback

### Implementation Details:
- Uses Cloudflare's DNS-over-HTTPS API as primary resolver
- Falls back to Node.js DNS module for local resolution
- Implements automatic retry logic with configurable intervals
- Properly handles quoted TXT records and trailing dots in domain names

### Key Methods:
- `getRecordsA()`, `getRecordsAAAA()`, `getRecordsTxt()` - Type-specific queries
- `getRecords()` - Generic record query with retry support
- `checkUntilAvailable()` - DNS propagation verification
- `getNameServers()` - NS record lookup
- `makeNodeProcessUseDnsProvider()` - Configure system DNS resolver

## Server Module (DnsServer class)

### Key Features:
- Full DNS server supporting UDP and HTTPS (DoH) protocols
- DNSSEC implementation with multiple algorithms
- Dynamic handler registration for custom responses
- Let's Encrypt integration for automatic SSL certificates
- Wildcard domain support with pattern matching

### DNSSEC Implementation:
- Supports ECDSA (algorithm 13), ED25519 (algorithm 15), and RSA (algorithm 8)
- Automatic DNSKEY and DS record generation
- RRSIG signature generation for authenticated responses
- Key tag computation following RFC 4034

### Let's Encrypt Integration:
- Automatic SSL certificate retrieval using DNS-01 challenges
- Dynamic TXT record handler registration for ACME validation
- Certificate renewal and HTTPS server restart capability
- Domain authorization filtering for security

### Handler System:
- Pattern-based domain matching using minimatch
- Support for all common record types
- **Multiple Handler Support**: As of v7.4.2+, multiple handlers can contribute records of the same type
- Handler chaining for complex scenarios
- Automatic SOA response for unhandled queries

### Multiple Records Support (v7.4.2+):
- Server now processes ALL matching handlers for a query (previously stopped after first match)
- Enables proper multi-NS record support for domain registration
- Supports round-robin DNS with multiple A/AAAA records
- Allows multiple TXT records (SPF, DKIM, domain verification)
- Each handler contributes its record to the response

## Key Dependencies

- `dns-packet`: DNS packet encoding/decoding (wire format)
- `elliptic`: Cryptographic operations for DNSSEC
- `acme-client`: Let's Encrypt certificate automation
- `minimatch`: Glob pattern matching for domains
- `@push.rocks/smartrequest`: HTTP client for DoH queries
- `@tsclass/tsclass`: Type definitions for DNS records

## Testing Insights

The test suite demonstrates:
- Mock ACME client for testing Let's Encrypt integration
- Self-signed certificate generation for HTTPS testing
- Unique port allocation to avoid conflicts
- Proper server cleanup between tests
- Both UDP and HTTPS query validation

## Common Patterns

1. **DNS Record Types**: Internally mapped to numeric values (A=1, AAAA=28, etc.)
2. **Error Handling**: Graceful fallback and retry mechanisms
3. **DNSSEC Workflow**: Zone → Key Generation → Signing → Verification
4. **Certificate Flow**: Domain validation → Challenge setup → Verification → Certificate retrieval

## Performance Considerations

- Client implements caching via DNS-over-HTTPS responses
- Server can handle concurrent UDP and HTTPS requests
- DNSSEC signing is performed on-demand for efficiency
- Handler registration is O(n) lookup but uses pattern caching

## Security Notes

- DNSSEC provides authentication but not encryption
- DoH (DNS-over-HTTPS) provides both privacy and integrity
- Let's Encrypt integration requires proper domain authorization
- Handler patterns should be carefully designed to avoid open resolvers

## Recent Improvements (v7.4.3)

1. **DNSSEC RRset Signing**: Fixed to properly sign entire RRsets together instead of individual records
2. **SOA Record Serialization**: Implemented proper SOA record encoding for DNSSEC compatibility
3. **Configurable Primary Nameserver**: Added `primaryNameserver` option to customize SOA mname field

## Recent Improvements (v7.4.8)

1. **MX Record DNSSEC Support**: Implemented MX record serialization for DNSSEC signing
   - MX records consist of a 16-bit preference value followed by the exchange domain name
   - Properly serializes both components for DNSSEC signature generation
   - Enables mail exchange records to be authenticated with DNSSEC

## Known Limitations

1. **Handler Deduplication**: If the same handler is registered multiple times, it will contribute duplicate records (this may be desired behavior for some use cases)