Numa DNS Resolver

Instead of using a background thread to decrement TTLs, use a lazy expiration strategy.

1. Store the original_ttl and the cached_at timestamp for each record.
2. On lookup, calculate elapsed = current_time - cached_at.
3. If elapsed >= original_ttl, the entry is stale; remove it from the cache and return None.
4. If the entry is valid, return the packet but adjust the TTLs in the response to original_ttl - elapsed so clients receive the correct remaining time.

pub fn lookup(&mut self, domain: &str, qtype: QueryType) -> Option<DnsPacket> {
    let key = (domain.to_lowercase(), qtype);
    let entry = self.entries.get(&key)?;
    let elapsed = entry.cached_at.elapsed().as_secs() as u32;

    if elapsed >= entry.original_ttl {
        self.entries.remove(&key);
        return None;
    }

    // Adjust TTLs in the response to reflect remaining time
    let mut packet = entry.packet.clone();
    for answer in &mut packet.answers {
        answer.set_ttl(entry.original_ttl.saturating_sub(elapsed));
    }
    Some(packet)
}

To cryptographically prove that a domain name does not exist (NXDOMAIN), Numa uses NSEC or NSEC3 records.

NSEC (Next Secure)

NSEC records create a chain of existing names. An NSEC record defines a gap between two existing names (e.g., alpha → gamma). If a query for beta falls within that gap, it proves beta does not exist.

• Ordering: Uses canonical DNS name ordering (RFC 4034), comparing labels right-to-left, case-insensitively.

NSEC3

NSEC3 prevents zone enumeration by hashing names (iterated SHA-1 with a salt) instead of using plain text. To prove non-existence, Numa performs a 3-part closest encloser proof (RFC 5155 §8.4):

1. Find an ancestor whose hash matches an NSEC3 owner.
2. Prove the next-closer name falls within a hash range gap.
3. Prove the wildcard at the closest encloser also falls within a gap.

Security Note: Numa caps NSEC3 iterations at 500 to prevent Denial of Service (DoS) attacks, as higher iteration counts increase CPU load for verification.

Numa operates as a forwarding resolver using a deterministic pipeline. Each incoming UDP packet triggers a task that walks through several stages. Each stage either provides a response (terminating the pipeline) or passes the query to the next stage.

Pipeline Stages:

1. Overrides: Matches specific queries to provide temporary responses (e.g., for debugging). These can be configured to auto-revert after a set number of minutes.
2. .numa TLD: Handles the custom .numa top-level domain, providing reverse proxying and TLS.
3. Blocklist: Checks if the domain is blocked. If blocked, it returns 0.0.0.0 (effectively making the 'ad gone').
4. Zones: Matches queries against static records defined in configured zones.
5. Cache: Checks for a cache hit. If found, it responds with a TTL-adjusted record.
6. DoH (DNS-over-HTTPS): If no previous stage responds, the query is forwarded to an encrypted upstream DoH provider.

Numa implements recursive resolution using an iterative approach. Instead of trusting an upstream provider, Numa starts at the root nameservers and follows the delegation chain (Root → TLD → Authoritative) by querying each level sequentially.

The resolution loop in src/recursive.rs handles three primary outcomes for every query:

1. Answer: The server provides the requested record. Numa caches this and returns it.
2. Referral: The server delegates authority to another zone. Numa extracts the NS records and 'glue' records (A/AAAA records for the nameservers found in the additional section) to query the next server in the chain.
3. NXDOMAIN/REFUSED: The name does not exist or the server refuses the query. Numa caches this negative result.

Note on CNAMEs: If a query results in a CNAME (Canonical Name) redirect, Numa restarts the resolution process for the new name, capped at 8 levels of chasing to prevent infinite loops.

resolve("cloudflare.com", A)
  → ask 198.41.0.4 (a.root-servers.net)
    ← "try .com: ns1.gtld-servers.net (192.5.6.30)"  [referral + glue]
  → ask 192.5.6.30 (ns1.gtld-servers.net)
    ← "try cloudflare: ns1.cloudflare.com (173.245.58.51)"  [referral + glue]
  → ask 173.245.58.51 (ns1.cloudflare.com)
    ← "104.16.132.229"  [answer]

When using Numa with ODoH, be aware of the following technical limitations and security models:

• Target Visibility: ODoH moves trust but does not eliminate it; the target resolver can still see the DNS question, though it is unattributed to your IP.
• Recursive Mode Egress: If the target operates in recursive mode, the subsequent walk to root/TLD/authoritative servers is plaintext UDP/TCP. Numa's recursive mode protects the client $\rightarrow$ target hop and validates against the IANA root key via DNSSEC.
• Traffic Analysis: Small, self-hosted relays are susceptible to timing correlation attacks. Privacy scales with the volume of users on a relay (anonymity set).
• Key Distribution: Numa fetches the target's HPKE configuration over HTTPS from the target's well-known endpoint. This relies on the security of the WebPKI.
• DNSSEC: ODoH provides path encryption, while DNSSEC provides answer authenticity. Numa's recursive mode implements both.