zlayer-overlay 0.13.0

//! macOS overlay firewall management via the `pfctl` packet filter.
//!
//! `ZLayer`'s overlay DNS server listens on the node overlay IP, and the
//! cluster's `WireGuard` / API / Raft ports plus dynamically-published service
//! ports must reach the host. On Linux this is enforced through `iptables`
//! chains (see `firewall/linux.rs`); on macOS the kernel packet filter is
//! `pf`, configured with `pfctl`.
//!
//! ## How `pf` anchors work on macOS
//!
//! macOS does not let an external process splice rules into the live ruleset
//! the way `iptables -I` does. The supported mechanism is a named **anchor**:
//! a sub-ruleset loaded from a file. Critically, macOS only *evaluates* an
//! anchor if `/etc/pf.conf` (the ruleset `pf` loads at boot / on `-f`)
//! references it with both an `anchor "<name>"` declaration and a
//! `load anchor "<name>" from "<file>"` directive. A dangling anchor file
//! that `/etc/pf.conf` never mentions has no effect.
//!
//! So this module, idempotently:
//!   1. writes our rules to [`ANCHOR_FILE`],
//!   2. ensures `/etc/pf.conf` references the anchor (appending our two marked
//!      lines only if absent), and
//!   3. reloads (`pfctl -f /etc/pf.conf`) and enables (`pfctl -E`) `pf`.
//!
//! ## Honesty about macOS firewalling
//!
//! macOS ships with `pf` **disabled** by default — the user-facing firewall is
//! the application-layer Application Firewall (`socketfilterfw`), not a
//! port-based packet filter. On a stock host, inbound ports are already open
//! and these rules are belt-and-suspenders. Accordingly, if any `pfctl` step
//! fails because we're not root or `pf` is administratively unavailable, we
//! log a [`tracing::warn!`] naming the ports that should be opened manually and
//! return `Ok(())` — overlay setup must never abort on a firewall hiccup. Only
//! a genuinely unclassifiable failure surfaces as an `Err`.

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

use super::FirewallError;

/// Path of the anchor ruleset file `ZLayer` writes and `/etc/pf.conf` loads.
const ANCHOR_FILE: &str = "/etc/pf.anchors/zlayer-overlay";

/// The main `pf` configuration file macOS loads on `pfctl -f`.
const PF_CONF: &str = "/etc/pf.conf";

/// Marker comment that tags every line `ZLayer` appends to `/etc/pf.conf`, so
/// [`remove_overlay_rules`] can find and strip exactly our additions without
/// disturbing operator-authored rules.
const PF_CONF_MARKER: &str = "# managed by zlayer-overlay";

/// The `anchor` declaration line `ZLayer` injects into `/etc/pf.conf`.
const ANCHOR_DECL: &str = "anchor \"zlayer-overlay\"";

/// The `load anchor` directive line `ZLayer` injects into `/etc/pf.conf`.
const ANCHOR_LOAD: &str = "load anchor \"zlayer-overlay\" from \"/etc/pf.anchors/zlayer-overlay\"";

/// Build the full anchor ruleset text for the cluster ports.
///
/// Emits a `pass in quick proto <proto> from any to any port <port>` rule for
/// each of: `WireGuard` (UDP), API (TCP), Raft (TCP), and DNS (both UDP and TCP
/// on port 53). `quick` makes each match terminal, matching how an explicit
/// allow-list anchor is expected to behave.
///
/// Pure function (no I/O) so it can be unit-tested directly.
fn build_overlay_anchor(wg_port: u16, api_port: u16, raft_port: u16) -> String {
    let mut out = String::new();
    out.push_str("# managed by zlayer-overlay — DO NOT EDIT (regenerated by ZLayer)\n");
    out.push_str("# Overlay cluster + DNS allow-rules.\n");
    out.push_str(&pass_rule(wg_port, true));
    out.push_str(&pass_rule(api_port, false));
    out.push_str(&pass_rule(raft_port, false));
    out.push_str(&pass_rule(53, true));
    out.push_str(&pass_rule(53, false));
    out
}

/// Render a single `pass in quick` rule line (with trailing newline) for the
/// given port, choosing `udp` when `udp` is true, otherwise `tcp`.
fn pass_rule(port: u16, udp: bool) -> String {
    let proto = if udp { "udp" } else { "tcp" };
    format!("pass in quick proto {proto} from any to any port {port}\n")
}

