@push.rocks/smartnftables 1.4.0 → 1.6.0

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@push.rocks/smartnftables",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "private": false,
   "description": "A TypeScript module for managing nftables rules including NAT, firewall, and rate limiting with a high-level API.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
   "type": "module",
-  "author": "Lossless GmbH",
+  "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "devDependencies": {
     "@git.zone/cli": "6.13.2",

package/readme.md

@@ -43,7 +43,7 @@ namespace rejects. Await complete policy and process cleanup before releasing
 the caller's final namespace owner. Namespace entry does not create uplink
 authority, drain conntrack flows or authorize address and port reuse.
 
-The Linux x86_64 musl candidate passed nine isolated Linux 6.18.35 kernel tests,
+The Linux x86_64 musl candidate passes isolated Linux 6.18.35 kernel tests,
 including inherited namespace entry, retained policy after process loss, recovery
 in the original namespace, rejection in another namespace, and denied entry
 before readiness. ARM binaries are built; privileged ARM and complete Pallet
@@ -115,7 +115,7 @@ grants remain outstanding.
 | `release(applied)` | Verifies the exact retained graph and confirms deletion; repeats are idempotent. |
 | `close()` | Stops command admission, joins admitted policy operations, confirms owned-table deletion, then joins the native process. Failure retains the owner for explicit recovery. |
 
-Policies are directed. Return traffic requires its own grant; there is no broad
+Schema-v1 policies are directed. Return traffic requires its own grant; there is no broad
 connection-tracking bypass. A null endpoint denotes the actual local host, with an
 explicit prefix that cannot overlap any endpoint. Such a grant applies only to
 input/output. Forwarding requires two explicit endpoint references; a relay TUN
@@ -142,7 +142,10 @@ uses the same caller-retained owner, instance, table and boot/namespace receipt.
 Recovery checks the complete graph before and after orphan adoption. The kernel's
 wrapping generation counter only fences concurrent transactions; it is never a
 durable revision or sufficient ownership proof. Foreign owners, unexpected tables,
-chains, rules, sets or objects reject without deletion.
+chains, rules, sets or objects inside the owned table reject without deletion.
+Other tables coexist independently. Linux's family-wide chain dump is explicitly
+filtered by table identity before graph comparison; foreign chains are never
+included in replacement or cleanup.
 
 PERSIST deliberately retains accepted static grants if the native process crashes.
 It supplies no wall-clock lease or timed revocation. The caller must keep revocation
@@ -159,15 +162,149 @@ workload before treating revocation as complete or reusing its addresses and
 interfaces. Table deletion does not release IP allocation authority or clean up
 conntrack/NAT state. This restriction also applies to private veth/TUN forwarding.
 
