# Native Linux nftables Engine (`NativeLinuxNftablesEngine`)

The `NativeLinuxNftablesEngine` manages Linux firewall filtering and Network Address Translation (NAT) via direct in-process interaction with `libnftables.so.1` and the Linux Netfilter Netlink subsystem.

---

## 1. Protocol Architecture & In-Process Netfilter Binding

`nx9-wg` uses `libnftables` in-process C-ABI FFI via `NftContext` to execute atomic transaction batches without spawning the `nft` or `iptables` CLI utilities:

```
┌────────────────────────────────────────────────────────┐
│              NativeLinuxNftablesEngine                 │
└───────────────────────────┬────────────────────────────┘
                            │
               In-Process FFI Transactions
               via libnftables (NftContext)
                            │
┌───────────────────────────▼────────────────────────────┐
│         Netfilter Subsystem (table inet nx9_wg)        │
└────────────────────────────────────────────────────────┘
```

---

## 2. Table Scoping & Multi-Tenant Host Isolation

To prevent breaking container networks, hypervisors, or external security tools, `nx9-wg` enforces strict table isolation:

### A. Dedicated Table Namespace: `table inet nx9_wg`
All chains, sets, rules, and NAT masquerade policies are strictly contained inside `table inet nx9_wg`.

### B. Zero Table Interference
- **No Global Flushes**: `nx9-wg` NEVER executes `flush ruleset` or alters tables belonging to Docker (`table ip docker`), Kubernetes (`table inet cni`), libvirt (`table ip libvirt`), fail2ban, or UFW/Firewalld.
- **Ownership Verification**: Before modifying or inspecting rules, `nx9-wg` validates table family (`inet`) and name (`nx9_wg`). Any foreign table is rejected and untouched.

---

## 3. Ruleset Architecture & Chains

The generated `inet nx9_wg` table contains three dedicated chains:

```
table inet nx9_wg {
    chain input {
        type filter hook input priority filter; policy accept;
        # Custom peer filter rules (e.g. UDP/TCP port restrictions)
    }

    chain forward {
        type filter hook forward priority filter; policy accept;
        # Inter-client routing and subnet forward policies
    }

    chain postrouting {
        type nat hook postrouting priority srcnat; policy accept;
        # Outbound NAT masquerade scoped strictly to managed WireGuard subnets
        ip saddr { 10.100.0.0/24 } oifname != "wg0" masquerade
    }
}
```

---

## 4. Scoped NAT Masquerade Invariant

Outbound NAT masquerading is dynamically scoped exclusively to managed WireGuard client subnets:
1. **Subnet Deduplication**: Overlapping subnets are merged to prevent redundant rules.
2. **Interface Exclusion**: Traffic routing back into the WireGuard interface (`oifname != "wg0"`) is not masqueraded to preserve true source IPs for site-to-site tunnels.
3. **No Catch-All Masquerade**: `nx9-wg` never creates a catch-all `masquerade` rule that affects non-WireGuard traffic on the host.

---

## 5. Atomic Rule Compilation & Verification

The ruleset builder (`NftablesRulesetBuilder`) compiles desired database state into a single atomic Netfilter transaction buffer:
1. **Deterministic Rule Ordering**: Rules are sorted by priority index (ascending) to guarantee consistent packet evaluation.
2. **Protocol Grouping**: Supports `tcp`, `udp`, `tcp_udp`, `icmp`, and `any`.
3. **Port & Port-Range Parsing**: Supports single ports (`53`), comma-separated lists (`80,443`), and contiguous ranges (`8000-8100`).
4. **Validation via `nft_ctx_buffer_output`**: The compiled batch is verified by `libnftables` before committing to the kernel.

---

## 6. Runtime Dependency Qualification

On Linux systems, `nx9-wg` dynamically links against:
- `libnftables.so.1` (provided by `libnftables1` / `nftables` package)
- `libmnl.so.0`
- `libnftnl.so.11`

No runtime dependency on the `nft` CLI binary or shell scripts exists.