/// Ensure `/etc/pf.conf` text references our anchor.
///
/// Given the current contents of `/etc/pf.conf`, return the contents that
/// should be written back: the `anchor` declaration and the `load anchor`
/// directive are each appended (tagged with [`PF_CONF_MARKER`]) only if not
/// already present. Returns `None` when no change is needed, so the caller can
/// skip the write (and the privileged file mutation) entirely.
///
/// Pure function (no I/O) so it can be unit-tested directly.
fn inject_pf_conf(current: &str) -> Option<String> {
    let has_decl = current
        .lines()
        .any(|l| l.trim() == ANCHOR_DECL || l.trim_start().starts_with(ANCHOR_DECL));
    let has_load = current
        .lines()
        .any(|l| l.trim() == ANCHOR_LOAD || l.trim_start().starts_with(ANCHOR_LOAD));
    if has_decl && has_load {
        return None;
    }

    let mut out = current.to_string();
    if !out.is_empty() && !out.ends_with('\n') {
        out.push('\n');
    }
    // macOS pf requires all `anchor` declarations to appear before any
    // `load anchor` directives, and both after the option/normalization
    // rules; appending at the end of a default pf.conf satisfies this since
    // the stock file has no anchors of its own.
    if !has_decl {
        out.push_str(ANCHOR_DECL);
        out.push(' ');
        out.push_str(PF_CONF_MARKER);
        out.push('\n');
    }
    if !has_load {
        out.push_str(ANCHOR_LOAD);
        out.push(' ');
        out.push_str(PF_CONF_MARKER);
        out.push('\n');
    }
    Some(out)
}

/// Strip the `ZLayer`-marked anchor lines from `/etc/pf.conf` text.
///
/// Removes any line that carries [`PF_CONF_MARKER`] (i.e. lines we appended in
/// [`inject_pf_conf`]). Returns the cleaned contents, leaving every other line
/// — including operator-authored rules — untouched.
///
/// Pure function (no I/O) so it can be unit-tested directly.
fn strip_pf_conf(current: &str) -> String {
    let mut out = String::new();
    for line in current.lines().filter(|l| !l.contains(PF_CONF_MARKER)) {
        out.push_str(line);
        out.push('\n');
    }
    // Preserve the "no trailing newline" shape of an input that had none and
    // ended up empty, to avoid spuriously rewriting an already-clean file.
    if !current.ends_with('\n') {
        let _ = out.pop();
    }
    out
}

/// Add or remove a single published-port rule in anchor-file text.
///
/// Given the current anchor-file contents, ensure the
/// `pass in quick proto <tcp|udp> ... port <port>` line is present (when
/// `add` is true) or absent (when `add` is false). Idempotent and convergent:
/// the rule is never duplicated, and removing an already-absent rule is a
/// no-op. Returns the new contents.
///
/// Pure function (no I/O) so it can be unit-tested directly.
fn edit_published_port(current: &str, port: u16, udp: bool, add: bool) -> String {
    let rule = pass_rule(port, udp);
    let rule_line = rule.trim_end();

    // Drop any existing copy of this exact rule first (de-dup / removal).
    let mut out = String::new();
    for line in current.lines().filter(|l| l.trim_end() != rule_line) {
        out.push_str(line);
        out.push('\n');
    }

    if add {
        out.push_str(&rule);
    }
    out
}

/// Read a file to a `String`, returning an empty string when it does not exist
/// yet (so callers can treat "missing" and "empty" identically for the
/// convergent read-modify-write flows below).
fn read_or_empty(path: &str) -> Result<String, std::io::Error> {
    match std::fs::read_to_string(path) {
        Ok(s) => Ok(s),
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(String::new()),
        Err(e) => Err(e),
    }
}

