zlayer-overlay 0.13.0

//! Linux overlay firewall management via the `iptables` / `ip6tables` CLI.
//!
//! `ZLayer`'s overlay DNS server listens on the node overlay IP, and overlay
//! containers reach it (and each other) through the host's `INPUT` / `FORWARD`
//! chains. On a host with a default-deny firewall (UFW, firewalld, or a bare
//! `iptables -P FORWARD DROP`), that traffic is silently dropped and service
//! discovery breaks — a container's DNS query to the node overlay IP never
//! reaches the daemon's resolver.
//!
//! This module installs a dedicated `ZLAYER-OVERLAY` filter chain, *appended* to
//! both `INPUT` and `FORWARD`, that ACCEPTs any packet to/from the overlay CIDR.
//! Each `ZLayer` chain leads with an `ESTABLISHED,RELATED -j RETURN` so an
//! in-flight host connection it doesn't own (SSH, etc.) is never disturbed, and
//! the jumps are appended (not inserted at position 1) so `ZLayer` runs AFTER the
//! host's own rules rather than preempting the distro/UFW/firewalld accepts. It
//! mirrors how Docker manages its own chains rather than assuming the operator
//! pre-authorised the traffic. Everything is idempotent and best-effort: the
//! `iptables` binary maps to the nft backend on modern hosts, so the same calls
//! work under iptables-legacy and iptables-nft.

use std::net::IpAddr;
use std::process::Command;

use super::FirewallError;

/// Name of the dedicated filter chain `ZLayer` owns.
const CHAIN: &str = "ZLAYER-OVERLAY";

/// Parent chains the overlay chain is jumped from.
const PARENTS: &[&str] = &["INPUT", "FORWARD"];

/// Name of the INPUT-only chain that holds host-destined underlay/cluster
/// ports (`WireGuard`, API, Raft, DNS) plus dynamically-published service ports.
///
/// Unlike [`CHAIN`], this chain is never flushed: it accumulates published
/// ports over the daemon's lifetime, so every mutation is an idempotent
/// `-C`/`-A` (or `-D`) on a single rule rather than a flush-rebuild.
const IN_CHAIN: &str = "ZLAYER-OVERLAY-IN";

/// Name of the dedicated `nat`-table chain that holds the overlay egress
/// masquerade rule, jumped from the `nat` `POSTROUTING` chain.
///
/// Without this, overlay-sourced packets (`10.200.0.0/16`) destined for the
/// public internet are forwarded out the host's WAN NIC with their *private*
/// overlay source address, so replies have nowhere to route back to and every
/// outbound connection from an overlay container times out (`ip_forward=1` and
/// the filter-table ACCEPTs alone are not enough — the source must be SNAT'd to
/// the host's address). This chain masquerades overlay traffic that egresses
/// any *non-overlay* interface, leaving intra-overlay (`zl-*`) traffic untouched.
const NAT_CHAIN: &str = "ZLAYER-OVERLAY-NAT";

/// Name of the dedicated filter chain holding per-member L3-isolation rules,
/// *appended* to `FORWARD` (after the host's own rules, so an established host
/// flow is never disturbed). Its catch-all DROP is overlay-CIDR-scoped, and the
/// chain leads with an `ESTABLISHED,RELATED -j RETURN`, so it isolates overlay
/// members without preempting the host's existing forwarding policy.
///
/// This implements Docker-style per-network isolation: each container lives on
/// its own `zl-<id>-b` bridge, and an isolated network's members may reach each
/// other (by overlay service IP), egress (LAN/internet), and the daemon node IP,
/// but NOT other networks' members or arbitrary cluster overlay IPs. The chain's
/// invariant is that **all `RETURN` (allow) rules precede all `DROP` rules**:
/// allows are inserted at the top (`-I ISO 1`) and the catch-all DROP is appended
/// (`-A ISO`), so a member's permitted peers/node are matched and returned before
/// the `-d <overlay_cidr> -j DROP` fallthrough fires.
const ISO_CHAIN: &str = "ZLAYER-OVERLAY-ISO";

/// Interface wildcard matching every `ZLayer` overlay device — per-service
/// bridges (`zl-<id>-b`), the global `WireGuard` carrier (`zl-<id>-g`), and any
/// other `zl-`-prefixed device. Used as a negated output-interface match
/// (`! -o zl-+`) so masquerade applies only to traffic genuinely *leaving* the
/// overlay (toward the LAN/internet), never to overlay-internal forwarding.
const OVERLAY_IFACE_WILDCARD: &str = "zl-+";

/// `iptables` for an IPv4 CIDR, `ip6tables` for an IPv6 one.
fn tool_for_cidr(cidr: &str) -> &'static str {
    if cidr.contains(':') {
        "ip6tables"
    } else {
        "iptables"
    }
}

/// Run an `iptables`/`ip6tables` invocation. Returns `Ok(true)` when the
/// command exits 0, `Ok(false)` on any non-zero exit (used for existence
/// probes like `-C`), and `Err` only when the binary can't be spawned.
fn run(tool: &str, args: &[&str]) -> Result<bool, FirewallError> {
    let output = Command::new(tool)
        .args(args)
        .output()
        .map_err(|e| FirewallError::AddRule {
            name: format!("{tool} {}", args.join(" ")),
            reason: e.to_string(),
        })?;
    Ok(output.status.success())
}

