ts_control/

node.rs

//! The parsed domain [`Node`] model: a tailnet node decoded from the wire (`tailcfg.Node`).
//!
//! [`Node`] is the owned, validated form the rest of the fork reasons about (addresses, keys, caps,
//! accepted routes, peerAPI/VIP services), built from the borrow-bound `ts_control_serde::Node` via
//! the [`From`] impl. It also carries the route/exit-node/funnel predicates ([`Node::is_subnet_route`],
//! [`Node::routes_to_install`], [`Node::can_funnel`]) and the [`ExitNodeSelector`] resolution.
//!
//! Fail-closed: route, funnel, and service-host gates all deny on a missing/malformed input.

use core::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr};
use std::collections::BTreeMap;

use chrono::{DateTime, Utc};
use ts_capabilityversion::CapabilityVersion;
use ts_keys::{DiscoPublicKey, MachinePublicKey, NodePublicKey};

use crate::dns::Resolver;

/// An owned node-capability map (`Node.CapMap` in Go: `map[NodeCapability][]RawMessage`).
///
/// Keys are capability names or URLs (e.g. `"funnel"`, `"https"`, or
/// `"https://tailscale.com/cap/funnel-ports?ports=443,8443"`); values are the raw JSON-encoded
/// argument blobs for that capability (often empty). Stored *owned* because the wire form
/// ([`ts_control_serde::Node::cap_map`]) borrows from the decode buffer, whereas the domain
/// [`Node`] outlives it. Funnel gating only inspects the keys (see [`Node::can_funnel`] and
/// [`Node::check_funnel_port`]); the values are retained for capabilities that carry argument data.
pub type NodeCapMap = BTreeMap<String, Vec<String>>;

/// Whether `addr` falls in a range Tailscale assigns to nodes: the CGNAT range for IPv4
/// (`100.64.0.0/10`, excluding the ChromeOS VM carve-out `100.115.92.0/23`) and the Tailscale
/// ULA for IPv6 (`fd7a:115c:a1e0::/48`).
///
/// Mirrors `tsaddr.IsTailscaleIP` in the Go client. Used to tell a peer's own node addresses
/// (always single Tailscale IPs) apart from the larger subnet routes it advertises.
pub fn is_tailscale_ip(addr: IpAddr) -> bool {
    match addr {
        IpAddr::V4(v4) => {
            let cgnat = ipnet::Ipv4Net::new(Ipv4Addr::new(100, 64, 0, 0), 10).unwrap();
            let chromeos = ipnet::Ipv4Net::new(Ipv4Addr::new(100, 115, 92, 0), 23).unwrap();
            cgnat.contains(&v4) && !chromeos.contains(&v4)
        }
        IpAddr::V6(v6) => {
            let ula = ipnet::Ipv6Net::new(Ipv6Addr::new(0xfd7a, 0x115c, 0xa1e0, 0, 0, 0, 0, 0), 48)
                .unwrap();
            ula.contains(&v6)
        }
    }
}

/// The unique id of a node.
pub type Id = i64;

/// The stable ID of a node.
#[derive(
    Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, serde::Serialize, serde::Deserialize,
)]
pub struct StableId(pub String);

/// How this node selects which peer to use as its exit node (`--exit-node` in the Go client).
///
/// Mirrors the Go client's `--exit-node`, which accepts a tailnet IP, a MagicDNS name, or a stable
/// node ID, and resolves it to a `StableNodeID` (`resolveExitNodeIPLocked`). We keep the selector
/// *unresolved* and re-run [`ExitNodeSelector::resolve`] against the live peer set on every route
/// rebuild, so an IP- or name-based selection follows the peer as the netmap changes (e.g. the
/// exit node re-registers under a new stable id).
///
/// A selector can be parsed from a string with [`str::parse`]/[`FromStr`](core::str::FromStr),
/// auto-detecting the variant the way the Go CLI's `--exit-node` does: a value that parses as an IP
/// address becomes [`ExitNodeSelector::Ip`], anything else becomes [`ExitNodeSelector::Name`].
/// Stable-id selection is available only by constructing [`ExitNodeSelector::StableId`] directly
/// (it is not auto-detected, since a stable id is otherwise indistinguishable from a hostname).
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum ExitNodeSelector {
    /// Select the peer with this exact stable node id.
    StableId(StableId),
    /// Select the peer whose tailnet address is this IP.
    Ip(IpAddr),
    /// Select the peer matching this bare hostname or MagicDNS name (case-insensitive, optional
    /// trailing dot), as per [`Node::matches_name`].
    Name(String),
}

impl core::str::FromStr for ExitNodeSelector {
    type Err = core::convert::Infallible;

    /// Parse a selector from a string, auto-detecting IP vs. name (matching the Go CLI's
    /// `--exit-node`). Parsing never fails: a non-IP string is taken as a MagicDNS name.
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Ok(match s.parse::<IpAddr>() {
            Ok(ip) => ExitNodeSelector::Ip(ip),
            Err(_) => ExitNodeSelector::Name(s.to_owned()),
        })
    }
}

impl ExitNodeSelector {
    /// Resolve this selector to the stable id of the matching peer, if any, given the current set
    /// of peers.
    ///
    /// Resolution is **deterministic**: if a selector somehow matches more than one peer (e.g. two
    /// peers sharing a MagicDNS name during a transient netmap state), the peer with the smallest
    /// [`StableId`] is chosen. This matters because both the outbound route table and the inbound
    /// source filter resolve independently; a deterministic tiebreak guarantees they pick the
    /// *same* peer, preserving the cryptokey-routing coupling that prevents source-spoofing.
    ///
    /// Returns `None` when no peer matches (a stale/typo'd selector). Callers treat `None` as
    /// fail-closed: no peer is granted a default route, so internet-bound traffic is dropped.
    pub fn resolve<'a>(&self, peers: impl Iterator<Item = &'a Node>) -> Option<StableId> {
        peers
            .filter(|node| match self {
                ExitNodeSelector::StableId(id) => &node.stable_id == id,
                ExitNodeSelector::Ip(ip) => node.tailnet_address.contains(*ip),
                ExitNodeSelector::Name(name) => node.matches_name(name),
            })
            .map(|node| &node.stable_id)
            .min()
            .cloned()
    }
}

/// A node in a tailnet.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct Node {
    /// The node's id.
    pub id: Id,
    /// The node's stable id.
    pub stable_id: StableId,

    /// This node's hostname.
    pub hostname: String,

    /// The integer id of the user that owns this node (`Node.User` in Go). `0` when control sends
    /// no owner (e.g. tagged/ACL nodes have no human owner). Join against the netmap's
    /// `UserProfiles` table (accumulated by the runtime's peer tracker) to resolve a login/display
    /// name — see the runtime `WhoIs` lookup.
    pub user_id: ts_control_serde::UserId,

    /// The tailnet this node belongs to.
    pub tailnet: Option<String>,

    /// The tags assigned to this node.
    pub tags: Vec<String>,

    /// Every prefix control assigned this node (`tailcfg.Node.Addresses`), in wire order.
    ///
    /// Normally one IPv4 `/32` and one IPv6 `/128`, but the wire field is a variable-length list:
    /// an IPv6-off tailnet assigns only the v4 prefix, and nothing in the protocol stops control
    /// assigning more than one prefix of a family.
    ///
    /// [`tailnet_address`](Self::tailnet_address) is the *identity* projection of this list — the
    /// first prefix of each family — and is what the overlay, MagicDNS and exit-node selection
    /// reason about. The whole list is retained because [`is_router`](Self::is_router) has to ask
    /// "is this prefix one of my own?" of **all** of them, exactly as Go's `tailcfg.Node.IsRouter`
    /// does. Keep the two consistent when building a `Node` by hand.
    pub addresses: Vec<ipnet::IpNet>,

    /// The address of the node in the tailnet: the first prefix of each family in
    /// [`addresses`](Self::addresses), with an unspecified placeholder for a family the tailnet
    /// does not assign.
    pub tailnet_address: TailnetAddress,

    /// The node's [`NodePublicKey`].
    pub node_key: NodePublicKey,
    /// The node key's expiration.
    pub node_key_expiry: Option<DateTime<Utc>>,

    /// Whether this node's key is expired (`tailcfg.Node.Expired`).
    ///
    /// Two writers, exactly as upstream. Control may send it on the wire, and the client sets it
    /// itself — only ever `false` → `true` — when
    /// [`node_key_expiry`](Self::node_key_expiry) has passed, so the decision is made against a
    /// clock corrected for control skew rather than the raw local one. See
    /// [`ExpiryManager::flag_expired_peer`](crate::ExpiryManager::flag_expired_peer), which is what
    /// sets it and which also clears this node's endpoints and home DERP and breaks its
    /// [`node_key`](Self::node_key).
    ///
    /// An expired peer is **kept** in the netmap, not dropped: that is what lets a caller answer
    /// [`PEER_KEY_EXPIRED`](crate::PEER_KEY_EXPIRED) rather than "no such peer". Distinct from
    /// [`key_expired`](Self::key_expired), which recomputes the answer from the raw local clock and
    /// is what the **self**-node re-auth decision reads.
    pub expired: bool,

    /// Whether control reports this node currently connected to the coordination server
    /// (`tailcfg.Node.Online`, a tri-state `*bool`). `None` = unknown / no permission to know /
    /// never been online — **do not collapse to `false`** (that would fabricate an offline status
    /// control never asserted). Updated by full nodes AND by the delta channels (a
    /// [`PeerChange::online`], or the `MapResponse.online_change` map).
    pub online: Option<bool>,
    /// When control last saw this node online (`tailcfg.Node.LastSeen`). Per Go, only meaningful
    /// while `online` is not `Some(true)` ("not updated when Online is true"). `None` = unknown /
    /// never online.
    pub last_seen: Option<DateTime<Utc>>,

    /// Marshalled TKA node-key signature (`tailcfg.Node.KeySignature`); empty when control sends
    /// none. Verified against a TKA `Authority` at the peer-trust chokepoint WHEN tailnet-lock
    /// enforcement is active.
    pub key_signature: Vec<u8>,

    /// The node's [`MachinePublicKey`], if known.
    pub machine_key: Option<MachinePublicKey>,
    /// The node's [`DiscoPublicKey`], if known.
    pub disco_key: Option<DiscoPublicKey>,

    /// Whether control marked this node as peerAPI-only and outside tailnet lock's coverage
    /// (`tailcfg.Node.UnsignedPeerAPIOnly`).
    ///
    /// Such a node carries no node-key signature. Upstream Go treats that as deliberate: it exempts
    /// the node from tailnet-lock verification and, in exchange, gives it **no network access** —
    /// only this node's peerAPI.
    ///
    /// **This fork does not implement that admission exemption yet.** While a tailnet-lock authority
    /// with a **non-empty trusted-key set** is active, the runtime's peer-admission gate
    /// (`ts_runtime`'s `PeerTracker::tka_snapshot_admits`) drops *every* peer with an empty
    /// [`key_signature`](Self::key_signature), this flag included — so such a peer is not admitted
    /// to the peer db at all and gets no peerAPI access either. That is stricter than Go (the safe
    /// direction); the carve-out is tracked as a parity gap in `docs/PARITY_ROADMAP.md`.
    ///
    /// The trusted-key qualifier is not hypothetical hedging, it names the one case where the gate
    /// does not enforce: an authority whose trusted-key set is *empty* admits every peer, signed or
    /// not. A verified chain can never produce that state (genesis rejects an empty key set and the
    /// last key cannot be removed), so it means a `ts_tka` invariant was violated — and the gate
    /// prefers admitting everyone (logged at `error!`) over black-holing the whole netmap. In that
    /// state this flag changes nothing either, because nothing is being enforced against.
    ///
    /// The *routes* half of upstream's treatment **is** implemented here. Because the node is
    /// outside the lock, a (possibly malicious) control server must not be able to grant it
    /// network access via advertised routes, so [`accepted_routes`](Self::accepted_routes) is
    /// clamped to the node's own [`addresses`](Self::addresses) when this is set. See the `From`
    /// impl on this type, which mirrors Go's `upgradeNode` in `control/controlclient/map.go`.
    ///
    /// The clamp is **unconditional** — it does not depend on tailnet lock being enabled locally,
    /// because the point is that an unsigned peer is by definition outside the lock's coverage.
    ///
    /// The clamp alone is not enough, because it closes only one of the two doors control has.
    /// Control can leave the node's `AllowedIPs` at its own addresses — which the clamp permits,
    /// those *are* its addresses — and write those same addresses into the **packet filter** as an
    /// allowed source instead. Upstream's answer is to reject the filter outright: a filter that
    /// grants an unsigned peer network access is treated as invalid ("the server is either broken
    /// or malicious") and ignored wholesale. That is
    /// [`ts_packetfilter::permits_unlocked_nodes`], driven by `ts_runtime`'s packet-filter updater
    /// on every netmap that moves either the filter or the peer set — Go's
    /// `packetFilterPermitsUnlockedNodes` / `nodeBackend.unlockedNodesPermitted` in
    /// `ipn/ipnlocal/local.go`.
    ///
    /// The **capability** half is still unported: there is no per-peer capability map in this
    /// domain model, only the node-attribute [`cap_map`](Self::cap_map). When it is ported, note
    /// that upstream does **not** withhold every capability. `capsAllowedForUnsignedPeer`
    /// (`ipn/ipnlocal/node_backend.go`) keeps `tailcfg.PeerCapabilityIngress` when the peer has it
    /// and drops the rest, on upstream's own reasoning that "Tailscale Funnel ingress nodes are
    /// unsigned by design, and the capability only permits ingress requests over the PeerAPI, which
    /// unsigned peers can already reach". Withholding it too would refuse Funnel ingress from real
    /// Tailscale nodes, so the carve-out travels with the port rather than after it.
    pub unsigned_peer_api_only: bool,

    /// The routes this node accepts traffic for.
    ///
    /// Clamped to [`addresses`](Self::addresses) when
    /// [`unsigned_peer_api_only`](Self::unsigned_peer_api_only) is set.
    pub accepted_routes: Vec<ipnet::IpNet>,
    /// The underlay addresses this node is reachable on (`Endpoints` in Go).
    pub underlay_addresses: Vec<SocketAddr>,

    /// The node's advertised SSH host public keys, in known_hosts format (Go
    /// `tailcfg.Hostinfo.SSHHostKeys`, surfaced by tsnet as `ipnstate.PeerStatus.SSH_HostKeys`).
    /// Used by `tailscale ssh` to pin a peer's host key (TOFU). Empty when control advertised none
    /// (the wire `Hostinfo.sshHostKeys` was absent), never fabricated. Projected from
    /// [`ts_control_serde::HostInfo::ssh_host_keys`].
    pub ssh_host_keys: Vec<String>,

    /// The DERP region for this node, if known.
    pub derp_region: Option<ts_derp::RegionId>,

    /// This node's advertised capability version (`Node.Cap` in Go). Old control servers may not
    /// send it, in which case it defaults to [`CapabilityVersion::default`]. Used to gate features
    /// that require a minimum peer capability, e.g. exit-node DNS proxying (`peerCanProxyDNS`).
    pub cap: CapabilityVersion,

    /// This node's capability map (`Node.CapMap` in Go). Keys are capability names/URLs; values are
    /// the raw JSON argument blobs (often empty). Threaded from the wire
    /// ([`ts_control_serde::Node::cap_map`]) as an owned copy. Used to gate node-level features such
    /// as Funnel ingress ([`Node::can_funnel`], [`Node::check_funnel_port`]).
    pub cap_map: NodeCapMap,

    /// The peerAPI port this node advertises over IPv4 (`peerapi4` service), if any.
    ///
    /// Derived from `HostInfo.Services`. `None` means the peer advertises no IPv4 peerAPI, so it
    /// cannot be reached for peerAPI DoH (DNS-over-HTTPS) exit-node delegation.
    pub peerapi_port: Option<u16>,

    /// Whether this peer advertises the `peerapi-dns-proxy` service (Go `PeerAPIDNSProxy`),
    /// indicating it will proxy DNS lookups for other nodes when used as an exit node.
    pub peerapi_dns_proxy: bool,

    /// Whether this is a non-Tailscale WireGuard-only peer (`IsWireGuardOnly` in Go). Such peers
    /// cannot run a peerAPI DoH server, so exit-node DNS for them comes from
    /// [`Node::exit_node_dns_resolvers`] instead.
    pub is_wireguard_only: bool,

    /// DNS resolvers to use when this WireGuard-only peer is selected as an exit node
    /// (`ExitNodeDNSResolvers` in Go). Only meaningful when [`Node::is_wireguard_only`] is set.
    /// Encrypted-transport resolvers are dropped (see `Resolver::from_serde`).
    pub exit_node_dns_resolvers: Vec<Resolver>,

    /// Whether this node advertises itself as a **peer relay** (Go `Hostinfo.PeerRelay`): it runs a
    /// UDP relay server other peers can allocate relay endpoints on. This fork is a relay client
    /// only and never sets this for itself; it is parsed off peers so a relay candidate can be
    /// recognized. Actually *using* a relay path (the Geneve data path + allocation handshake) is
    /// not yet implemented — see the crate docs.
    pub peer_relay: bool,

    /// Per-service virtual IP addresses of the Tailscale VIP services this node *hosts*, keyed by
    /// `svc:<label>` service name. Parsed from the `service-host`
    /// ([`ts_control_serde::NODE_ATTR_SERVICE_HOST`]) node-capability value
    /// (`tailcfg.ServiceIPMappings`). These VIPs are control-assigned and also injected into the
    /// node's `AllowedIPs`; the application netstack must accept packets for them so a
    /// `Device::listen_service`-bound listener can answer. Empty when the
    /// node hosts no VIP services (the common case). Per-service IP lists are deduplicated, source
    /// order otherwise preserved. Use [`Node::service_addresses`] for the flattened set (netstack
    /// accept list) and [`Node::service_addresses_for`] for a specific service's VIPs.
    pub service_vips: alloc::collections::BTreeMap<String, Vec<IpAddr>>,
}

