@push.rocks/smartnftables 1.5.0 → 1.7.0

package/rust/src/owner_poolguard_tests.rs

@@ -0,0 +1,265 @@
+use super::egress_traffic_tests::{connect, ns_ip, roundtrip, socket};
+use super::host_traffic_tests::{immediate, payload};
+use super::*;
+use crate::{
+    egress,
+    policy::{expr, meta},
+};
+use serde_json::json;
+use std::net::{SocketAddr, UdpSocket};
+use std::time::Duration;
+
+const SOURCE: &str = "pg_source";
+const HOST: &str = "pg_host";
+const PEER: &str = "pg_peer";
+
+#[test]
+#[ignore = "requires disposable isolated native qualification guest"]
+fn allocation_pool_guard_maximum_graph_persist_and_lost_ack_recovery() {
+    isolated();
+    let mut policy = egress::tests::pool_guard();
+    policy["scope"]["prefixes"] = json!((0..64)
+        .map(|part| format!("10.{part}.0.0/16"))
+        .collect::<Vec<_>>());
+    super::egress_tests::recover("pools_v2", serde_json::from_value(policy).unwrap());
+}
+
+// Foreign capture controls exist only in this offline guest. They are never
+// composed into or removed with the managed policy under test.
+fn foreign_captures() {
+    let table = "snft_foreign_pool_capture";
+    let mut operations = vec![(0, 0x600, vec![Attr::string(1, table), Attr::u32(2, 6)])];
+    for (chain, hook, priority, kind) in [
+        ("raw_pre", 0, -300_i32, "filter"),
+        ("raw_out", 3, -300, "filter"),
+        ("pre", 0, -100, "nat"),
+        ("out", 3, -100, "nat"),
+    ] {
+        operations.push((
+            3,
+            0x600,
+            vec![
+                Attr::string(1, table),
+                Attr::string(3, chain),
+                Attr::nested(4, vec![Attr::u32(1, hook), Attr::u32(2, priority as u32)]),
+                Attr::u32(5, 1),
+                Attr::string(7, kind),
+                Attr::u32(10, 1),
+            ],
+        ));
+    }
+    let mut rule = |chain: &str, expressions| {
+        operations.push((
+            6,
+            0xc00,
+            vec![
+                Attr::string(1, table),
+                Attr::string(2, chain),
+                Attr::nested(4, expressions),
+            ],
+        ))
+    };
+    for chain in ["raw_pre", "raw_out"] {
+        let mut expressions = meta(16, vec![17]);
+        expressions.extend(payload(2, 44003_u16.to_be_bytes().to_vec(), true));
+        expressions.push(expr("notrack", vec![]));
+        rule(chain, expressions);
+    }
+    for chain in ["pre", "out"] {
+        for (port, destination, target) in [
+            (44001_u16, [10, 250, 0, 2], [203, 0, 113, 2]),
+            (44002, [203, 0, 113, 2], [10, 250, 0, 2]),
+            (44004, [10, 250, 0, 2], [192, 0, 2, 2]),
+            (44005, [203, 0, 113, 2], [10, 241, 0, 1]),
+        ] {
+            let mut expressions = meta(16, vec![17]);
+            expressions.extend(payload(16, destination.to_vec(), false));
+            expressions.extend(payload(2, port.to_be_bytes().to_vec(), true));
+            expressions.push(immediate(target.to_vec()));
+            expressions.push(expr(
+                "nat",
+                vec![
+                    Attr::u32(1, 1),
+                    Attr::u32(2, 2),
+                    Attr::u32(3, 1),
+                    Attr::u32(4, 1),
+                    Attr::u32(7, 1),
+                ],
+            ));
+            rule(chain, expressions);
+        }
+    }
+    let mut socket = wire::Socket::open().unwrap();
+    let generation = socket.generation().unwrap();
+    socket.batch(generation, operations).unwrap();
+}
+
+fn bound(namespace: &str, address: &str) -> UdpSocket {
+    let address = address.to_owned();
+    let socket = in_namespace(namespace, move || UdpSocket::bind(address).unwrap());
+    socket
+        .set_read_timeout(Some(Duration::from_millis(250)))
+        .unwrap();
+    socket
+}
+fn probe(
+    source: &UdpSocket,
+    destination: &str,
+    target: &UdpSocket,
+    allowed: bool,
+    local: bool,
+) -> Option<SocketAddr> {
+    let result = source.send_to(b"probe", destination);
+    if !allowed && local {
+        assert_eq!(
+            result.unwrap_err().raw_os_error(),
+            Some(libc::EPERM),
+            "{destination}"
+        );
+    } else {
+        assert_eq!(result.unwrap(), 5, "{destination}");
+    }
+    match target.recv_from(&mut [0; 64]) {
+        Ok((size, sender)) => {
+            assert!(allowed, "unexpected packet to {destination}");
+            assert_eq!(size, 5);
+            Some(sender)
+        }
+        Err(error) => {
+            assert!(!allowed, "missing packet to {destination}: {error}");
+            assert!(matches!(
+                error.kind(),
+                std::io::ErrorKind::WouldBlock | std::io::ErrorKind::TimedOut
+            ));
+            None
+        }
+    }
+}
+
+#[test]
+#[ignore = "requires disposable isolated native qualification guest"]
+fn allocation_pool_guard_covers_all_host_hooks_dnat_untracked_and_reply_direction() {
+    isolated();
+    for name in [SOURCE, HOST, PEER] {
+        ip(&["netns", "add", name]);
+        ns_ip(name, &["link", "set", "lo", "up"]);
+        in_namespace(name, || {
+            std::fs::write("/proc/sys/net/ipv4/ip_forward", "1").unwrap()
+        });
+    }
+    connect(
+        SOURCE,
+        "source",
+        "10.240.0.2/30",
+        HOST,
+        "router",
+        "10.240.0.1/30",
+    );
+    connect(
+        HOST,
+        "uplink",
+        "192.0.2.2/24",
+        PEER,
+        "underlay",
+        "192.0.2.3/24",
+    );
+    ns_ip(SOURCE, &["route", "add", "default", "via", "10.240.0.1"]);
+    ns_ip(PEER, &["route", "add", "default", "via", "192.0.2.2"]);
+    ns_ip(HOST, &["address", "add", "10.241.0.1/32", "dev", "lo"]);
+    for address in ["203.0.113.2", "10.250.0.2"] {
+        ns_ip(
+            PEER,
+            &["address", "add", &format!("{address}/32"), "dev", "lo"],
+        );
+        ns_ip(
+            HOST,
+            &["route", "add", &format!("{address}/32"), "via", "192.0.2.3"],
+        );
+    }
+    in_namespace(HOST, foreign_captures);
+    let source = socket(SOURCE, "10.240.0.2:10000");
+    let host = socket(HOST, "192.0.2.2:10000");
+    let host_pool = socket(HOST, "10.241.0.1:10000");
+    let public = socket(PEER, "203.0.113.2:42000");
+    let lan = socket(PEER, "192.0.2.3:42000");
+    // Controls exercise established flows before apply, plus fresh ones below.
+    roundtrip(&source, &public);
+    roundtrip(&source, &host);
+    roundtrip(&host_pool, &public);
+    roundtrip(&host, &lan);
+    let cases = [
+        ("10.250.0.2:42001", PEER, "10.250.0.2:42001"),
+        ("10.241.0.1:42002", HOST, "10.241.0.1:42002"),
+        ("10.250.0.2:44001", PEER, "203.0.113.2:44001"),
+        ("203.0.113.2:44002", PEER, "10.250.0.2:44002"),
+        ("10.250.0.2:44003", PEER, "10.250.0.2:44003"),
+        ("10.250.0.2:44004", HOST, "192.0.2.2:44004"),
+        ("203.0.113.2:44005", HOST, "10.241.0.1:44005"),
+    ];
+    let targets: Vec<_> = cases
+        .iter()
+        .map(|(_, ns, address)| bound(ns, address))
+        .collect();
+    let mut replies = Vec::new();
+    for ((destination, _, _), target) in cases.iter().zip(&targets) {
+        for sender in [&source, &host] {
+            replies.push(probe(sender, destination, target, true, false).unwrap());
+        }
+    }
+    // INPUT with NOTRACK is independent of OUTPUT/FORWARD controls.
+    let untracked_input = socket(HOST, "10.241.0.1:44003");
+    probe(&lan, "10.241.0.1:44003", &untracked_input, true, false);
+    // A reply to a public original destination can have a pool source before
+    // reverse DNAT in POSTROUTING. Both INPUT and FORWARD must deny that reply.
+    for (sender, receiver) in [(&source, replies[6]), (&host, replies[7])] {
+        targets[3].send_to(b"before", receiver).unwrap();
+        assert_eq!(sender.recv(&mut [0; 64]).unwrap(), 6);
+    }
+    let (owner, applied) = in_namespace(HOST, || {
+        let mut owner = Owner::new(options("pool_traffic")).unwrap();
+        let mut policy = egress::tests::pool_guard();
+        policy["scope"]["prefixes"]
+            .as_array_mut()
+            .unwrap()
+            .push(json!("10.250.0.0/16"));
+        let target = serde_json::from_value::<egress::Policy>(policy)
+            .unwrap()
+            .prepare()
+            .unwrap()
+            .into();
+        let applied = owner
+            .reconcile(Transition {
+                previous: None,
+                target,
+            })
+            .unwrap();
+        assert!(owner.inspect().enforced);
+        (owner, applied)
+    });
+    for ((destination, _, _), target) in cases.iter().zip(&targets) {
+        probe(&source, destination, target, false, false);
+        probe(&host, destination, target, false, true);
+    }
+    probe(&lan, "10.241.0.1:44003", &untracked_input, false, false);
+    for (sender, receiver) in [(&source, replies[6]), (&host, replies[7])] {
+        targets[3].send_to(b"after", receiver).unwrap();
+        assert!(sender.recv(&mut [0; 64]).is_err());
+    }
+    roundtrip(&source, &public);
+    roundtrip(&source, &host);
+    roundtrip(&host_pool, &public);
+    roundtrip(&host, &lan);
+    let fresh = socket(SOURCE, "10.240.0.2:10001");
+    roundtrip(&fresh, &public);
+    in_namespace(HOST, move || {
+        let mut owner = owner;
+        assert!(owner.inspect().enforced);
+        owner.release(applied).unwrap();
+    });
+    // Positive control after release proves the denials were this guard.
+    for ((destination, _, _), target) in cases.iter().zip(&targets) {
+        probe(&source, destination, target, true, false);
+        probe(&host, destination, target, true, false);
+    }
+    println!("POOL_GUARD_PACKET_PROOF input=true forward=true output=true current_dnat=true original_dnat=true untracked=true reply_current_source=true established_and_fresh_public=true management_lan=true release_control=true allocation_reusable=false");
+}

