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 Blame History