@push.rocks/smartnftables 1.2.1 → 1.4.0

package/rust/src/wire.rs

@@ -0,0 +1,437 @@
+//! Small private codec for the Linux nftables UAPI. There is no public raw message API.
+use crate::{Error, Result};
+use std::os::fd::{AsRawFd, FromRawFd, OwnedFd};
+use std::time::{Duration, Instant};
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Attr {
+    pub kind: u16,
+    pub value: Vec<u8>,
+}
+impl Attr {
+    pub fn bytes(kind: u16, value: Vec<u8>) -> Self {
+        Self { kind, value }
+    }
+    pub fn string(kind: u16, value: &str) -> Self {
+        Self::bytes(kind, [value.as_bytes(), &[0]].concat())
+    }
+    pub fn u32(kind: u16, value: u32) -> Self {
+        Self::bytes(kind, value.to_be_bytes().to_vec())
+    }
+    pub fn u64(kind: u16, value: u64) -> Self {
+        Self::bytes(kind, value.to_be_bytes().to_vec())
+    }
+    pub fn nested(kind: u16, value: Vec<Attr>) -> Self {
+        Self::bytes(kind | 0x8000, encode_attrs(&value))
+    }
+    pub fn id(&self) -> u16 {
+        self.kind & 0x3fff
+    }
+}
+pub fn encode_attrs(attrs: &[Attr]) -> Vec<u8> {
+    let mut result = Vec::new();
+    for attr in attrs {
+        let len = 4 + attr.value.len();
+        result.extend((len as u16).to_ne_bytes());
+        result.extend(attr.kind.to_ne_bytes());
+        result.extend(&attr.value);
+        result.resize((result.len() + 3) & !3, 0);
+    }
+    result
+}
+pub fn attrs(mut bytes: &[u8]) -> Result<Vec<Attr>> {
+    let mut result = Vec::new();
+    while !bytes.is_empty() {
+        if bytes.len() < 4 || result.len() > 4096 {
+            return Err(Error::Protocol);
+        }
+        let len = u16::from_ne_bytes(bytes[..2].try_into().unwrap()) as usize;
+        let size = (len + 3) & !3;
+        if len < 4 || size > bytes.len() {
+            return Err(Error::Protocol);
+        }
+        result.push(Attr::bytes(
+            u16::from_ne_bytes(bytes[2..4].try_into().unwrap()),
+            bytes[4..len].to_vec(),
+        ));
+        bytes = &bytes[size..];
+    }
+    Ok(result)
+}
+pub fn one(attrs: &[Attr], id: u16) -> Result<&Attr> {
+    let mut matches = attrs.iter().filter(|v| v.id() == id);
+    let value = matches.next().ok_or(Error::Protocol)?;
+    if matches.next().is_some() {
+        return Err(Error::Protocol);
+    }
+    Ok(value)
+}
+pub fn text(attrs: &[Attr], id: u16) -> Result<String> {
+    let bytes = &one(attrs, id)?.value;
+    if bytes.last() != Some(&0) || bytes[..bytes.len() - 1].contains(&0) {
+        return Err(Error::Protocol);
+    }
+    String::from_utf8(bytes[..bytes.len() - 1].to_vec()).map_err(|_| Error::Protocol)
+}
+pub fn number(attrs: &[Attr], id: u16) -> Result<u32> {
+    Ok(u32::from_be_bytes(
+        one(attrs, id)?
+            .value
+            .as_slice()
+            .try_into()
+            .map_err(|_| Error::Protocol)?,
+    ))
+}
+pub fn handle(attrs: &[Attr], id: u16) -> Result<u64> {
+    Ok(u64::from_be_bytes(
+        one(attrs, id)?
+            .value
+            .as_slice()
+            .try_into()
+            .map_err(|_| Error::Protocol)?,
+    ))
+}
+
+/// Attribute order/byte-order flags are not identity; ordered nested expression lists are.
+pub fn canonical(attributes: &[Attr], ordered: bool) -> Result<Vec<(u16, Vec<u8>)>> {
+    let mut result = Vec::new();
+    for attr in attributes {
+        let value = if attr.kind & 0x8000 != 0 {
+            let nested = attrs(&attr.value)?;
+            let ordered = nested.iter().all(|item| item.id() == 1);
+            serde_json::to_vec(&canonical(&nested, ordered)?).map_err(|_| Error::Protocol)?
+        } else {
+            attr.value.clone()
+        };
+        result.push((attr.id(), value));
+    }
+    if !ordered {
+        result.sort_by_key(|(id, _)| *id);
+    }
+    Ok(result)
+}
+
+struct Message {
+    kind: u16,
+    flags: u16,
+    sequence: u32,
+    payload: Vec<u8>,
+}
+pub struct Socket {
+    fd: OwnedFd,
+    pub port: u32,
+    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(())
+}
+impl Socket {
+    pub fn open() -> Result<Self> {
+        Self::open_protocol(libc::NETLINK_NETFILTER)
+    }
+    fn open_protocol(protocol: i32) -> Result<Self> {
+        // SAFETY: valid AF_NETLINK sockaddr and owned descriptor, never shared with callers.
+        let raw = unsafe {
+            libc::socket(
+                libc::AF_NETLINK,
+                libc::SOCK_RAW | libc::SOCK_CLOEXEC,
+                protocol,
+            )
+        };
+        if raw < 0 {
+            return Err(Error::Unavailable);
+        }
+        let fd = unsafe { OwnedFd::from_raw_fd(raw) };
+        let mut address: libc::sockaddr_nl = unsafe { std::mem::zeroed() };
+        address.nl_family = libc::AF_NETLINK as u16;
+        if unsafe {
+            libc::bind(
+                raw,
+                (&address as *const libc::sockaddr_nl).cast(),
+                std::mem::size_of_val(&address) as _,
+            )
+        } < 0
+        {
+            return Err(Error::Unavailable);
+        }
+        let mut len = std::mem::size_of_val(&address) as libc::socklen_t;
+        if unsafe {
+            libc::getsockname(
+                raw,
+                (&mut address as *mut libc::sockaddr_nl).cast(),
+                &mut len,
+            )
+        } < 0
+        {
+            return Err(Error::Unavailable);
+        }
+        let capacity: libc::c_int = 1_048_576;
+        for option in [libc::SO_SNDBUF, libc::SO_RCVBUF] {
+            if unsafe {
+                libc::setsockopt(
+                    raw,
+                    libc::SOL_SOCKET,
+                    option,
+                    (&capacity as *const libc::c_int).cast(),
+                    std::mem::size_of_val(&capacity) as _,
+                )
+            } < 0
+            {
+                return Err(Error::Unavailable);
+            }
+        }
+        Ok(Self {
+            fd,
+            port: address.nl_pid,
+            sequence: 0,
+        })
+    }
+    fn sequence(&mut self) -> Result<u32> {
+        self.sequence = self.sequence.checked_add(1).ok_or(Error::Unavailable)?;
+        Ok(self.sequence)
+    }
+    fn message(&mut self, kind: u16, flags: u16, attributes: &[Attr]) -> Result<(u32, Vec<u8>)> {
+        let sequence = self.sequence()?;
+        let batch = kind == 16 || kind == 17;
+        let payload = encode_attrs(attributes);
+        if payload.len() > 200_000 {
+            return Err(Error::Invalid);
+        }
+        let mut bytes = Vec::new();
+        bytes.extend(((payload.len() + 20) as u32).to_ne_bytes());
+        bytes.extend(kind.to_ne_bytes());
+        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 { 10_u16 } else { 0 }.to_be_bytes());
+        bytes.extend(payload);
+        Ok((sequence, bytes))
+    }
+    fn send(&self, bytes: &[u8]) -> Result<()> {
+        if bytes.len() > 240_000 {
+            return Err(Error::Invalid);
+        }
+        let mut address: libc::sockaddr_nl = unsafe { std::mem::zeroed() };
+        address.nl_family = libc::AF_NETLINK as u16;
+        let written = unsafe {
+            libc::sendto(
+                self.fd.as_raw_fd(),
+                bytes.as_ptr().cast(),
+                bytes.len(),
+                0,
+                (&address as *const libc::sockaddr_nl).cast(),
+                std::mem::size_of_val(&address) as _,
+            )
+        };
+        if written < 0 || written as usize != bytes.len() {
+            return Err(Error::Unavailable);
+        }
+        Ok(())
+    }
+    fn receive(&self, until: Instant) -> Result<Vec<Message>> {
+        let remaining = until.saturating_duration_since(Instant::now()).as_millis();
+        if remaining == 0 {
+            return Err(Error::Unavailable);
+        }
+        let mut poll = libc::pollfd {
+            fd: self.fd.as_raw_fd(),
+            events: libc::POLLIN,
+            revents: 0,
+        };
+        if unsafe { libc::poll(&mut poll, 1, remaining.min(3000) as i32) } <= 0 {
+            return Err(Error::Unavailable);
+        }
+        let mut bytes = vec![0_u8; 262_144];
+        let mut address: libc::sockaddr_nl = unsafe { std::mem::zeroed() };
+        let mut length = std::mem::size_of_val(&address) as libc::socklen_t;
+        let received = unsafe {
+            libc::recvfrom(
+                self.fd.as_raw_fd(),
+                bytes.as_mut_ptr().cast(),
+                bytes.len(),
+                libc::MSG_TRUNC,
+                (&mut address as *mut libc::sockaddr_nl).cast(),
+                &mut length,
+            )
+        };
+        if received < 0 || received as usize > bytes.len() || address.nl_pid != 0 {
+            return Err(Error::Protocol);
+        }
+        bytes.truncate(received as usize);
+        let mut offset = 0;
+        let mut result = Vec::new();
+        while offset < bytes.len() {
+            if bytes.len() - offset < 16 {
+                return Err(Error::Protocol);
+            }
+            let header = &bytes[offset..offset + 16];
+            let size = u32::from_ne_bytes(header[..4].try_into().unwrap()) as usize;
+            if size < 16 || offset + size > bytes.len() {
+                return Err(Error::Protocol);
+            }
+            result.push(Message {
+                kind: u16::from_ne_bytes(header[4..6].try_into().unwrap()),
+                flags: u16::from_ne_bytes(header[6..8].try_into().unwrap()),
+                sequence: u32::from_ne_bytes(header[8..12].try_into().unwrap()),
+                payload: bytes[offset + 16..offset + size].to_vec(),
+            });
+            offset += (size + 3) & !3;
+        }
+        Ok(result)
+    }
+    pub fn query(
+        &mut self,
+        operation: u16,
+        input: Vec<Attr>,
+        dump: bool,
+    ) -> Result<Vec<Vec<Attr>>> {
+        let (sequence, bytes) =
+            self.message(0x0a00 | operation, 1 | if dump { 0x300 } else { 0 }, &input)?;
+        self.send(&bytes)?;
+        let until = Instant::now() + Duration::from_secs(3);
+        let mut result = Vec::new();
+        let mut total = 0;
+        loop {
+            for message in self.receive(until)? {
+                if message.sequence != sequence {
+                    continue;
+                }
+                if message.flags & 0x10 != 0 {
+                    return Err(Error::Conflict);
+                }
+                if message.kind == 2 {
+                    let code = i32::from_ne_bytes(
+                        message
+                            .payload
+                            .get(..4)
+                            .ok_or(Error::Protocol)?
+                            .try_into()
+                            .unwrap(),
+                    );
+                    if code != 0 {
+                        return Err(Error::kernel(code));
+                    }
+                } else if message.kind == 3 {
+                    if message.payload.len() >= 4
+                        && i32::from_ne_bytes(message.payload[..4].try_into().unwrap()) != 0
+                    {
+                        return Err(Error::Conflict);
+                    }
+                    return Ok(result);
+                } else if message.kind & 0xff00 == 0x0a00 {
+                    total += message.payload.len();
+                    if total > 2_097_152 || result.len() >= 4096 || message.payload.len() < 4 {
+                        return Err(Error::Protocol);
+                    }
+                    result.push(attrs(&message.payload[4..])?);
+                    if !dump {
+                        return Ok(result);
+                    }
+                } else {
+                    return Err(Error::Protocol);
+                }
+            }
+        }
+    }
+    pub fn generation(&mut self) -> Result<u32> {
+        let values = self.query(16, vec![], false)?;
+        let generation = number(values.first().ok_or(Error::Protocol)?, 1)?;
+        if generation == 0 {
+            return Err(Error::Protocol);
+        }
+        Ok(generation)
+    }
+    pub fn batch(&mut self, generation: u32, operations: Vec<(u16, u16, Vec<Attr>)>) -> Result<()> {
+        if generation == 0 || operations.len() > 2048 {
+            return Err(Error::Invalid);
+        }
+        let (first, mut bytes) = self.message(16, 1 | 4, &[Attr::u32(1, generation)])?;
+        for (kind, flags, attributes) in operations {
+            bytes.extend(self.message(0x0a00 | kind, flags | 1 | 4, &attributes)?.1);
+        }
+        let (last, end) = self.message(17, 1 | 4, &[])?;
+        bytes.extend(end);
+        self.send(&bytes)?;
+        let until = Instant::now() + Duration::from_secs(3);
+        loop {
+            for message in self.receive(until)? {
+                if message.sequence < first || message.sequence > last {
+                    continue;
+                }
+                if message.kind != 2 || message.payload.len() < 4 {
+                    return Err(Error::Protocol);
+                }
+                let code = i32::from_ne_bytes(message.payload[..4].try_into().unwrap());
+                if code != 0 {
+                    return Err(Error::kernel(code));
+                }
+                if message.sequence == last {
+                    return Ok(());
+                }
+            }
+        }
+    }
+}