/// Install (idempotently) the overlay allow-rules for `overlay_cidr` (e.g.
/// `10.200.0.0/16`).
///
/// Creates the `ZLAYER-OVERLAY` chain, (re)populates it with a leading
/// `ESTABLISHED,RELATED -j RETURN` plus `-s <cidr> -j ACCEPT` and
/// `-d <cidr> -j ACCEPT`, and *appends* a jump to it from `INPUT` and `FORWARD`
/// (after the host's own rules) if one is not already present.
///
/// # Errors
///
/// Returns [`FirewallError::AddRule`] only if the `iptables`/`ip6tables` binary
/// cannot be spawned (missing or not executable). Individual rule failures are
/// surfaced; chain-already-exists is tolerated.
pub fn ensure_overlay_subnet_rules(overlay_cidr: &str) -> Result<(), FirewallError> {
    let tool = tool_for_cidr(overlay_cidr);

    // Create the chain; an "already exists" non-zero exit is fine.
    let _ = run(tool, &["-N", CHAIN])?;

    // Rebuild the chain's rules from scratch so repeated calls converge.
    let _ = run(tool, &["-F", CHAIN])?;

    // First rule: RETURN any already-ESTABLISHED/RELATED flow untouched, so an
    // in-flight host connection (SSH, etc.) that this chain doesn't own is never
    // affected by the overlay-CIDR ACCEPTs that follow. Appended first while the
    // chain is empty, so it sits at the top.
    if !run(
        tool,
        &[
            "-A",
            CHAIN,
            "-m",
            "conntrack",
            "--ctstate",
            "ESTABLISHED,RELATED",
            "-j",
            "RETURN",
        ],
    )? {
        return Err(FirewallError::AddRule {
            name: format!("{CHAIN} established,related"),
            reason: format!("{tool} -A returned non-zero"),
        });
    }

    for direction in ["-s", "-d"] {
        if !run(
            tool,
            &["-A", CHAIN, direction, overlay_cidr, "-j", "ACCEPT"],
        )? {
            return Err(FirewallError::AddRule {
                name: format!("{CHAIN} {direction} {overlay_cidr}"),
                reason: format!("{tool} -A returned non-zero"),
            });
        }
    }

    // Jump from INPUT + FORWARD, *appended* so ZLayer runs AFTER the host's own
    // existing rules (incl. the distro's ESTABLISHED,RELATED accept and
    // UFW/firewalld) instead of preempting them. The chain is pure RETURN/ACCEPT,
    // so appending loses no overlay behaviour. Skip if the jump already exists.
    for parent in PARENTS {
        let present = run(tool, &["-C", parent, "-j", CHAIN]).unwrap_or(false);
        if !present && !run(tool, &["-A", parent, "-j", CHAIN])? {
            return Err(FirewallError::AddRule {
                name: format!("{parent} -> {CHAIN}"),
                reason: format!("{tool} -A {parent} returned non-zero"),
            });
        }
    }

    Ok(())
}

/// Remove the `ZLAYER-OVERLAY` chain and its jumps from both IPv4 and IPv6
/// tables. Safe to call when nothing is installed (every step is tolerant of a
/// missing chain/rule); all firewall-binary failures are swallowed so a missing
/// `ip6tables` doesn't abort IPv4 cleanup.
pub fn remove_overlay_subnet_rules() {
    for tool in ["iptables", "ip6tables"] {
        for parent in PARENTS {
            let _ = run(tool, &["-D", parent, "-j", CHAIN]);
        }
        let _ = run(tool, &["-F", CHAIN]);
        let _ = run(tool, &["-X", CHAIN]);
    }
}

/// Build the argument vector for the overlay masquerade rule on [`NAT_CHAIN`]
/// in the `nat` table. `op` is the `iptables` flag selecting the action
/// (`-C` probe, `-A` append, `-D` delete); `overlay_cidr` is the source CIDR to
/// SNAT (e.g. `10.200.0.0/16`).
///
/// The rule masquerades overlay-sourced traffic that egresses any interface
/// *other* than a `ZLayer` overlay device (`! -o zl-+`), so packets leaving the
/// host toward the LAN/internet are SNAT'd to the host address while
/// overlay-internal forwarding is left alone.
///
/// Factored out as a pure function so the exact argument shape can be unit
/// tested without spawning `iptables`.
fn masquerade_rule_args(op: &str, overlay_cidr: &str) -> Vec<String> {
    vec![
        "-t".to_string(),
        "nat".to_string(),
        op.to_string(),
        NAT_CHAIN.to_string(),
        "-s".to_string(),
        overlay_cidr.to_string(),
        "!".to_string(),
        "-o".to_string(),
        OVERLAY_IFACE_WILDCARD.to_string(),
        "-j".to_string(),
        "MASQUERADE".to_string(),
    ]
}

/// Install (idempotently) the overlay egress masquerade for `overlay_cidr`
/// (e.g. `10.200.0.0/16`).
///
/// Creates the `ZLAYER-OVERLAY-NAT` chain in the `nat` table, (re)populates it
/// with a single `-s <cidr> ! -o zl-+ -j MASQUERADE` rule, and appends a jump to
/// it from `POSTROUTING` if one is not already present. Appended (not inserted)
/// so it composes with any pre-existing SNAT rules (e.g. a VPN mesh's own
/// masquerade) rather than shadowing them.
///
/// Masquerade is an IPv4 concept here (the cluster CIDR is IPv4); the
/// [`tool_for_cidr`] split still routes an IPv6 CIDR to `ip6tables` should the
/// overlay ever be v6.
///
/// # Errors
///
/// Returns [`FirewallError::AddRule`] only if the `iptables`/`ip6tables` binary
/// cannot be spawned, or if a rule insert returns non-zero. Chain-already-exists
/// is tolerated.
pub fn ensure_overlay_masquerade(overlay_cidr: &str) -> Result<(), FirewallError> {
    let tool = tool_for_cidr(overlay_cidr);

    // Create the chain in the nat table; an "already exists" non-zero exit is fine.
    let _ = run(tool, &["-t", "nat", "-N", NAT_CHAIN])?;

    // Rebuild the chain's single rule from scratch so repeated calls converge.
    let _ = run(tool, &["-t", "nat", "-F", NAT_CHAIN])?;
    let add: Vec<String> = masquerade_rule_args("-A", overlay_cidr);
    let add_ref: Vec<&str> = add.iter().map(String::as_str).collect();
    if !run(tool, &add_ref)? {
        return Err(FirewallError::AddRule {
            name: format!("{NAT_CHAIN} masquerade {overlay_cidr}"),
            reason: format!("{tool} -t nat -A returned non-zero"),
        });
    }

    // Jump from POSTROUTING, appended so existing NAT rules are preserved. Skip
    // if the jump already exists.
    let present = run(tool, &["-t", "nat", "-C", "POSTROUTING", "-j", NAT_CHAIN]).unwrap_or(false);
    if !present && !run(tool, &["-t", "nat", "-A", "POSTROUTING", "-j", NAT_CHAIN])? {
        return Err(FirewallError::AddRule {
            name: format!("POSTROUTING -> {NAT_CHAIN}"),
            reason: format!("{tool} -t nat -A POSTROUTING returned non-zero"),
        });
    }

    Ok(())
}