/// Reload `pf` from `/etc/pf.conf` and ensure it is enabled.
///
/// `pfctl -f` reloads the ruleset (picking up anchor changes); `pfctl -E`
/// enables `pf` with a reference count (the modern enable, tolerant of `pf`
/// already being on). Returns `Ok(false)` — *not* an error — when a step fails
/// for an expected reason (not root / `pf` unavailable), so the caller can
/// downgrade to a warning. Returns `Err` only when `pfctl` cannot be spawned.
fn reload_pf() -> Result<bool, FirewallError> {
    let load = Command::new("pfctl")
        .args(["-f", PF_CONF])
        .output()
        .map_err(|e| FirewallError::AddRule {
            name: "pfctl -f /etc/pf.conf".to_string(),
            reason: e.to_string(),
        })?;
    if !load.status.success() {
        let stderr = String::from_utf8_lossy(&load.stderr);
        // Not-root / operation-not-permitted is the common, expected case.
        if is_permission_failure(&stderr) {
            return Ok(false);
        }
        return Err(FirewallError::AddRule {
            name: "pfctl -f /etc/pf.conf".to_string(),
            reason: stderr.trim().to_string(),
        });
    }

    let enable = Command::new("pfctl")
        .arg("-E")
        .output()
        .map_err(|e| FirewallError::AddRule {
            name: "pfctl -E".to_string(),
            reason: e.to_string(),
        })?;
    if !enable.status.success() {
        let stderr = String::from_utf8_lossy(&enable.stderr);
        // `pfctl -E` prints "pf already enabled" (or similar) to stderr and may
        // exit non-zero; that is success for our purposes.
        if stderr.contains("already enabled") || stderr.contains("altered to") {
            return Ok(true);
        }
        if is_permission_failure(&stderr) {
            return Ok(false);
        }
        return Err(FirewallError::AddRule {
            name: "pfctl -E".to_string(),
            reason: stderr.trim().to_string(),
        });
    }
    Ok(true)
}

/// Heuristic for "this `pfctl` failure is because we lack privilege / `pf` is
/// administratively unavailable" — the expected, non-fatal case on a default
/// macOS host where `pf` is off and only root may touch it.
fn is_permission_failure(stderr: &str) -> bool {
    let s = stderr.to_ascii_lowercase();
    s.contains("permission denied")
        || s.contains("operation not permitted")
        || s.contains("you must be root")
        || s.contains("not permitted")
        || s.contains("/dev/pf")
}

/// Install (idempotently) the overlay allow-rules for the cluster's `WireGuard`,
/// API, Raft, and DNS ports.
///
/// Writes the anchor ruleset to [`ANCHOR_FILE`], ensures `/etc/pf.conf`
/// references the anchor, and reloads + enables `pf`.
///
/// # Errors
///
/// Returns [`FirewallError::AddRule`] only for a genuinely unexpected failure
/// (e.g. `pfctl` missing, or an unclassifiable `pfctl` error). A
/// not-root / `pf`-unavailable failure is logged via [`tracing::warn!`] and
/// reported as `Ok(())` — overlay setup must not abort on it.
pub fn ensure_overlay_rules(
    wg_port: u16,
    api_port: u16,
    raft_port: u16,
) -> Result<(), FirewallError> {
    let ruleset = build_overlay_anchor(wg_port, api_port, raft_port);

    // 1 + 2: write the anchor file (create the anchors dir if needed).
    if let Some(dir) = Path::new(ANCHOR_FILE).parent() {
        if let Err(e) = std::fs::create_dir_all(dir) {
            if e.kind() != std::io::ErrorKind::AlreadyExists {
                return warn_manual_ports(wg_port, api_port, raft_port, &e.to_string());
            }
        }
    }
    if let Err(e) = std::fs::write(ANCHOR_FILE, &ruleset) {
        // Almost always EACCES (not root). Treat as the non-fatal case.
        return warn_manual_ports(wg_port, api_port, raft_port, &e.to_string());
    }

    // 3: ensure /etc/pf.conf references the anchor (idempotent append).
    let conf = match read_or_empty(PF_CONF) {
        Ok(c) => c,
        Err(e) => return warn_manual_ports(wg_port, api_port, raft_port, &e.to_string()),
    };
    if let Some(updated) = inject_pf_conf(&conf) {
        if let Err(e) = std::fs::write(PF_CONF, updated) {
            return warn_manual_ports(wg_port, api_port, raft_port, &e.to_string());
        }
    }

    // 4: reload + enable pf.
    if reload_pf()? {
        Ok(())
    } else {
        warn_manual_ports(
            wg_port,
            api_port,
            raft_port,
            "pfctl requires root / pf is unavailable",
        )
    }
}

/// Log the belt-and-suspenders warning naming the ports that should be opened
/// by hand, then return `Ok(())`. Centralised so every non-fatal bail-out in
/// [`ensure_overlay_rules`] emits a consistent message.
///
/// Always returns `Ok(())`: callers use it as `return warn_manual_ports(..)` to
/// turn a non-fatal pf failure into the success path, so the `Result` return is
/// intentional API symmetry with [`ensure_overlay_rules`], not an oversight.
#[allow(clippy::unnecessary_wraps)]
fn warn_manual_ports(
    wg_port: u16,
    api_port: u16,
    raft_port: u16,
    reason: &str,
) -> Result<(), FirewallError> {
    tracing::warn!(
        reason,
        "could not configure macOS pf overlay rules; macOS ships with pf \
         disabled by default (the Application Firewall is app-based, not \
         port-based), so this is normally belt-and-suspenders. If your host \
         has pf enabled, open these inbound ports manually: WireGuard udp/{wg}, \
         API tcp/{api}, Raft tcp/{raft}, DNS udp/53 + tcp/53",
        wg = wg_port,
        api = api_port,
        raft = raft_port,
    );
    Ok(())
}

