nx9-wg/docs/FIREWALL_NAT.md

Firewall and NAT Domain Model Reference

This document describes the domain representations, rule structures, port specifications, and safety invariants for packet filtering and NAT in nx9-wg.

---

1. Domain Entities

A. Firewall Rule (FirewallRule)

Represents an individual packet filtering rule in the database:

Field	Type	Description
id	Uuid	Unique identifier (Primary Key)
name	String	Human-readable identifier (e.g., allow-dns-udp)
direction	FirewallDirection	In, Out, or Forward
protocol	FirewallProtocol	Tcp, Udp, TcpUdp, Icmp, or Any
action	FirewallAction	Accept, Drop, or Reject
source	Option<String>	Source CIDR or IP (e.g., 10.100.0.0/24)
destination	Option<String>	Destination CIDR or IP
source_port	Option<u16>	Specific source port
destination_port	Option<u16>	Specific destination port
port_range	Option<String>	Single port, list, or range (53, 80,443, 8000-8100)
interface_id	Option<Uuid>	Optional interface association
peer_id	Option<Uuid>	Optional cryptographic peer association
priority	i32	Rule evaluation priority (lower numbers evaluate first)
enabled	bool	Active state flag

---

2. Port Specification Syntax

The port_range field supports three RFC-compliant formats:

1. Single Port: 80 \rightarrow Evaluates as dport 80
2. Multi-Port Comma List: 80,443,8080 \rightarrow Evaluates as dport { 80, 443, 8080 }
3. Port Range: 8000-8100 \rightarrow Evaluates as dport 8000-8100

---

3. Protocol Grouping

• Tcp: Filters IPv4/IPv6 TCP packets.
• Udp: Filters IPv4/IPv6 UDP packets.
• TcpUdp: Translates to { tcp, udp } protocol match in a single atomic rule.
• Icmp: Translates to icmp (IPv4) or icmpv6 (IPv6).
• Any: Omits protocol match, applying action to all transport protocols.

---

4. NAT Masquerade Domain Configuration

NAT masquerading is governed by key-value appliance settings in SQLite:

• enable_nat: Boolean string ("true" / "false"). When enabled, all active managed WireGuard subnets are masqueraded outbound to the host WAN interface.
• Dynamic Subnet Calculation: The reconciliation engine queries all enabled interfaces (Interface.address_v4) and generates dedicated masquerade rules for each unique subnet.

---

5. Domain Validation & Invariants

1. Priority Uniqueness & Ordering: Rules are sorted by priority ASC, created_at ASC ensuring determinism.
2. CIDR Validation: Source and destination values must parse as valid IPv4 or IPv6 CIDRs.
3. Port Bounds: Port numbers must fall within standard bounds (1..=65535). In ranges A-B, A <= B is strictly enforced.