/// Remove the `ZLAYER-OVERLAY-NAT` chain and its `POSTROUTING` jump from both
/// the IPv4 and IPv6 `nat` tables (the counterpart of
/// [`ensure_overlay_masquerade`]). Safe to call when nothing is installed; all
/// firewall-binary failures are swallowed so a missing `ip6tables` doesn't abort
/// IPv4 cleanup.
pub fn remove_overlay_masquerade() {
    for tool in ["iptables", "ip6tables"] {
        let _ = run(tool, &["-t", "nat", "-D", "POSTROUTING", "-j", NAT_CHAIN]);
        let _ = run(tool, &["-t", "nat", "-F", NAT_CHAIN]);
        let _ = run(tool, &["-t", "nat", "-X", NAT_CHAIN]);
    }
}

/// Build the argument vector for a bidirectional-allow rule on [`ISO_CHAIN`]
/// permitting `a_ip` to reach `b_ip` (`-s <a> -d <b> -j RETURN`). `op` is the
/// `iptables` flag selecting the action (`-C` probe, `-I`/`-A` install,
/// `-D` delete).
///
/// `RETURN` (not `ACCEPT`) so the packet falls back to the parent `FORWARD`
/// chain's remaining rules — letting the blanket [`CHAIN`] accept and the host's
/// own policy continue to apply — rather than being short-circuited.
///
/// Factored out as a pure function so the exact argument shape can be unit
/// tested without spawning `iptables`.
fn iso_pair_rule_args(op: &str, a_ip: IpAddr, b_ip: IpAddr) -> Vec<String> {
    vec![
        op.to_string(),
        ISO_CHAIN.to_string(),
        "-s".to_string(),
        a_ip.to_string(),
        "-d".to_string(),
        b_ip.to_string(),
        "-j".to_string(),
        "RETURN".to_string(),
    ]
}

/// Build the argument vector for the rule letting `member_ip` reach the daemon
/// `node_ip` (`-s <member> -d <node>/32 -j RETURN`, `/128` for IPv6). `op` is
/// the `iptables` flag selecting the action (`-C` probe, `-I`/`-A` install,
/// `-D` delete).
///
/// A host-mask (`/32` or `/128`) is appended so the match is exactly the node
/// overlay IP — the resolver/daemon endpoint a member must always reach — and
/// not a wider range.
///
/// Factored out as a pure function so the exact argument shape can be unit
/// tested without spawning `iptables`.
fn iso_node_rule_args(op: &str, member_ip: IpAddr, node_ip: IpAddr) -> Vec<String> {
    let host_mask = if node_ip.is_ipv6() { "/128" } else { "/32" };
    vec![
        op.to_string(),
        ISO_CHAIN.to_string(),
        "-s".to_string(),
        member_ip.to_string(),
        "-d".to_string(),
        format!("{node_ip}{host_mask}"),
        "-j".to_string(),
        "RETURN".to_string(),
    ]
}

/// Build the argument vector for the catch-all DROP isolating `member_ip` from
/// the rest of `overlay_cidr` (`-s <member> -d <overlay_cidr> -j DROP`). `op` is
/// the `iptables` flag selecting the action (`-C` probe, `-I`/`-A` install,
/// `-D` delete).
///
/// Appended *after* the per-member allows (which `RETURN` early), so a member
/// reaching anything in the overlay that is not an explicitly-permitted peer or
/// the node IP — i.e. another network's members or arbitrary cluster overlay
/// IPs — is dropped.
///
/// Factored out as a pure function so the exact argument shape can be unit
/// tested without spawning `iptables`.
fn iso_drop_rule_args(op: &str, member_ip: IpAddr, overlay_cidr: &str) -> Vec<String> {
    vec![
        op.to_string(),
        ISO_CHAIN.to_string(),
        "-s".to_string(),
        member_ip.to_string(),
        "-d".to_string(),
        overlay_cidr.to_string(),
        "-j".to_string(),
        "DROP".to_string(),
    ]
}

/// Idempotently apply one rule on [`ISO_CHAIN`]: probe with `-C` (built by
/// swapping the leading op of `rule` to `-C`), and only run `rule` when absent.
/// On apply failure returns [`FirewallError::AddRule`] tagged with `name`.
fn ensure_iso_rule(tool: &str, rule: &[String], name: &str) -> Result<(), FirewallError> {
    let mut probe = rule.to_vec();
    probe[0] = "-C".to_string();
    let probe_ref: Vec<&str> = probe.iter().map(String::as_str).collect();
    if run(tool, &probe_ref).unwrap_or(false) {
        return Ok(());
    }

    let rule_ref: Vec<&str> = rule.iter().map(String::as_str).collect();
    if !run(tool, &rule_ref)? {
        return Err(FirewallError::AddRule {
            name: name.to_string(),
            reason: format!("{tool} {} returned non-zero", rule[0]),
        });
    }
    Ok(())
}