package/rust/src/owner_tests.rs

@@ -21,6 +21,9 @@ mod packet_fixture;
 #[path = "owner_host_traffic_tests.rs"]
 mod host_traffic_tests;
 
+#[path = "owner_poolguard_tests.rs"]
+mod poolguard_tests;
+
 #[path = "owner_coexistence_tests.rs"]
 mod coexistence_tests;
 

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.7.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 } };
+};

package/ts/managed.egress.types.ts

@@ -78,8 +78,17 @@ export interface IManagedNftHostTransitScopeV2 {
   snatAddress: string;
 }
 
+/** Host-wide IPv4 destination denial for caller-authenticated private allocation pools.
+ * This has no link dependency or allow grants. It is not allocation-release or boot-order proof. */
+export interface IManagedNftAllocationPoolGuardScopeV2 {
+  kind: 'allocationPoolGuard';
+  authorityDigest: string;
+  /** Complete current pool list: 1–64 canonical, disjoint RFC1918 prefixes. */
+  prefixes: string[];
+}
+
 export interface IManagedNftPolicyV2 {
   schemaVersion: 2;
   revision: number;
-  scope: IManagedNftRouterEgressScopeV2 | IManagedNftHostTransitScopeV2;
+  scope: IManagedNftRouterEgressScopeV2 | IManagedNftHostTransitScopeV2 | IManagedNftAllocationPoolGuardScopeV2;
 }