smartdns/readme.plan.md

# SmartDNS Improvement Plan

Command to reread CLAUDE.md: `cat /home/philkunz/.claude/CLAUDE.md`

## Critical Issue: Support Multiple DNS Records of Same Type

### Current Status: ✅ IMPLEMENTED (v7.4.2)
**Priority: HIGH** - This issue blocks proper DNS server operation and domain registration

## All Issues Fixed (v7.4.3)

### Successfully Implemented:
1. ✅ **Multiple DNS Records Support** (v7.4.2) - Core fix allowing multiple handlers to contribute records
2. ✅ **DNSSEC RRset Signing** - Now signs entire RRsets together instead of individual records
3. ✅ **SOA Record Serialization** - Proper SOA record encoding for DNSSEC compatibility
4. ✅ **Configurable Primary Nameserver** - Added `primaryNameserver` option to IDnsServerOptions

### Problem Summary
The DNS server currently exits after finding the first matching handler for a query, preventing it from serving multiple records of the same type (e.g., multiple NS records, multiple A records for round-robin, multiple TXT records).

### Implementation Plan

#### Phase 1: Analysis and Testing ✅ COMPLETED
- [x] Create comprehensive test cases demonstrating the issue
- [x] Test with multiple NS records scenario
- [x] Test with multiple A records (round-robin) scenario
- [x] Test with multiple TXT records scenario
- [x] Document current behavior vs expected behavior

#### Phase 2: Core Fix Implementation ✅ COMPLETED
- [x] Remove the `break` statement in `processDnsRequest` method (line 609)
- [x] Ensure all matching handlers are processed
- [x] Accumulate all answers from matching handlers
- [x] Add NS record serialization for DNSSEC support

#### Phase 3: Handler Interface Enhancement (Optional)
- [ ] Consider allowing handlers to return arrays of records
- [ ] Update `IDnsHandler` interface to support `DnsAnswer | DnsAnswer[] | null`
- [ ] Update processing logic to handle array responses
- [ ] Maintain backward compatibility with existing handlers

#### Phase 4: Testing and Validation
- [ ] Test multiple NS records return correctly
- [ ] Test round-robin DNS with multiple A records
- [ ] Test multiple TXT records (SPF + DKIM + verification)
- [ ] Test DNSSEC signatures for multiple records
- [ ] Verify no regression in single-record scenarios

#### Phase 5: Documentation and Examples
- [ ] Update documentation with multiple record examples
- [ ] Add example for registering multiple NS records
- [ ] Add example for round-robin DNS setup
- [ ] Document best practices for handler registration

### Technical Details

#### Current Code Issue (ts_server/classes.dnsserver.ts:609)
```typescript
answered = true;
break; // <-- This prevents multiple handlers from contributing answers
```

#### Proposed Fix
```typescript
answered = true;
// Continue processing other handlers instead of breaking
```

### Success Criteria
- DNS queries return ALL matching records from ALL matching handlers
- Domain registration with multiple NS records succeeds
- Round-robin DNS works with multiple A records
- Multiple TXT records can be served for the same domain
- DNSSEC signatures are properly generated for all returned records

### Implementation Summary

#### What Was Fixed
1. **Core Issue Resolved**: Removed the `break` statement at line 609 in `processDnsRequest` that was preventing multiple handlers from contributing DNS answers
2. **NS Record Serialization**: Added NS record type support in `serializeRData` method for DNSSEC compatibility
3. **Result**: DNS server now correctly returns multiple records of the same type from different handlers

#### Test Results
- ✅ Multiple NS records now work (2+ nameservers returned)
- ✅ Round-robin DNS with multiple A records works
- ✅ Multiple TXT records (SPF, DKIM, verification) work
- ⚠️ DNSSEC RRSIG generation needs additional fixes for multiple record scenarios

#### Code Changes
```typescript
// Before (line 609):
answered = true;
break;  // This was preventing multiple handlers from running

// After:
answered = true;
// Continue processing other handlers to allow multiple records
```

## Next Steps and Future Improvements

### Released in v7.4.2
The critical issue of supporting multiple DNS records of the same type has been successfully implemented and released in version 7.4.2.

## Comprehensive Fix Plan for Remaining Issues

Command to reread CLAUDE.md: `cat /home/philkunz/.claude/CLAUDE.md`

### Outstanding Issues to Address

#### 1. DNSSEC RRSIG Generation for Multiple Records
**Status**: Pending  
**Priority**: Medium  
**Issue**: When multiple records of the same type are returned with DNSSEC enabled, the RRSIG generation may encounter issues with the current implementation. Each record gets its own RRSIG instead of signing the entire RRset together.

**Implementation Plan**:
1. Modify `processDnsRequest` to collect all records of the same type before signing
2. Create a map to group answers by record type
3. After all handlers have been processed, sign each RRset as a whole
4. Generate one RRSIG per record type (not per record)
5. Update tests to verify proper DNSSEC RRset signing
6. Ensure canonical ordering of records in RRset for consistent signatures

**Code Changes**:
- Refactor the DNSSEC signing logic in `processDnsRequest`
- Move RRSIG generation outside the handler loop
- Group records by type before signing

#### 2. SOA Record Timeout Issues  
**Status**: Not Started  
**Priority**: Low  
**Issue**: SOA queries sometimes timeout or return incorrect data, possibly related to incomplete SOA record serialization.

**Implementation Plan**:
1. Implement proper SOA record serialization in `serializeRData` method
2. Ensure all SOA fields are properly encoded in wire format
3. Add comprehensive SOA record tests
4. Verify SOA responses with standard DNS tools (dig, nslookup)

**Code Changes**:
- Implement SOA serialization in `serializeRData` method
- Add SOA-specific test cases

#### 3. Configurable DNSSEC Zone Prefix
**Status**: Not Started  
**Priority**: Low  
**Issue**: The server hardcodes 'ns1.' prefix for SOA mname field which may not match actual nameserver names.

**Implementation Plan**:
1. Add `primaryNameserver` option to `IDnsServerOptions`
2. Default to `ns1.{dnssecZone}` if not provided
3. Update SOA record generation to use configurable nameserver
4. Update documentation with new option
5. Add tests for custom primary nameserver configuration

**Code Changes**:
- Add `primaryNameserver?: string` to `IDnsServerOptions`
- Update SOA mname field generation logic
- Update constructor to handle the new option

### Testing Recommendations
- Test DNSSEC validation with multiple records using `dig +dnssec`
- Verify SOA records with `dig SOA`
- Test custom nameserver configuration
- Validate with real-world DNS resolvers (Google DNS, Cloudflare)