/// Install (idempotently) Docker-style L3 isolation for one overlay member.
///
/// Creates the [`ISO_CHAIN`] filter chain, *appends* a jump to it from `FORWARD`
/// (after the host's own rules) if not already present, ensures a leading
/// `ESTABLISHED,RELATED -j RETURN`, then for `member_ip` installs:
///
/// - For every `peer` in `peers`: a **bidirectional** allow (`member -> peer`
///   and `peer -> member`), inserted at the top of the chain (`-I ISO 1`).
/// - An allow letting `member_ip` reach the daemon `node_ip` (`/32` or `/128`),
///   also inserted at the top.
/// - A catch-all DROP for `member -> overlay_cidr`, *appended* to the chain
///   (`-A ISO`).
///
/// The top-insert-allows / append-drop split preserves the invariant that all
/// `RETURN` rules precede the `DROP`, so permitted peers and the node IP are
/// matched first and the rest of the overlay (other networks, arbitrary cluster
/// IPs) is dropped. Egress to the LAN/internet is unaffected: the DROP only
/// matches `-d <overlay_cidr>`. Every rule is `-C`-probed before applying so
/// repeated calls converge without duplicates.
///
/// IPv4 only: the `member_ip`/`node_ip`/`peers` are the cluster's overlay
/// addresses (IPv4). The [`IpAddr`] types let an IPv6 overlay route through
/// [`iso_node_rule_args`]' `/128` path, but the chain operations use `iptables`.
///
/// The `network` name is accepted for signature parity with the macOS backend
/// (which keys a per-network `pf` table by it); on Linux the pairwise rules
/// already isolate each member correctly, so it is unused here.
///
/// # Errors
///
/// Returns [`FirewallError::AddRule`] if the `iptables` binary cannot be spawned,
/// a chain/jump operation fails, or an allow/drop insert returns non-zero.
pub fn ensure_member_isolation(
    network: &str,
    member_ip: IpAddr,
    peers: &[IpAddr],
    node_ip: IpAddr,
    overlay_cidr: &str,
) -> Result<(), FirewallError> {
    // The network name is the macOS pf-table key; Linux pairwise rules already
    // isolate correctly, so it is not needed here.
    let _ = network;
    let tool = "iptables";

    // Create the chain; an "already exists" non-zero exit is fine.
    let _ = run(tool, &["-N", ISO_CHAIN])?;

    // Jump from FORWARD only (this is inter-container forwarding, never
    // host-destined), *appended* so ZLayer's isolation runs AFTER the host's own
    // existing FORWARD rules (incl. the distro's ESTABLISHED,RELATED accept)
    // instead of preempting them. The chain's only DROP is overlay-CIDR-scoped,
    // so appending loses no isolation behaviour. Skip if the jump already exists.
    let present = run(tool, &["-C", "FORWARD", "-j", ISO_CHAIN]).unwrap_or(false);
    if !present && !run(tool, &["-A", "FORWARD", "-j", ISO_CHAIN])? {
        return Err(FirewallError::AddRule {
            name: format!("FORWARD -> {ISO_CHAIN}"),
            reason: format!("{tool} -A FORWARD returned non-zero"),
        });
    }

    // First rule: RETURN any already-ESTABLISHED/RELATED flow untouched, so a
    // forwarded host connection this chain doesn't own is never caught by the
    // overlay-CIDR catch-all DROP. Idempotently inserted at the top of the chain
    // (it is a RETURN, so it preserves the "all RETURN precede the DROP"
    // invariant); the -C probe ignores the numeric position.
    let est = vec![
        "-I".to_string(),
        ISO_CHAIN.to_string(),
        "-m".to_string(),
        "conntrack".to_string(),
        "--ctstate".to_string(),
        "ESTABLISHED,RELATED".to_string(),
        "-j".to_string(),
        "RETURN".to_string(),
    ];
    let est = insert_pos(est);
    ensure_iso_rule(tool, &est, &format!("{ISO_CHAIN} established,related"))?;

    // Bidirectional peer allows, inserted at the top (-I ISO 1) so they precede
    // the appended DROP.
    for peer in peers {
        let fwd = iso_pair_rule_args("-I", member_ip, *peer);
        // -I needs the position; splice "1" after the chain name.
        let fwd = insert_pos(fwd);
        ensure_iso_rule(
            tool,
            &fwd,
            &format!("{ISO_CHAIN} allow {member_ip} -> {peer}"),
        )?;

        let rev = iso_pair_rule_args("-I", *peer, member_ip);
        let rev = insert_pos(rev);
        ensure_iso_rule(
            tool,
            &rev,
            &format!("{ISO_CHAIN} allow {peer} -> {member_ip}"),
        )?;
    }

    // Allow the member to reach the daemon node IP, inserted at the top.
    let node = iso_node_rule_args("-I", member_ip, node_ip);
    let node = insert_pos(node);
    ensure_iso_rule(
        tool,
        &node,
        &format!("{ISO_CHAIN} allow {member_ip} -> {node_ip}"),
    )?;

    // Catch-all DROP for the rest of the overlay, appended after the allows.
    let drop = iso_drop_rule_args("-A", member_ip, overlay_cidr);
    ensure_iso_rule(
        tool,
        &drop,
        &format!("{ISO_CHAIN} drop {member_ip} -> {overlay_cidr}"),
    )?;

    Ok(())
}

/// Splice the insert position `"1"` after the chain name for an `-I` rule, so
/// `[-I, ISO_CHAIN, ...]` becomes `[-I, ISO_CHAIN, "1", ...]` (insert at the
/// top). The `-C` probe form derived from this by [`ensure_iso_rule`] drops the
/// leading op back to `-C`; `iptables -C` ignores the numeric position, so the
/// extra `"1"` is harmless on the probe.
fn insert_pos(mut rule: Vec<String>) -> Vec<String> {
    rule.insert(2, "1".to_string());
    rule
}

