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:

✅ 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)

// 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

ts_server/classes.dnsserver.ts - Interface and implementation
readme.md - Documentation updates
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

3.7 KiB Raw Permalink Blame History