impl Node {
    /// The fully-qualified domain name of the node.
    ///
    /// This is a string of the form `$HOST.$TAILNET_DOMAIN.`. For tailnets controlled by
    /// Tailscale's control plane, this usually means `$HOST.tail1234.ts.net.`
    ///
    /// The `trailing_dot` parameter specifies whether to include the trailing dot in the
    /// fqdn. This is included by the definition of FQDN, and is the way the Go codebase
    /// formats this field, but the parameter is included to allow turning it off for use
    /// in contexts that expect it to be absent.
    pub fn fqdn(&self, trailing_dot: bool) -> String {
        let dot = if trailing_dot { "." } else { "" };
        match &self.tailnet {
            Some(tailnet) => format!("{}.{tailnet}{dot}", self.hostname),
            None => format!("{}{dot}", self.hostname),
        }
    }

    /// Whether this node's key has expired as of `now`, mirroring Go's
    /// `netmap.NetworkMap.SelfKeyExpiry` + the `!expiry.IsZero() && expiry.Before(now)` check in
    /// `ipnlocal`. A node with no expiry ([`Node::node_key_expiry`] is `None`, the Go "zero value =
    /// does not expire") is never expired.
    ///
    /// Like Go, this fork is **reactive**: it reports expiry rather than auto-rotating in the
    /// background (Go transitions to `NeedsLogin` on expiry and re-registers via stored auth-key or
    /// interactive login). A caller observing `true` should re-register
    /// (`crate::tokio::register`) — supplying `RegisterRequest::old_node_key` (the prior key) and
    /// a fresh `node_key` when rotating the key, or the same key to merely refresh.
    pub fn key_expired(&self, now: DateTime<Utc>) -> bool {
        match self.node_key_expiry {
            None => false,
            Some(expiry) => expiry < now,
        }
    }

    /// The instant this node's key expires (`Node.KeyExpiry` in Go), or `None` if it never expires.
    /// A caller can schedule a re-evaluation/re-auth at this time.
    pub fn key_expiry(&self) -> Option<DateTime<Utc>> {
        self.node_key_expiry
    }

    /// Whether this node advertises itself as a peer relay (Go `Hostinfo.PeerRelay`): it runs a UDP
    /// relay server other peers may allocate relay endpoints on. Recognizing a relay candidate;
    /// actually traversing a relay path is not yet implemented in this fork.
    pub fn is_peer_relay(&self) -> bool {
        self.peer_relay
    }

    /// The key-expiry instant as **Unix seconds**, or `None` if the key never expires. Provided for
    /// callers (e.g. the root crate) that don't depend on `chrono`.
    pub fn key_expiry_unix(&self) -> Option<i64> {
        self.node_key_expiry.map(|t| t.timestamp())
    }

    /// Whether the key has expired as of `now_unix_secs` (Unix seconds). Equivalent to
    /// [`key_expired`](Self::key_expired) for `chrono`-free callers. A key with no expiry is never
    /// expired.
    pub fn key_expired_at_unix(&self, now_unix_secs: i64) -> bool {
        match self.key_expiry_unix() {
            None => false,
            Some(expiry) => expiry < now_unix_secs,
        }
    }

    /// The fully-qualified domain name of the node, only returning `Some` if the tailnet
    /// component is present.
    ///
    /// See [`Node::fqdn`].
    pub fn fqdn_opt(&self, trailing_dot: bool) -> Option<String> {
        let dot = if trailing_dot { "." } else { "" };
        let tailnet = self.tailnet.as_deref()?;

        Some(format!("{}.{tailnet}{dot}", self.hostname))
    }

    /// Report whether this node matches the given `name`.
    ///
    /// `name` is checked for equality with both this node's bare hostname and its fqdn. A
    /// trailing `.` may be present. Matching is case-insensitive (DNS names are
    /// case-insensitive), so this agrees with the canonicalized MagicDNS-name index used for
    /// peer lookups.
    pub fn matches_name(&self, name: &str) -> bool {
        // Strip an optional trailing root dot, then chop our `.tailnet` suffix off the end (if it
        // matches, case-insensitively) and compare the remainder to our hostname. If the tailnet
        // suffix doesn't match, the final case-insensitive compare against our bare hostname fails
        // naturally; if `name` was just the hostname, nothing is chopped and we compare directly.

        let name = name.strip_suffix('.').unwrap_or(name);

        let name = if let Some(tailnet) = &self.tailnet {
            name.get(name.len().saturating_sub(tailnet.len())..)
                .filter(|suffix| suffix.eq_ignore_ascii_case(tailnet))
                .and_then(|_| name.get(..name.len() - tailnet.len()))
                .and_then(|name| name.strip_suffix('.'))
                .unwrap_or(name)
        } else {
            name
        };

        name.eq_ignore_ascii_case(&self.hostname)
    }

    /// Report whether this node is a **router**: it routes addresses besides its own. An exit
    /// node, a subnet router and an app connector are all routers.
    ///
    /// Mirrors Go's `tailcfg.Node.IsRouter` (`tailcfg/tailcfg.go`, added upstream in `8d830599b`),
    /// which is `true` when any prefix in `AllowedIPs` is not also one of the node's own
    /// `Addresses`. It is a *derived predicate*, not a wire field: control sends nothing new for
    /// it, so there is no interop surface here and no capability version to gate on.
    ///
    /// Deliberately **not** [`Node::is_subnet_route`] folded over [`Node::accepted_routes`]. That
    /// predicate also excuses any single Tailscale-range IP (`100.64.0.0/10` /
    /// `fd7a:115c:a1e0::/48`) so route installation never mistakes another peer's address for an
    /// advertised subnet; Go's `IsRouter` makes no such exception — a `/32` that is not *this*
    /// node's own address still makes it a router. The two must stay separate.
    ///
    /// The comparison is against [`Node::addresses`] — *every* prefix control assigned this node,
    /// as Go's `slices.Contains(n.Addresses, r)` is — and not against the first-prefix-per-family
    /// pair in [`Node::tailnet_address`]. A node control handed two prefixes of one family would
    /// otherwise have the second read as a routed address and be misreported as a router.
    pub fn is_router(&self) -> bool {
        self.accepted_routes
            .iter()
            .any(|route| !self.addresses.contains(route))
    }

    /// Report whether `route` is an advertised *subnet* route (as opposed to one of this node's
    /// own tailnet addresses).
    ///
    /// Mirrors `cidrIsSubnet` in the Go client (`wgengine/wgcfg/nmcfg/nmcfg.go`). A route is *not*
    /// a subnet route (i.e. it's a self-address) when it is a single host IP that is either a
    /// Tailscale-assigned IP or exactly one of this node's [`TailnetAddress`] addresses. Everything
    /// else — multi-IP CIDRs, and single IPs outside the Tailscale ranges — is a subnet route.
    ///
    /// The default route (`0.0.0.0/0` / `::/0`) is treated as a subnet route here; exit-node
    /// handling is a separate concern.
    pub fn is_subnet_route(&self, route: &ipnet::IpNet) -> bool {
        let host_prefix = match route {
            ipnet::IpNet::V4(_) => 32,
            ipnet::IpNet::V6(_) => 128,
        };

        if route.prefix_len() != host_prefix {
            // Any multi-IP CIDR (including the default route) is a subnet route.
            return true;
        }

        let addr = route.addr();
        !(is_tailscale_ip(addr) || self.tailnet_address.contains(addr))
    }