/// Remove the per-member L3-isolation rules installed by
/// [`ensure_member_isolation`] for `member_ip`. Best-effort: every `-D` is
/// tolerant of a missing rule and all firewall-binary failures are swallowed,
/// so a partially-installed member tears down cleanly. The [`ISO_CHAIN`] itself
/// and its `FORWARD` jump are left in place (other members may still use them).
///
/// `network` is accepted for signature parity with the macOS backend and is
/// unused on Linux (the pairwise rules carry no per-network key).
pub fn remove_member_isolation(
    network: &str,
    member_ip: IpAddr,
    peers: &[IpAddr],
    node_ip: IpAddr,
    overlay_cidr: &str,
) {
    let _ = network;
    let tool = "iptables";
    for peer in peers {
        let fwd = iso_pair_rule_args("-D", member_ip, *peer);
        let fwd_ref: Vec<&str> = fwd.iter().map(String::as_str).collect();
        let _ = run(tool, &fwd_ref);

        let rev = iso_pair_rule_args("-D", *peer, member_ip);
        let rev_ref: Vec<&str> = rev.iter().map(String::as_str).collect();
        let _ = run(tool, &rev_ref);
    }

    let node = iso_node_rule_args("-D", member_ip, node_ip);
    let node_ref: Vec<&str> = node.iter().map(String::as_str).collect();
    let _ = run(tool, &node_ref);

    let drop = iso_drop_rule_args("-D", member_ip, overlay_cidr);
    let drop_ref: Vec<&str> = drop.iter().map(String::as_str).collect();
    let _ = run(tool, &drop_ref);
}

/// Remove the [`ISO_CHAIN`] (`ZLAYER-OVERLAY-ISO`) filter chain and its `FORWARD`
/// jump from both the IPv4 and IPv6 tables — the global-teardown counterpart of
/// [`ensure_member_isolation`].
///
/// [`remove_member_isolation`] deliberately leaves the chain and its jump
/// resident (other members may still use them), so on a *full* overlay teardown
/// the chain would otherwise leak. This removes the whole structure: `-D` the
/// `FORWARD -j ZLAYER-OVERLAY-ISO` jump, `-F` flush the chain, `-X` delete it.
///
/// Safe to call when nothing is installed (every step tolerates a missing
/// chain/rule) and all firewall-binary failures are swallowed so a missing
/// `ip6tables` doesn't abort IPv4 cleanup. Mirrors
/// [`remove_overlay_subnet_rules`] / [`remove_overlay_masquerade`].
pub fn remove_overlay_isolation() {
    for tool in ["iptables", "ip6tables"] {
        let _ = run(tool, &["-D", "FORWARD", "-j", ISO_CHAIN]);
        let _ = run(tool, &["-F", ISO_CHAIN]);
        let _ = run(tool, &["-X", ISO_CHAIN]);
    }
}

/// Build the argument vector for a single per-port rule operation on
/// [`IN_CHAIN`]. `op` is the `iptables` flag selecting the action
/// (`-C` probe, `-A` append, `-D` delete); `proto` is `"tcp"` or `"udp"`.
///
/// Factored out as a pure function so the exact argument shape can be unit
/// tested without spawning `iptables`.
fn port_rule_args(op: &str, port: u16, proto: &str) -> Vec<String> {
    vec![
        op.to_string(),
        IN_CHAIN.to_string(),
        "-p".to_string(),
        proto.to_string(),
        "--dport".to_string(),
        port.to_string(),
        "-j".to_string(),
        "ACCEPT".to_string(),
    ]
}

/// Ensure [`IN_CHAIN`] exists, leads with an `ESTABLISHED,RELATED -j RETURN`,
/// and is *appended* to `INPUT`.
///
/// The chain is created with `-N` (an "already exists" non-zero exit is fine),
/// a leading established/related RETURN is idempotently inserted at the top so an
/// in-flight host connection is never disturbed, and a jump is appended to
/// `INPUT` (after the host's own rules) only if one is not already present. These
/// ports are host-destined, so — unlike the subnet chain — the jump is wired only
/// into `INPUT`, never `FORWARD`.
///
/// # Errors
///
/// Returns [`FirewallError::AddRule`] only if `tool` cannot be spawned, or if
/// the `-I IN_CHAIN`/`-A INPUT` operation returns non-zero.
fn ensure_in_chain(tool: &str) -> Result<(), FirewallError> {
    // Create the chain; an "already exists" non-zero exit is fine.
    let _ = run(tool, &["-N", IN_CHAIN])?;

    // First rule: RETURN any already-ESTABLISHED/RELATED flow untouched, so an
    // in-flight host connection (SSH, etc.) this chain doesn't own is never
    // affected by the per-port ACCEPTs that follow. The chain is never flushed,
    // so this is an idempotent -C/-I 1 (insert at the top); the -C probe ignores
    // the numeric position.
    let est_present = run(
        tool,
        &[
            "-C",
            IN_CHAIN,
            "-m",
            "conntrack",
            "--ctstate",
            "ESTABLISHED,RELATED",
            "-j",
            "RETURN",
        ],
    )
    .unwrap_or(false);
    if !est_present
        && !run(
            tool,
            &[
                "-I",
                IN_CHAIN,
                "1",
                "-m",
                "conntrack",
                "--ctstate",
                "ESTABLISHED,RELATED",
                "-j",
                "RETURN",
            ],
        )?
    {
        return Err(FirewallError::AddRule {
            name: format!("{IN_CHAIN} established,related"),
            reason: format!("{tool} -I {IN_CHAIN} returned non-zero"),
        });
    }

    // Jump from INPUT only, *appended* so ZLayer runs AFTER the host's own
    // existing INPUT rules (incl. the distro's ESTABLISHED,RELATED accept and
    // UFW/firewalld) instead of preempting them. The chain is pure RETURN/ACCEPT,
    // so appending loses no behaviour. Skip if the jump already exists.
    let present = run(tool, &["-C", "INPUT", "-j", IN_CHAIN]).unwrap_or(false);
    if !present && !run(tool, &["-A", "INPUT", "-j", IN_CHAIN])? {
        return Err(FirewallError::AddRule {
            name: format!("INPUT -> {IN_CHAIN}"),
            reason: format!("{tool} -A INPUT returned non-zero"),
        });
    }
    Ok(())
}