/// Remove the overlay anchor and its `/etc/pf.conf` references, then reload
/// `pf`.
///
/// Deletes [`ANCHOR_FILE`], strips the two `ZLayer`-marked lines from
/// `/etc/pf.conf`, and reloads. Every step tolerates a missing file/line.
///
/// # Errors
///
/// As with [`ensure_overlay_rules`], a not-root / `pf`-unavailable failure is
/// downgraded to a warning and reported as `Ok(())`. Returns
/// [`FirewallError::RemoveRule`] only for an unclassifiable failure.
pub fn remove_overlay_rules() -> Result<(), FirewallError> {
    // Delete the anchor file; missing is fine.
    if let Err(e) = std::fs::remove_file(ANCHOR_FILE) {
        if e.kind() != std::io::ErrorKind::NotFound {
            // EACCES (not root) is the expected non-fatal case.
            tracing::warn!(
                error = %e,
                "could not remove macOS pf overlay anchor file {ANCHOR_FILE}; \
                 skipping (pf is likely disabled / requires root)"
            );
            return Ok(());
        }
    }

    // Strip our marked lines from /etc/pf.conf, rewriting only if changed.
    match read_or_empty(PF_CONF) {
        Ok(conf) => {
            let stripped = strip_pf_conf(&conf);
            if stripped != conf {
                if let Err(e) = std::fs::write(PF_CONF, stripped) {
                    tracing::warn!(
                        error = %e,
                        "could not rewrite {PF_CONF} to drop overlay anchor refs"
                    );
                    return Ok(());
                }
            }
        }
        Err(e) => {
            tracing::warn!(error = %e, "could not read {PF_CONF} during overlay teardown");
            return Ok(());
        }
    }

    // Reload pf so the removal takes effect. Best-effort.
    match reload_pf() {
        Ok(_) => Ok(()),
        Err(FirewallError::AddRule { name, reason }) => {
            // reload_pf only ever yields AddRule; re-tag as RemoveRule for this
            // teardown path, but keep it non-fatal.
            tracing::warn!(name, reason, "pf reload failed during overlay teardown");
            Err(FirewallError::RemoveRule { name, reason })
        }
        Err(other) => Err(other),
    }
}

/// Open a single published service port in the overlay anchor.
///
/// Reads the current anchor file, adds the `pass in quick` rule for `port`
/// (TCP unless `udp`), rewrites the file, and reloads `pf`. Idempotent: a
/// repeated call does not duplicate the rule.
///
/// # Errors
///
/// Non-fatal not-root / `pf`-unavailable failures are warned and reported as
/// `Ok(())`. Returns [`FirewallError::AddRule`] only for an unclassifiable
/// failure (e.g. `pfctl` missing).
pub fn ensure_published_port(port: u16, udp: bool) -> Result<(), FirewallError> {
    let current = match read_or_empty(ANCHOR_FILE) {
        Ok(c) => c,
        Err(e) => {
            tracing::warn!(error = %e, "could not read pf anchor file to publish port {port}");
            return Ok(());
        }
    };
    let updated = edit_published_port(&current, port, udp, true);
    if updated != current {
        if let Err(e) = std::fs::write(ANCHOR_FILE, updated) {
            tracing::warn!(error = %e, "could not write pf anchor file to publish port {port}");
            return Ok(());
        }
    }
    if reload_pf()? {
        Ok(())
    } else {
        tracing::warn!(
            "pf unavailable / not root; published port {port} ({proto}) not enforced — \
             open it manually if your host has pf enabled",
            proto = if udp { "udp" } else { "tcp" },
        );
        Ok(())
    }
}

/// Close a previously-published service port in the overlay anchor.
///
/// Mirror of [`ensure_published_port`] with `add = false`. Swallows all errors
/// (returns `()`): teardown must never fail a caller, and an absent rule or a
/// disabled `pf` is a no-op.
pub fn remove_published_port(port: u16, udp: bool) {
    let Ok(current) = read_or_empty(ANCHOR_FILE) else {
        return;
    };
    let updated = edit_published_port(&current, port, udp, false);
    if updated != current && std::fs::write(ANCHOR_FILE, updated).is_err() {
        return;
    }
    // Best-effort reload; ignore every outcome.
    let _ = reload_pf();
}