    /// The routes that should be installed for this peer, given whether this node accepts
    /// advertised subnet routes (`--accept-routes` / `RouteAll` in the Go client) and which peer
    /// (if any) is the selected exit node (`--exit-node` / `ExitNodeID` in the Go client).
    ///
    /// This node's own addresses (the peer's `/32` and `/128`) are always installed so the peer
    /// itself stays reachable. Larger advertised subnet routes are only installed when
    /// `accept_routes` is set; otherwise they are dropped (fail-closed). The same filtered set
    /// governs both outbound routing to the peer and inbound source validation, exactly as
    /// WireGuard cryptokey routing couples them in the Go client.
    ///
    /// The default route (`0.0.0.0/0` / `::/0`) is installed *only* for the peer whose
    /// [`StableId`] equals `exit_node`, mirroring `nmcfg.go`'s `if allowedIP.Bits()==0 &&
    /// peer.StableID()!=exitNode { skip }`. Exit-node use is gated behind this separate, explicit
    /// preference (`ExitNodeID`, not `RouteAll`): conflating the two would let enabling
    /// subnet-route acceptance silently route every packet through any peer advertising a default
    /// route — unacceptable for a fail-closed privacy posture. When `exit_node` is `None` (the
    /// default) no peer ever receives a `/0`, so internet-bound traffic has no overlay route and is
    /// dropped by the userspace netstack (fail-closed, no leak). Longest-prefix-match means a peer
    /// selected as the exit node still loses more-specific destinations to other peers; only
    /// residual default-route traffic egresses through it.
    pub fn routes_to_install<'a>(
        &'a self,
        accept_routes: bool,
        exit_node: Option<&StableId>,
    ) -> impl Iterator<Item = &'a ipnet::IpNet> + 'a {
        // Computed eagerly so the returned iterator doesn't borrow `exit_node`.
        let is_selected_exit = exit_node == Some(&self.stable_id);
        self.accepted_routes.iter().filter(move |route| {
            if route.prefix_len() == 0 {
                // Default route: installed only when this peer is the selected exit node. Both the
                // outbound route table and the inbound source filter call this, so the exit peer
                // may legitimately source arbitrary internet IPs on return traffic — and only it.
                return is_selected_exit;
            }
            accept_routes || !self.is_subnet_route(route)
        })
    }

    /// The capability version at and above which a peer can proxy DNS for nodes using it as an exit
    /// node (Go `tailcfg.CapabilityVersion` `peerCanProxyDNS`, introduced 2022-01-12 at V26).
    const PEER_CAN_PROXY_DNS: CapabilityVersion = CapabilityVersion::V26;

    /// The base URL of this peer's IPv4 peerAPI DoH endpoint for exit-node DNS proxying, if it can
    /// proxy DNS. Returns e.g. `http://100.64.0.5:8080/dns-query`.
    ///
    /// Mirrors Go `peerAPIBase(...)+"/dns-query"` gated by `exitNodeCanProxyDNS`: a peer can proxy
    /// DNS when it advertises an IPv4 peerAPI port **and** either advertises the explicit
    /// `peerapi-dns-proxy` service or is new enough ([`Node::cap`] ≥ `PEER_CAN_PROXY_DNS`). A
    /// WireGuard-only peer never runs a peerAPI, so it returns `None` here (its exit-node DNS comes
    /// from [`Node::exit_node_dns_resolvers`] instead).
    ///
    /// IPv4-only by deliberate design: the tailnet dataplane in this fork binds IPv4 only, so we
    /// never form a peerAPI URL on the peer's IPv6 address.
    ///
    /// `None` for an [`expired`](Self::expired) peer — see [`Node::peerapi_addr`].
    pub fn peerapi_doh_url(&self) -> Option<String> {
        self.peerapi_doh_addr()
            .map(|addr| format!("http://{addr}/dns-query"))
    }

    /// The IPv4 socket address (`<tailnet-ipv4>:<peerapi-port>`) of this peer's peerAPI DoH endpoint
    /// for exit-node DNS proxying, if it can proxy DNS. Same gate as [`Node::peerapi_doh_url`]; this
    /// is the form the DoH *client* dials (over the overlay netstack) when delegating recursive
    /// resolution to a selected exit node. `SocketAddr`'s `Display` is `ip:port`, so
    /// `peerapi_doh_url` formats to `http://<ip>:<port>/dns-query` over this.
    pub fn peerapi_doh_addr(&self) -> Option<SocketAddr> {
        if self.is_wireguard_only || self.expired {
            return None;
        }
        let port = self.peerapi_port?;
        if !(self.peerapi_dns_proxy || self.cap >= Self::PEER_CAN_PROXY_DNS) {
            return None;
        }
        Some(SocketAddr::new(
            IpAddr::V4(self.tailnet_address.ipv4.addr()),
            port,
        ))
    }

    /// The IPv4 peerAPI socket address (`<tailnet-ipv4>:<peerapi4-port>`) of this node, if it
    /// advertises an IPv4 peerAPI. Unlike [`Node::peerapi_doh_addr`], this is **not** gated on the
    /// DNS-proxy capability: it is the general base for any peerAPI request to this node (e.g. a
    /// Taildrop `PUT /v0/put/<name>` upload), mirroring Go's `peerAPIBase`/`peerAPIPorts`.
    ///
    /// IPv4-only by this fork's deliberate design (the tailnet dataplane binds IPv4 only, so we never
    /// form a peerAPI URL on the peer's IPv6 address). Returns `None` for a WireGuard-only peer (which
    /// runs no peerAPI) or a peer advertising no IPv4 peerAPI port.
    ///
    /// Also `None` for an [`expired`](Self::expired) peer: Go refuses a peerAPI dial to one with
    /// [`PEER_KEY_EXPIRED`](crate::PEER_KEY_EXPIRED) (`LocalBackend.pingPeerAPI`), and this is the
    /// chokepoint every peerAPI dial in this fork resolves its destination through. Callers that
    /// want to *report* the refusal rather than silently skip the peer should test
    /// [`expired`](Self::expired) first.
    pub fn peerapi_addr(&self) -> Option<SocketAddr> {
        if self.is_wireguard_only || self.expired {
            return None;
        }
        let port = self.peerapi_port?;
        Some(SocketAddr::new(
            IpAddr::V4(self.tailnet_address.ipv4.addr()),
            port,
        ))
    }

    /// The node attribute granting HTTPS (TLS cert provisioning) for this node (Go
    /// `tailcfg.CapabilityHTTPS`). One of the two caps [`Node::can_funnel`] requires.
    const CAP_HTTPS: &'static str = "https";

    /// The node attribute granting the ability to host Funnel ingress (Go `tailcfg.NodeAttrFunnel`).
    /// The other cap [`Node::can_funnel`] requires.
    const NODE_ATTR_FUNNEL: &'static str = "funnel";

    /// The capability URL whose `?ports=` query enumerates the ports Funnel may listen on (Go
    /// `tailcfg.CapabilityFunnelPorts`). The allowed ports live entirely in the *key's* query
    /// string, not the cap value.
    const CAP_FUNNEL_PORTS: &'static str = "https://tailscale.com/cap/funnel-ports";

    /// Report whether the cap map contains `cap` as a key (Go `NodeCapMap.Contains` / `HasCap`).
    pub fn has_node_attr(&self, cap: &str) -> bool {
        self.cap_map.contains_key(cap)
    }

    /// Report whether this node is permitted to host Tailscale Funnel ingress.
    ///
    /// Mirrors Go `ipn.NodeCanFunnel`: the node must advertise BOTH `CapabilityHTTPS` (`"https"`)
    /// AND `NodeAttrFunnel` (`"funnel"`) in its cap map. Fail-closed: a missing cap denies.
    pub fn can_funnel(&self) -> bool {
        self.has_node_attr(Self::CAP_HTTPS) && self.has_node_attr(Self::NODE_ATTR_FUNNEL)
    }

    /// The capability control grants the **self** node when Taildrop is enabled for the tailnet (Go
    /// `tailcfg.CapabilityFileSharing`). Gates [`Node::can_share_files`].
    const CAP_FILE_SHARING: &'static str = "https://tailscale.com/cap/file-sharing";

    /// The capability marking a **peer** as an explicit Taildrop send target even across owners (Go
    /// `tailcfg.PeerCapabilityFileSharingTarget`). Checked by [`Node::is_file_sharing_target`].
    const CAP_FILE_SHARING_TARGET: &'static str = "tailscale.com/cap/file-sharing-target";

    /// Report whether this node may send Taildrop files — i.e. the admin has enabled file sharing for
    /// the tailnet (Go `self.CapMap().Contains(CapabilityFileSharing)`). Applied to the **self** node
    /// as the node-level gate in `FileTargets`; fail-closed when the cap is absent.
    pub fn can_share_files(&self) -> bool {
        self.has_node_attr(Self::CAP_FILE_SHARING)
    }

    /// Report whether this **peer** is an explicit Taildrop send target via ACL caps (Go
    /// `PeerHasCap(p, PeerCapabilityFileSharingTarget)`) — the cross-owner path that lets a peer owned
    /// by a different user still be a valid target.
    pub fn is_file_sharing_target(&self) -> bool {
        self.has_node_attr(Self::CAP_FILE_SHARING_TARGET)
    }

    /// The node attribute control sets on a node whose **subdomains** all resolve to the node
    /// itself (Go `tailcfg/nodecap`'s `NodeAttrDNSSubdomainResolve`). Read by
    /// [`Node::resolves_subdomains`].
    const NODE_ATTR_DNS_SUBDOMAIN_RESOLVE: &'static str = "dns-subdomain-resolve";

    /// Report whether every subdomain of this node's MagicDNS name resolves to this node's
    /// addresses — `foo.<node>` and `bar.foo.<node>` alike.
    ///
    /// Go's resolver (`net/dns/resolver/tsdns.go`) learns the same thing two ways — a
    /// `Config.SubdomainHosts` set of FQDNs beside its `Hosts` map, and a `SubdomainHost` predicate
    /// on its MagicDNS host index — and on a lookup miss walks the queried name's parents,
    /// answering from the first parent either one accepts. Here the attribute on the node *is* that
    /// predicate, read where the parent walk finds the node.
    ///
    /// Being a plain per-node attribute, it needs no capability version: a node control has not set
    /// it on is unaffected, and its subdomains stay `NXDOMAIN`.
    pub fn resolves_subdomains(&self) -> bool {
        self.has_node_attr(Self::NODE_ATTR_DNS_SUBDOMAIN_RESOLVE)
    }

    /// The node attribute control sets to stop the DNS forwarder re-asking a truncated upstream
    /// answer over TCP (Go `tailcfg/nodecap`'s `NodeAttrDNSForwarderDisableTCPRetries`, surfaced in
    /// `control/controlknobs` as `Knobs.DisableDNSForwarderTCPRetries`). Read by
    /// [`Node::disable_dns_forwarder_tcp_retries`].
    const NODE_ATTR_DNS_FORWARDER_DISABLE_TCP_RETRIES: &'static str =
        "dns-forwarder-disable-tcp-retries";

    /// Report whether control has told this node **not** to retry a truncated forwarded DNS answer
    /// over TCP.
    ///
    /// The retry is on by default and this attribute is its *off* switch — so, unlike every other
    /// attribute here, the fail-closed reading is the one that ignores it: a node control has not
    /// set it on keeps retrying, which is what a stub resolver on this node needs for a name whose
    /// answer does not fit a datagram. Go reads it the same way round
    /// (`skipTCP := skipTCPRetry() || (f.controlKnobs != nil &&
    /// f.controlKnobs.DisableDNSForwarderTCPRetries.Load())`, net/dns/resolver/forwarder.go).
    ///
    /// Upstream dates a client's understanding of the attribute to capability version 75
    /// ([`ts_capabilityversion::CapabilityVersion::V75`]), which this tree's `CURRENT` is well
    /// above, so control will send it to this node when the tailnet sets it.
    pub fn disable_dns_forwarder_tcp_retries(&self) -> bool {
        self.has_node_attr(Self::NODE_ATTR_DNS_FORWARDER_DISABLE_TCP_RETRIES)
    }

    /// The node attribute by which control asks this node to keep its periodic STUN sweep running
    /// even while the datapath is idle (Go `tailcfg/nodecap`'s `NodeAttrDebugForceBackgroundSTUN`,
    /// surfaced in `control/controlknobs` as `Knobs.ForceBackgroundSTUN`). Read by
    /// [`force_background_stun`](Self::force_background_stun).
    const NODE_ATTR_DEBUG_FORCE_BACKGROUND_STUN: &'static str = "debug-always-stun";

    /// Report whether control has asked this node to keep STUNning in the background regardless of
    /// datapath activity.
    ///
    /// This is the single override on the idle stop condition in Go magicsock's
    /// `shouldDoPeriodicReSTUNLocked`: once the datapath has been idle longer than the session-active
    /// timeout the periodic sweep stops, *unless* `c.controlKnobs.ForceBackgroundSTUN` is set, in
    /// which case it keeps running. It overrides nothing else — a node with no peers still does not
    /// STUN, with or without the attribute, because that arm returns before the idle arm is reached.
    ///
    /// Read off the **self** node's cap map, like every other control knob. Absent (the normal case)
    /// means "let the idle stop apply", which is the quiet default; the attribute is a debugging
    /// escape hatch control sets deliberately, so there is nothing to fail closed to here.
    pub fn force_background_stun(&self) -> bool {
        self.has_node_attr(Self::NODE_ATTR_DEBUG_FORCE_BACKGROUND_STUN)
    }

    /// The node attribute by which control asks this node to collapse its per-peer CGNAT host
    /// routes into the single `100.64.0.0/10` (Go `tailcfg/nodecap`'s `OneCGNATEnable`).
    ///
    /// Note the query string: the key is the literal `one-cgnat?v=true`, not `one-cgnat`. The
    /// attribute is a tri-state carried as two mutually exclusive keys rather than as a key with a
    /// value, so the lookup is on the whole literal.
    const NODE_ATTR_ONE_CGNAT_ENABLE: &'static str = "one-cgnat?v=true";

    /// The node attribute by which control asks this node NOT to force the collapsed route (Go
    /// `tailcfg/nodecap`'s `OneCGNATDisable`): one host route per peer until the consumer's own
    /// peer-count ceiling, which still applies. The other half of
    /// [`NODE_ATTR_ONE_CGNAT_ENABLE`](Self::NODE_ATTR_ONE_CGNAT_ENABLE)'s tri-state.
    ///
    /// It declines the **forced** collapse only. It is not a licence for an unbounded host route
    /// table: the consumer's own peer-count ceiling still applies above it — see
    /// [`Node::one_cgnat`](Self::one_cgnat).
    const NODE_ATTR_ONE_CGNAT_DISABLE: &'static str = "one-cgnat?v=false";

    /// Control's tri-state instruction about collapsing this node's per-peer CGNAT host routes
    /// into the single `100.64.0.0/10`, read off the **self** node's cap map.
    ///
    /// Mirrors Go `ipn/ipnlocal`'s read of `nodecap.OneCGNATEnable` / `nodecap.OneCGNATDisable`
    /// into `controlknobs.Knobs.OneCGNAT`, which is an `opt.Bool` and not a `bool` precisely so the
    /// third state exists:
    ///
    /// * `Some(true)` — `one-cgnat?v=true`: collapse as soon as there is more than one peer route.
    /// * `Some(false)` — `one-cgnat?v=false`: do not force the collapse, whatever the platform
    ///   would default to. It is NOT "never collapse": the consumer's peer-count ceiling (Go
    ///   `net/routemanager`'s `cgnatThreshold`) still collapses a large enough tailnet.
    /// * `None` — neither attribute present: control has no opinion, and the consumer's platform
    ///   default decides (Go `ipn/ipnlocal`'s `shouldUseOneCGNATRoute`), under the same ceiling.
    ///
    /// What the third state does NOT do is switch the consumer's peer-count ceiling off. Upstream
    /// resolves this `opt.Bool` down to a plain `bool` before the route manager sees it, and
    /// `RouteManager.cgnatThreshold()` then picks between `1` and `cgnatThreshold` (`10_000`) —
    /// so a node holding `one-cgnat?v=false` still collapses once it has more CGNAT peer routes
    /// than the ceiling. The tri-state chooses whether to collapse *early*, not whether a host
    /// route table may grow without bound.
    ///
    /// A node holding BOTH attributes reads as `Some(true)`: the enabling attribute is checked
    /// first and wins. Control setting both is a policy conflict rather than a state upstream
    /// specifies, and collapsing is the safe way to break the tie — the `/10` is a superset of the
    /// `/32`s it replaces, so no peer becomes unreachable, whereas honouring the disabling
    /// attribute on a tailnet large enough for control to have set the enabling one would keep a
    /// per-peer route table far past the point where it is worth programming.
    pub fn one_cgnat(&self) -> Option<bool> {
        if self.has_node_attr(Self::NODE_ATTR_ONE_CGNAT_ENABLE) {
            Some(true)
        } else if self.has_node_attr(Self::NODE_ATTR_ONE_CGNAT_DISABLE) {
            Some(false)
        } else {
            None
        }
    }

    /// The node attribute by which control asks this node to stop processing netmap updates through
    /// the delta (incremental) path (Go `tailcfg/nodecap`'s `DisableDeltaUpdates`, read into
    /// `controlknobs.Knobs.DisableDeltaUpdates`). Read off the **self** node's cap map by
    /// [`delta_updates_disabled`](Self::delta_updates_disabled).
    ///
    /// Upstream documents the intent on the knob itself: the client "should not process updates via
    /// the delta update mechanism and should instead treat all netmap changes as 'full' ones as
    /// tailscaled did in 1.48.x and earlier". It is control's escape hatch for a delta-encoding bug
    /// on *either* side of the map protocol — control emitting bad patches, or a client applying
    /// them wrongly — without waiting for a client release to ship.
    const NODE_ATTR_DISABLE_DELTA_UPDATES: &'static str = "disable-delta-updates";

    /// Report whether control has asked this node to decline the incremental netmap path and treat
    /// every netmap change as a full one.
    ///
    /// Mirrors the first statement of Go `control/controlclient/map.go`'s `tryHandleIncrementally`:
    /// `if ms.controlKnobs != nil && ms.controlKnobs.DisableDeltaUpdates.Load() { return false }`.
    /// Returning `false` there does **not** reject the response and does not drop the mutations it
    /// carries — it declines the incremental arm so the full netmap rebuild handles the very same
    /// response. A consumer of this method owes the same shape: fall back, never drop.
    ///
    /// Absent attribute ⇒ `false` ⇒ the delta path, which is the default and the overwhelmingly
    /// common case. Being a plain per-node attribute it needs no capability version: a node control
    /// has not set it on is unaffected.
    pub fn delta_updates_disabled(&self) -> bool {
        self.has_node_attr(Self::NODE_ATTR_DISABLE_DELTA_UPDATES)
    }

    /// The node attribute by which control tells this node to stop sending disco heartbeats to its
    /// peers (Go `tailcfg/nodecap`'s `SilentDisco`, read into `controlknobs.Knobs.SilentDisco` and
    /// handed to magicsock by `ipn/ipnlocal`'s `b.MagicConn().SetSilentDisco(...)`). Read off the
    /// **self** node's cap map by [`silent_disco`](Self::silent_disco).
    ///
    /// Upstream's own summary of the attribute is one sentence — it "makes the client suppress
    /// disco heartbeats to its peers" — and the node it is set on is the node that goes quiet, so
    /// it is the *self* node's cap map that decides, never the peer's.
    const NODE_ATTR_SILENT_DISCO: &'static str = "silent-disco";

    /// Report whether control has asked this node to stop heartbeating its peers' confirmed direct
    /// paths.
    ///
    /// Mirrors Go magicsock `Conn.debugFlagsLocked`'s `heartbeatDisabled`, which the netmap push
    /// (`endpoint.updateFromNode`) stamps onto every endpoint. With it set, the periodic
    /// keep-the-best-path-alive ping is not sent — and, as the compensating half, an inbound packet
    /// from the current best address extends that path's trust directly, because with no heartbeat
    /// there is nothing else keeping it trusted.
    ///
    /// Absent attribute ⇒ `false` ⇒ the existing heartbeat cadence, which is the default and the
    /// overwhelmingly common case. Being a plain per-node attribute it needs no capability version:
    /// a node control has not set it on is unaffected.
    ///
    /// Go additionally ORs in a `TS_DEBUG_ENABLE_SILENT_DISCO` envknob at the same place. This tree
    /// has no envknob layer at all, so the control attribute is the whole input here.
    pub fn silent_disco(&self) -> bool {
        self.has_node_attr(Self::NODE_ATTR_SILENT_DISCO)
    }

    /// The node attribute by which control tells this node that the network it sits on tolerates
    /// nothing but TCP on port 443 (Go `tailcfg/nodecap`'s `OnlyTCP443`, read off `nm.SelfNode` in
    /// `ipn/ipnlocal` and handed to magicsock by `b.MagicConn().SetOnlyTCP443(...)`). Read off the
    /// **self** node's cap map by [`only_tcp_443`](Self::only_tcp_443).
    ///
    /// Upstream's own words: the client "should not attempt to generate any outbound traffic that
    /// isn't TCP on port 443", which "thus implies all traffic is over DERP". The node it is set on
    /// is the node that goes quiet, so it is the *self* node's cap map that decides, never the
    /// peer's.
    const NODE_ATTR_ONLY_TCP_443: &'static str = "only-tcp-443";

    /// Report whether control has told this node to emit nothing but TCP/443 — no UDP at all, so
    /// every tailnet packet rides DERP.
    ///
    /// This is the single predicate behind all of upstream's TCP-443-only behaviour: magicsock's
    /// UDP send chokepoint refuses silently, netcheck's UDP (STUN) probes refuse with
    /// `errors.ErrUnsupported`, the portmapper is disabled and the peer-relay client is switched
    /// off. Consumers in this tree read it here rather than each re-deriving it from the cap map.
    ///
    /// Absent attribute ⇒ `false` ⇒ UDP as before, which is the default and the overwhelmingly
    /// common case. Being a plain per-node attribute it needs no capability version: a node control
    /// has not set it on is unaffected. It is read live off each netmap, never latched at start-up,
    /// because upstream's setter (`Conn.SetOnlyTCP443`) is live — control withdrawing the attribute
    /// has to restore UDP without a restart.
    pub fn only_tcp_443(&self) -> bool {
        self.has_node_attr(Self::NODE_ATTR_ONLY_TCP_443)
    }

    /// Report whether `wanted_port` is allowed for Funnel on this node.
    ///
    /// Mirrors Go `ipn.CheckFunnelPort`: scan the cap-map keys for one prefixed by
    /// `Node::CAP_FUNNEL_PORTS`, URL-parse that key, read its `ports` query parameter, and match
    /// `wanted_port` against the comma-separated list of single ports and `first-last` ranges. The
    /// port list lives in the *key*, never the value. Fail-closed: no matching cap, an empty or
    /// unparseable `ports` query, or a key whose non-query part isn't exactly the funnel-ports URL
    /// all deny.
    pub fn check_funnel_port(&self, wanted_port: u16) -> bool {
        // Extract the `ports=` list from the first cap-map key that is the funnel-ports URL with a
        // non-empty `ports` query. Returns `None` (deny) if the key is unparseable, the query is
        // missing/empty, or the URL (sans query) isn't exactly the funnel-ports cap.
        let parse_attr = |attr: &str| -> Option<String> {
            let mut url = url::Url::parse(attr).ok()?;
            let ports = url
                .query_pairs()
                .find(|(k, _)| k == "ports")
                .map(|(_, v)| v.into_owned())?;
            if ports.is_empty() {
                return None;
            }
            url.set_query(None);
            // Go compares `u.String()` against the bare cap; `url`'s serializer keeps a trailing
            // `/` only if present in the input, and the funnel-ports cap has none, so a direct
            // string compare matches Go's behavior.
            if url.as_str() != Self::CAP_FUNNEL_PORTS {
                return None;
            }
            Some(ports)
        };

        let Some(ports_str) = self
            .cap_map
            .keys()
            .filter(|attr| attr.starts_with(Self::CAP_FUNNEL_PORTS))
            .find_map(|attr| parse_attr(attr))
        else {
            return false;
        };

        let wanted = wanted_port.to_string();
        for ps in ports_str.split(',') {
            if ps.is_empty() {
                continue;
            }
            match ps.split_once('-') {
                None => {
                    if ps == wanted {
                        return true;
                    }
                }
                Some((first, last)) => {
                    let (Ok(fp), Ok(lp)) = (first.parse::<u16>(), last.parse::<u16>()) else {
                        continue;
                    };
                    if fp <= wanted_port && wanted_port <= lp {
                        return true;
                    }
                }
            }
        }
        false
    }

    /// Report whether this node is permitted to host Tailscale VIP services.
    ///
    /// Mirrors the Go grant model: possession of the `service-host`
    /// ([`ts_control_serde::NODE_ATTR_SERVICE_HOST`]) node-capability **and** at least one assigned
    /// VIP address. Go additionally requires the host to be tagged
    /// (`ErrUntaggedServiceHost`); that tag gate is enforced at
    /// `Device::listen_service` using [`Node::tags`]. Fail-closed: no cap
    /// or no assigned VIP denies.
    pub fn is_service_host(&self) -> bool {
        self.has_node_attr(ts_control_serde::NODE_ATTR_SERVICE_HOST)
            && !self.service_vips.is_empty()
    }

    /// The control-assigned VIP addresses for one named service (`svc:<label>`), or an empty slice
    /// if this node does not host that service. This is the exact per-service mapping (so a
    /// multi-service co-host binds the right VIP for each service).
    pub fn service_addresses_for(&self, service: &str) -> &[IpAddr] {
        self.service_vips
            .get(service)
            .map(Vec::as_slice)
            .unwrap_or(&[])
    }

    /// The flattened, deduplicated set of every VIP address this node hosts across all services.
    /// Used to widen the netstack's accepted-address set so any hosted-service listener is
    /// reachable. Per-service binding uses [`Node::service_addresses_for`] instead.
    pub fn service_addresses(&self) -> Vec<IpAddr> {
        let mut seen = alloc::collections::BTreeSet::new();
        let mut out = Vec::new();
        for addr in self.service_vips.values().flatten() {
            if seen.insert(*addr) {
                out.push(*addr);
            }
        }
        out
    }

    /// The VIP services control has told this node it can *reach* (`tailcfg.ServiceDetails`),
    /// parsed from every `services/<id>`
    /// ([`ts_control_serde::NODE_ATTR_PREFIX_SERVICES`]) node-capability value, in capability-key
    /// order.
    ///
    /// This is the consuming half of the VIP services model, and the counterpart to
    /// [`Node::service_vips`], which is what this node *hosts*. Each entry carries the service's
    /// canonical name, its VIP addresses, the ports it accepts and the client application actions
    /// available on those ports. The capability key's suffix is an opaque server-chosen id, so the
    /// name comes from `ServiceDetails::name` and never from the key.
    ///
    /// Fail-closed per value, never per netmap: a capability value that does not parse as a
    /// `ServiceDetails` is skipped and the remaining services are still returned — the same
    /// treatment the `service-host` parser gives a malformed `tailcfg.ServiceIPMappings` value. An
    /// carrying a *type* this build does not know is not a parse failure: it decodes and is
    /// returned, matching Go's rule that clients ignore actions they do not recognize. Use
    /// `ts_control_serde::ServiceDetails::known_actions` to walk only the recognized ones.
    pub fn visible_services(&self) -> Vec<ts_control_serde::ServiceDetails<'_>> {
        self.cap_map
            .iter()
            .filter(|(key, _)| key.starts_with(ts_control_serde::NODE_ATTR_PREFIX_SERVICES))
            .flat_map(|(_, values)| values.iter())
            .filter_map(|raw| serde_json::from_str(raw).ok())
            .collect()
    }
}