+### Combined router egress and host transit
+
+`ManagedNftables<IManagedNftPolicyV2>` accepts the exported schema-v2 policy.
+The prepared/applied/transition/status interfaces accept the same policy type
+parameter; existing callers default to the unchanged schema-v1 contract. V1
+canonical digests and compiled bytes are preserved. V2 uses its own hash domain.
+An owner cannot transition between v1 private, v2 router, and v2 host policy kinds.
+
+| V2 scope | Required authority and behavior |
+| --- | --- |
+| `routerEgress` | Private `endpoints` and `rules`, one exact `links` binding per endpoint, a separate veth `handoff`, `protection`, and active `generations`. Private veth/TUN/local DNS and egress share one table so terminal private denial cannot override a separate egress table. |
+| `hostTransit` | Exact handoff `link`/`allocations` pairs, complete `protection`, an explicit veth or Ethernet `uplink`, and its current `snatAddress`. It checks each handoff's leased source address and protocol/port range, default conntrack zone, direction, uplink, and protected destinations before outer SNAT. |
+
+Local bindings include name, index, kind, MAC (null for L3 TUN), interface-link
+index, and required IPv4 addresses. RTM_GETLINK/RTM_GETADDR verify those local
+facts at apply, recovery and inspection. Ethernet must be unbridged driver-backed
+Ethernet, including VirtIO; virtual VLAN/bond/bridge/dummy kinds are not inferred
+uplinks. The caller retains actual peer namespaces and link-generation ownership.
+These serialized facts are not native lifetime capabilities or a continuous
+link-change monitor. Address, DHCP and route changes require caller fencing.
+
+`protection` carries an authority digest, non-overlapping protected IPv4 prefixes
+and exact platform endpoint IDs/address/protocol/port tuples. The caller must
+authenticate and supply complete authority. Hashing does not prove completeness.
+A public grant means its declared IPv4 prefix excluding the protected union;
+only an explicit platform endpoint grant admits a protected destination. Host
+checks cover both the current packet destination and original conntrack destination,
+so foreign DNAT cannot turn a protected destination into a public exception or
+redirect public traffic into protected space. INPUT diversion, local OUTPUT into
+handoffs, unmatched handoff traffic and IPv6 forwarding are denied.
+
+Each router generation binds an immutable lease reference, transit source address,
+leased TCP/UDP source-port ranges, a nonzero conntrack zone and a 16-byte label.
+Each directed grant selects one exact leased protocol range for SNAT. A grant's
+source is a workload veth or the actual router-local host with an exact assigned
+IPv4 source address; TUN endpoints retain private routing only. Router-local DNS
+and relay transports therefore need explicit local-origin grants. Raw PREROUTING
+and OUTPUT classify before conntrack; filter rules validate current and original
+tuples, links, direction, zone, state and generation label on every packet.
+Opening TCP requires SYN with FIN/RST/ACK clear and permits ECN negotiation.
+Replies must match the labelled original flow and current directed grant.
+There is no broad ESTABLISHED/RELATED bypass.
+
+Active overlapping classifiers, duplicate zones/labels and conflicting handoff
+allocations reject. Empty router generations retain private routing while denying
+egress. Input bounds include 32 private endpoints, 128 private rules, 32 active
+generations, 128 total egress grants, 128 protected prefixes, 96 platform endpoints,
+16 ranges per allocation, and 32 host handoffs/active allocations. The complete
+compiled graph still must fit 768 operations and 100,000 bytes; cross-products can
+reach that limit before individual input limits. Exhausted source-port ranges
+drop new flows rather than allocate outside the lease.
+
+The caller must coordinate router and host apply order, retain complete intents
+and receipts, authenticate protected authority, prevent reuse of quarantined
+leases, and qualify other packet owners. An ACCEPT in this table cannot override
+Docker's independent FORWARD DROP. `ManagedDockerForwarding`, described below,
+owns the separate DOCKER-USER contribution. The caller must also control deferred packets, proxy/BPF/
+offload paths and changing network authority. No table receipt proves flow
+drainage, conntrack cleanup, elapsed-time expiry, or safe address/port/zone reuse.
+
+### Docker forwarding contribution
+
+`ManagedDockerForwarding` admits the leased handoff traffic from an exact applied
+schema-v2 `hostTransit` receipt through Docker's existing IPv4 forwarding path.
+It reads and verifies that dedicated barrier's complete table and local links,
+without adopting its ownership. The contribution uses Docker's supported
+[DOCKER-USER extension point](https://docs.docker.com/engine/network/firewall-iptables/).
+Docker's native nftables backend has no equivalent user chain and is unsupported.
+
+The host must provide root-owned `/usr/sbin/iptables-nft`,
+`/usr/sbin/iptables-nft-save` and `/usr/sbin/iptables-nft-restore`, using the same
+1.8.10-or-newer 1.8-series `nf_tables` frontend. `prepare()` captures the exact
+frontend version in its digest. Apply, inspection and recovery require that same
+version. Subprocesses use fixed argv, a clean environment, bounded input/output,
+one shared eight-second frontend deadline per request, and joined termination.
+No shell or raw rule API is exposed.
+
+One node-level contribution owns a contiguous leading block in DOCKER-USER.
+FORWARD must already have policy DROP and its first two unconditional jumps must
+be DOCKER-USER and DOCKER-FORWARD. Their exact ordered raw graphs are checked
+without claiming their ownership. Other managed contribution owners, altered or
+duplicated owned rules, missing chains and changed placement reject. Unrelated
+rules following the owned block and Docker's own chains remain separate owners.
+Saved text verifies placement, count and normalized policy. Native netlink reads
+verify every contributed rule's complete ordered expression graph, including
+register flow and all match bytes; only counter values and attribute encoding
+order/flags are normalized. An exact xtables `-C` check also verifies each compiled
+deletion specification. These reads must share an unchanged ruleset generation;
+concurrent Docker reconciliation can therefore make inspection inconclusive.
+Conntrack source addresses use the canonical bare IPv4 form because
+an explicit `/32` has different hidden match bytes in these frontends. A
+semantically equal rewrite with a different exact representation rejects, as does
+an early ACCEPT that the frontend reconstructs as the same command.
+The contribution never creates, flushes, adopts or deletes a Docker table/chain,
+and never changes a host forwarding policy.
+
+Each contributed rule binds the handoff and uplink names, current and original
+transit source, exact leased TCP/UDP port range, packet direction and connection
+state. New TCP flows require SYN with FIN/RST/ACK clear; reverse traffic requires
+ESTABLISHED. The exact v2 host barrier independently checks interface indices,
+MAC/iflink facts, the default host conntrack zone, protected original/current
+destinations and explicit outer SNAT. A complete contribution is bounded to 192
+rules and 100,000 generated command bytes.
+
+Create the class with `ownerId`, a caller-retained `instanceId` of at least 16
+identifier characters, and optional `binaryPath`/`networkNamespaceFd`. After
+`start()`, call `prepare({ schemaVersion: 1, revision, barrier })`, where `barrier`
+is the exact applied host policy. Persist the complete `{ previous, target }`
+transition before `reconcile()`. Keep every affected handoff link down through
+mutations; retain those exact links until cleanup finishes. The native owner
+verifies this down state before and after its single no-flush restore transaction.
+Exact target replay can recover a lost response without rewriting live rules.
+
+`inspect().present` confirms the contribution and its referenced barrier, not
+the complete host packet path or durable controller authority. Errors retain
+failed-owned state and pending intent. `release(applied)` and `close()` delete
+only exact contributed rules under the same link fence. A cold boot needs a new
+barrier receipt and caller-authorized replay; old boot receipts cannot authorize
+native operations. The caller owns restart ordering, disjoint retained leases,
+exclusive privileged mutation authority and activation. The frontend transaction
+does not provide compare-and-swap against other privileged processes.
+
 ### Native qualification
 
-`cargo test --manifest-path rust/Cargo.toml --locked` runs only unprivileged pure
-tests. The ignored native cases require the explicitly marked disposable guest
+The separate [Docker fixture](test/native/readme.docker.md) exercises the native
+contribution with pinned Docker packages on offline Ubuntu 26.04 and Ubuntu
+24.04.4/HWE guests, including retained-state cold boots and published workloads.
+Its checked-in input manifest and per-run receipts identify the tested artifacts.
+
+`cargo test --manifest-path rust/Cargo.toml --locked` runs unprivileged compiler,
+snapshot and bounded-subprocess tests. The ignored native cases require the explicitly marked disposable guest
 from `test/native/qualify.py`; requesting them on an ordinary host fails its scope
 check. Qualification uses an offline Linux 6.18.35 x86_64 guest with no host disks,
-mounts or network devices, and guest-owned network namespaces/veth pairs. It covers
+mounts or external network backend. One VirtIO device connects only to a singleton
+QEMU-internal hub; packet-path tests use guest-owned namespaces, veth pairs and TUN.
+It covers
 UDP/TCP grants, direct-IP denial, source spoofing, IPv6 denial, renamed interfaces,
 foreign ownership, atomic rollback, generation conflicts and lost-ACK recovery.
+V2 tests exercise complete graph persistence/recovery, private and local DNS,
+local TCP, TUN isolation, observed UDP/TCP handoff ranges, range exhaustion,
+fragment reassembly, ECN SYN and invalid opening flags, protected current/original
+DNAT barriers, nonzero foreign zones, local diversion, IPv6 denial, revocation
+and restoration with disjoint generation ranges while old flows remain retained.
 The arm64 binary is cross-built; native packet qualification is currently x86_64.
 Kernel 6.8 is unsupported. No production activation is implied by these tests.
 

package/rust/src/docker.frontend.rs

@@ -0,0 +1,203 @@
+use super::policy::{Options, Rule};
+use crate::{Error, Result};
+use std::collections::{BTreeMap, BTreeSet};
+use std::io::{Read, Write};
+use std::os::fd::AsRawFd;
+use std::os::unix::{fs::MetadataExt, process::CommandExt};
+use std::process::{Command, Stdio};
+use std::time::{Duration, Instant};
+
+const IPTABLES: &str = "/usr/sbin/iptables-nft";
+const SAVE: &str = "/usr/sbin/iptables-nft-save";
+const RESTORE: &str = "/usr/sbin/iptables-nft-restore";
+const MAX_OUTPUT: usize = 2_097_152;
+#[cfg(test)]
+#[path="docker_process_tests.rs"]
+mod process_tests;
+
+fn nonblocking(fd: i32) -> Result<()> {
+    let flags = unsafe { libc::fcntl(fd, libc::F_GETFL) };
+    if flags < 0 || unsafe { libc::fcntl(fd,libc::F_SETFL,flags|libc::O_NONBLOCK) } < 0 {return Err(Error::Unavailable);}
+    Ok(())
+}
+pub fn deadline() -> Instant { Instant::now()+Duration::from_secs(8) }
+fn command(path: &str, args: &[&str], input: &[u8], deadline: Instant) -> Result<String> {
+    if Instant::now()>=deadline {return Err(Error::Unavailable);}
+    let metadata=std::fs::metadata(path).map_err(|_|Error::Unavailable)?;
+    if !metadata.is_file() || metadata.uid()!=0 || metadata.mode() & 0o022 != 0 { return Err(Error::Permission); }
+    let mut child=Command::new(path).args(args).env_clear().env("PATH","/usr/sbin:/usr/bin:/sbin:/bin")
+        .env("LC_ALL","C").stdin(Stdio::piped()).stdout(Stdio::piped()).stderr(Stdio::piped()).process_group(0)
+        .spawn().map_err(|_|Error::Unavailable)?;
+    let result=(|| {
+        let mut stdin=child.stdin.take();
+        let mut stdout=child.stdout.take().ok_or(Error::Unavailable)?;
+        let mut stderr=child.stderr.take().ok_or(Error::Unavailable)?;
+        for fd in [stdin.as_ref().ok_or(Error::Unavailable)?.as_raw_fd(),stdout.as_raw_fd(),stderr.as_raw_fd()] {nonblocking(fd)?;}
+        let mut written=0;let mut output=Vec::new();let mut errors=Vec::new();
+        let mut out_eof=false;let mut err_eof=false;let mut status=None;
+        loop {
+            if Instant::now()>=deadline {return Err(Error::Unavailable);}
+            if written==input.len() {stdin=None;}
+            if let Some(pipe)=stdin.as_mut() {
+                match pipe.write(&input[written..]) {
+                    Ok(0)=>return Err(Error::Unavailable),Ok(count)=>written+=count,
+                    Err(error) if error.kind()==std::io::ErrorKind::WouldBlock=>{},
+                    Err(_)=>return Err(Error::Unavailable),
+                }
+            }
+            for (pipe,bytes,eof) in [(&mut stdout as &mut dyn Read,&mut output,&mut out_eof),(&mut stderr as &mut dyn Read,&mut errors,&mut err_eof)] {
+                let mut buffer=[0;8192];
+                loop {
+                    match pipe.read(&mut buffer) {
+                        Ok(0)=>{*eof=true;break;},
+                        Ok(count)=>{if bytes.len()+count>MAX_OUTPUT{return Err(Error::Protocol);}bytes.extend_from_slice(&buffer[..count]);},
+                        Err(error) if error.kind()==std::io::ErrorKind::WouldBlock=>break,
+                        Err(_)=>return Err(Error::Unavailable),
+                    }
+                }
+            }
+            if status.is_none() {status=child.try_wait().map_err(|_|Error::Unavailable)?;}
+            if let Some(status)=status.filter(|_|out_eof&&err_eof) {
+                if !status.success() || written!=input.len() {
+                    if path==IPTABLES && args.get(2)==Some(&"-C") && status.code()==Some(1)
+                        && errors==b"iptables: Bad rule (does a matching rule exist in that chain?).\n" {
+                        return Err(Error::Conflict);
+                    }
+                    return Err(Error::Unavailable);
+                }
+                return String::from_utf8(output).map_err(|_|Error::Protocol);
+            }
+            std::thread::sleep(Duration::from_millis(2));
+        }
+    })();
+    if result.is_err() {
+        // Stop and join this exact mutator before reporting an inconclusive ACK.
+        if child.try_wait().ok().flatten().is_none() {
+            unsafe {libc::kill(-(child.id() as i32),libc::SIGKILL);}
+        }
+    }
+    child.wait().map_err(|_|Error::Unavailable)?;
+    result
+}
+pub fn version(deadline: Instant) -> Result<String> {
+    let mut version=None;
+    for path in [IPTABLES,SAVE,RESTORE] {
+        let output=command(path,&["--version"],&[],deadline)?;
+        let parts:Vec<_>=output.split_whitespace().collect();
+        if parts.len()!=3 {return Err(Error::UnsupportedBackend);}
+        let observed=format!("{} {}",parts[1],parts[2]);
+        super::policy::validate_backend(&observed)?;
+        if version.as_ref().is_some_and(|v|v!=&observed) {return Err(Error::Conflict);}
+        version=Some(observed);
+    }
+    version.ok_or(Error::Unavailable)
+}
+
+/// Tokenize save output only; no token is ever evaluated by a shell.
+fn tokens(line: &str) -> Result<Vec<String>> {
+    if line.len()>16_384 {return Err(Error::Protocol);}
+    let mut values=Vec::new();let mut word=String::new();let mut quoted=false;let mut escaped=false;let mut active=false;
+    for byte in line.bytes() {
+        if !(32..127).contains(&byte) {return Err(Error::Protocol);}
+        if escaped {word.push(byte as char);escaped=false;active=true;continue;}
+        if byte==b'\\' {escaped=true;continue;}
+        if byte==b'"' {quoted=!quoted;active=true;continue;}
+        if byte==b' ' && !quoted {if active {values.push(std::mem::take(&mut word));active=false;}} else {word.push(byte as char);active=true;}
+    }
+    if quoted||escaped {return Err(Error::Protocol);}
+    if active {values.push(word);}
+    if values.len()>512 {return Err(Error::Protocol);}
+    Ok(values)
+}
+fn normalized(args: &[String]) -> Result<Vec<(String, Vec<String>)>> {
+    let mut values=BTreeMap::new();let mut modules=BTreeSet::new();let mut index=0;
+    while index<args.len() {
+        let key=&args[index];let count=if key=="--tcp-flags" {2} else {1};
+        if !["-i","-o","-s","-d","-p","-m","--sport","--dport","--tcp-flags","--ctstate","--ctproto","--ctorigsrc","--ctorigsrcport","--ctdir","--comment","-j"].contains(&key.as_str()) {return Err(Error::Conflict);}
+        let mut value=args.get(index+1..index+1+count).ok_or(Error::Conflict)?.to_vec();index+=1+count;
+        if key=="-m" {if !modules.insert(value[0].clone()) {return Err(Error::Conflict);}continue;}
+        if key=="--ctorigsrc" && !value[0].contains('/') {value[0].push_str("/32");}
+        if key=="--ctproto" {value[0]=match value[0].as_str() {"tcp"=>"6".into(),"udp"=>"17".into(),_=>value[0].clone()};}
+        if values.insert(key.clone(),value).is_some() {return Err(Error::Conflict);}
+    }
+    values.insert("-m".into(),modules.into_iter().collect());
+    Ok(values.into_iter().collect())
+}
+pub struct Snapshot {
+    pub backend: String,
+    pub rows: Vec<Vec<String>>,
+    pub user: Vec<Vec<String>>,
+    raw: Option<super::graph::Snapshot>,
+}
+impl Snapshot {
+    pub fn read(deadline: Instant) -> Result<Self> {
+        let backend=version(deadline)?;
+        let (raw,text)=super::graph::Snapshot::read(||command(SAVE,&["-t","filter"],&[],deadline))?;
+        let mut snapshot=Self::parse(backend,&text)?;
+        snapshot.raw=Some(raw);
+        Ok(snapshot)
+    }
+    pub fn parse(backend: String, text: &str) -> Result<Self> {
+        if text.len()>MAX_OUTPUT {return Err(Error::Protocol);}
+        let mut table=false;let mut committed=false;let mut chains=BTreeMap::new();let mut rows=Vec::new();
+        for line in text.lines().filter(|line|!line.starts_with('#')&&!line.is_empty()) {
+            if line=="*filter" {if table||committed {return Err(Error::Conflict);}table=true;continue;}
+            if line=="COMMIT" {if !table||committed {return Err(Error::Conflict);}committed=true;continue;}
+            if !table||committed {return Err(Error::Conflict);}
+            let row=tokens(line)?;
+            if line.starts_with(':') {
+                if row.len()!=3 || chains.insert(row[0][1..].to_string(),row[1].clone()).is_some() {return Err(Error::Conflict);}
+            } else {
+                if row.len()<2 || row[0]!="-A" || rows.len()>=4096 {return Err(Error::Conflict);}
+                rows.push(row);
+            }
+        }
+        if !committed || chains.get("FORWARD").map(String::as_str)!=Some("DROP")
+            || chains.get("DOCKER-USER").map(String::as_str)!=Some("-")
+            || chains.get("DOCKER-FORWARD").map(String::as_str)!=Some("-") {return Err(Error::Conflict);}
+        let forward:Vec<_>=rows.iter().filter(|r|r[1]=="FORWARD").collect();
+        for (index,target) in ["DOCKER-USER","DOCKER-FORWARD"].iter().enumerate() {
+            if forward.get(index).map(|r|r.iter().map(String::as_str).collect::<Vec<_>>())!=Some(vec!["-A","FORWARD","-j",target]) {return Err(Error::Conflict);}
+        }
+        let user=rows.iter().filter(|r|r[1]=="DOCKER-USER").cloned().collect();
+        Ok(Self {backend,rows,user,raw:None})
+    }
+    /// Text proves placement/count and logical policy; -C additionally checks
+    /// match-extension bytes hidden by save output. Deletion uses the same spec.
+    pub fn verified_matches(&self, options: &Options, expected: &[Rule], deadline: Instant) -> Result<bool> {
+        if !self.matches(options,expected)? {return Ok(false);}
+        let raw=self.raw.as_ref().ok_or(Error::Conflict)?;
+        if !raw.matches(expected)? {return Ok(false);}
+        for rule in expected {
+            let mut args=vec!["-t","filter","-C","DOCKER-USER"];
+            args.extend(rule.args.iter().map(String::as_str));
+            match command(IPTABLES,&args,&[],deadline) {
+                Ok(_)=>{},Err(Error::Conflict)=>return Ok(false),Err(error)=>return Err(error),
+            }
+        }
+        raw.unchanged()
+    }
+    pub fn matches(&self, options: &Options, expected: &[Rule]) -> Result<bool> {
+        let prefix=format!("snftd1:{}:",options.owner_id);
+        // One node-level contribution owns the leading block. Do not prepend
+        // another managed owner and silently invalidate its placement proof.
+        if self.rows.iter().any(|r|r.iter().any(|t|t.starts_with("snftd1:")&&!t.starts_with(&prefix))) {return Err(Error::ForeignOwner);}
+        let owned:Vec<_>=self.rows.iter().filter(|r|r.iter().any(|t|t.starts_with(&prefix))).collect();
+        if owned.len()!=expected.len() || self.user.len()<expected.len() {return Ok(false);}
+        for (index,rule) in expected.iter().enumerate() {
+            let row=&self.user[index];
+            if row[1]!="DOCKER-USER" || !row.iter().any(|t|t==&rule.comment)
+                || normalized(&row[2..])?!=normalized(&rule.args)? {return Ok(false);}
+        }
+        Ok(true)
+    }
+}
+pub fn replace(previous: &[Rule], target: &[Rule], deadline: Instant) -> Result<()> {
+    let mut batch="*filter\n".to_string();
+    for rule in previous {batch.push_str(&format!("-D DOCKER-USER {}\n",rule.args.join(" ")));}
+    for rule in target.iter().rev() {batch.push_str(&format!("-I DOCKER-USER 1 {}\n",rule.args.join(" ")));}
+    batch.push_str("COMMIT\n");
+    if batch.len()>210_000 {return Err(Error::Invalid);}
+    command(RESTORE,&["--noflush","--wait","5"],batch.as_bytes(),deadline)?;
+    Ok(())
+}

package/rust/src/docker.graph.rs

@@ -0,0 +1,129 @@
+//! Ordered iptables-nft graph identity. Command-state reconstruction loses order.
+use super::policy::Rule;
+use crate::{policy::{compare, expr, meta, verdict}, wire::{self, Attr, Socket}, Error, Result};
+
+fn value<'a>(rule: &'a Rule, key: &str) -> Result<&'a str> {
+    rule.args.windows(2).find(|pair|pair[0]==key).map(|pair|pair[1].as_str()).ok_or(Error::Invalid)
+}
+fn payload(base: u32, offset: u32, length: u32) -> Attr {
+    expr("payload",vec![Attr::u32(1,1),Attr::u32(2,base),Attr::u32(3,offset),Attr::u32(4,length)])
+}
+
+/// Fixed Linux UAPI / xtables 1.8.10 and 1.8.11 constructors, not a raw rule API.
+pub(super) fn expected(rule: &Rule) -> Result<Vec<Attr>> {
+    let reply=value(rule,"--ctdir")?=="REPLY";
+    let new=value(rule,"--ctstate")?=="NEW";
+    let protocol=match value(rule,"-p")? {"tcp"=>6_u16,"udp"=>17,_=>return Err(Error::Invalid)};
+    let address=value(rule,"--ctorigsrc")?.parse::<std::net::Ipv4Addr>().map_err(|_|Error::Invalid)?.octets();
+    let ports=value(rule,"--ctorigsrcport")?;
+    let (first,last)=ports.split_once(':').unwrap_or((ports,ports));
+    let first=first.parse::<u16>().map_err(|_|Error::Invalid)?;
+    let last=last.parse::<u16>().map_err(|_|Error::Invalid)?;
+    let mut result=vec![payload(1,if reply {16} else {12},4),compare(address.to_vec())];
+    for (key,argument) in [(6,"-i"),(7,"-o")] {
+        result.extend(meta(key,[value(rule,argument)?.as_bytes(),&[0]].concat()));
+    }
+    result.extend([payload(1,9,1),compare(vec![protocol as u8])]);
+    if new && protocol==6 {
+        result.extend([payload(2,13,1),expr("bitwise",vec![
+            Attr::u32(1,1),Attr::u32(2,1),Attr::u32(3,1),Attr::u32(6,0),
+            Attr::nested(4,vec![Attr::bytes(1,vec![0x17])]),Attr::nested(5,vec![Attr::bytes(1,vec![0])]),
+        ]),compare(vec![2])]);
+    }
+    result.push(payload(2,if reply {2} else {0},2));
+    result.push(if first==last {compare(first.to_be_bytes().to_vec())} else {
+        expr("range",vec![Attr::u32(1,1),Attr::u32(2,0),
+            Attr::nested(3,vec![Attr::bytes(1,first.to_be_bytes().to_vec())]),
+            Attr::nested(4,vec![Attr::bytes(1,last.to_be_bytes().to_vec())])])
+    });
+    // xt_conntrack_mtinfo3 is 164 bytes, XT_ALIGN'ed to 168 on both shipped
+    // 64-bit Linux targets. All fields and padding are initialized explicitly.
+    let mut conntrack=vec![0;168];
+    conntrack[..4].copy_from_slice(&address);
+    conntrack[16..32].fill(0xff); // canonical bare-host nf_inet_addr mask
+    for (offset,number) in [(136,protocol),(138,first),(146,0x1107),
+        (148,if reply {0x1000} else {0}),(150,if new {8} else {2}),(154,last)] {
+        conntrack[offset..offset+2].copy_from_slice(&number.to_ne_bytes());
+    }
+    result.push(expr("match",vec![Attr::string(1,"conntrack"),Attr::u32(2,3),Attr::bytes(3,conntrack)]));
+    let mut comment=vec![0;256];
+    if rule.comment.len()>=comment.len() {return Err(Error::Invalid);}
+    comment[..rule.comment.len()].copy_from_slice(rule.comment.as_bytes());
+    result.push(expr("match",vec![Attr::string(1,"comment"),Attr::u32(2,0),Attr::bytes(3,comment)]));
+    result.push(expr("counter",vec![Attr::u64(1,0),Attr::u64(2,0)]));
+    result.push(verdict(1,None));
+    Ok(result)
+}
+
+/// Kernel dumps may omit nested flags and reorder fields; list order is exact.
+fn equivalent(actual: &[Attr], expected: &[Attr], ordered: bool) -> Result<bool> {
+    if actual.len()!=expected.len() {return Ok(false);}
+    let mut actual=actual.iter().collect::<Vec<_>>();let mut expected=expected.iter().collect::<Vec<_>>();
+    if !ordered {actual.sort_by_key(|a|a.id());expected.sort_by_key(|a|a.id());}
+    for (actual,expected) in actual.into_iter().zip(expected) {
+        if actual.id()!=expected.id() {return Ok(false);}
+        if expected.kind & 0x8000 != 0 {
+            let expected=wire::attrs(&expected.value)?;
+            if !equivalent(&wire::attrs(&actual.value)?,&expected,expected.iter().all(|a|a.id()==1))? {return Ok(false);}
+        } else if actual.value!=expected.value {return Ok(false);}
+    }
+    Ok(true)
+}
+pub(super) fn matches_rule(row: &[Attr], rule: &Rule) -> Result<bool> {
+    matches_graph(row,"DOCKER-USER",&expected(rule)?)
+}
+pub(super) fn matches_forward(row: &[Attr], target: &str) -> Result<bool> {
+    if !["DOCKER-USER","DOCKER-FORWARD"].contains(&target) {return Err(Error::Invalid);}
+    matches_graph(row,"FORWARD",&[expr("counter",vec![Attr::u64(1,0),Attr::u64(2,0)]),verdict(-3,Some(target))])
+}
+fn matches_graph(row: &[Attr], chain: &str, expected: &[Attr]) -> Result<bool> {
+    if row.iter().any(|a|![1,2,3,4,6,8].contains(&a.id()))
+        || wire::text(row,1)?!="filter" || wire::text(row,2)?!=chain
+        || wire::handle(row,3)?==0 {return Ok(false);}
+    for id in [6,8] {
+        if row.iter().any(|a|a.id()==id) {
+            let attr=wire::one(row,id)?;
+            if id==6 {wire::handle(row,id)?;} else if !attr.value.is_empty() {return Ok(false);}
+        }
+    }
+    let mut expressions=wire::attrs(&wire::one(row,4)?.value)?;
+    for expression in &mut expressions {
+        let mut fields=wire::attrs(&expression.value)?;
+        if wire::text(&fields,1)?=="counter" {
+            let mut data=wire::attrs(&wire::one(&fields,2)?.value)?;
+            // Counter values change without a ruleset generation change. No
+            // expression, including the counter itself, may move or disappear.
+            data.retain(|a|!(a.id()==3 && a.value.is_empty()));
+            if data.len()!=2 {return Ok(false);}
+            for id in [1,2] {wire::handle(&data,id)?;}
+            for attribute in &mut data {attribute.value=0_u64.to_be_bytes().to_vec();}
+            let field=fields.iter_mut().find(|a|a.id()==2).ok_or(Error::Protocol)?;
+            *field=Attr::nested(2,data);
+            expression.value=wire::encode_attrs(&fields);
+        }
+    }
+    equivalent(&expressions,expected,true)
+}
+
+pub struct Snapshot { generation: u32, rows: Vec<Vec<Attr>> }
+impl Snapshot {
+    pub fn read(save: impl FnOnce()->Result<String>) -> Result<(Self,String)> {
+        let mut socket=Socket::open()?;let generation=socket.generation()?;
+        let text=save()?;
+        let rows=socket.query_ipv4(7,vec![Attr::string(1,"filter"),Attr::string(2,"DOCKER-USER")],true)?;
+        let forward=socket.query_ipv4(7,vec![Attr::string(1,"filter"),Attr::string(2,"FORWARD")],true)?;
+        if socket.generation()!=Ok(generation) {return Err(Error::Conflict);}
+        for (index,target) in ["DOCKER-USER","DOCKER-FORWARD"].iter().enumerate() {
+            if !matches_forward(forward.get(index).ok_or(Error::Conflict)?,target)? {return Err(Error::Conflict);}
+        }
+        Ok((Self {generation,rows},text))
+    }
+    pub fn matches(&self, expected: &[Rule]) -> Result<bool> {
+        if self.rows.len()<expected.len() {return Ok(false);}
+        for (row,rule) in self.rows.iter().zip(expected) {
+            if !matches_rule(row,rule)? {return Ok(false);}
+        }
+        Ok(true)
+    }
+    pub fn unchanged(&self) -> Result<bool> {Ok(Socket::open()?.generation()?==self.generation)}
+}