@push.rocks/smartdns 7.0.2 → 7.4.0

package/readme.plan.md

@@ -0,0 +1,103 @@
+# DNS Server Interface Binding Implementation Plan
+
+Command to reread CLAUDE.md: `cat /home/philkunz/.claude/CLAUDE.md`
+
+## Overview ✅ COMPLETED
+Enable specific interface binding for the DNSServer class to allow binding to specific network interfaces instead of all interfaces (0.0.0.0).
+
+## Implementation Status: COMPLETED ✅
+
+### What was implemented:
+
+✅ **1. Updated IDnsServerOptions Interface**
+- Added optional `udpBindInterface?: string` property (defaults to '0.0.0.0')
+- Added optional `httpsBindInterface?: string` property (defaults to '0.0.0.0')
+- Located in `ts_server/classes.dnsserver.ts:5-11`
+
+✅ **2. Modified DnsServer.start() Method**
+- Updated UDP server binding to use `this.options.udpBindInterface || '0.0.0.0'`
+- Updated HTTPS server listening to use `this.options.httpsBindInterface || '0.0.0.0'`
+- Added IP address validation before binding
+- Updated console logging to show specific interface being bound
+- Located in `ts_server/classes.dnsserver.ts:699-752`
+
+✅ **3. Added IP Address Validation**
+- Created `isValidIpAddress()` method supporting IPv4 and IPv6
+- Validates interface addresses before binding
+- Throws meaningful error messages for invalid addresses
+- Located in `ts_server/classes.dnsserver.ts:392-398`
+
+✅ **4. Updated Documentation**
+- Added dedicated "Interface Binding" section to readme.md
+- Included examples for localhost-only binding (`127.0.0.1`, `::1`)
+- Documented security considerations and use cases
+- Added examples for specific interface binding
+
+✅ **5. Added Comprehensive Tests**
+- **localhost binding test**: Verifies binding to `127.0.0.1` instead of `0.0.0.0`
+- **Invalid IP validation test**: Ensures invalid IP addresses are rejected
+- **IPv6 support test**: Tests `::1` binding (with graceful fallback if IPv6 unavailable)
+- **Backwards compatibility**: Existing tests continue to work with default behavior
+- Located in `test/test.server.ts`
+
+✅ **6. Updated restartHttpsServer Method**
+- Modified to respect interface binding options during certificate updates
+- Ensures Let's Encrypt certificate renewal maintains interface binding
+
+## ✅ Implementation Results
+
+### Test Results
+All interface binding functionality has been successfully tested:
+
+```bash
+✅ should bind to localhost interface only (318ms)
+   - UDP DNS server running on 127.0.0.1:8085
+   - HTTPS DNS server running on 127.0.0.1:8084
+
+✅ should reject invalid IP addresses (151ms)
+   - Validates IP address format correctly
+   - Throws meaningful error messages
+
+✅ should work with IPv6 localhost if available
+   - Gracefully handles IPv6 unavailability in containerized environments
+```
+
+### Benefits Achieved
+- ✅ Enhanced security by allowing localhost-only binding
+- ✅ Support for multi-homed servers with specific interface requirements
+- ✅ Better isolation in containerized environments
+- ✅ Backwards compatible (defaults to current behavior)
+- ✅ IP address validation with clear error messages
+- ✅ IPv4 and IPv6 support
+
+## Example Usage (Now Available)
+```typescript
+// Bind to localhost only
+const dnsServer = new DnsServer({
+  httpsKey: cert.key,
+  httpsCert: cert.cert,
+  httpsPort: 443,
+  udpPort: 53,
+  dnssecZone: 'example.com',
+  udpBindInterface: '127.0.0.1',
+  httpsBindInterface: '127.0.0.1'
+});
+
+// Bind to specific interface
+const dnsServer = new DnsServer({
+  // ... other options
+  udpBindInterface: '192.168.1.100',
+  httpsBindInterface: '192.168.1.100'
+});
+```
+
+## Files to Modify
+1. `ts_server/classes.dnsserver.ts` - Interface and implementation
+2. `readme.md` - Documentation updates
+3. `test/test.server.ts` - Add interface binding tests
+
+## Testing Strategy
+- Unit tests for interface validation
+- Integration tests for binding behavior
+- Error handling tests for invalid interfaces
+- Backwards compatibility tests

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartdns',
-  version: '7.0.2',
+  version: '7.4.0',
   description: 'A robust TypeScript library providing advanced DNS management and resolution capabilities including support for DNSSEC, custom DNS servers, and integration with various DNS providers.'
 }