/// Validate a Tailscale VIP service name (`tailcfg.ServiceName.Validate`): it must carry the
/// `svc:` prefix ([`ts_control_serde::SERVICE_NAME_PREFIX`]) followed by a valid DNS label
/// (1–63 chars, ASCII alphanumeric or `-`, not starting/ending with `-`). Returns the bare label on
/// success. Fail-closed: anything malformed is rejected so a listener can never bind for a bogus
/// service name.
pub fn validate_service_name(name: &str) -> Option<&str> {
    let label = name.strip_prefix(ts_control_serde::SERVICE_NAME_PREFIX)?;
    if label.is_empty() || label.len() > 63 {
        return None;
    }
    if label.starts_with('-') || label.ends_with('-') {
        return None;
    }
    if label
        .bytes()
        .all(|b| b.is_ascii_alphanumeric() || b == b'-')
    {
        Some(label)
    } else {
        None
    }
}

/// Parse the per-service VIP map this node hosts from the `service-host` node-capability value(s).
/// Each value is the raw JSON text of a [`ts_control_serde::ServiceIpMappings`] object (svc-name ->
/// VIP IPs); unparseable values are skipped (fail-closed: a malformed mapping contributes no VIPs).
/// Per-service IP lists are deduplicated, source order otherwise preserved.
fn service_vips_from_cap_map(
    cap_map: &NodeCapMap,
) -> alloc::collections::BTreeMap<String, Vec<IpAddr>> {
    let mut out: alloc::collections::BTreeMap<String, Vec<IpAddr>> =
        alloc::collections::BTreeMap::new();
    let Some(values) = cap_map.get(ts_control_serde::NODE_ATTR_SERVICE_HOST) else {
        return out;
    };

    for raw in values {
        let Ok(mappings) = serde_json::from_str::<ts_control_serde::ServiceIpMappings>(raw) else {
            continue;
        };
        for (name, addrs) in &mappings.0 {
            let entry = out.entry((*name).to_string()).or_default();
            for addr in addrs {
                if !entry.contains(addr) {
                    entry.push(*addr);
                }
            }
        }
    }
    out
}

/// Collect a wire ([`ts_control_serde`]) node cap map into an owned [`NodeCapMap`].
///
/// Keys are copied as owned strings; each value's raw JSON text is preserved verbatim. The wire map
/// borrows from the decode buffer, so an owned copy is required to outlive it on the domain
/// [`Node`].
fn cap_map_from_serde(wire: &ts_nodecapability::Map<'_>) -> NodeCapMap {
    wire.iter()
        .map(|(&key, values)| {
            let owned_values = values.0.iter().map(|v| v.get().to_owned()).collect();
            (key.to_owned(), owned_values)
        })
        .collect()
}