/// Idempotently ACCEPT `proto`/`port` into [`IN_CHAIN`]: probe with `-C`, and
/// only `-A` when the rule is absent so repeated calls converge without
/// duplicating rules (the chain is never flushed).
///
/// # Errors
///
/// Returns [`FirewallError::AddRule`] only if `tool` cannot be spawned, or if
/// the `-A` append returns non-zero.
fn ensure_port_rule(tool: &str, proto: &str, port: u16) -> Result<(), FirewallError> {
    let probe: Vec<String> = port_rule_args("-C", port, proto);
    let probe_ref: Vec<&str> = probe.iter().map(String::as_str).collect();
    if run(tool, &probe_ref).unwrap_or(false) {
        return Ok(());
    }

    let append: Vec<String> = port_rule_args("-A", port, proto);
    let append_ref: Vec<&str> = append.iter().map(String::as_str).collect();
    if !run(tool, &append_ref)? {
        return Err(FirewallError::AddRule {
            name: format!("{IN_CHAIN} -p {proto} --dport {port}"),
            reason: format!("{tool} -A returned non-zero"),
        });
    }
    Ok(())
}

/// Open the cluster underlay ports inbound to the host: `WireGuard` (udp
/// `wg_port`), the API (tcp `api_port`), Raft (tcp `raft_port`), and DNS on
/// both udp and tcp `53`.
///
/// These services bind `0.0.0.0`/`::`, so the rules are applied to both the
/// IPv4 (`iptables`) and IPv6 (`ip6tables`) tables. A hard spawn failure on
/// IPv4 aborts the call; IPv6 is best-effort — a host without `ip6tables` (or
/// with IPv6 disabled) must not break IPv4 setup.
///
/// Everything is idempotent: [`IN_CHAIN`] is created/jumped via
/// [`ensure_in_chain`] and each port is added with a `-C`/`-A` probe-then-append
/// (no flush), so the chain can also hold dynamically-published ports.
///
/// # Errors
///
/// Returns [`FirewallError::AddRule`] if the IPv4 `iptables` binary cannot be
/// spawned or an IPv4 rule insert fails. IPv6 errors are swallowed.
pub fn ensure_overlay_rules(
    wg_port: u16,
    api_port: u16,
    raft_port: u16,
) -> Result<(), FirewallError> {
    // (proto, port) rules to open. DNS needs both transports.
    let rules: [(&str, u16); 5] = [
        ("udp", wg_port),
        ("tcp", api_port),
        ("tcp", raft_port),
        ("udp", 53),
        ("tcp", 53),
    ];

    // IPv4: hard-fail on any error (binary missing or insert non-zero).
    ensure_in_chain("iptables")?;
    for (proto, port) in rules {
        ensure_port_rule("iptables", proto, port)?;
    }

    // IPv6: best-effort. A v6-only failure (no ip6tables, disabled IPv6) must
    // not abort the call now that IPv4 is in place.
    if ensure_in_chain("ip6tables").is_ok() {
        for (proto, port) in rules {
            let _ = ensure_port_rule("ip6tables", proto, port);
        }
    }

    Ok(())
}

/// Idempotently ACCEPT one dynamically-published host `port` into [`IN_CHAIN`]
/// on both IPv4 and IPv6 (IPv6 best-effort). `udp` selects the transport.
///
/// # Errors
///
/// Returns [`FirewallError::AddRule`] if the IPv4 `iptables` binary cannot be
/// spawned or the IPv4 insert fails. IPv6 errors are swallowed.
pub fn ensure_published_port(port: u16, udp: bool) -> Result<(), FirewallError> {
    let proto = if udp { "udp" } else { "tcp" };

    // IPv4: hard-fail.
    ensure_in_chain("iptables")?;
    ensure_port_rule("iptables", proto, port)?;

    // IPv6: best-effort.
    if ensure_in_chain("ip6tables").is_ok() {
        let _ = ensure_port_rule("ip6tables", proto, port);
    }

    Ok(())
}

/// Remove a previously-published host `port` from [`IN_CHAIN`] on both IPv4 and
/// IPv6. `udp` selects the transport. Tolerant of a missing rule/chain — every
/// firewall-binary failure is swallowed.
pub fn remove_published_port(port: u16, udp: bool) {
    let proto = if udp { "udp" } else { "tcp" };
    let args: Vec<String> = port_rule_args("-D", port, proto);
    let args_ref: Vec<&str> = args.iter().map(String::as_str).collect();
    for tool in ["iptables", "ip6tables"] {
        let _ = run(tool, &args_ref);
    }
}