// ---------------------------------------------------------------------------
// Per-network L3 isolation (Docker-style) — the macOS analog of the Linux
// `ZLAYER-OVERLAY-ISO` iptables chain.
//
// On macOS a VZ Linux guest cannot reach sibling guests or remote nodes
// directly: ALL its overlay traffic hairpins through THIS node's WireGuard
// device, which forwards it. That makes the node the enforcement point for the
// guests it hosts — exactly where pf sits. We model each isolated overlay
// network as a pf TABLE of its member IPs plus a per-network sub-anchor holding
// a fixed rule template, so membership churn is a table mutation (`pfctl -T add`
// / `-T delete`) and never a rule re-push:
//
//   table <zliso_HASH> persist
//   pass quick from <zliso_HASH> to <zliso_HASH>     # same network allowed
//   pass quick from <zliso_HASH> to <node_ip>        # daemon node reachable
//   pass quick from <zliso_HASH> to ! <overlay_cidr> # egress (non-overlay) ok
//   block drop quick from <zliso_HASH> to <overlay_cidr> # cross-network blocked
//
// `quick` makes the first matching rule terminal. pf tables hold only host
// addresses, so the table name and the rule template are independent of the
// member set; adding/removing a member is a pure table op against the loaded
// sub-anchor.
// ---------------------------------------------------------------------------

/// Root directory under which per-network isolation sub-anchors are loaded.
/// Each network gets a child anchor `zlayer-overlay-iso/<short-hash>`.
const ISO_ANCHOR_ROOT: &str = "zlayer-overlay-iso";

/// Directory holding the per-network isolation sub-anchor rule files.
const ISO_ANCHOR_DIR: &str = "/etc/pf.anchors";

/// Derive a stable short hash of the network name for use in pf table /
/// sub-anchor names. pf table names must be <= 31 chars; `zliso_` (6) + 16 hex
/// digits = 22, comfortably within the limit.
fn network_hash(network: &str) -> String {
    use std::collections::hash_map::DefaultHasher;
    use std::hash::{Hash, Hasher};

    let mut hasher = DefaultHasher::new();
    network.hash(&mut hasher);
    format!("{:016x}", hasher.finish())
}

/// pf table name for `network` (e.g. `zliso_1a2b3c4d5e6f7a8b`).
fn iso_table_name(network: &str) -> String {
    format!("zliso_{}", network_hash(network))
}

/// Sub-anchor path for `network` (e.g. `zlayer-overlay-iso/1a2b3c4d5e6f7a8b`).
fn iso_anchor_name(network: &str) -> String {
    format!("{ISO_ANCHOR_ROOT}/{}", network_hash(network))
}

/// On-disk rule file for `network`'s sub-anchor.
fn iso_anchor_file(network: &str) -> String {
    format!(
        "{ISO_ANCHOR_DIR}/zlayer-overlay-iso-{}",
        network_hash(network)
    )
}

/// Build the fixed pf rule template for an isolated network's sub-anchor.
///
/// The `table` declaration is `persist` so it survives an empty member set, and
/// the four rules reference it by name. `to ! <cidr>` is pf's address negation
/// (egress to anything outside the overlay is allowed); the final `block drop`
/// catches cross-network / cluster traffic. `quick` gives first-match-wins.
///
/// Pure function (no I/O) so it can be unit-tested directly.
fn build_iso_anchor(table: &str, node_ip: IpAddr, overlay_cidr: &str) -> String {
    use std::fmt::Write as _;
    let host_mask = if node_ip.is_ipv6() { "128" } else { "32" };
    let mut out = String::new();
    out.push_str("# managed by zlayer-overlay — DO NOT EDIT (regenerated by ZLayer)\n");
    out.push_str("# Per-network L3 isolation anchor.\n");
    let _ = writeln!(out, "table <{table}> persist");
    let _ = writeln!(out, "pass quick from <{table}> to <{table}>");
    let _ = writeln!(out, "pass quick from <{table}> to {node_ip}/{host_mask}");
    let _ = writeln!(out, "pass quick from <{table}> to ! {overlay_cidr}");
    let _ = writeln!(out, "block drop quick from <{table}> to {overlay_cidr}");
    out
}