/// Extract the advertised IPv4 peerAPI port and whether the explicit `peerapi-dns-proxy` service is
/// advertised, from a peer's `HostInfo.Services` list.
fn peerapi_from_services(
    services: Option<&[ts_control_serde::Service<'_>]>,
) -> (Option<u16>, bool) {
    use ts_control_serde::ServiceProto;

    let Some(services) = services else {
        return (None, false);
    };
    let mut port = None;
    let mut dns_proxy = false;
    for svc in services {
        match svc.proto {
            ServiceProto::PeerApi4 => port = Some(svc.port),
            ServiceProto::PeerApiDnsProxy => dns_proxy = true,
            _ => {}
        }
    }
    (port, dns_proxy)
}

/// Addresses for a node within a tailnet.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct TailnetAddress {
    /// The IPv4 address of the node in the tailnet.
    pub ipv4: ipnet::Ipv4Net,
    /// The IPv6 address of the node in the tailnet.
    pub ipv6: ipnet::Ipv6Net,
}

impl TailnetAddress {
    /// Report whether `addr` matches either address in this [`TailnetAddress`].
    pub fn contains(&self, addr: IpAddr) -> bool {
        match addr {
            IpAddr::V4(a) => self.ipv4.addr() == a,
            IpAddr::V6(a) => self.ipv6.addr() == a,
        }
    }
}

impl From<&ts_control_serde::Node<'_>> for Node {
    fn from(value: &ts_control_serde::Node) -> Self {
        let fqdn_without_trailing_dot = value.name.strip_suffix('.').unwrap_or(&value.name);

        let (hostname, tailnet) = match fqdn_without_trailing_dot.split_once('.') {
            Some((hostname, tailnet)) => (hostname, Some(tailnet.to_owned())),
            None => (fqdn_without_trailing_dot, None),
        };

        let (peerapi_port, peerapi_dns_proxy) =
            peerapi_from_services(value.host_info.services.as_deref());

        let cap_map = cap_map_from_serde(&value.cap_map);
        let service_vips = service_vips_from_cap_map(&cap_map);

        // `addresses` is a variable-length `Vec<IpNet>` on the wire (Go `[]netip.Prefix`), not a
        // fixed (v4, v6) pair: an IPv6-off tailnet assigns only a v4 prefix. The whole list is kept
        // verbatim on `Node::addresses` (Go's `Node.Addresses`, which `IsRouter` tests routes
        // against); `tailnet_address` is the identity projection. Pick the first of each
        // family. The v4 prefix is the node's tailnet identity (always present on a normal node);
        // if somehow absent we fall back to the unspecified `0.0.0.0/32` rather than panicking.
        // The v6 prefix is optional — when the tailnet is IPv4-only there is none, and the overlay
        // never reads `ipv6` in that mode (gated on `enable_ipv6`); we synthesize the unspecified
        // `::/128` placeholder so the domain `TailnetAddress` stays infallible.
        let ipv4 = value
            .addresses
            .iter()
            .find_map(|p| match p {
                ipnet::IpNet::V4(n) => Some(*n),
                ipnet::IpNet::V6(_) => None,
            })
            .unwrap_or_else(|| ipnet::Ipv4Net::new(core::net::Ipv4Addr::UNSPECIFIED, 32).unwrap());
        let ipv6 = value
            .addresses
            .iter()
            .find_map(|p| match p {
                ipnet::IpNet::V6(n) => Some(*n),
                ipnet::IpNet::V4(_) => None,
            })
            .unwrap_or_else(|| ipnet::Ipv6Net::new(core::net::Ipv6Addr::UNSPECIFIED, 128).unwrap());

        Self {
            id: value.id,
            stable_id: StableId(value.stable_id.0.to_string()),

            hostname: hostname.to_owned(),
            user_id: value.user,
            tailnet,

            tags: value
                .tags
                .as_ref()
                .map(|x| x.iter().map(|x| x.to_string()).collect())
                .unwrap_or_default(),

            addresses: value.addresses.clone(),
            tailnet_address: TailnetAddress { ipv4, ipv6 },
            node_key: value.key,
            node_key_expiry: value.key_expiry,
            // Control's own verdict, carried verbatim; `ExpiryManager` only ever raises it.
            expired: value.expired,
            online: value.online,
            last_seen: value.last_seen,
            key_signature: value.key_signature.to_vec(),
            machine_key: value.machine,
            disco_key: value.disco_key,

            unsigned_peer_api_only: value.unsigned_peer_api_only,

            // Per capver-112, `AllowedIPs` null/absent means "same as `addresses`". Fall back to the
            // node's own assigned prefixes verbatim (whatever families the wire carried), not a
            // synthesized v4+v6 pair.
            //
            // `UnsignedPeerAPIOnly` clamps the result back to `addresses` whatever control sent,
            // mirroring Go's `upgradeNode` (`control/controlclient/map.go`): such a node is outside
            // tailnet lock's coverage, so a possibly-malicious control server must not be able to
            // grant it network access by handing it advertised routes (in the limit, `0.0.0.0/0`).
            // Unconditional, exactly as upstream — it does not depend on tailnet lock being
            // enabled here.
            accepted_routes: if value.unsigned_peer_api_only {
                value.addresses.clone()
            } else {
                value
                    .allowed_ips
                    .clone()
                    .unwrap_or_else(|| value.addresses.clone())
            },
            underlay_addresses: value.endpoints.clone(),

            // legacy_derp_string is still in practical use as of 3/2026
            #[allow(deprecated)]
            derp_region: value
                .home_derp
                .or(value.legacy_derp_string)
                .or_else(|| value.host_info.net_info.as_ref()?.preferred_derp)
                .map(|x| ts_derp::RegionId(x.into())),

            cap: value.cap,
            cap_map,
            peerapi_port,
            peerapi_dns_proxy,
            is_wireguard_only: value.is_wireguard_only,
            exit_node_dns_resolvers: value
                .exit_node_dns_resolvers
                .iter()
                .filter_map(Resolver::from_serde)
                .collect(),
            peer_relay: value.host_info.peer_relay,
            // Project the advertised SSH host keys (Go `Hostinfo.SSHHostKeys`), mapping the
            // borrowed `Option<Vec<&str>>` to owned `Vec<String>`; absent ⇒ empty (never
            // fabricated), matching how `services`/`peer_relay` above are projected from host_info.
            ssh_host_keys: value
                .host_info
                .ssh_host_keys
                .as_ref()
                .map(|keys| keys.iter().map(|k| k.to_string()).collect())
                .unwrap_or_default(),
            service_vips,
        }
    }
}

/// An incremental update to a single already-known peer [`Node`], carried in
/// [`MapResponse::peers_changed_patch`][ts_control_serde::MapResponse::peers_changed_patch].
///
/// Control sends a patch (rather than a full node in `peers_changed`) when only a peer's
/// reachability changes mid-session — most importantly its UDP `endpoints`
/// and home [`derp_region`][PeerChange::derp_region] when an idle peer re-establishes connectivity.
/// Every field is `Option`: a patch sets only the fields it carries and leaves the rest of the
/// target node unchanged (see `PeerTracker::apply_peer_update` for the merge). Owned counterpart
/// of the borrow-bound [`ts_control_serde::PeerChange`]; the fields that map onto a domain
/// [`Node`] field are retained, including control's `online`/`last_seen` liveness deltas — the
/// dominant channel by which peer online transitions are delivered (see [`Node::online`]).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PeerChange {
    /// The [`Node::id`] of the peer being mutated. If no peer with this id is in the current
    /// netmap, the patch is ignored (the wire contract — a patch never creates a node).
    pub id: Id,
    /// If `Some`, the peer's new home DERP region.
    pub derp_region: Option<ts_derp::RegionId>,
    /// If `Some`, the peer's new advertised capability version.
    pub cap: Option<CapabilityVersion>,
    /// If `Some`, the peer's new capability map (replaces the prior map wholesale).
    pub cap_map: Option<NodeCapMap>,
    /// If `Some`, the peer's new UDP underlay endpoints (`Endpoints` in Go; replaces the prior
    /// set). This is the field that lets magicsock re-handshake a peer that moved.
    pub underlay_addresses: Option<Vec<SocketAddr>>,
    /// If `Some`, the peer's new WireGuard public key (key rotation).
    pub node_key: Option<NodePublicKey>,
    /// If `Some`, the marshalled TKA signature over the new node key. Re-verified at the
    /// peer-trust chokepoint when tailnet-lock enforcement is active.
    pub key_signature: Option<Vec<u8>>,
    /// If `Some`, the peer's new disco public key.
    pub disco_key: Option<DiscoPublicKey>,
    /// If `Some`, the peer's new node-key expiry (`KeyExpiry` in Go). Maps to
    /// [`Node::node_key_expiry`]; carried so an expiry-only patch isn't lost until the next full
    /// resync.
    pub node_key_expiry: Option<DateTime<Utc>>,
    /// If `Some`, the peer's new online status (`PeerChange.Online`). `None` here means "this patch
    /// did not touch online", **not** "offline" — the merge sets [`Node::online`] only when present.
    pub online: Option<bool>,
    /// If `Some`, the peer's new last-seen time (`PeerChange.LastSeen`). Maps to [`Node::last_seen`].
    pub last_seen: Option<DateTime<Utc>>,
}

impl From<&ts_control_serde::PeerChange<'_>> for PeerChange {
    fn from(value: &ts_control_serde::PeerChange) -> Self {
        Self {
            id: value.node_id,
            derp_region: value.derp_region.map(|x| ts_derp::RegionId(x.into())),
            cap: value.cap,
            cap_map: value.cap_map.as_ref().map(cap_map_from_serde),
            underlay_addresses: value.endpoints.clone(),
            node_key: value.key,
            key_signature: value.key_signature.map(|s| s.to_vec()),
            disco_key: value.disco_key,
            node_key_expiry: value.key_expiry,
            online: value.online,
            last_seen: value.last_seen,
        }
    }
}

/// Identity of the user that owns a [`Node`], resolved from the netmap's `UserProfiles` table
/// (Go `tailcfg.UserProfile`). Owned counterpart of the borrow-bound
/// [`ts_control_serde::UserProfile`]. Keyed by [`UserProfile::id`] (== [`Node::user_id`]).
///
/// Mostly display-friendly text ([`login_name`](Self::login_name),
/// [`display_name`](Self::display_name)), plus [`groups`](Self::groups) — the one attribute here an
/// embedder can *authorise* on, because it is the one a node cannot re-derive from anything else
/// control sends.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UserProfile {
    /// The integer id of the Tailscale user this profile describes (matches [`Node::user_id`]).
    pub id: ts_control_serde::UserId,
    /// An email-ish login name for display (e.g. `alice@example.com` / `alice@github`). May be
    /// empty if control sent none.
    pub login_name: String,
    /// The user's display name (e.g. `Alice Smith`), if the IdP provided one.
    pub display_name: Option<String>,
    /// The groups that contain this user and that the coordination server was configured to report
    /// to this node (Go `tailcfg.UserProfile.Groups`): SCIM groups (e.g.
    /// `engineering@example.com`) or tailnet-policy group names (e.g. `group:eng`).
    ///
    /// Carried in the order control sent it (control sorts it when it loads the profile from
    /// storage). **Empty** when control reported no groups — including every control server older
    /// than the field, which omits it entirely. An empty list therefore means "control told this
    /// node nothing", not "this user is in no group": treat it as no grant, never as a denial you
    /// can act on.
    pub groups: Vec<String>,
}

impl From<&ts_control_serde::UserProfile<'_>> for UserProfile {
    fn from(value: &ts_control_serde::UserProfile) -> Self {
        Self {
            id: value.id,
            login_name: value.login_name.to_string(),
            display_name: value.display_name.as_deref().map(str::to_string),
            groups: value.groups.iter().map(|g| g.to_string()).collect(),
        }
    }
}

