@push.rocks/smartnftables 1.5.0 → 1.6.0

package/rust/src/docker_process_tests.rs

@@ -0,0 +1,29 @@
+use super::*;
+
+#[test]
+fn frontend_subprocess_drains_large_input_and_output_with_a_clean_environment() {
+    let input="bounded-input\n".repeat(12_000);
+    assert_eq!(command("/usr/bin/cat",&[],input.as_bytes(),deadline()).unwrap(),input);
+    let environment=command("/usr/bin/env",&[],&[],deadline()).unwrap();
+    let values:BTreeSet<_>=environment.lines().collect();
+    assert_eq!(values,BTreeSet::from(["PATH=/usr/sbin:/usr/bin:/sbin:/bin","LC_ALL=C"]));
+}
+fn child_failure(kind: &str, source: &str, expected: Error) {
+    let directory=std::env::temp_dir().join(format!("smartnftables-command-{}-{kind}",std::process::id()));
+    std::fs::create_dir(&directory).unwrap();
+    let pidfile=directory.join("pid");
+    let source=format!("import os,pathlib,time;pathlib.Path({:?}).write_text(str(os.getpid()));{source}",pidfile.to_str().unwrap());
+    assert_eq!(command("/usr/bin/python3",&["-c",&source],&[],deadline()),Err(expected));
+    let pid=std::fs::read_to_string(&pidfile).unwrap().parse::<i32>().unwrap();
+    assert_eq!(unsafe{libc::kill(pid,0)},-1);
+    assert_eq!(std::io::Error::last_os_error().raw_os_error(),Some(libc::ESRCH));
+    std::fs::remove_file(pidfile).unwrap();std::fs::remove_dir(directory).unwrap();
+}
+#[test]
+fn frontend_subprocess_output_overflow_stops_and_joins_the_exact_child() {
+    child_failure("output","os.write(1,b'x'*2097153);time.sleep(60)",Error::Protocol);
+}
+#[test]
+fn frontend_subprocess_timeout_stops_and_joins_the_exact_child() {
+    child_failure("timeout","time.sleep(60)",Error::Unavailable);
+}

package/rust/src/docker_tests.rs