/// Load (idempotently) the sub-anchor for `network` with the fixed isolation
/// template referencing the network's pf table, via
/// `pfctl -a <anchor> -f <file>`.
///
/// Returns `Ok(false)` — *not* an error — when the load fails for an expected
/// reason (not root / `pf` unavailable), mirroring [`reload_pf`]. Returns `Err`
/// only when `pfctl` cannot be spawned or fails unclassifiably.
fn load_iso_anchor(
    network: &str,
    node_ip: IpAddr,
    overlay_cidr: &str,
) -> Result<bool, FirewallError> {
    let table = iso_table_name(network);
    let file = iso_anchor_file(network);
    let anchor = iso_anchor_name(network);
    let ruleset = build_iso_anchor(&table, node_ip, overlay_cidr);

    if let Some(dir) = Path::new(&file).parent() {
        if let Err(e) = std::fs::create_dir_all(dir) {
            if e.kind() != std::io::ErrorKind::AlreadyExists {
                return Ok(false);
            }
        }
    }
    if std::fs::write(&file, &ruleset).is_err() {
        // Almost always EACCES (not root) — the expected non-fatal case.
        return Ok(false);
    }

    let load = Command::new("pfctl")
        .args(["-a", &anchor, "-f", &file])
        .output()
        .map_err(|e| FirewallError::AddRule {
            name: format!("pfctl -a {anchor} -f {file}"),
            reason: e.to_string(),
        })?;
    if load.status.success() {
        return Ok(true);
    }
    let stderr = String::from_utf8_lossy(&load.stderr);
    if is_permission_failure(&stderr) {
        return Ok(false);
    }
    Err(FirewallError::AddRule {
        name: format!("pfctl -a {anchor} -f {file}"),
        reason: stderr.trim().to_string(),
    })
}

/// Install (idempotently) Docker-style L3 isolation for one overlay member on
/// the macOS node, enforced against the hairpinned VZ-guest traffic this node
/// forwards.
///
/// Loads the per-`network` sub-anchor with the fixed isolation template (so the
/// rules are present even on the first member), then adds `member_ip` to the
/// network's pf table. `peers` is unused on macOS — the table + the
/// `from <table> to <table>` rule already permit every same-network member, so
/// membership is a single table op, not a pairwise rule set.
///
/// Mirrors the non-fatal contract of [`ensure_overlay_rules`]: a not-root /
/// `pf`-unavailable failure is logged via [`tracing::warn!`] and reported as
/// `Ok(())` — overlay attach must never abort on a firewall hiccup.
///
/// # Errors
///
/// Returns [`FirewallError::AddRule`] only for a genuinely unexpected failure
/// (e.g. `pfctl` missing, or an unclassifiable `pfctl` error).
pub fn ensure_member_isolation(
    network: &str,
    member_ip: IpAddr,
    peers: &[IpAddr],
    node_ip: IpAddr,
    overlay_cidr: &str,
) -> Result<(), FirewallError> {
    // The pf table + same-network rule cover every member, so per-peer rules are
    // unnecessary on macOS.
    let _ = peers;

    if !load_iso_anchor(network, node_ip, overlay_cidr)? {
        tracing::warn!(
            network,
            member = %member_ip,
            "could not load macOS pf isolation anchor (pf disabled / requires root); \
             per-network L3 isolation not enforced on this node"
        );
        return Ok(());
    }

    let table = iso_table_name(network);
    let anchor = iso_anchor_name(network);
    let member = member_ip.to_string();
    let add = Command::new("pfctl")
        .args(["-a", &anchor, "-t", &table, "-T", "add", &member])
        .output()
        .map_err(|e| FirewallError::AddRule {
            name: format!("pfctl -a {anchor} -t {table} -T add {member}"),
            reason: e.to_string(),
        })?;
    if !add.status.success() {
        let stderr = String::from_utf8_lossy(&add.stderr);
        if is_permission_failure(&stderr) {
            tracing::warn!(
                network,
                member = %member_ip,
                "could not add member to macOS pf isolation table (pf disabled / requires root)"
            );
            return Ok(());
        }
        return Err(FirewallError::AddRule {
            name: format!("pfctl -a {anchor} -t {table} -T add {member}"),
            reason: stderr.trim().to_string(),
        });
    }
    Ok(())
}

