@push.rocks/smartnftables 1.4.0 → 1.6.0

package/rust/src/wire.links.rs

@@ -0,0 +1,279 @@
+use super::{attrs, one, text, Attr, Socket};
+use crate::{Error, Result};
+use std::collections::BTreeSet;
+use std::net::Ipv4Addr;
+use std::time::{Duration, Instant};
+
+struct Link {
+    hardware: u16,
+    flags: u32,
+    attributes: Vec<Attr>,
+}
+
+/// Current local facts only. Peer namespaces and link-generation lifetimes remain caller-owned.
+#[derive(Clone, Copy)]
+pub struct BoundInterface<'a> {
+    pub index: u32,
+    pub name: &'a str,
+    pub kind: &'a str,
+    pub mac: Option<&'a str>,
+    pub link_index: u32,
+    pub addresses: &'a [String],
+}
+
+fn read_link(socket: &mut Socket, index: u32) -> Result<Link> {
+    let sequence = socket.sequence()?;
+    let mut request = Vec::new();
+    request.extend(32_u32.to_ne_bytes());
+    request.extend(18_u16.to_ne_bytes());
+    request.extend(1_u16.to_ne_bytes());
+    request.extend(sequence.to_ne_bytes());
+    request.extend(socket.port.to_ne_bytes());
+    request.extend([0; 4]);
+    request.extend(index.to_ne_bytes());
+    request.extend([0; 8]);
+    socket.send(&request)?;
+    let until = Instant::now() + Duration::from_secs(3);
+    loop {
+        for message in socket.receive(until)? {
+            if message.sequence != sequence {
+                continue;
+            }
+            if message.kind == 2 {
+                let error = i32::from_ne_bytes(
+                    message
+                        .payload
+                        .get(..4)
+                        .ok_or(Error::Protocol)?
+                        .try_into()
+                        .unwrap(),
+                );
+                if error != 0 {
+                    return Err(Error::kernel(error));
+                }
+            } else if message.kind == 16 && message.payload.len() >= 16 {
+                if u32::from_ne_bytes(message.payload[4..8].try_into().unwrap()) != index {
+                    return Err(Error::Conflict);
+                }
+                return Ok(Link {
+                    hardware: u16::from_ne_bytes(message.payload[2..4].try_into().unwrap()),
+                    flags: u32::from_ne_bytes(message.payload[8..12].try_into().unwrap()),
+                    attributes: attrs(&message.payload[16..])?,
+                });
+            } else {
+                return Err(Error::Protocol);
+            }
+        }
+    }
+}
+fn unbridged(attributes: &[Attr]) -> Result<()> {
+    if attributes.iter().any(|attr| attr.id() == 10)
+        && one(attributes, 10)?.value != 0_u32.to_ne_bytes()
+    {
+        return Err(Error::Conflict);
+    }
+    Ok(())
+}
+fn virtual_kind(attributes: &[Attr], kind: &str) -> Result<()> {
+    let info = attrs(&one(attributes, 18)?.value)?;
+    if text(&info, 1)? != kind {
+        return Err(Error::Conflict);
+    }
+    if kind == "tun" && one(&attrs(&one(&info, 2)?.value)?, 3)?.value != [1] {
+        return Err(Error::Conflict);
+    }
+    Ok(())
+}
+/// Preserve schema-v1's local name/index/kind/master checks exactly.
+pub fn verify_interfaces<'a>(
+    interfaces: impl Iterator<Item = (u32, &'a str, &'a str)>,
+) -> Result<()> {
+    let mut socket = Socket::open_protocol(libc::NETLINK_ROUTE)?;
+    for (index, name, kind) in interfaces {
+        let link = read_link(&mut socket, index)?;
+        if text(&link.attributes, 3)? != name {
+            return Err(Error::Conflict);
+        }
+        unbridged(&link.attributes)?;
+        virtual_kind(&link.attributes, kind)?;
+    }
+    Ok(())
+}
+fn matches(link: &Link, binding: &BoundInterface<'_>) -> Result<()> {
+    if text(&link.attributes, 3)? != binding.name || link.flags & libc::IFF_LOOPBACK as u32 != 0 {
+        return Err(Error::Conflict);
+    }
+    unbridged(&link.attributes)?;
+    match binding.kind {
+        "veth" | "tun" => virtual_kind(&link.attributes, binding.kind)?,
+        "ethernet" => {
+            // Physical/VirtIO Ethernet has no IFLA_LINKINFO; bridge, VLAN, bond,
+            // dummy and other virtual kinds are not an implicit uplink role.
+            if link.attributes.iter().any(|item| item.id() == 18) {
+                return Err(Error::Conflict);
+            }
+        }
+        _ => return Err(Error::Invalid),
+    }
+    if binding.kind == "tun" {
+        if link.hardware != 65534 || binding.mac.is_some() {
+            return Err(Error::Conflict);
+        }
+    } else {
+        let mac = &one(&link.attributes, 1)?.value;
+        if link.hardware != 1
+            || mac.len() != 6
+            || mac[0] & 1 != 0
+            || mac.iter().all(|item| *item == 0)
+        {
+            return Err(Error::Conflict);
+        }
+        let actual = mac
+            .iter()
+            .map(|item| format!("{item:02x}"))
+            .collect::<Vec<_>>()
+            .join(":");
+        if binding.mac != Some(actual.as_str()) {
+            return Err(Error::Conflict);
+        }
+    }
+    let peer = if link.attributes.iter().any(|item| item.id() == 5) {
+        u32::from_ne_bytes(
+            one(&link.attributes, 5)?
+                .value
+                .as_slice()
+                .try_into()
+                .map_err(|_| Error::Protocol)?,
+        )
+    } else {
+        binding.index
+    };
+    if peer != binding.link_index {
+        return Err(Error::Conflict);
+    }
+    Ok(())
+}
+fn read_addresses(socket: &mut Socket, index: u32) -> Result<BTreeSet<String>> {
+    let sequence = socket.sequence()?;
+    let mut request = Vec::new();
+    request.extend(24_u32.to_ne_bytes());
+    request.extend(22_u16.to_ne_bytes());
+    request.extend(0x301_u16.to_ne_bytes());
+    request.extend(sequence.to_ne_bytes());
+    request.extend(socket.port.to_ne_bytes());
+    request.extend([libc::AF_INET as u8, 0, 0, 0]);
+    request.extend(index.to_ne_bytes());
+    socket.send(&request)?;
+    let until = Instant::now() + Duration::from_secs(3);
+    let mut result = BTreeSet::new();
+    let mut total = 0;
+    let mut count = 0;
+    loop {
+        for message in socket.receive(until)? {
+            if message.sequence != sequence {
+                continue;
+            }
+            if message.flags & 0x10 != 0 {
+                return Err(Error::Conflict);
+            }
+            if message.kind == 2 || message.kind == 3 {
+                if message.kind == 2 || !message.payload.is_empty() {
+                    let error = i32::from_ne_bytes(
+                        message
+                            .payload
+                            .get(..4)
+                            .ok_or(Error::Protocol)?
+                            .try_into()
+                            .unwrap(),
+                    );
+                    if error != 0 {
+                        return Err(Error::kernel(error));
+                    }
+                }
+                if message.kind == 3 {
+                    return Ok(result);
+                }
+                continue;
+            }
+            count += 1;
+            total += message.payload.len();
+            if message.kind != 20 || message.payload.len() < 8 || count > 4096 || total > 2_097_152
+            {
+                return Err(Error::Protocol);
+            }
+            if message.payload[0] != libc::AF_INET as u8 {
+                return Err(Error::Protocol);
+            }
+            if u32::from_ne_bytes(message.payload[4..8].try_into().unwrap()) != index {
+                continue;
+            }
+            let data = attrs(&message.payload[8..])?;
+            let local = if data.iter().any(|item| item.id() == 2) {
+                one(&data, 2)?
+            } else {
+                one(&data, 1)?
+            };
+            let bytes: [u8; 4] = local
+                .value
+                .as_slice()
+                .try_into()
+                .map_err(|_| Error::Protocol)?;
+            let flags = if data.iter().any(|item| item.id() == 8) {
+                u32::from_ne_bytes(
+                    one(&data, 8)?
+                        .value
+                        .as_slice()
+                        .try_into()
+                        .map_err(|_| Error::Protocol)?,
+                )
+            } else {
+                u32::from(message.payload[2])
+            };
+            // Tentative, failed or deprecated source addresses do not qualify.
+            if flags & (0x40 | 0x08 | 0x20) != 0 {
+                continue;
+            }
+            if data.iter().any(|item| item.id() == 6) {
+                let cache = &one(&data, 6)?.value;
+                if cache.len() != 16 {
+                    return Err(Error::Protocol);
+                }
+                if u32::from_ne_bytes(cache[..4].try_into().unwrap()) == 0
+                    || u32::from_ne_bytes(cache[4..8].try_into().unwrap()) == 0
+                {
+                    continue;
+                }
+            }
+            result.insert(Ipv4Addr::from(bytes).to_string());
+        }
+    }
+}
+pub fn verify_bound_interfaces<'a>(
+    interfaces: impl Iterator<Item = BoundInterface<'a>>,
+) -> Result<()> {
+    let mut socket = Socket::open_protocol(libc::NETLINK_ROUTE)?;
+    for binding in interfaces {
+        matches(&read_link(&mut socket, binding.index)?, &binding)?;
+        let addresses = read_addresses(&mut socket, binding.index)?;
+        if binding
+            .addresses
+            .iter()
+            .any(|address| !addresses.contains(address))
+        {
+            return Err(Error::Conflict);
+        }
+        matches(&read_link(&mut socket, binding.index)?, &binding)?;
+    }
+    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

@@ -123,70 +123,9 @@ pub struct Socket {
     sequence: u32,
 }
 
-/// Read-only, namespace-local RTM_GETLINK qualification. This is not a public
-/// routing or link-creation escape; only the strict native compiler calls it.
-pub fn verify_interfaces<'a>(
-    interfaces: impl Iterator<Item = (u32, &'a str, &'a str)>,
-) -> Result<()> {
-    let mut socket = Socket::open_protocol(libc::NETLINK_ROUTE)?;
-    for (index, name, kind) in interfaces {
-        let sequence = socket.sequence()?;
-        let mut request = Vec::new();
-        request.extend(32_u32.to_ne_bytes());
-        request.extend(18_u16.to_ne_bytes());
-        request.extend(1_u16.to_ne_bytes());
-        request.extend(sequence.to_ne_bytes());
-        request.extend(socket.port.to_ne_bytes());
-        request.extend([0; 4]);
-        request.extend(index.to_ne_bytes());
-        request.extend([0; 8]);
-        socket.send(&request)?;
-        let until = Instant::now() + Duration::from_secs(3);
-        let response = 'read: loop {
-            for message in socket.receive(until)? {
-                if message.sequence != sequence {
-                    continue;
-                }
-                if message.kind == 2 {
-                    let error = i32::from_ne_bytes(
-                        message
-                            .payload
-                            .get(..4)
-                            .ok_or(Error::Protocol)?
-                            .try_into()
-                            .unwrap(),
-                    );
-                    if error != 0 {
-                        return Err(Error::kernel(error));
-                    }
-                } else if message.kind == 16 && message.payload.len() >= 16 {
-                    if u32::from_ne_bytes(message.payload[4..8].try_into().unwrap()) != index {
-                        return Err(Error::Conflict);
-                    }
-                    break 'read attrs(&message.payload[16..])?;
-                } else {
-                    return Err(Error::Protocol);
-                }
-            }
-        };
-        if text(&response, 3)? != name {
-            return Err(Error::Conflict);
-        }
-        if response.iter().any(|attr| attr.id() == 10)
-            && one(&response, 10)?.value != 0_u32.to_ne_bytes()
-        {
-            return Err(Error::Conflict);
-        }
-        let info = attrs(&one(&response, 18)?.value)?;
-        if text(&info, 1)? != kind {
-            return Err(Error::Conflict);
-        }
-        if kind == "tun" && one(&attrs(&one(&info, 2)?.value)?, 3)?.value != [1] {
-            return Err(Error::Conflict);
-        }
-    }
-    Ok(())
-}
+#[path = "wire.links.rs"]
+mod links;
+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)
@@ -253,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);
@@ -265,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))
@@ -348,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();
@@ -386,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.4.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