package/scripts/check-native-notices.mjs

@@ -0,0 +1,27 @@
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { resolve, relative } from 'node:path';
+
+const root = resolve(import.meta.dirname, '..');
+const notices = resolve(root, 'native-notices');
+const manifest = JSON.parse(readFileSync(resolve(notices, 'manifest.json'), 'utf8'));
+const digest = (path) => createHash('sha256').update(readFileSync(path)).digest('hex');
+const requireEqual = (actual, expected, label) => {
+  if (actual !== expected) throw new Error(`Native notice inventory mismatch: ${label}; refresh and review notices before distribution.`);
+};
+requireEqual(digest(resolve(root, 'rust/Cargo.lock')), manifest.cargoLockSha256, 'Cargo.lock');
+requireEqual(execFileSync('rustc', ['-vV'], { encoding: 'utf8' }).trim(), manifest.rustc, 'Rust compiler');
+const sysroot = execFileSync('rustc', ['--print', 'sysroot'], { encoding: 'utf8' }).trim();
+requireEqual(digest(resolve(sysroot, 'share/doc/rust/COPYRIGHT.html')), manifest.toolchainCopyrightSha256, 'toolchain copyright');
+for (const [name, hash] of Object.entries(manifest.noticeHashes)) {
+  const path = resolve(notices, name);
+  if (relative(notices, path).startsWith('..')) throw new Error('Invalid notice inventory path.');
+  requireEqual(digest(path), hash, name);
+}
+for (const [name, hash] of Object.entries(manifest.runtimeArtifactHashes)) {
+  const path = resolve(sysroot, name);
+  if (relative(sysroot, path).startsWith('..')) throw new Error('Invalid runtime inventory path.');
+  requireEqual(digest(path), hash, name);
+}
+console.log('Native notices match the locked crates and qualified Rust runtime artifacts.');