@@ -0,0 +1,148 @@
+use super::*;
+use serde_json::json;
+
+fn options() -> Options {Options {owner_id:"dockerfixture".into(),instance_id:"qualification_20260913".into()}}
+fn policy() -> policy::Policy {
+    let prepared:crate::managed::Prepared=serde_json::from_value::<crate::egress::Policy>(crate::egress::tests::host()).unwrap().prepare().unwrap().into();
+    policy::Policy {schema_version:1,revision:1,barrier:owner::Applied {
+        receipt:owner::Receipt {identity:owner::Identity {owner_id:"barrier".into(),instance_id:"qualification_20260913".into(),table_name:"snft_fixture".into(),boot_id:"00000000-0000-4000-8000-000000000000".into(),namespace_device:"4".into(),namespace_inode:"1".into()},table_handle:"1".into(),revision:1,digest:prepared.digest.clone()},prepared}}
+}
+fn text(rules: &[policy::Rule]) -> String {
+    let mut text="*filter\n:INPUT ACCEPT [0:0]\n:FORWARD DROP [0:0]\n:OUTPUT ACCEPT [0:0]\n:DOCKER-USER - [0:0]\n:DOCKER-FORWARD - [0:0]\n-A FORWARD -j DOCKER-USER\n-A FORWARD -j DOCKER-FORWARD\n".to_owned();
+    for rule in rules {text.push_str(&format!("-A DOCKER-USER {}\n",rule.args.join(" ")));}
+    text.push_str("-A DOCKER-USER -m comment --comment \"foreign unrelated rule\" -j RETURN\nCOMMIT\n");text
+}
+fn snapshot(text: &str) -> frontend::Snapshot {frontend::Snapshot::parse("v1.8.11 (nf_tables)".into(),text).unwrap()}
+
+#[test]
+fn docker_compiler_derives_only_scoped_directed_ranges_from_host_barrier() {
+    let prepared=policy().prepare("v1.8.11 (nf_tables)".into()).unwrap();let rules=prepared.rules(&options()).unwrap();
+    assert_eq!(rules.len(),6);
+    assert!(rules.iter().all(|r|r.args.contains(&"--ctorigsrcport".into()) && r.args.contains(&"--ctdir".into()) && !r.args.iter().any(|s|s.contains("RELATED"))));
+    let new_tcp=&rules[0].args;
+    assert!(new_tcp.windows(3).any(|w|w==["--tcp-flags","FIN,SYN,RST,ACK","SYN"]));
+    assert!(rules.iter().all(|r|r.comment.len()<256));
+    assert!(rules.iter().all(|r|r.args.windows(2).any(|w|w[0]=="--ctorigsrc" && !w[1].contains('/'))));
+    assert!(snapshot(&text(&rules)).matches(&options(),&rules).unwrap());
+}
+#[test]
+fn docker_prepare_rejects_router_receipts_bad_hashes_and_unbounded_restore() {
+    let mut value=policy();value.schema_version=2;assert!(value.prepare("v1.8.11 (nf_tables)".into()).is_err());
+    let mut value=policy();value.barrier.receipt.digest="sha256:wrong".into();assert!(value.prepare("v1.8.11 (nf_tables)".into()).is_err());
+    let mut value=policy();value.barrier.prepared.policy=crate::managed::Policy::Egress(serde_json::from_value(crate::egress::tests::router()).unwrap());assert!(value.prepare("v1.8.11 (nf_tables)".into()).is_err());
+    let value=serde_json::to_value(policy()).unwrap();
+    let mut extra=value.clone();extra["rules"]=json!([]);assert!(serde_json::from_value::<policy::Policy>(extra).is_err());
+    let mut extra=value;extra["barrier"]["receipt"]["tableHandle"]=json!("01");assert!(serde_json::from_value::<policy::Policy>(extra).unwrap().prepare("v1.8.11 (nf_tables)".into()).is_err());
+}
+#[test]
+fn docker_policy_digest_binds_barrier_handle_and_revision() {
+    let expected=policy().prepare("v1.8.11 (nf_tables)".into()).unwrap();
+    assert_ne!(policy().prepare("v1.8.10 (nf_tables)".into()).unwrap().digest,expected.digest);
+    for backend in ["v1.8. (nf_tables)","v1.8.9 (nf_tables)","v1.8.11 (legacy)","v1.8.011 (nf_tables)"] {
+        assert!(policy().prepare(backend.into()).is_err());
+    }
+    let mut value=policy();value.barrier.receipt.table_handle="2".into();assert_ne!(value.prepare("v1.8.11 (nf_tables)".into()).unwrap().digest,expected.digest);
+    let mut value=policy();value.revision=2;assert_ne!(value.prepare("v1.8.11 (nf_tables)".into()).unwrap().digest,expected.digest);
+    let mut forged=expected;forged.policy.revision=2;assert!(forged.validate().is_err());
+}
+#[test]
+fn docker_snapshot_accepts_only_equivalent_frontend_rendering() {
+    let rules=policy().prepare("v1.8.11 (nf_tables)".into()).unwrap().rules(&options()).unwrap();
+    let original=text(&rules);
+    let rendered=original.replace("--ctorigsrc 10.240.0.2/32","--ctorigsrc 10.240.0.2");
+    assert!(snapshot(&rendered).matches(&options(),&rules).unwrap());
+    for (before,after) in [("--ctdir ORIGINAL","--ctdir REPLY"),("--ctstate NEW","--ctstate RELATED"),("--sport 10000:10999","--sport 1:65535"),("-o ens18","-o foreign"),("-j ACCEPT","-j RETURN"),("FIN,SYN,RST,ACK SYN","FIN,SYN,RST,ACK ACK")] {
+        assert!(!snapshot(&original.replacen(before,after,1)).matches(&options(),&rules).unwrap());
+    }
+    assert!(snapshot(&original.replacen("-j ACCEPT","-m mark --mark 1 -j ACCEPT",1)).matches(&options(),&rules).is_err());
+}
+#[test]
+fn docker_snapshot_rejects_duplicates_moved_owner_and_foreign_instance() {
+    let rules=policy().prepare("v1.8.11 (nf_tables)".into()).unwrap().rules(&options()).unwrap();
+    let original=text(&rules);
+    let duplicate=original.replace("COMMIT",&format!("-A DOCKER-USER {}\nCOMMIT",rules[0].args.join(" ")));
+    assert!(!snapshot(&duplicate).matches(&options(),&rules).unwrap());
+    let moved=original.replacen("-A DOCKER-USER", "-A INPUT",1);
+    assert!(!snapshot(&moved).matches(&options(),&rules).unwrap());
+    assert!(!snapshot(&original.replace("qualification_20260913","foreign_instance_2026")).matches(&options(),&rules).unwrap());
+    assert_eq!(snapshot(&original.replace("snftd1:dockerfixture:","snftd1:anotherowner:")).matches(&options(),&[]),Err(Error::ForeignOwner));
+    let prepended=original.replacen("-A DOCKER-USER","-A DOCKER-USER -j RETURN\n-A DOCKER-USER",1);
+    assert!(!snapshot(&prepended).matches(&options(),&rules).unwrap());
+    assert!(!snapshot(&original).matches(&options(),&[]).unwrap());
+}
+#[test]
+fn docker_snapshot_rejects_wrong_backend_path_policy_chain_order_and_table_framing() {
+    let original=text(&[]);
+    for changed in [original.replace(":FORWARD DROP",":FORWARD ACCEPT"),original.replace("-A FORWARD -j DOCKER-USER","-A FORWARD -j ACCEPT"),original.replace("*filter","*nat"),original.replace("COMMIT","COMMIT\n*filter"),original.replace(":DOCKER-USER - [0:0]\n","")] {
+        assert!(frontend::Snapshot::parse("v1.8.11 (nf_tables)".into(),&changed).is_err());
+    }
+}
+
+#[test]
+fn docker_raw_graph_rejects_early_verdicts_reordered_matches_and_hidden_bytes() {
+    let rule=policy().prepare("v1.8.11 (nf_tables)".into()).unwrap().rules(&options()).unwrap().remove(0);
+    let expressions=graph::expected(&rule).unwrap();
+    let row=|expressions|vec![crate::wire::Attr::string(1,"filter"),crate::wire::Attr::string(2,"DOCKER-USER"),
+        crate::wire::Attr::u64(3,42),crate::wire::Attr::nested(4,expressions)];
+    assert!(graph::matches_rule(&row(expressions.clone()),&rule).unwrap());
+    let mut early=expressions.clone();let verdict=early.pop().unwrap();early.insert(0,verdict);
+    assert!(!graph::matches_rule(&row(early),&rule).unwrap());
+    let mut reordered=expressions.clone();reordered.swap(0,1);
+    assert!(!graph::matches_rule(&row(reordered),&rule).unwrap());
+    let mut moved_counter=expressions.clone();let length=moved_counter.len();moved_counter.swap(length-1,length-2);
+    assert!(!graph::matches_rule(&row(moved_counter),&rule).unwrap());
+    let mut hidden=expressions.clone();
+    for expression in &mut hidden {
+        let mut fields=crate::wire::attrs(&expression.value).unwrap();
+        if crate::wire::text(&fields,1).unwrap()!="match" {continue;}
+        let mut data=crate::wire::attrs(&crate::wire::one(&fields,2).unwrap().value).unwrap();
+        if crate::wire::text(&data,1).unwrap()!="conntrack" {continue;}
+        data.iter_mut().find(|a|a.id()==3).unwrap().value[20..32].fill(0);
+        *fields.iter_mut().find(|a|a.id()==2).unwrap()=crate::wire::Attr::nested(2,data);
+        expression.value=crate::wire::encode_attrs(&fields);
+    }
+    assert!(!graph::matches_rule(&row(hidden),&rule).unwrap());
+}
+
+#[test]
+fn docker_raw_graph_accepts_kernel_field_order_flags_and_changing_counters_only() {
+    let rule=policy().prepare("v1.8.11 (nf_tables)".into()).unwrap().rules(&options()).unwrap().remove(0);
+    let mut expressions=graph::expected(&rule).unwrap();
+    for expression in &mut expressions {
+        let mut fields=crate::wire::attrs(&expression.value).unwrap();
+        if crate::wire::text(&fields,1).unwrap()=="counter" {
+            *fields.iter_mut().find(|a|a.id()==2).unwrap()=crate::wire::Attr::nested(2,
+                vec![crate::wire::Attr::u64(2,123),crate::wire::Attr::u64(1,456)]);
+        }
+        fields.reverse();expression.value=crate::wire::encode_attrs(&fields);
+    }
+    fn kernel(attributes: &mut [crate::wire::Attr]) {
+        for attribute in attributes {
+            if attribute.kind&0x8000!=0 {
+                let mut children=crate::wire::attrs(&attribute.value).unwrap();kernel(&mut children);
+                attribute.value=crate::wire::encode_attrs(&children);
+            }
+            attribute.kind &= 0x3fff;
+        }
+    }
+    kernel(&mut expressions);
+    let row=vec![crate::wire::Attr::string(1,"filter"),crate::wire::Attr::string(2,"DOCKER-USER"),
+        crate::wire::Attr::u64(3,42),crate::wire::Attr::nested(4,expressions)];
+    assert!(graph::matches_rule(&row,&rule).unwrap());
+}
+
+#[test]
+fn docker_forward_jumps_require_exact_unconditional_order() {
+    use crate::{policy::{expr,verdict},wire::Attr};
+    let row=|expressions|vec![Attr::string(1,"filter"),Attr::string(2,"FORWARD"),
+        Attr::u64(3,42),Attr::nested(4,expressions)];
+    for target in ["DOCKER-USER","DOCKER-FORWARD"] {
+        let expected=vec![expr("counter",vec![Attr::u64(1,7),Attr::u64(2,11)]),verdict(-3,Some(target))];
+        assert!(graph::matches_forward(&row(expected.clone()),target).unwrap());
+        let mut early=expected.clone();early.insert(0,verdict(1,None));
+        assert!(!graph::matches_forward(&row(early),target).unwrap());
+        let mut reordered=expected.clone();reordered.reverse();
+        assert!(!graph::matches_forward(&row(reordered),target).unwrap());
+        assert!(!graph::matches_forward(&row(expected),if target=="DOCKER-USER" {"DOCKER-FORWARD"} else {"DOCKER-USER"}).unwrap());
+    }
+}