/// Remove `member_ip` from `network`'s pf isolation table (the counterpart of
/// [`ensure_member_isolation`]). Best-effort: every failure (including a missing
/// table / disabled `pf`) is swallowed. The sub-anchor and table are left loaded
/// even when empty — other members may still use them, and a `persist` table is
/// cheap to leave in place.
///
/// `peers`, `node_ip`, and `overlay_cidr` are accepted for signature parity with
/// the Linux backend; only the table name (derived from `network`) and
/// `member_ip` matter for a delete.
pub fn remove_member_isolation(
    network: &str,
    member_ip: IpAddr,
    peers: &[IpAddr],
    node_ip: IpAddr,
    overlay_cidr: &str,
) {
    let _ = (peers, node_ip, overlay_cidr);
    let table = iso_table_name(network);
    let anchor = iso_anchor_name(network);
    let member = member_ip.to_string();
    let _ = Command::new("pfctl")
        .args(["-a", &anchor, "-t", &table, "-T", "delete", &member])
        .output();
}

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

    #[test]
    fn anchor_text_contains_all_cluster_ports() {
        let text = build_overlay_anchor(51820, 3669, 4001);
        assert!(text.contains("pass in quick proto udp from any to any port 51820"));
        assert!(text.contains("pass in quick proto tcp from any to any port 3669"));
        assert!(text.contains("pass in quick proto tcp from any to any port 4001"));
        // DNS on both protocols, port 53.
        assert!(text.contains("pass in quick proto udp from any to any port 53"));
        assert!(text.contains("pass in quick proto tcp from any to any port 53"));
        // Header marker so removal/regeneration can recognise our file.
        assert!(text.contains("managed by zlayer-overlay"));
    }

    #[test]
    fn anchor_text_honours_custom_ports() {
        let text = build_overlay_anchor(1, 2, 3);
        assert!(text.contains("port 1\n"));
        assert!(text.contains("port 2\n"));
        assert!(text.contains("port 3\n"));
    }

    #[test]
    fn pass_rule_picks_proto() {
        assert_eq!(
            pass_rule(80, false),
            "pass in quick proto tcp from any to any port 80\n"
        );
        assert_eq!(
            pass_rule(53, true),
            "pass in quick proto udp from any to any port 53\n"
        );
    }

    #[test]
    fn inject_appends_both_lines_to_empty_conf() {
        let updated = inject_pf_conf("").expect("empty conf must change");
        assert!(updated.contains(ANCHOR_DECL));
        assert!(updated.contains(ANCHOR_LOAD));
        assert!(updated.contains(PF_CONF_MARKER));
    }

    #[test]
    fn inject_is_idempotent() {
        let base = "scrub-anchor \"com.apple/*\"\n";
        let once = inject_pf_conf(base).expect("first inject must change");
        // A second pass over the already-injected text must be a no-op.
        assert!(inject_pf_conf(&once).is_none());
    }

    #[test]
    fn inject_does_not_duplicate_when_decl_present_without_load() {
        let base = format!("{ANCHOR_DECL}\n");
        let updated = inject_pf_conf(&base).expect("missing load must be added");
        // The declaration must not be duplicated. Count decl *lines* (not raw
        // substring matches): `ANCHOR_DECL` is a substring of `ANCHOR_LOAD`
        // (`load anchor "zlayer-overlay" …`), so a substring count would also
        // catch the load line and report 2.
        let decl_count = updated
            .lines()
            .filter(|l| l.trim_start().starts_with(ANCHOR_DECL))
            .count();
        assert_eq!(decl_count, 1, "anchor decl should appear exactly once");
        assert!(updated.contains(ANCHOR_LOAD));
    }

    #[test]
    fn inject_normalizes_missing_trailing_newline() {
        let base = "rdr-anchor \"com.apple/*\""; // no trailing newline
        let updated = inject_pf_conf(base).expect("must change");
        // Original line preserved on its own line.
        assert!(updated.starts_with("rdr-anchor \"com.apple/*\"\n"));
        assert!(updated.contains(ANCHOR_DECL));
    }

    #[test]
    fn strip_removes_only_marked_lines() {
        let conf = format!(
            "scrub-anchor \"com.apple/*\"\n{ANCHOR_DECL} {PF_CONF_MARKER}\n\
             {ANCHOR_LOAD} {PF_CONF_MARKER}\npass out all\n"
        );
        let cleaned = strip_pf_conf(&conf);
        assert!(!cleaned.contains(ANCHOR_DECL));
        assert!(!cleaned.contains(ANCHOR_LOAD));
        assert!(!cleaned.contains(PF_CONF_MARKER));
        // Operator-authored lines are preserved.
        assert!(cleaned.contains("scrub-anchor \"com.apple/*\""));
        assert!(cleaned.contains("pass out all"));
    }

    #[test]
    fn strip_is_noop_on_clean_conf() {
        let conf = "scrub-anchor \"com.apple/*\"\npass out all\n";
        assert_eq!(strip_pf_conf(conf), conf);
    }

    #[test]
    fn inject_then_strip_roundtrips() {
        let base = "scrub-anchor \"com.apple/*\"\n";
        let injected = inject_pf_conf(base).expect("inject changes");
        let stripped = strip_pf_conf(&injected);
        assert_eq!(stripped, base);
    }

    #[test]
    fn edit_published_port_adds_once() {
        let added = edit_published_port("", 8080, false, true);
        assert!(added.contains("pass in quick proto tcp from any to any port 8080"));
        // Adding the same port again must not duplicate it.
        let twice = edit_published_port(&added, 8080, false, true);
        assert_eq!(
            twice.matches("port 8080\n").count(),
            1,
            "published port must not be duplicated"
        );
    }

    #[test]
    fn edit_published_port_removes() {
        let added = edit_published_port("", 9000, true, true);
        assert!(added.contains("port 9000"));
        let removed = edit_published_port(&added, 9000, true, false);
        assert!(!removed.contains("port 9000"));
    }

    #[test]
    fn edit_published_port_remove_absent_is_noop() {
        let base = "pass in quick proto tcp from any to any port 80\n";
        let removed = edit_published_port(base, 443, false, false);
        assert_eq!(removed, base);
    }

    #[test]
    fn edit_published_port_tcp_and_udp_are_distinct() {
        let with_tcp = edit_published_port("", 53, false, true);
        let with_both = edit_published_port(&with_tcp, 53, true, true);
        assert!(with_both.contains("proto tcp from any to any port 53"));
        assert!(with_both.contains("proto udp from any to any port 53"));
        // Removing the UDP one must leave the TCP one intact.
        let only_tcp = edit_published_port(&with_both, 53, true, false);
        assert!(only_tcp.contains("proto tcp from any to any port 53"));
        assert!(!only_tcp.contains("proto udp from any to any port 53"));
    }

    #[test]
    fn permission_failure_classification() {
        assert!(is_permission_failure("pfctl: Operation not permitted"));
        assert!(is_permission_failure("you must be root"));
        assert!(is_permission_failure("pfctl: /dev/pf: Permission denied"));
        assert!(!is_permission_failure("syntax error in rule"));
    }

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

    #[test]
    fn iso_table_name_is_stable_and_within_pf_limit() {
        let a = iso_table_name("net-a");
        let b = iso_table_name("net-a");
        let c = iso_table_name("net-b");
        // Stable for the same network, distinct across networks.
        assert_eq!(a, b);
        assert_ne!(a, c);
        // pf table names must be <= 31 chars; `zliso_` + 16 hex = 22.
        assert!(a.len() <= 31, "pf table name too long: {a}");
        assert!(a.starts_with("zliso_"));
    }

    #[test]
    fn iso_anchor_name_nests_under_root() {
        let anchor = iso_anchor_name("net-a");
        assert!(anchor.starts_with("zlayer-overlay-iso/"));
        // The hash component matches the table's hash suffix.
        let table = iso_table_name("net-a");
        let hash = table.strip_prefix("zliso_").unwrap();
        assert!(anchor.ends_with(hash));
    }

    #[test]
    fn build_iso_anchor_emits_table_and_four_rules() {
        let table = iso_table_name("net-a");
        let text = build_iso_anchor(&table, ip("10.200.0.1"), "10.200.0.0/16");
        // Persistent table declaration.
        assert!(text.contains(&format!("table <{table}> persist")));
        // Same-network allow.
        assert!(text.contains(&format!("pass quick from <{table}> to <{table}>")));
        // Node reachable (host-masked /32 for v4).
        assert!(text.contains(&format!("pass quick from <{table}> to 10.200.0.1/32")));
        // Egress (non-overlay) allowed via pf negation.
        assert!(text.contains(&format!("pass quick from <{table}> to ! 10.200.0.0/16")));
        // Cross-network / cluster blocked.
        assert!(text.contains(&format!("block drop quick from <{table}> to 10.200.0.0/16")));
        // Header marker so the file is recognisable.
        assert!(text.contains("managed by zlayer-overlay"));
    }

    #[test]
    fn build_iso_anchor_host_masks_ipv6_node() {
        let table = iso_table_name("net-v6");
        let text = build_iso_anchor(&table, ip("fd00::1"), "fd00::/16");
        assert!(text.contains(&format!("pass quick from <{table}> to fd00::1/128")));
        assert!(text.contains(&format!("block drop quick from <{table}> to fd00::/16")));
    }
}