/// Tear down [`IN_CHAIN`] and its `INPUT` jump on both IPv4 and IPv6. Safe to
/// call when nothing is installed; all firewall-binary failures are swallowed
/// so a missing `ip6tables` doesn't abort IPv4 cleanup.
pub fn remove_overlay_rules() {
    for tool in ["iptables", "ip6tables"] {
        let _ = run(tool, &["-D", "INPUT", "-j", IN_CHAIN]);
        let _ = run(tool, &["-F", IN_CHAIN]);
        let _ = run(tool, &["-X", IN_CHAIN]);
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn port_rule_args_builds_check_probe() {
        // An api_port (tcp) probe is exactly the `-C` form on IN_CHAIN.
        assert_eq!(
            port_rule_args("-C", 3669, "tcp"),
            vec![
                "-C",
                "ZLAYER-OVERLAY-IN",
                "-p",
                "tcp",
                "--dport",
                "3669",
                "-j",
                "ACCEPT",
            ]
        );
    }

    #[test]
    fn port_rule_args_builds_append_and_delete() {
        // The -A append and -D delete shapes differ only by the leading op.
        assert_eq!(
            port_rule_args("-A", 51820, "udp"),
            vec![
                "-A",
                "ZLAYER-OVERLAY-IN",
                "-p",
                "udp",
                "--dport",
                "51820",
                "-j",
                "ACCEPT",
            ]
        );
        assert_eq!(
            port_rule_args("-D", 51820, "udp"),
            vec![
                "-D",
                "ZLAYER-OVERLAY-IN",
                "-p",
                "udp",
                "--dport",
                "51820",
                "-j",
                "ACCEPT",
            ]
        );
    }

    #[test]
    fn dns_builds_both_udp_and_tcp_on_port_53() {
        assert_eq!(
            port_rule_args("-C", 53, "udp"),
            vec![
                "-C",
                "ZLAYER-OVERLAY-IN",
                "-p",
                "udp",
                "--dport",
                "53",
                "-j",
                "ACCEPT",
            ]
        );
        assert_eq!(
            port_rule_args("-C", 53, "tcp"),
            vec![
                "-C",
                "ZLAYER-OVERLAY-IN",
                "-p",
                "tcp",
                "--dport",
                "53",
                "-j",
                "ACCEPT",
            ]
        );
    }

    #[test]
    fn masquerade_rule_args_builds_append_in_nat_table() {
        // The egress masquerade is an append on ZLAYER-OVERLAY-NAT in the nat
        // table: -s <cidr> ! -o zl-+ -j MASQUERADE.
        assert_eq!(
            masquerade_rule_args("-A", "10.200.0.0/16"),
            vec![
                "-t",
                "nat",
                "-A",
                "ZLAYER-OVERLAY-NAT",
                "-s",
                "10.200.0.0/16",
                "!",
                "-o",
                "zl-+",
                "-j",
                "MASQUERADE",
            ]
        );
    }

    /// `remove_overlay_isolation` is the global-teardown counterpart of
    /// `ensure_member_isolation`; teardown calls it unconditionally, so it must be
    /// a tolerant no-op when the `ZLAYER-OVERLAY-ISO` chain was never installed
    /// (fresh boot, or a node that never ran an isolated network). Every step is a
    /// best-effort `let _ = run(...)` that swallows the firewall-binary exit code,
    /// so this runs as a non-root, always-on test: on a box without `iptables` or
    /// without privileges, each `run` simply returns a non-success status (or a
    /// spawn error mapped into the swallowed `Err`) and the function still returns
    /// cleanly. The assertion is simply that calling it does not panic and that it
    /// is idempotent across repeated invocations.
    #[test]
    fn remove_overlay_isolation_is_idempotent_no_chain() {
        // First call: no ZLAYER-OVERLAY-ISO chain present (we never installed it).
        remove_overlay_isolation();
        // Second call: still nothing to remove — must remain a clean no-op.
        remove_overlay_isolation();
    }

    #[test]
    fn masquerade_rule_args_probe_and_delete_differ_only_by_op() {
        // -C probe and -D delete share the same shape as -A, differing only in
        // the op flag — so an installed rule can be probed/removed exactly.
        let probe = masquerade_rule_args("-C", "10.200.0.0/16");
        let delete = masquerade_rule_args("-D", "10.200.0.0/16");
        assert_eq!(probe[2], "-C");
        assert_eq!(delete[2], "-D");
        assert_eq!(&probe[3..], &delete[3..]);
        // The negated output-interface match must survive verbatim.
        assert_eq!(probe[6], "!");
        assert_eq!(probe[7], "-o");
        assert_eq!(probe[8], "zl-+");
    }

    /// Root-gated kernel test: exercises the exact `iptables -t nat` operations
    /// the production masquerade functions use (chain create, a
    /// `-s <cidr> ! -o zl-+ -j MASQUERADE` append, a `POSTROUTING` jump, then
    /// teardown) against the real backend.
    ///
    /// It uses a uniquely-named throwaway chain — NOT the production
    /// `ZLAYER-OVERLAY-NAT` — so running it on a live `ZLayer` host never
    /// disturbs the daemon's own egress masquerade. All probes are collected and
    /// the chain is torn down *before* asserting, so a failed assertion still
    /// leaves the kernel clean. Skips gracefully when not root or `iptables` is
    /// missing.
    #[test]
    #[ignore = "Requires root (mutates the nat table via iptables)"]
    fn masquerade_against_kernel_nat_table_installs_and_removes() {
        const TEST_CHAIN: &str = "ZLTEST-NAT-EGRESS";
        const CIDR: &str = "10.211.0.0/16";

        // Skip if iptables can't even list the nat table (no binary / no privs).
        let Ok(true) = run("iptables", &["-t", "nat", "-L", "-n"]) else {
            eprintln!("skipping: iptables nat table not accessible (need root)");
            return;
        };

        let probe_rule = [
            "-t",
            "nat",
            "-C",
            TEST_CHAIN,
            "-s",
            CIDR,
            "!",
            "-o",
            "zl-+",
            "-j",
            "MASQUERADE",
        ];
        let probe_jump = ["-t", "nat", "-C", "POSTROUTING", "-j", TEST_CHAIN];

        // --- install ---
        let _ = run("iptables", &["-t", "nat", "-N", TEST_CHAIN]);
        let _ = run("iptables", &["-t", "nat", "-F", TEST_CHAIN]);
        let add_rule = run(
            "iptables",
            &[
                "-t",
                "nat",
                "-A",
                TEST_CHAIN,
                "-s",
                CIDR,
                "!",
                "-o",
                "zl-+",
                "-j",
                "MASQUERADE",
            ],
        );
        let add_jump = run(
            "iptables",
            &["-t", "nat", "-A", "POSTROUTING", "-j", TEST_CHAIN],
        );

        // --- verify present ---
        let rule_present = run("iptables", &probe_rule).unwrap_or(false);
        let jump_present = run("iptables", &probe_jump).unwrap_or(false);

        // --- teardown (always, before asserting) ---
        let _ = run(
            "iptables",
            &["-t", "nat", "-D", "POSTROUTING", "-j", TEST_CHAIN],
        );
        let _ = run("iptables", &["-t", "nat", "-F", TEST_CHAIN]);
        let _ = run("iptables", &["-t", "nat", "-X", TEST_CHAIN]);

        let rule_gone = !run("iptables", &probe_rule).unwrap_or(false);
        let jump_gone = !run("iptables", &probe_jump).unwrap_or(false);

        assert!(add_rule.unwrap_or(false), "masquerade -A should succeed");
        assert!(
            add_jump.unwrap_or(false),
            "POSTROUTING jump -A should succeed"
        );
        assert!(
            rule_present,
            "masquerade rule should be present after install"
        );
        assert!(
            jump_present,
            "POSTROUTING jump should be present after install"
        );
        assert!(rule_gone, "masquerade rule should be gone after teardown");
        assert!(jump_gone, "POSTROUTING jump should be gone after teardown");
    }

    fn ip(s: &str) -> IpAddr {
        s.parse().expect("valid IP literal")
    }

    #[test]
    fn iso_pair_rule_args_builds_bidirectional_return() {
        // member -> peer allow is exactly the -s/-d RETURN form on ISO_CHAIN.
        assert_eq!(
            iso_pair_rule_args("-I", ip("10.200.1.5"), ip("10.200.2.7")),
            vec![
                "-I",
                "ZLAYER-OVERLAY-ISO",
                "-s",
                "10.200.1.5",
                "-d",
                "10.200.2.7",
                "-j",
                "RETURN",
            ]
        );
        // The reverse direction simply swaps -s and -d.
        assert_eq!(
            iso_pair_rule_args("-I", ip("10.200.2.7"), ip("10.200.1.5")),
            vec![
                "-I",
                "ZLAYER-OVERLAY-ISO",
                "-s",
                "10.200.2.7",
                "-d",
                "10.200.1.5",
                "-j",
                "RETURN",
            ]
        );
    }

    #[test]
    fn iso_node_rule_args_appends_host_mask() {
        // The node allow host-masks the destination (/32 for v4) and RETURNs.
        assert_eq!(
            iso_node_rule_args("-I", ip("10.200.1.5"), ip("10.200.0.1")),
            vec![
                "-I",
                "ZLAYER-OVERLAY-ISO",
                "-s",
                "10.200.1.5",
                "-d",
                "10.200.0.1/32",
                "-j",
                "RETURN",
            ]
        );
        // IPv6 node IPs get a /128 host mask.
        assert_eq!(
            iso_node_rule_args("-I", ip("fd00::5"), ip("fd00::1")),
            vec![
                "-I",
                "ZLAYER-OVERLAY-ISO",
                "-s",
                "fd00::5",
                "-d",
                "fd00::1/128",
                "-j",
                "RETURN",
            ]
        );
    }

    #[test]
    fn iso_drop_rule_args_builds_overlay_catch_all() {
        // The catch-all DROP isolates the member from the rest of the overlay.
        assert_eq!(
            iso_drop_rule_args("-A", ip("10.200.1.5"), "10.200.0.0/16"),
            vec![
                "-A",
                "ZLAYER-OVERLAY-ISO",
                "-s",
                "10.200.1.5",
                "-d",
                "10.200.0.0/16",
                "-j",
                "DROP",
            ]
        );
    }

    #[test]
    fn iso_rule_args_ops_differ_only_by_leading_flag() {
        // -C probe, -A/-I install, and -D delete share the same shape, differing
        // only in the leading op — so an installed rule can be probed/removed
        // exactly by the same builder.
        let m = ip("10.200.1.5");
        let p = ip("10.200.2.7");
        let n = ip("10.200.0.1");

        let check = iso_pair_rule_args("-C", m, p);
        let install = iso_pair_rule_args("-A", m, p);
        let delete = iso_pair_rule_args("-D", m, p);
        assert_eq!(check[0], "-C");
        assert_eq!(install[0], "-A");
        assert_eq!(delete[0], "-D");
        assert_eq!(&check[1..], &install[1..]);
        assert_eq!(&check[1..], &delete[1..]);

        let nc = iso_node_rule_args("-C", m, n);
        let nd = iso_node_rule_args("-D", m, n);
        assert_eq!(nc[0], "-C");
        assert_eq!(nd[0], "-D");
        assert_eq!(&nc[1..], &nd[1..]);

        let dc = iso_drop_rule_args("-C", m, "10.200.0.0/16");
        let dd = iso_drop_rule_args("-D", m, "10.200.0.0/16");
        assert_eq!(dc[0], "-C");
        assert_eq!(dd[0], "-D");
        assert_eq!(&dc[1..], &dd[1..]);
    }

    #[test]
    fn raft_port_rule_uses_tcp() {
        assert_eq!(
            port_rule_args("-A", 7000, "tcp"),
            vec![
                "-A",
                "ZLAYER-OVERLAY-IN",
                "-p",
                "tcp",
                "--dport",
                "7000",
                "-j",
                "ACCEPT",
            ]
        );
    }
}