package/rust/src/main.rs

@@ -1,4 +1,5 @@
 mod egress;
+mod docker;
 mod managed;
 mod namespace;
 mod owner;
@@ -14,6 +15,7 @@ use std::io::{BufRead, Read, Write};
 pub enum Error {
     Invalid,
     Unsupported,
+    UnsupportedBackend,
     Permission,
     ForeignOwner,
     Conflict,
@@ -27,6 +29,7 @@ impl Error {
         match self {
             Self::Invalid => "INVALID",
             Self::Unsupported => "UNSUPPORTED_KERNEL",
+            Self::UnsupportedBackend => "UNSUPPORTED_BACKEND",
             Self::Permission => "PERMISSION",
             Self::ForeignOwner => "FOREIGN_OWNER",
             Self::Conflict => "CONFLICT",
@@ -101,13 +104,14 @@ fn dispatch(owner: &mut Option<owner::Owner>, request: Request) -> Result<serde_
 
 fn main() {
     let arguments = std::env::args().skip(1).collect::<Vec<_>>();
-    let descriptor = match arguments.as_slice() {
-        [management] if management == "--management" => None,
+    let (docker_mode, descriptor) = match arguments.as_slice() {
+        [management] if management == "--management" => (false, None),
+        [management] if management == "--docker-forwarding" => (true, None),
         [management, option, fd]
-            if management == "--management" && option == "--network-namespace-fd" =>
+            if (management == "--management" || management == "--docker-forwarding") && option == "--network-namespace-fd" =>
         {
             match fd.parse::<i32>() {
-                Ok(value) => Some(value),
+                Ok(value) => (management == "--docker-forwarding", Some(value)),
                 Err(_) => std::process::exit(2),
             }
         }
@@ -125,6 +129,7 @@ fn main() {
     output.flush().unwrap();
     let mut input = std::io::stdin().lock();
     let mut owner = None;
+    let mut docker = None;
     loop {
         let mut bytes = Vec::new();
         let read = std::io::Read::by_ref(&mut input)
@@ -144,7 +149,7 @@ fn main() {
             std::process::exit(2);
         }
         let id = request.id.clone();
-        let response = match dispatch(&mut owner, request) {
+        let response = match if docker_mode { docker::dispatch(&mut docker, request) } else { dispatch(&mut owner, request) } {
             Ok(result) => serde_json::json!({"id":id,"success":true,"result":result}),
             Err(error) => {
                 serde_json::json!({"id":id,"success":false,"error":"Managed policy operation failed.","errorCode":error.code()})

package/rust/src/owner.rs

@@ -70,7 +70,7 @@ pub struct Owner {
     released: bool,
 }
 
-fn context() -> Result<(String, String, String)> {
+pub(crate) fn context() -> Result<(String, String, String)> {
     let boot = std::fs::read_to_string("/proc/sys/kernel/random/boot_id")
         .map_err(|_| Error::Unavailable)?
         .trim()
@@ -112,6 +112,24 @@ fn kernel_floor() -> Result<()> {
 }
 
 impl Owner {
+    /// Read another dedicated owner's exact receipt without claiming its table.
+    /// PERSIST may retain enforcement after that owner's socket closes.
+    pub(crate) fn verify_external(expected: &Applied) -> Result<()> {
+        let identity = &expected.receipt.identity;
+        let mut reader = Self::new(Options {
+            owner_id: identity.owner_id.clone(),
+            instance_id: identity.instance_id.clone(),
+            table_name: identity.table_name.clone(),
+        })?;
+        reader.validate_receipt(expected)?;
+        let graph = reader.graph()?.ok_or(Error::Conflict)?;
+        reader.binding(&graph, Some(expected))?;
+        if !reader.matches(&graph, &expected.prepared)? {
+            return Err(Error::Conflict);
+        }
+        expected.prepared.validate_interfaces()
+    }
+
     pub fn new(options: Options) -> Result<Self> {
         if !identifier(&options.owner_id)
             || !identifier(&options.instance_id)

package/rust/src/wire.links.rs

@@ -266,3 +266,14 @@ pub fn verify_bound_interfaces<'a>(
     }
     Ok(())
 }
+
+/// Mutation fence: the caller retains these exact links until cleanup completes.
+pub fn verify_bound_interfaces_down<'a>(interfaces: impl Iterator<Item = BoundInterface<'a>>) -> Result<()> {
+    let mut socket = Socket::open_protocol(libc::NETLINK_ROUTE)?;
+    for binding in interfaces {
+        let link = read_link(&mut socket, binding.index)?;
+        matches(&link, &binding)?;
+        if link.flags & libc::IFF_UP as u32 != 0 {return Err(Error::Conflict);}
+    }
+    Ok(())
+}

package/rust/src/wire.rs

@@ -125,7 +125,7 @@ pub struct Socket {
 
 #[path = "wire.links.rs"]
 mod links;
-pub use links::{verify_bound_interfaces, verify_interfaces, BoundInterface};
+pub use links::{verify_bound_interfaces, verify_bound_interfaces_down, verify_interfaces, BoundInterface};
 impl Socket {
     pub fn open() -> Result<Self> {
         Self::open_protocol(libc::NETLINK_NETFILTER)
@@ -192,6 +192,9 @@ impl Socket {
         Ok(self.sequence)
     }
     fn message(&mut self, kind: u16, flags: u16, attributes: &[Attr]) -> Result<(u32, Vec<u8>)> {
+        self.message_family(kind, flags, attributes, 1)
+    }
+    fn message_family(&mut self, kind: u16, flags: u16, attributes: &[Attr], family: u8) -> Result<(u32, Vec<u8>)> {
         let sequence = self.sequence()?;
         let batch = kind == 16 || kind == 17;
         let payload = encode_attrs(attributes);
@@ -204,7 +207,7 @@ impl Socket {
         bytes.extend(flags.to_ne_bytes());
         bytes.extend(sequence.to_ne_bytes());
         bytes.extend(self.port.to_ne_bytes());
-        bytes.extend([if batch { 0 } else { 1 }, 0]);
+        bytes.extend([if batch { 0 } else { family }, 0]);
         bytes.extend(if batch { 10_u16 } else { 0 }.to_be_bytes());
         bytes.extend(payload);
         Ok((sequence, bytes))
@@ -287,8 +290,15 @@ impl Socket {
         input: Vec<Attr>,
         dump: bool,
     ) -> Result<Vec<Vec<Attr>>> {
+        self.query_family(operation, input, dump, 1)
+    }
+    /// Read Docker's IPv4 nft graph without claiming or mutating its table.
+    pub fn query_ipv4(&mut self, operation: u16, input: Vec<Attr>, dump: bool) -> Result<Vec<Vec<Attr>>> {
+        self.query_family(operation, input, dump, 2)
+    }
+    fn query_family(&mut self, operation: u16, input: Vec<Attr>, dump: bool, family: u8) -> Result<Vec<Vec<Attr>>> {
         let (sequence, bytes) =
-            self.message(0x0a00 | operation, 1 | if dump { 0x300 } else { 0 }, &input)?;
+            self.message_family(0x0a00 | operation, 1 | if dump { 0x300 } else { 0 }, &input, family)?;
         self.send(&bytes)?;
         let until = Instant::now() + Duration::from_secs(3);
         let mut result = Vec::new();
@@ -325,6 +335,7 @@ impl Socket {
                     if total > 2_097_152 || result.len() >= 4096 || message.payload.len() < 4 {
                         return Err(Error::Protocol);
                     }
+                    if family == 2 && message.payload[0] != family {return Err(Error::Protocol);}
                     result.push(attrs(&message.payload[4..])?);
                     if !dump {
                         return Ok(result);

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartnftables',
-  version: '1.5.0',
+  version: '1.6.0',
   description: 'A TypeScript module for managing nftables rules including NAT, firewall, and rate limiting with a high-level API.'
 }

package/ts/classes.manageddockerforwarding.ts

@@ -0,0 +1,113 @@
+import * as plugins from './plugins.js';
+import { snapshot, ManagedNftablesError } from './classes.managednftables.js';
+import type { IManagedDockerForwardingOptions, IManagedDockerForwardingStatus, IManagedDockerForwardingPolicy, IPreparedManagedDockerForwardingPolicy, IManagedDockerForwardingTransition, IAppliedManagedDockerForwardingPolicy, TManagedDockerForwardingCommands } from './managed.docker.types.js';
+
+/** One node-level Docker DOCKER-USER contribution. Caller owns durable intents and handoff lifetimes. */
+export class ManagedDockerForwarding {
+  readonly #options: Readonly<IManagedDockerForwardingOptions>;
+  #bridge: plugins.smartrust.RustBridge<TManagedDockerForwardingCommands> | null = null;
+  #state: 'new' | 'starting' | 'ready' | 'closing' | 'failed-owned' | 'stopped' = 'new';
+  #work: Promise<unknown> | null = null;
+  #close: Promise<void> | null = null;
+  #nativeMayOwn = false;
+
+  constructor(options: IManagedDockerForwardingOptions) {
+    this.#options = snapshot(options);
+    if (Object.keys(this.#options).some((key) => !['ownerId', 'instanceId', 'binaryPath', 'networkNamespaceFd'].includes(key))
+      || ![this.#options.ownerId, this.#options.instanceId].every((value) => typeof value === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(value))
+      || this.#options.instanceId.length < 16
+      || this.#options.binaryPath !== undefined && (!plugins.path.isAbsolute(this.#options.binaryPath) || this.#options.binaryPath.includes('\0'))) {
+      throw new ManagedNftablesError('INVALID');
+    }
+    if (this.#options.networkNamespaceFd !== undefined && (process.platform !== 'linux'
+      || !Number.isInteger(this.#options.networkNamespaceFd) || this.#options.networkNamespaceFd < 0
+      || this.#options.networkNamespaceFd > 0x7fff_ffff)) throw new ManagedNftablesError('INVALID');
+  }
+
+  public get state(): string { return this.#state; }
+
+  /** Starts only the compiler/IPC owner. The returned idle status is not enforcement. */
+  public start(): Promise<IManagedDockerForwardingStatus> {
+    if (this.#state !== 'new') return Promise.reject(new ManagedNftablesError('UNAVAILABLE'));
+    this.#state = 'starting';
+    const work = (async () => {
+      if (process.platform !== 'linux' || !['x64', 'arm64'].includes(process.arch)) throw new ManagedNftablesError('UNSUPPORTED_PLATFORM');
+      const root = plugins.url.fileURLToPath(new URL('../', import.meta.url));
+      this.#bridge = new plugins.smartrust.RustBridge<TManagedDockerForwardingCommands>({
+        binaryName: 'smartnftables', binaryPath: this.#options.binaryPath
+          ?? plugins.path.join(root, 'dist_rust', `smartnftables_linux_${process.arch === 'x64' ? 'amd64' : 'arm64'}_musl`),
+        localPaths: [], searchSystemPath: false,
+        cliArgs: ['--docker-forwarding', ...(this.#options.networkNamespaceFd === undefined ? [] : ['--network-namespace-fd', '3'])],
+        inheritedFileDescriptors: this.#options.networkNamespaceFd === undefined ? undefined : [this.#options.networkNamespaceFd],
+        readyTimeoutMs: 3000, requestTimeoutMs: 30_000, maxPayloadSize: 262_144,
+        maxPendingRequestsByMethod: { prepareDockerForwarding: 1, openDockerForwarding: 1, reconcileDockerForwarding: 1, inspectDockerForwarding: 1, releaseDockerForwarding: 1, closeDockerForwarding: 1 },
+      });
+      this.#bridge.on('exit', () => {
+        if (!['closing', 'stopped'].includes(this.#state)) this.#state = 'failed-owned';
+      });
+      if (!await this.#bridge.spawn()) throw new ManagedNftablesError('UNAVAILABLE');
+      const { ownerId, instanceId } = this.#options;
+      const status = snapshot(await this.#bridge.sendCommand('openDockerForwarding', { ownerId, instanceId }));
+      if (this.#state !== 'starting') throw new ManagedNftablesError('UNAVAILABLE');
+      this.#state = 'ready'; return status;
+    })();
+    return this.#track(work);
+  }
+
+  public prepare(policy: IManagedDockerForwardingPolicy): Promise<IPreparedManagedDockerForwardingPolicy> {
+    return this.#invoke('prepareDockerForwarding', policy);
+  }
+  public reconcile(transition: IManagedDockerForwardingTransition): Promise<IAppliedManagedDockerForwardingPolicy> {
+    return this.#invoke('reconcileDockerForwarding', transition);
+  }
+  public inspect(): Promise<IManagedDockerForwardingStatus> { return this.#invoke('inspectDockerForwarding', {}); }
+  public release(expected: IAppliedManagedDockerForwardingPolicy): Promise<{ released: true }> {
+    return this.#invoke('releaseDockerForwarding', expected);
+  }
+
+  /** Join operations and exact contributed-rule deletion, then native termination. Keep affected handoff links down through cleanup. */
+  public close(): Promise<void> {
+    if (this.#close) return this.#close;
+    if (this.#state === 'stopped') return Promise.resolve();
+    this.#state = 'closing';
+    this.#close = (async () => {
+      await this.#work?.catch(() => undefined);
+      if (this.#bridge) {
+        if (this.#nativeMayOwn) {
+          const result = await this.#bridge.sendCommand('closeDockerForwarding', {});
+          if (result.released !== true) throw new ManagedNftablesError('PROTOCOL');
+        }
+        await this.#bridge.terminate({ gracePeriodMs: 1000 });
+      }
+      this.#bridge = null; this.#state = 'stopped';
+    })().catch(() => {
+      this.#state = 'failed-owned'; this.#close = null;
+      throw new ManagedNftablesError('CLEANUP_UNCONFIRMED');
+    });
+    return this.#close;
+  }
+
+  #invoke<K extends keyof TManagedDockerForwardingCommands>(method: K, params: TManagedDockerForwardingCommands[K]['params']): Promise<TManagedDockerForwardingCommands[K]['result']> {
+    if (!['ready', 'failed-owned'].includes(this.#state) || !this.#bridge || this.#work) return Promise.reject(new ManagedNftablesError('UNAVAILABLE'));
+    let captured: TManagedDockerForwardingCommands[K]['params'];
+    try { captured = snapshot(params); } catch { return Promise.reject(new ManagedNftablesError('INVALID')); }
+    if (method === 'reconcileDockerForwarding' || method === 'releaseDockerForwarding') this.#nativeMayOwn = true;
+    return this.#track(this.#bridge.sendCommand(method, captured).then((result) => {
+      const capturedResult = snapshot(result);
+      if (method === 'releaseDockerForwarding') this.#nativeMayOwn = false;
+      if (this.#state !== 'closing' && (method === 'reconcileDockerForwarding' || method === 'releaseDockerForwarding'
+        || method === 'inspectDockerForwarding' && (capturedResult as IManagedDockerForwardingStatus).error === null)) this.#state = 'ready';
+      return capturedResult;
+    }));
+  }
+  #track<T>(work: Promise<T>): Promise<T> {
+    const owned = work.catch((error) => {
+      if (this.#state !== 'closing') this.#state = 'failed-owned';
+      const code = error instanceof plugins.smartrust.RustBridgeRequestError ? error.responseErrorCode : undefined;
+      throw new ManagedNftablesError(typeof code === 'string' && /^[A-Z_]{1,64}$/.test(code) ? code : 'UNAVAILABLE');
+    });
+    this.#work = owned;
+    void owned.then(() => { this.#work = null; }, () => { this.#work = null; });
+    return owned;
+  }
+}

package/ts/classes.managednftables.ts

@@ -7,7 +7,7 @@ export class ManagedNftablesError extends Error {
 }
 
 /** Capture inert input without evaluating getters, proxies, coercions or toJSON. */
-function snapshot<T>(input: T): T {
+export function snapshot<T>(input: T): T {
   let count = 0;
   let stringBytes = 0;
   const string = (value: string): string => {

package/ts/index.ts

@@ -62,3 +62,5 @@ export type {
   ISmartNftablesOptions,
   INftStatus,
 } from './nft.types.js';
+export * from './managed.docker.types.js';
+export * from './classes.manageddockerforwarding.js';

package/ts/managed.docker.types.ts

@@ -0,0 +1,49 @@
+import type { IAppliedManagedNftPolicy, IManagedNftOptions } from './managed.types.js';
+import type { IManagedNftPolicyV2, IManagedNftHostTransitScopeV2 } from './managed.egress.types.js';
+
+export interface IManagedDockerForwardingOptions extends Omit<IManagedNftOptions, 'tableName'> {}
+export interface IManagedDockerForwardingPolicy {
+  schemaVersion: 1;
+  revision: number;
+  /** Exact dedicated host barrier. This contribution never adopts or modifies its table. */
+  barrier: IAppliedManagedNftPolicy<IManagedNftPolicyV2 & { scope: IManagedNftHostTransitScopeV2 }>;
+}
+export interface IPreparedManagedDockerForwardingPolicy {
+  policy: IManagedDockerForwardingPolicy;
+  /** Exact nft frontend version captured during prepare and checked through recovery. */
+  backend: string;
+  digest: string;
+}
+export interface IManagedDockerForwardingIdentity {
+  ownerId: string;
+  instanceId: string;
+  bootId: string;
+  namespaceDevice: string;
+  namespaceInode: string;
+}
+export interface IAppliedManagedDockerForwardingPolicy {
+  receipt: { identity: IManagedDockerForwardingIdentity; backend: string; revision: number; digest: string };
+  prepared: IPreparedManagedDockerForwardingPolicy;
+}
+/** Persist before mutation. Keep both generations' exact handoff links down until reconciliation is confirmed. */
+export interface IManagedDockerForwardingTransition {
+  previous: IAppliedManagedDockerForwardingPolicy | null;
+  target: IPreparedManagedDockerForwardingPolicy;
+}
+export interface IManagedDockerForwardingStatus {
+  identity: IManagedDockerForwardingIdentity;
+  state: 'idle' | 'applied' | 'failed-owned' | 'released';
+  /** Exact contribution and barrier inspected; does not attest the whole host path or durable fencing. */
+  present: boolean;
+  applied: IAppliedManagedDockerForwardingPolicy | null;
+  pending: IManagedDockerForwardingTransition | null;
+  error: string | null;
+}
+export type TManagedDockerForwardingCommands = {
+  prepareDockerForwarding: { params: IManagedDockerForwardingPolicy; result: IPreparedManagedDockerForwardingPolicy };
+  openDockerForwarding: { params: Pick<IManagedDockerForwardingOptions, 'ownerId' | 'instanceId'>; result: IManagedDockerForwardingStatus };
+  reconcileDockerForwarding: { params: IManagedDockerForwardingTransition; result: IAppliedManagedDockerForwardingPolicy };
+  inspectDockerForwarding: { params: Record<string, never>; result: IManagedDockerForwardingStatus };
+  releaseDockerForwarding: { params: IAppliedManagedDockerForwardingPolicy; result: { released: true } };
+  closeDockerForwarding: { params: Record<string, never>; result: { released: true } };
+};