package/ts/00_commitinfo_data.ts

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

package/ts/classes.managednftables.ts

@@ -0,0 +1,153 @@
+import * as plugins from './plugins.js';
+import type { IManagedNftOptions, IManagedNftPolicy, IManagedNftTransition, IAppliedManagedNftPolicy,
+  IPreparedManagedNftPolicy, IManagedNftStatus, TManagedNftCommands } 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 {
+  let count = 0;
+  let stringBytes = 0;
+  const string = (value: string): string => {
+    if (value.length > 240_000 || (stringBytes += Buffer.byteLength(value)) > 240_000) throw new ManagedNftablesError('INVALID');
+    return value;
+  };
+  const copy = (value: unknown, depth: number): unknown => {
+    if (++count > 16_384 || depth > 20) throw new ManagedNftablesError('INVALID');
+    if (typeof value === 'string') return string(value);
+    if (value === null || typeof value === 'boolean') return value;
+    if (typeof value === 'number' && Number.isSafeInteger(value)) return value;
+    if (typeof value !== 'object' || plugins.util.types.isProxy(value)) throw new ManagedNftablesError('INVALID');
+    const array = Array.isArray(value);
+    if (Object.getPrototypeOf(value) !== (array ? Array.prototype : Object.prototype)) throw new ManagedNftablesError('INVALID');
+    const keys = Reflect.ownKeys(value);
+    if (keys.length > 16_384 - count) throw new ManagedNftablesError('INVALID');
+    for (const key of keys) if (typeof key === 'string') string(key);
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    const result: Record<string, unknown> | unknown[] = array ? [] : {};
+    if (array && keys.length !== (value as unknown[]).length + 1) throw new ManagedNftablesError('INVALID');
+    for (const key of keys) {
+      if (array && key === 'length') continue;
+      const descriptor = descriptors[key as string];
+      if (typeof key !== 'string' || !descriptor.enumerable || !('value' in descriptor)
+        || array && !/^(0|[1-9][0-9]*)$/.test(key)) throw new ManagedNftablesError('INVALID');
+      Object.defineProperty(result, key, { value: copy(descriptor.value, depth + 1), enumerable: true, configurable: true, writable: true });
+    }
+    return result;
+  };
+  const result = copy(input, 0) as T;
+  if (Buffer.byteLength(JSON.stringify(result)) > 240_000) throw new ManagedNftablesError('INVALID');
+  return result;
+}
+
+/** One private native/netlink owner. Persistence and workload link lifetimes belong to its caller. */
+export class ManagedNftables {
+  readonly #options: Readonly<IManagedNftOptions>;
+  #bridge: plugins.smartrust.RustBridge<TManagedNftCommands> | 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: IManagedNftOptions) {
+    this.#options = snapshot(options);
+    if (Object.keys(this.#options).some((key) => !['ownerId', 'instanceId', 'tableName', 'binaryPath', 'networkNamespaceFd'].includes(key))
+      || ![this.#options.ownerId, this.#options.instanceId, this.#options.tableName].every((value) => typeof value === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(value))
+      || this.#options.instanceId.length < 16 || !this.#options.tableName.startsWith('snft_')
+      || 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<IManagedNftStatus> {
+    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>({
+        binaryName: 'smartnftables', binaryPath: this.#options.binaryPath
+          ?? plugins.path.join(root, 'dist_rust', `smartnftables_linux_${process.arch === 'x64' ? 'amd64' : 'arm64'}_musl`),
+        localPaths: [], searchSystemPath: false,
+        cliArgs: ['--management', ...(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: { preparePolicy: 1, openOwner: 1, reconcilePolicy: 1, inspectPolicy: 1, releasePolicy: 1, closeOwner: 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, tableName } = this.#options;
+      const status = snapshot(await this.#bridge.sendCommand('openOwner', { ownerId, instanceId, tableName }));
+      if (this.#state !== 'starting') throw new ManagedNftablesError('UNAVAILABLE');
+      this.#state = 'ready'; return status;
+    })();
+    return this.#track(work);
+  }
+
+  public prepare(policy: IManagedNftPolicy): Promise<IPreparedManagedNftPolicy> {
+    return this.#invoke('preparePolicy', policy);
+  }
+  public reconcile(transition: IManagedNftTransition): Promise<IAppliedManagedNftPolicy> {
+    return this.#invoke('reconcilePolicy', transition);
+  }
+  public inspect(): Promise<IManagedNftStatus> { return this.#invoke('inspectPolicy', {}); }
+  public release(expected: IAppliedManagedNftPolicy): Promise<{ released: true }> {
+    return this.#invoke('releasePolicy', expected);
+  }
+
+  /** Join policy operations and owned-table deletion, then native termination; packet/allocation fencing belongs to the caller. */
+  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('closeOwner', {});
+          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 TManagedNftCommands>(method: K, params: TManagedNftCommands[K]['params']): Promise<TManagedNftCommands[K]['result']> {
+    if (!['ready', 'failed-owned'].includes(this.#state) || !this.#bridge || this.#work) return Promise.reject(new ManagedNftablesError('UNAVAILABLE'));
+    let captured: TManagedNftCommands[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';
+      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/index.ts

@@ -1,5 +1,7 @@
 // Main facade
 export { SmartNftables } from './nft.manager.js';
+export { ManagedNftables, ManagedNftablesError } from './classes.managednftables.js';
+export type * from './managed.types.js';
 
 // Sub-managers
 export { NatManager } from './nft.manager.nat.js';