122 lines
5.0 KiB
Markdown
122 lines
5.0 KiB
Markdown
# 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) |