@push.rocks/smartdns 7.0.2 → 7.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist_ts/00_commitinfo_data.js +1 -1
- package/dist_ts_server/classes.dnsserver.d.ts +45 -0
- package/dist_ts_server/classes.dnsserver.js +201 -41
- package/dist_ts_server/plugins.d.ts +2 -1
- package/dist_ts_server/plugins.js +3 -2
- package/package.json +2 -2
- package/readme.hints.md +97 -1
- package/readme.md +618 -197
- package/readme.plan.md +103 -0
- package/ts/00_commitinfo_data.ts +1 -1
package/readme.hints.md
CHANGED
|
@@ -1 +1,97 @@
|
|
|
1
|
-
|
|
1
|
+
# smartdns - Implementation Hints
|
|
2
|
+
|
|
3
|
+
## Architecture Overview
|
|
4
|
+
|
|
5
|
+
The smartdns library is structured into three main modules:
|
|
6
|
+
|
|
7
|
+
1. **Client Module** (`ts_client/`) - DNS client functionality
|
|
8
|
+
2. **Server Module** (`ts_server/`) - DNS server implementation
|
|
9
|
+
3. **Main Module** (`ts/`) - Re-exports both client and server
|
|
10
|
+
|
|
11
|
+
## Client Module (Smartdns class)
|
|
12
|
+
|
|
13
|
+
### Key Features:
|
|
14
|
+
- DNS record queries (A, AAAA, TXT, MX, etc.)
|
|
15
|
+
- Support for multiple DNS providers (Google DNS, Cloudflare)
|
|
16
|
+
- DNS propagation checking with retry logic
|
|
17
|
+
- DNSSEC verification support
|
|
18
|
+
- Both HTTP-based (DoH) and Node.js DNS resolver fallback
|
|
19
|
+
|
|
20
|
+
### Implementation Details:
|
|
21
|
+
- Uses Cloudflare's DNS-over-HTTPS API as primary resolver
|
|
22
|
+
- Falls back to Node.js DNS module for local resolution
|
|
23
|
+
- Implements automatic retry logic with configurable intervals
|
|
24
|
+
- Properly handles quoted TXT records and trailing dots in domain names
|
|
25
|
+
|
|
26
|
+
### Key Methods:
|
|
27
|
+
- `getRecordsA()`, `getRecordsAAAA()`, `getRecordsTxt()` - Type-specific queries
|
|
28
|
+
- `getRecords()` - Generic record query with retry support
|
|
29
|
+
- `checkUntilAvailable()` - DNS propagation verification
|
|
30
|
+
- `getNameServers()` - NS record lookup
|
|
31
|
+
- `makeNodeProcessUseDnsProvider()` - Configure system DNS resolver
|
|
32
|
+
|
|
33
|
+
## Server Module (DnsServer class)
|
|
34
|
+
|
|
35
|
+
### Key Features:
|
|
36
|
+
- Full DNS server supporting UDP and HTTPS (DoH) protocols
|
|
37
|
+
- DNSSEC implementation with multiple algorithms
|
|
38
|
+
- Dynamic handler registration for custom responses
|
|
39
|
+
- Let's Encrypt integration for automatic SSL certificates
|
|
40
|
+
- Wildcard domain support with pattern matching
|
|
41
|
+
|
|
42
|
+
### DNSSEC Implementation:
|
|
43
|
+
- Supports ECDSA (algorithm 13), ED25519 (algorithm 15), and RSA (algorithm 8)
|
|
44
|
+
- Automatic DNSKEY and DS record generation
|
|
45
|
+
- RRSIG signature generation for authenticated responses
|
|
46
|
+
- Key tag computation following RFC 4034
|
|
47
|
+
|
|
48
|
+
### Let's Encrypt Integration:
|
|
49
|
+
- Automatic SSL certificate retrieval using DNS-01 challenges
|
|
50
|
+
- Dynamic TXT record handler registration for ACME validation
|
|
51
|
+
- Certificate renewal and HTTPS server restart capability
|
|
52
|
+
- Domain authorization filtering for security
|
|
53
|
+
|
|
54
|
+
### Handler System:
|
|
55
|
+
- Pattern-based domain matching using minimatch
|
|
56
|
+
- Support for all common record types
|
|
57
|
+
- Handler chaining for complex scenarios
|
|
58
|
+
- Automatic SOA response for unhandled queries
|
|
59
|
+
|
|
60
|
+
## Key Dependencies
|
|
61
|
+
|
|
62
|
+
- `dns-packet`: DNS packet encoding/decoding (wire format)
|
|
63
|
+
- `elliptic`: Cryptographic operations for DNSSEC
|
|
64
|
+
- `acme-client`: Let's Encrypt certificate automation
|
|
65
|
+
- `minimatch`: Glob pattern matching for domains
|
|
66
|
+
- `@push.rocks/smartrequest`: HTTP client for DoH queries
|
|
67
|
+
- `@tsclass/tsclass`: Type definitions for DNS records
|
|
68
|
+
|
|
69
|
+
## Testing Insights
|
|
70
|
+
|
|
71
|
+
The test suite demonstrates:
|
|
72
|
+
- Mock ACME client for testing Let's Encrypt integration
|
|
73
|
+
- Self-signed certificate generation for HTTPS testing
|
|
74
|
+
- Unique port allocation to avoid conflicts
|
|
75
|
+
- Proper server cleanup between tests
|
|
76
|
+
- Both UDP and HTTPS query validation
|
|
77
|
+
|
|
78
|
+
## Common Patterns
|
|
79
|
+
|
|
80
|
+
1. **DNS Record Types**: Internally mapped to numeric values (A=1, AAAA=28, etc.)
|
|
81
|
+
2. **Error Handling**: Graceful fallback and retry mechanisms
|
|
82
|
+
3. **DNSSEC Workflow**: Zone → Key Generation → Signing → Verification
|
|
83
|
+
4. **Certificate Flow**: Domain validation → Challenge setup → Verification → Certificate retrieval
|
|
84
|
+
|
|
85
|
+
## Performance Considerations
|
|
86
|
+
|
|
87
|
+
- Client implements caching via DNS-over-HTTPS responses
|
|
88
|
+
- Server can handle concurrent UDP and HTTPS requests
|
|
89
|
+
- DNSSEC signing is performed on-demand for efficiency
|
|
90
|
+
- Handler registration is O(n) lookup but uses pattern caching
|
|
91
|
+
|
|
92
|
+
## Security Notes
|
|
93
|
+
|
|
94
|
+
- DNSSEC provides authentication but not encryption
|
|
95
|
+
- DoH (DNS-over-HTTPS) provides both privacy and integrity
|
|
96
|
+
- Let's Encrypt integration requires proper domain authorization
|
|
97
|
+
- Handler patterns should be carefully designed to avoid open resolvers
|