impl UserProfile {
    /// The best human-facing label for this user: the login name when present, else the display
    /// name, else `None`. This is what a `WhoIs` surfaces as the owning user.
    pub fn best_label(&self) -> Option<String> {
        if !self.login_name.is_empty() {
            Some(self.login_name.clone())
        } else {
            self.display_name.clone()
        }
    }
}

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

    /// The wire `Node.User` id must be carried onto the domain `Node.user_id` by the `From` impl
    /// (the field the runtime joins against the netmap `UserProfiles` table for `WhoIs.user`).
    /// Guards against the `From` impl wiring the wrong serde field or dropping it.
    #[test]
    fn from_wire_node_carries_user_id() {
        let mut wire = ts_control_serde::Node {
            user: 4242,
            ..Default::default()
        };
        wire.name = "host.tail.ts.net.".into();
        let domain: Node = (&wire).into();
        assert_eq!(domain.user_id, 4242);

        // Default (no owner / tagged node) stays 0.
        let tagged = ts_control_serde::Node::default();
        assert_eq!(Node::from(&tagged).user_id, 0);
    }

    /// The wire `Hostinfo.sshHostKeys` must be projected onto the domain `Node.ssh_host_keys`
    /// (the field `tailscale ssh` reads via `StatusNode` to pin a peer's host key). Present →
    /// carried verbatim; absent → empty (never fabricated).
    #[test]
    fn from_wire_node_carries_ssh_host_keys() {
        let wire = ts_control_serde::Node {
            host_info: ts_control_serde::HostInfo {
                ssh_host_keys: Some(vec![
                    "ssh-ed25519 AAAAC3Nz host",
                    "ecdsa-sha2-nistp256 AAAAE2Vj host",
                ]),
                ..Default::default()
            },
            ..Default::default()
        };
        let domain: Node = (&wire).into();
        assert_eq!(
            domain.ssh_host_keys,
            vec![
                "ssh-ed25519 AAAAC3Nz host".to_string(),
                "ecdsa-sha2-nistp256 AAAAE2Vj host".to_string(),
            ]
        );

        // Absent on the wire → empty Vec, not fabricated.
        let bare = ts_control_serde::Node::default();
        assert!(Node::from(&bare).ssh_host_keys.is_empty());
    }

    /// A node from an **IPv4-only** tailnet (IPv6-off control plane / Headscale) carries a
    /// single-element `addresses` list. This used to fail deserialization ("invalid length 1,
    /// expected a tuple of size 2") when `addresses` was a fixed 2-tuple; it must now parse and
    /// derive the v4 identity, with the unused v6 a synthesized placeholder.
    #[test]
    fn from_wire_node_ipv4_only_addresses() {
        let wire = ts_control_serde::Node {
            addresses: vec!["100.64.0.5/32".parse().unwrap()],
            ..Default::default()
        };
        let domain: Node = (&wire).into();
        assert_eq!(
            domain.tailnet_address.ipv4,
            "100.64.0.5/32".parse().unwrap()
        );
        // No v6 on the wire → unspecified placeholder (never read in IPv4-only mode).
        assert_eq!(
            domain.tailnet_address.ipv6,
            ipnet::Ipv6Net::new(core::net::Ipv6Addr::UNSPECIFIED, 128).unwrap()
        );
        // AllowedIPs absent → falls back to the node's own assigned prefixes (just the v4 here).
        assert_eq!(
            domain.accepted_routes,
            vec!["100.64.0.5/32".parse::<ipnet::IpNet>().unwrap()]
        );
    }

    /// A dual-stack node carries both families (any order); the domain picks the first of each.
    #[test]
    fn from_wire_node_dual_stack_addresses() {
        let wire = ts_control_serde::Node {
            addresses: vec![
                "100.64.0.7/32".parse().unwrap(),
                "fd7a:115c:a1e0::7/128".parse().unwrap(),
            ],
            ..Default::default()
        };
        let domain: Node = (&wire).into();
        assert_eq!(
            domain.tailnet_address.ipv4,
            "100.64.0.7/32".parse().unwrap()
        );
        assert_eq!(
            domain.tailnet_address.ipv6,
            "fd7a:115c:a1e0::7/128".parse().unwrap()
        );
    }

    /// A wire peer that owns `100.64.0.9/32` and is handed `route` plus the default route in its
    /// `AllowedIPs`. `unsigned` sets `UnsignedPeerAPIOnly`; everything else is identical between
    /// the two, so the only variable in the test below is that flag.
    fn wire_peer_advertising(
        stable_id: &'static str,
        route: &str,
        unsigned: bool,
    ) -> ts_control_serde::Node<'static> {
        ts_control_serde::Node {
            stable_id: ts_control_serde::StableNodeId(stable_id),
            addresses: vec!["100.64.0.9/32".parse().unwrap()],
            allowed_ips: Some(vec![
                "100.64.0.9/32".parse().unwrap(),
                route.parse().unwrap(),
                "0.0.0.0/0".parse().unwrap(),
            ]),
            unsigned_peer_api_only: unsigned,
            ..Default::default()
        }
    }

    /// `UnsignedPeerAPIOnly` must clamp a peer's accepted routes back to its own addresses, so a
    /// control server cannot grant an unsigned (lock-exempt) peer network access via advertised
    /// routes. Mirrors Go's `upgradeNode` in `control/controlclient/map.go`.
    ///
    /// The signed peer is the control: it advertises the **same** route and the same default route,
    /// and keeps both. Without it this test would still pass if the `From` impl simply dropped every
    /// advertised route.
    #[test]
    fn from_wire_unsigned_peer_api_only_clamps_routes_to_own_addresses() {
        let own: ipnet::IpNet = "100.64.0.9/32".parse().unwrap();
        let subnet: ipnet::IpNet = "192.0.2.0/24".parse().unwrap();
        let default_route: ipnet::IpNet = "0.0.0.0/0".parse().unwrap();

        let unsigned: Node = (&wire_peer_advertising("nUnsigned", "192.0.2.0/24", true)).into();
        let signed: Node = (&wire_peer_advertising("nSigned", "192.0.2.0/24", false)).into();

        // The flag is carried onto the domain node, not silently dropped.
        assert!(unsigned.unsigned_peer_api_only);
        assert!(!signed.unsigned_peer_api_only);

        // Unsigned: clamped to its own addresses. The advertised subnet and the default route are
        // both gone, whatever control sent.
        assert_eq!(unsigned.accepted_routes, vec![own]);

        // Signed: the identical advertisement survives verbatim.
        assert_eq!(
            signed.accepted_routes,
            vec![own, subnet, default_route],
            "the clamp must be specific to UnsignedPeerAPIOnly, not a blanket route drop"
        );

        // Consequences the rest of the fork reads. `is_router` reports the unsigned peer routes
        // nothing but itself...
        assert!(!unsigned.is_router());
        assert!(signed.is_router());

        // ...and no route-install policy can resurrect the advertisement: even with
        // `--accept-routes` on AND the peer selected as the exit node — the most permissive input
        // `routes_to_install` accepts — the unsigned peer yields only its own address.
        let installed: Vec<_> = unsigned
            .routes_to_install(true, Some(&unsigned.stable_id))
            .copied()
            .collect();
        assert_eq!(installed, vec![own]);

        // The same permissive inputs against the signed peer do install the subnet and the /0,
        // proving the difference is the flag and not the policy arguments.
        let installed_signed: Vec<_> = signed
            .routes_to_install(true, Some(&signed.stable_id))
            .copied()
            .collect();
        assert_eq!(installed_signed, vec![own, subnet, default_route]);
    }

    /// The wire default (`UnsignedPeerAPIOnly` absent) must leave `AllowedIPs` untouched, including
    /// the capver-112 "null AllowedIPs means the node's own addresses" fallback. Guards against the
    /// clamp being applied on the wrong branch.
    #[test]
    fn from_wire_default_is_not_clamped() {
        let wire = ts_control_serde::Node {
            addresses: vec!["100.64.0.9/32".parse().unwrap()],
            allowed_ips: Some(vec!["198.51.100.0/24".parse().unwrap()]),
            ..Default::default()
        };
        assert!(!wire.unsigned_peer_api_only);
        let domain: Node = (&wire).into();
        assert_eq!(
            domain.accepted_routes,
            vec!["198.51.100.0/24".parse::<ipnet::IpNet>().unwrap()]
        );
    }

    /// An unsigned peer with **no** `AllowedIPs` on the wire still lands on its own addresses (the
    /// clamp and the capver-112 fallback agree), and a multi-prefix unsigned peer keeps *all* of
    /// its assigned prefixes — the clamp is to `Addresses`, not to the v4/v6 identity pair.
    #[test]
    fn from_wire_unsigned_peer_clamp_keeps_every_assigned_prefix() {
        let wire = ts_control_serde::Node {
            addresses: vec![
                "100.64.0.9/32".parse().unwrap(),
                "fd7a:115c:a1e0::9/128".parse().unwrap(),
            ],
            allowed_ips: None,
            unsigned_peer_api_only: true,
            ..Default::default()
        };
        let domain: Node = (&wire).into();
        assert_eq!(
            domain.accepted_routes,
            vec![
                "100.64.0.9/32".parse::<ipnet::IpNet>().unwrap(),
                "fd7a:115c:a1e0::9/128".parse::<ipnet::IpNet>().unwrap(),
            ]
        );
        assert!(!domain.is_router());
    }

    /// The deserialization regression itself: a MapResponse-style Node JSON with a 1-element
    /// `Addresses` array must parse (this is the exact shape the dev-Headscale sends).
    #[test]
    fn deserialize_node_with_single_address() {
        let json = r#"{
            "ID": 1,
            "StableID": "n1",
            "Name": "host.tail.ts.net.",
            "User": 1,
            "Addresses": ["100.64.0.9/32"],
            "Key": "nodekey:0000000000000000000000000000000000000000000000000000000000000000",
            "Machine": null,
            "DiscoKey": null,
            "AllowedIPs": null,
            "Endpoints": []
        }"#;
        let wire: ts_control_serde::Node = serde_json::from_str(json).expect("1-addr node parses");
        assert_eq!(wire.addresses.len(), 1);
        let domain: Node = (&wire).into();
        assert_eq!(
            domain.tailnet_address.ipv4,
            "100.64.0.9/32".parse().unwrap()
        );
    }

    /// The consume side end to end: a MapResponse-shaped wire Node carrying a
    /// `services/<opaque-id>` capability decodes into the domain node, and the service — including
    /// an action type this build has never heard of — is surfaced rather than dropping the node.
    #[test]
    fn visible_services_parse_from_the_services_cap() {
        let json = r#"{
            "ID": 1,
            "StableID": "n1",
            "Name": "host.tail.ts.net.",
            "User": 1,
            "Addresses": ["100.64.0.9/32"],
            "Key": "nodekey:0000000000000000000000000000000000000000000000000000000000000000",
            "Machine": null,
            "DiscoKey": null,
            "AllowedIPs": null,
            "Endpoints": [],
            "CapMap": {
                "services/01HQ": [{
                    "Name": "svc:postgres",
                    "DisplayName": "Analytics DB",
                    "Addrs": ["100.65.32.7"],
                    "Ports": ["tcp:5432", "tcp:22"],
                    "Actions": [
                        {
                            "Type": "postgresql",
                            "Port": 5432,
                            "Attributes": {
                                "tailscale.com/cap/resource-name": "metrics"
                            }
                        },
                        { "Type": "ftp", "Port": 22 }
                    ]
                }],
                "services/01HR": [{ "Name": "svc:web", "Ports": ["tcp:80"] }]
            }
        }"#;
        let wire: ts_control_serde::Node =
            serde_json::from_str(json).expect("a node advertising services parses");
        let domain: Node = (&wire).into();

        let services = domain.visible_services();
        assert_eq!(services.len(), 2);

        let pg = &services[0];
        assert_eq!(pg.name.0, "svc:postgres");
        assert_eq!(pg.display_name, "Analytics DB");
        assert_eq!(pg.addrs, vec!["100.65.32.7".parse::<IpAddr>().unwrap()]);
        assert_eq!(pg.ports.len(), 2);
        // Both actions survive decoding, the unrecognized slug included.
        assert_eq!(pg.actions.len(), 2);
        assert_eq!(
            pg.actions[0].action_type,
            ts_control_serde::SERVICE_ACTION_TYPE_POSTGRESQL
        );
        assert_eq!(
            pg.actions[0].attributes[ts_control_serde::SERVICE_ACTION_ATTRIBUTE_RESOURCE_NAME]
                .get(),
            r#""metrics""#
        );
        assert!(!pg.actions[1].action_type.is_known());
        // …but only the recognized one is offered to a caller about to act on it.
        assert_eq!(pg.known_actions().count(), 1);

        assert_eq!(services[1].name.0, "svc:web");
        assert!(services[1].actions.is_empty());

        // The services cap is a consume-side grant only: it does not make this a service host.
        assert!(!domain.is_service_host());
    }

    /// A `services/` value that is not a `ServiceDetails` at all costs only itself: the other
    /// services still come back, and the node is still usable.
    #[test]
    fn visible_services_skips_an_unparseable_value() {
        let mut n = node("peer", Some("ts.net"));
        n.cap_map.insert(
            "services/broken".to_string(),
            vec!["\"not an object\"".to_string()],
        );
        n.cap_map.insert(
            "services/good".to_string(),
            vec![r#"{"Name":"svc:web","Ports":["tcp:80"]}"#.to_string()],
        );

        let services = n.visible_services();
        assert_eq!(services.len(), 1);
        assert_eq!(services[0].name.0, "svc:web");
    }

    /// No services cap at all is the common case and yields nothing, not an error.
    #[test]
    fn visible_services_empty_without_the_cap() {
        let n = node("peer", Some("ts.net"));
        assert!(n.visible_services().is_empty());
    }

    #[test]
    fn key_expiry_semantics() {
        let now: DateTime<Utc> = "2026-06-05T00:00:00Z".parse().unwrap();
        let past: DateTime<Utc> = "2020-01-01T00:00:00Z".parse().unwrap();
        let future: DateTime<Utc> = "2099-01-01T00:00:00Z".parse().unwrap();

        let mut n = node("h", Some("t.ts.net"));

        // No expiry set => never expired (Go zero-value semantics).
        n.node_key_expiry = None;
        assert!(!n.key_expired(now));
        assert_eq!(n.key_expiry(), None);

        // Future expiry => not yet expired.
        n.node_key_expiry = Some(future);
        assert!(!n.key_expired(now));
        assert_eq!(n.key_expiry(), Some(future));

        // Past expiry => expired.
        n.node_key_expiry = Some(past);
        assert!(n.key_expired(now));
    }

    #[test]
    fn key_expiry_unix_agrees_with_chrono() {
        // The chrono-free variants (`key_expired_at_unix` / `key_expiry_unix`) must agree with the
        // chrono variants for the same none/future/past cases (Unix seconds of the same instants).
        let now: DateTime<Utc> = "2026-06-05T00:00:00Z".parse().unwrap();
        let past: DateTime<Utc> = "2020-01-01T00:00:00Z".parse().unwrap();
        let future: DateTime<Utc> = "2099-01-01T00:00:00Z".parse().unwrap();
        let now_unix = now.timestamp();

        let mut n = node("h", Some("t.ts.net"));

        // No expiry => never expired; the unix accessor reports `None`.
        n.node_key_expiry = None;
        assert_eq!(n.key_expired(now), n.key_expired_at_unix(now_unix));
        assert!(!n.key_expired_at_unix(now_unix));
        assert_eq!(n.key_expiry_unix(), None);

        // Future expiry => not yet expired; unix accessor matches the chrono timestamp.
        n.node_key_expiry = Some(future);
        assert_eq!(n.key_expired(now), n.key_expired_at_unix(now_unix));
        assert!(!n.key_expired_at_unix(now_unix));
        assert_eq!(n.key_expiry_unix(), Some(future.timestamp()));

        // Past expiry => expired; unix accessor matches the chrono timestamp.
        n.node_key_expiry = Some(past);
        assert_eq!(n.key_expired(now), n.key_expired_at_unix(now_unix));
        assert!(n.key_expired_at_unix(now_unix));
        assert_eq!(n.key_expiry_unix(), Some(past.timestamp()));
    }

    #[test]
    fn key_expiry_boundary_is_not_expired() {
        // A key whose expiry exactly equals `now` is NOT expired: the code uses strict `<`, matching
        // Go's `Before`. Both the chrono and chrono-free variants must agree at the boundary.
        let now: DateTime<Utc> = "2026-06-05T00:00:00Z".parse().unwrap();
        let now_unix = now.timestamp();

        let mut n = node("h", Some("t.ts.net"));
        n.node_key_expiry = Some(now);

        assert!(!n.key_expired(now));
        assert!(!n.key_expired_at_unix(now_unix));
    }

    #[test]
    fn is_peer_relay_returns_field() {
        let mut n = node("h", Some("t.ts.net"));

        n.peer_relay = true;
        assert!(n.is_peer_relay());

        n.peer_relay = false;
        assert!(!n.is_peer_relay());
    }

    /// A minimal well-formed peer, shared with the `expiry` module's tests so both reason about
    /// the same node shape.
    pub(crate) fn test_node() -> Node {
        node("h", Some("t.ts.net"))
    }

    fn node(hostname: &str, tailnet: Option<&str>) -> Node {
        Node {
            id: 1,
            stable_id: StableId("n1".to_string()),
            hostname: hostname.to_string(),
            user_id: 0,
            tailnet: tailnet.map(str::to_string),
            tags: vec![],
            addresses: vec![
                "100.64.0.1/32".parse().unwrap(),
                "fd7a::1/128".parse().unwrap(),
            ],
            tailnet_address: TailnetAddress {
                ipv4: "100.64.0.1/32".parse().unwrap(),
                ipv6: "fd7a::1/128".parse().unwrap(),
            },
            node_key: [0u8; 32].into(),
            node_key_expiry: None,
            expired: false,
            online: None,
            last_seen: None,
            key_signature: vec![],
            machine_key: None,
            disco_key: None,
            accepted_routes: vec![],
            underlay_addresses: vec![],
            derp_region: None,
            cap: CapabilityVersion::default(),
            cap_map: NodeCapMap::new(),
            peerapi_port: None,
            peerapi_dns_proxy: false,
            is_wireguard_only: false,
            exit_node_dns_resolvers: vec![],
            peer_relay: false,
            ssh_host_keys: vec![],
            service_vips: Default::default(),
            unsigned_peer_api_only: false,
        }
    }

    #[test]
    fn matches_name_is_case_and_trailing_dot_insensitive() {
        let n = node("MyHost", Some("tail-scale.ts.net"));

        // bare hostname, any case
        assert!(n.matches_name("myhost"));
        assert!(n.matches_name("MYHOST"));
        assert!(n.matches_name("MyHost"));

        // fqdn, any case, with and without trailing dot
        assert!(n.matches_name("myhost.tail-scale.ts.net"));
        assert!(n.matches_name("MYHOST.TAIL-SCALE.TS.NET"));
        assert!(n.matches_name("myhost.tail-scale.ts.net."));
        assert!(n.matches_name("MyHost.Tail-Scale.TS.NET."));

        // wrong host / wrong tailnet must not match
        assert!(!n.matches_name("other"));
        assert!(!n.matches_name("myhost.other.ts.net"));
    }

    #[test]
    fn matches_name_no_tailnet() {
        let n = node("solo", None);
        assert!(n.matches_name("solo"));
        assert!(n.matches_name("SOLO."));
        assert!(!n.matches_name("solo.ts.net"));
    }

    #[test]
    fn is_tailscale_ip_ranges() {
        // CGNAT v4
        assert!(is_tailscale_ip("100.64.0.1".parse().unwrap()));
        assert!(is_tailscale_ip("100.127.255.254".parse().unwrap()));
        // ChromeOS carve-out is excluded
        assert!(!is_tailscale_ip("100.115.92.5".parse().unwrap()));
        // outside CGNAT
        assert!(!is_tailscale_ip("10.0.0.1".parse().unwrap()));
        assert!(!is_tailscale_ip("100.128.0.1".parse().unwrap()));
        // Tailscale ULA v6
        assert!(is_tailscale_ip("fd7a:115c:a1e0::1".parse().unwrap()));
        assert!(!is_tailscale_ip("fd00::1".parse().unwrap()));
    }

    /// Taildrop SSRF guard (defense-in-depth). `Device::send_file` rejects an upload destination
    /// unless `is_tailscale_ip(peer.peerapi_addr().ip())` holds. `Device::send_file` itself needs a
    /// live runtime (it goes through `self.channel()`), so it can't be unit-tested here; instead we
    /// test the exact composition the guard relies on — `is_tailscale_ip ∘ peerapi_addr` — against a
    /// `Node` whose `tailnet_address.ipv4` has been corrupted to a non-CGNAT (public) address. A
    /// well-formed peer always has a CGNAT 100.64.0.0/10 address, but the guard exists to catch a
    /// malformed/hostile node; this proves it would reject one.
    #[test]
    fn taildrop_ssrf_guard_rejects_non_cgnat_peerapi_addr() {
        let mut n = node("evil", Some("ts.net"));
        // Corrupt the peer to a public, non-CGNAT address and advertise a peerAPI port so
        // `peerapi_addr` returns `Some(_)`.
        n.tailnet_address.ipv4 = "1.2.3.4/32".parse().unwrap();
        n.peerapi_port = Some(443);

        let addr = n
            .peerapi_addr()
            .expect("peerapi_addr yields Some with a port set");
        assert_eq!(addr.ip(), Ipv4Addr::new(1, 2, 3, 4));
        // The guard `if !is_tailscale_ip(dst.ip()) { return Err(BadRequest) }` WOULD reject this.
        assert!(
            !is_tailscale_ip(addr.ip()),
            "SSRF guard must reject a peer whose peerAPI addr is not a Tailscale CGNAT IP"
        );

        // Conversely, a well-formed CGNAT peer passes the guard.
        let mut good = node("friend", Some("ts.net"));
        good.peerapi_port = Some(443);
        let good_addr = good.peerapi_addr().expect("peerapi_addr yields Some");
        assert!(is_tailscale_ip(good_addr.ip()));
    }

    /// Ported from upstream's `TestNodeIsRouter` (`tailcfg/tailcfg_test.go`, `8d830599b`): a node
    /// is a router exactly when its `AllowedIPs` reach past its own `Addresses`. The absent case
    /// (a plain node advertising only its own addresses) is asserted alongside the present one,
    /// since "no routes besides my own" is the answer that must not drift.
    #[test]
    fn is_router_reports_routes_beyond_own_addresses() {
        let v4: ipnet::Ipv4Net = "100.64.0.1/32".parse().unwrap();
        let v6: ipnet::Ipv6Net = "fd7a:115c:a1e0::1/128".parse().unwrap();
        let self4 = ipnet::IpNet::V4(v4);
        let self6 = ipnet::IpNet::V6(v6);

        let cases: &[(&str, Vec<ipnet::IpNet>, bool)] = &[
            ("empty", vec![], false),
            ("plain-ipv4", vec![self4], false),
            ("plain-ipv6", vec![self6], false),
            ("plain-ipv4-ipv6", vec![self4, self6], false),
            ("duplicates", vec![self4, self4], false),
            (
                "exit-node-ipv4",
                vec![self4, "0.0.0.0/0".parse().unwrap()],
                true,
            ),
            ("exit-node-ipv6", vec![self6, "::/0".parse().unwrap()], true),
            (
                "exit-node-ipv4-ipv6",
                vec![
                    self4,
                    self6,
                    "0.0.0.0/0".parse().unwrap(),
                    "::/0".parse().unwrap(),
                ],
                true,
            ),
            (
                "subnet-router-ipv4",
                vec![self4, "192.0.2.0/24".parse().unwrap()],
                true,
            ),
            (
                "subnet-router-ipv6",
                vec![self6, "2001:db8::/32".parse().unwrap()],
                true,
            ),
            (
                "subnet-router-ipv4-ipv6",
                vec![
                    self4,
                    self6,
                    "192.0.2.0/24".parse().unwrap(),
                    "2001:db8::/32".parse().unwrap(),
                ],
                true,
            ),
            // Go's `IsRouter` has no Tailscale-range exception: another peer's /32 is still a
            // routed address. This is where it parts ways with `is_subnet_route`.
            (
                "other-tailnet-host",
                vec![self4, "100.64.5.5/32".parse().unwrap()],
                true,
            ),
        ];

        for (name, allowed, want) in cases {
            let mut n = node("host", Some("ts.net"));
            n.addresses = vec![self4, self6];
            n.tailnet_address = TailnetAddress { ipv4: v4, ipv6: v6 };
            n.accepted_routes = allowed.clone();
            assert_eq!(n.is_router(), *want, "{name}");
        }
    }

    /// Go's `IsRouter` tests each `AllowedIPs` prefix against the node's **whole** `Addresses`
    /// slice, so every prefix control assigned is "its own". The wire field is a variable-length
    /// list, not a v4/v6 pair, so a tailnet may hand a node more than one prefix of a family; such
    /// a node must not be reported as a router on account of the extra one — which comparing only
    /// against the first-of-family `tailnet_address` pair does. Runs through the production `From`
    /// impl so the retention of the full list is pinned along with the predicate.
    #[test]
    fn is_router_tests_every_assigned_address_not_only_the_first_of_each_family() {
        let second4: ipnet::IpNet = "100.64.0.9/32".parse().unwrap();
        let second6: ipnet::IpNet = "fd7a:115c:a1e0::9/128".parse().unwrap();
        let wire = ts_control_serde::Node {
            addresses: vec![
                "100.64.0.1/32".parse().unwrap(),
                second4,
                "fd7a:115c:a1e0::1/128".parse().unwrap(),
                second6,
            ],
            ..Default::default()
        };
        let domain: Node = (&wire).into();

        // The identity projection is still the first prefix of each family...
        assert_eq!(
            domain.tailnet_address.ipv4,
            "100.64.0.1/32".parse().unwrap()
        );
        // ...but every assigned prefix is retained, and (AllowedIPs absent ⇒ routes are exactly
        // the addresses) none of them makes the node a router.
        assert_eq!(domain.addresses, wire.addresses);
        assert!(
            !domain.is_router(),
            "a node whose routes are exactly its own assigned prefixes is not a router"
        );

        // Either second-of-family address on its own is still not a routed prefix.
        for extra in [second4, second6] {
            let mut n = domain.clone();
            n.accepted_routes = vec![extra];
            assert!(
                !n.is_router(),
                "{extra} is one of this node's own addresses"
            );
        }

        // The predicate still fires for a route that does reach past every assigned address.
        let mut router = domain.clone();
        router.accepted_routes.push("192.0.2.0/24".parse().unwrap());
        assert!(router.is_router(), "a real subnet route makes it a router");
    }

    #[test]
    fn is_subnet_route_distinguishes_self_from_subnet() {
        let n = node("host", Some("ts.net"));

        // The node's own /32 and /128 are self-addresses, not subnet routes.
        assert!(!n.is_subnet_route(&"100.64.0.1/32".parse().unwrap()));
        assert!(!n.is_subnet_route(&"fd7a::1/128".parse().unwrap()));
        // A different single Tailscale IP is still a self-address (Tailscale-assigned host).
        assert!(!n.is_subnet_route(&"100.64.5.5/32".parse().unwrap()));
        // A LAN /24 the node advertises is a subnet route.
        assert!(n.is_subnet_route(&"192.168.1.0/24".parse().unwrap()));
        // A single non-Tailscale host IP counts as a subnet route.
        assert!(n.is_subnet_route(&"8.8.8.8/32".parse().unwrap()));
        // The default route is treated as a subnet route.
        assert!(n.is_subnet_route(&"0.0.0.0/0".parse().unwrap()));
        assert!(n.is_subnet_route(&"::/0".parse().unwrap()));
    }

    #[test]
    fn routes_to_install_gates_subnets_on_accept_routes() {
        let mut n = node("host", Some("ts.net"));
        let self4: ipnet::IpNet = "100.64.0.1/32".parse().unwrap();
        let self6: ipnet::IpNet = "fd7a::1/128".parse().unwrap();
        let subnet: ipnet::IpNet = "192.168.1.0/24".parse().unwrap();
        n.accepted_routes = vec![self4, self6, subnet];

        // accept_routes off: only the self addresses are installed.
        let off: Vec<_> = n.routes_to_install(false, None).copied().collect();
        assert_eq!(off, vec![self4, self6]);

        // accept_routes on: the advertised subnet is installed too.
        let on: Vec<_> = n.routes_to_install(true, None).copied().collect();
        assert_eq!(on, vec![self4, self6, subnet]);
    }

    #[test]
    fn routes_to_install_default_route_only_for_selected_exit_node() {
        let mut n = node("host", Some("ts.net"));
        n.stable_id = StableId("exit1".to_string());
        let self4: ipnet::IpNet = "100.64.0.1/32".parse().unwrap();
        let default4: ipnet::IpNet = "0.0.0.0/0".parse().unwrap();
        let default6: ipnet::IpNet = "::/0".parse().unwrap();
        n.accepted_routes = vec![self4, default4, default6];

        // No exit node selected: default routes are excluded even with accept_routes on
        // (fail-closed — internet-bound traffic has no overlay route and is dropped).
        let none_off: Vec<_> = n.routes_to_install(false, None).copied().collect();
        assert_eq!(none_off, vec![self4]);
        let none_on: Vec<_> = n.routes_to_install(true, None).copied().collect();
        assert_eq!(none_on, vec![self4]);

        // A *different* peer selected as exit node: this peer still gets no default route.
        let other = StableId("exit2".to_string());
        let other_sel: Vec<_> = n.routes_to_install(false, Some(&other)).copied().collect();
        assert_eq!(other_sel, vec![self4]);

        // This peer selected as the exit node: its default routes are installed.
        let me = StableId("exit1".to_string());
        let sel: Vec<_> = n.routes_to_install(false, Some(&me)).copied().collect();
        assert_eq!(sel, vec![self4, default4, default6]);
    }

    fn exit_node_with(id: &str, ipv4: &str, hostname: &str, tailnet: Option<&str>) -> Node {
        let mut n = node(hostname, tailnet);
        n.stable_id = StableId(id.to_string());
        n.tailnet_address.ipv4 = format!("{ipv4}/32").parse().unwrap();
        n
    }

    #[test]
    fn exit_node_selector_resolves_by_id_ip_and_name() {
        let a = exit_node_with("nA", "100.64.0.5", "alpha", Some("ts.net"));
        let b = exit_node_with("nB", "100.64.0.6", "beta", Some("ts.net"));
        let peers = [a, b];
        let it = || peers.iter();

        // By stable id.
        assert_eq!(
            ExitNodeSelector::StableId(StableId("nB".into())).resolve(it()),
            Some(StableId("nB".into()))
        );
        // By tailnet IP.
        assert_eq!(
            ExitNodeSelector::Ip("100.64.0.5".parse().unwrap()).resolve(it()),
            Some(StableId("nA".into()))
        );
        // By MagicDNS name (fqdn, case-insensitive).
        assert_eq!(
            ExitNodeSelector::Name("BETA.ts.net".into()).resolve(it()),
            Some(StableId("nB".into()))
        );
        // By bare hostname.
        assert_eq!(
            ExitNodeSelector::Name("alpha".into()).resolve(it()),
            Some(StableId("nA".into()))
        );
        // Unresolvable selector => None (fail-closed at the call site).
        assert_eq!(
            ExitNodeSelector::Ip("100.64.0.99".parse().unwrap()).resolve(it()),
            None
        );
        assert_eq!(ExitNodeSelector::Name("ghost".into()).resolve(it()), None);
    }

    #[test]
    fn exit_node_selector_resolution_is_deterministic_on_ties() {
        // Two peers sharing a name (transient netmap state): the smallest stable id wins, so the
        // outbound table and inbound source filter — which resolve independently — agree.
        let a = exit_node_with("nZ", "100.64.0.5", "dup", Some("ts.net"));
        let b = exit_node_with("nA", "100.64.0.6", "dup", Some("ts.net"));
        let peers = [a, b];

        assert_eq!(
            ExitNodeSelector::Name("dup".into()).resolve(peers.iter()),
            Some(StableId("nA".into())),
            "smallest stable id wins the tie"
        );
        // Order of iteration must not change the result.
        assert_eq!(
            ExitNodeSelector::Name("dup".into()).resolve(peers.iter().rev()),
            Some(StableId("nA".into()))
        );
    }

    #[test]
    fn peerapi_doh_url_requires_port_and_capability() {
        let mut n = node("exit", Some("ts.net"));
        n.tailnet_address.ipv4 = "100.64.0.5/32".parse().unwrap();

        // No peerAPI port advertised: cannot proxy DNS.
        n.peerapi_port = None;
        n.cap = CapabilityVersion::V130;
        assert_eq!(n.peerapi_doh_url(), None);

        // Port advertised but capability too old and no explicit service: cannot proxy.
        n.peerapi_port = Some(8080);
        n.cap = CapabilityVersion::V25;
        n.peerapi_dns_proxy = false;
        assert_eq!(n.peerapi_doh_url(), None);

        // Port + new-enough capability: yields the DoH URL on the IPv4 address.
        n.cap = CapabilityVersion::V26;
        assert_eq!(
            n.peerapi_doh_url().as_deref(),
            Some("http://100.64.0.5:8080/dns-query")
        );

        // Port + explicit peerapi-dns-proxy service, even with an old capability.
        n.cap = CapabilityVersion::V25;
        n.peerapi_dns_proxy = true;
        assert_eq!(
            n.peerapi_doh_url().as_deref(),
            Some("http://100.64.0.5:8080/dns-query")
        );

        // WireGuard-only peers never run a peerAPI: no DoH URL even with a port.
        n.is_wireguard_only = true;
        assert_eq!(n.peerapi_doh_url(), None);
    }

    #[test]
    fn peerapi_doh_addr_matches_url_gate() {
        let mut n = node("exit", Some("ts.net"));
        n.tailnet_address.ipv4 = "100.64.0.5/32".parse().unwrap();
        n.peerapi_port = Some(8080);
        n.cap = CapabilityVersion::V26;

        // The addr form the DoH client dials is the same gated endpoint as the URL.
        assert_eq!(
            n.peerapi_doh_addr(),
            Some("100.64.0.5:8080".parse().unwrap())
        );
        // And it composes into exactly the URL form.
        assert_eq!(
            n.peerapi_doh_url().as_deref(),
            Some("http://100.64.0.5:8080/dns-query")
        );

        // Gated off the same way: no port => no addr.
        n.peerapi_port = None;
        assert_eq!(n.peerapi_doh_addr(), None);
    }

    #[test]
    fn peerapi_addr_returns_addr_when_advertised() {
        let mut n = node("peer", Some("ts.net"));
        n.tailnet_address.ipv4 = "100.64.0.5/32".parse().unwrap();
        n.peerapi_port = Some(8089);

        // Not gated on the DNS-proxy capability: a plain advertised peerAPI port is enough.
        assert_eq!(n.peerapi_addr(), Some("100.64.0.5:8089".parse().unwrap()));
    }

    #[test]
    fn peerapi_addr_none_when_no_port() {
        let mut n = node("peer", Some("ts.net"));
        n.tailnet_address.ipv4 = "100.64.0.5/32".parse().unwrap();
        n.peerapi_port = None;

        assert_eq!(n.peerapi_addr(), None);
    }

    #[test]
    fn peerapi_addr_none_for_wireguard_only() {
        let mut n = node("peer", Some("ts.net"));
        n.tailnet_address.ipv4 = "100.64.0.5/32".parse().unwrap();
        n.peerapi_port = Some(8089);
        n.is_wireguard_only = true;

        // WireGuard-only peers run no peerAPI, even with a port set.
        assert_eq!(n.peerapi_addr(), None);
    }

    #[test]
    fn can_share_files_gated_on_self_capability() {
        let mut n = node("self", Some("ts.net"));
        assert!(
            !n.can_share_files(),
            "no cap → file sharing not enabled (fail-closed)"
        );
        n.cap_map
            .insert("https://tailscale.com/cap/file-sharing".to_string(), vec![]);
        assert!(n.can_share_files(), "the file-sharing cap enables it");
    }

    #[test]
    fn is_file_sharing_target_gated_on_peer_capability() {
        let mut n = node("peer", Some("ts.net"));
        assert!(
            !n.is_file_sharing_target(),
            "no cap → not an explicit target"
        );
        n.cap_map
            .insert("tailscale.com/cap/file-sharing-target".to_string(), vec![]);
        assert!(
            n.is_file_sharing_target(),
            "the file-sharing-target cap marks a cross-owner target"
        );
    }

    #[test]
    fn resolves_subdomains_gated_on_the_node_attribute() {
        let mut n = node("peer", Some("ts.net"));
        assert!(
            !n.resolves_subdomains(),
            "no attribute → not a subdomain host: control has to opt the node in"
        );
        n.cap_map
            .insert("dns-subdomain-resolve".to_string(), vec![]);
        assert!(
            n.resolves_subdomains(),
            "the dns-subdomain-resolve attribute makes this node a subdomain host"
        );
    }

    /// The DNS forwarder's TCP retry is ON by default, so the attribute has to be read as the *off*
    /// switch it is: absent means retry. Getting the polarity backwards would silently disable the
    /// retry on every tailnet that never set the attribute — the failure the retry exists to remove.
    #[test]
    fn dns_forwarder_tcp_retries_disabled_only_by_the_node_attribute() {
        let mut n = node("peer", Some("ts.net"));
        assert!(
            !n.disable_dns_forwarder_tcp_retries(),
            "no attribute → the retry stays on: this is the off switch, not the on switch"
        );
        n.cap_map
            .insert("dns-forwarder-disable-tcp-retries".to_string(), vec![]);
        assert!(
            n.disable_dns_forwarder_tcp_retries(),
            "the dns-forwarder-disable-tcp-retries attribute turns the TCP retry off"
        );
    }

    /// The debug-always-stun attribute is control's only way to keep the periodic STUN sweep running
    /// once the datapath has gone idle, so its key has to be the literal Go sends
    /// (`NodeAttrDebugForceBackgroundSTUN`). Absent is the quiet default.
    #[test]
    fn force_background_stun_gated_on_the_node_attribute() {
        let mut n = node("self", Some("ts.net"));
        assert!(
            !n.force_background_stun(),
            "no attribute → the idle stop applies, which is the quiet default"
        );
        n.cap_map.insert("debug-always-stun".to_string(), vec![]);
        assert!(
            n.force_background_stun(),
            "the debug-always-stun attribute keeps the background sweep running"
        );
    }

    #[test]
    fn one_cgnat_is_a_tri_state_read_off_the_query_string_keys() {
        let mut n = node("self", Some("ts.net"));
        assert_eq!(
            n.one_cgnat(),
            None,
            "neither attribute → control has no opinion, the platform default decides"
        );

        // The key carries a query string; the bare `one-cgnat` is not the attribute and must not
        // be mistaken for either half of the tri-state.
        n.cap_map.insert("one-cgnat".to_string(), vec![]);
        assert_eq!(
            n.one_cgnat(),
            None,
            "a bare `one-cgnat` key is not one of the two attributes control sets"
        );

        n.cap_map.insert("one-cgnat?v=false".to_string(), vec![]);
        assert_eq!(
            n.one_cgnat(),
            Some(false),
            "`one-cgnat?v=false` declines the forced collapse"
        );

        n.cap_map.insert("one-cgnat?v=true".to_string(), vec![]);
        assert_eq!(
            n.one_cgnat(),
            Some(true),
            "a node holding both attributes collapses: the enabling attribute is checked first"
        );

        n.cap_map.remove("one-cgnat?v=false");
        assert_eq!(
            n.one_cgnat(),
            Some(true),
            "`one-cgnat?v=true` alone collapses"
        );
    }

    #[test]
    fn delta_updates_disabled_reads_the_disable_delta_updates_attribute() {
        let mut n = node("self", Some("ts.net"));
        assert!(
            !n.delta_updates_disabled(),
            "absent attribute → the incremental path, which is the default"
        );

        // The attribute is the bare key; the presence of the key is the whole signal, and its
        // value (control sends an empty one) is never read.
        n.cap_map
            .insert("disable-delta-updates".to_string(), vec![]);
        assert!(
            n.delta_updates_disabled(),
            "control granted the attribute → decline the incremental path"
        );

        n.cap_map.remove("disable-delta-updates");
        assert!(
            !n.delta_updates_disabled(),
            "control withdrawing the attribute returns the node to the incremental path"
        );
    }

    #[test]
    fn silent_disco_reads_the_silent_disco_attribute() {
        let mut n = node("self", Some("ts.net"));
        assert!(
            !n.silent_disco(),
            "absent attribute → keep heartbeating, which is the default"
        );

        // The attribute is the bare key; the presence of the key is the whole signal, and its
        // value (control sends an empty one) is never read.
        n.cap_map.insert("silent-disco".to_string(), vec![]);
        assert!(
            n.silent_disco(),
            "control granted the attribute → stop heartbeating peers"
        );

        n.cap_map.remove("silent-disco");
        assert!(
            !n.silent_disco(),
            "control withdrawing the attribute returns the node to the heartbeat cadence"
        );
    }

    /// Control's `only-tcp-443` attribute is read off the self node's cap map, and — because
    /// upstream's `SetOnlyTCP443` is live rather than start-time — withdrawing it reads back as
    /// `false` on the very next netmap.
    #[test]
    fn only_tcp_443_reads_the_only_tcp_443_attribute() {
        let mut n = node("self", Some("ts.net"));
        assert!(
            !n.only_tcp_443(),
            "absent attribute → UDP as before, which is the default"
        );

        // The attribute is the bare key; the presence of the key is the whole signal, and its
        // value (control sends an empty one) is never read.
        n.cap_map.insert("only-tcp-443".to_string(), vec![]);
        assert!(
            n.only_tcp_443(),
            "control granted the attribute → this node emits nothing but TCP/443"
        );

        n.cap_map.remove("only-tcp-443");
        assert!(
            !n.only_tcp_443(),
            "control withdrawing the attribute must restore UDP, with no restart"
        );
    }

    #[test]
    fn peerapi_from_services_extracts_v4_port_and_dns_proxy_flag() {
        use ts_control_serde::{Service, ServiceProto};

        let services = [
            Service {
                proto: ServiceProto::PeerApi4,
                port: 8080,
                description: "peerapi".into(),
            },
            Service {
                proto: ServiceProto::PeerApi6,
                port: 9090,
                description: "peerapi6".into(),
            },
            Service {
                proto: ServiceProto::PeerApiDnsProxy,
                port: 1,
                description: "dns".into(),
            },
        ];
        let (port, dns_proxy) = peerapi_from_services(Some(&services));
        assert_eq!(port, Some(8080), "only the IPv4 peerAPI port is taken");
        assert!(dns_proxy);

        // No services at all.
        assert_eq!(peerapi_from_services(None), (None, false));
    }

    #[test]
    fn exit_node_selector_parses_ip_vs_name() {
        assert_eq!(
            "100.64.0.5".parse::<ExitNodeSelector>().unwrap(),
            ExitNodeSelector::Ip("100.64.0.5".parse().unwrap())
        );
        assert_eq!(
            "fd7a::5".parse::<ExitNodeSelector>().unwrap(),
            ExitNodeSelector::Ip("fd7a::5".parse().unwrap())
        );
        assert_eq!(
            "my-exit.ts.net".parse::<ExitNodeSelector>().unwrap(),
            ExitNodeSelector::Name("my-exit.ts.net".into())
        );
    }
}