@@ -1,13 +1,13 @@
 import * as plugins from './plugins.js';
 import type { IManagedNftOptions, IManagedNftPolicy, IManagedNftTransition, IAppliedManagedNftPolicy,
-  IPreparedManagedNftPolicy, IManagedNftStatus, TManagedNftCommands } from './managed.types.js';
+  IPreparedManagedNftPolicy, IManagedNftStatus, TManagedNftCommands, TManagedNftPolicy } from './managed.types.js';
 
 export class ManagedNftablesError extends Error {
   constructor(public readonly code: string) { super(`Managed nftables ${code}.`); }
 }
 
 /** 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 => {
@@ -43,9 +43,9 @@ function snapshot<T>(input: T): T {
 }
 
 /** One private native/netlink owner. Persistence and workload link lifetimes belong to its caller. */
-export class ManagedNftables {
+export class ManagedNftables<TPolicy extends TManagedNftPolicy = IManagedNftPolicy> {
   readonly #options: Readonly<IManagedNftOptions>;
-  #bridge: plugins.smartrust.RustBridge<TManagedNftCommands> | null = null;
+  #bridge: plugins.smartrust.RustBridge<TManagedNftCommands<TPolicy>> | null = null;
   #state: 'new' | 'starting' | 'ready' | 'closing' | 'failed-owned' | 'stopped' = 'new';
   #work: Promise<unknown> | null = null;
   #close: Promise<void> | null = null;
@@ -67,13 +67,13 @@ export class ManagedNftables {
   public get state(): string { return this.#state; }
 
   /** Starts only the compiler/IPC owner. The returned idle status is not enforcement. */
-  public start(): Promise<IManagedNftStatus> {
+  public start(): Promise<IManagedNftStatus<TPolicy>> {
     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<TManagedNftCommands>({
+      this.#bridge = new plugins.smartrust.RustBridge<TManagedNftCommands<TPolicy>>({
         binaryName: 'smartnftables', binaryPath: this.#options.binaryPath
           ?? plugins.path.join(root, 'dist_rust', `smartnftables_linux_${process.arch === 'x64' ? 'amd64' : 'arm64'}_musl`),
         localPaths: [], searchSystemPath: false,
@@ -94,14 +94,14 @@ export class ManagedNftables {
     return this.#track(work);
   }
 
-  public prepare(policy: IManagedNftPolicy): Promise<IPreparedManagedNftPolicy> {
+  public prepare(policy: TPolicy): Promise<IPreparedManagedNftPolicy<TPolicy>> {
     return this.#invoke('preparePolicy', policy);
   }
-  public reconcile(transition: IManagedNftTransition): Promise<IAppliedManagedNftPolicy> {
+  public reconcile(transition: IManagedNftTransition<TPolicy>): Promise<IAppliedManagedNftPolicy<TPolicy>> {
     return this.#invoke('reconcilePolicy', transition);
   }
-  public inspect(): Promise<IManagedNftStatus> { return this.#invoke('inspectPolicy', {}); }
-  public release(expected: IAppliedManagedNftPolicy): Promise<{ released: true }> {
+  public inspect(): Promise<IManagedNftStatus<TPolicy>> { return this.#invoke('inspectPolicy', {}); }
+  public release(expected: IAppliedManagedNftPolicy<TPolicy>): Promise<{ released: true }> {
     return this.#invoke('releasePolicy', expected);
   }
 
@@ -127,16 +127,16 @@ export class ManagedNftables {
     return this.#close;
   }
 
-  #invoke<K extends keyof TManagedNftCommands>(method: K, params: TManagedNftCommands[K]['params']): Promise<TManagedNftCommands[K]['result']> {
+  #invoke<K extends keyof TManagedNftCommands<TPolicy>>(method: K, params: TManagedNftCommands<TPolicy>[K]['params']): Promise<TManagedNftCommands<TPolicy>[K]['result']> {
     if (!['ready', 'failed-owned'].includes(this.#state) || !this.#bridge || this.#work) return Promise.reject(new ManagedNftablesError('UNAVAILABLE'));
-    let captured: TManagedNftCommands[K]['params'];
+    let captured: TManagedNftCommands<TPolicy>[K]['params'];
     try { captured = snapshot(params); } catch { return Promise.reject(new ManagedNftablesError('INVALID')); }
     if (method === 'reconcilePolicy' || method === 'releasePolicy') this.#nativeMayOwn = true;
     return this.#track(this.#bridge.sendCommand(method, captured).then((result) => {
       const capturedResult = snapshot(result);
       if (method === 'releasePolicy') this.#nativeMayOwn = false;
       if (this.#state !== 'closing' && (method === 'reconcilePolicy' || method === 'releasePolicy'
-        || method === 'inspectPolicy' && (capturedResult as IManagedNftStatus).error === null)) this.#state = 'ready';
+        || method === 'inspectPolicy' && (capturedResult as IManagedNftStatus<TPolicy>).error === null)) this.#state = 'ready';
       return capturedResult;
     }));
   }

package/ts/index.ts

@@ -2,6 +2,7 @@
 export { SmartNftables } from './nft.manager.js';
 export { ManagedNftables, ManagedNftablesError } from './classes.managednftables.js';
 export type * from './managed.types.js';
+export type * from './managed.egress.types.js';
 
 // Sub-managers
 export { NatManager } from './nft.manager.nat.js';
@@ -61,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 } };
+};