@push.rocks/smartnftables 1.3.1 → 1.5.0

package/ts/classes.managednftables.ts

@@ -1,6 +1,6 @@
 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}.`); }
@@ -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;
@@ -53,27 +53,32 @@ export class ManagedNftables {
 
   constructor(options: IManagedNftOptions) {
     this.#options = snapshot(options);
-    if (Object.keys(this.#options).some((key) => !['ownerId', 'instanceId', 'tableName', 'binaryPath'].includes(key))
+    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> {
+  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, cliArgs: ['--management'],
+        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 },
       });
@@ -89,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);
   }
 
@@ -122,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';

package/ts/managed.egress.types.ts

@@ -0,0 +1,85 @@
+import type { IManagedNftEndpoint, IManagedNftRule } from './managed.types.js';
+
+/** Namespace-local facts, checked through rtnetlink. The caller retains actual link-generation ownership. */
+export interface IManagedNftLocalLinkV2 {
+  interfaceIndex: number;
+  interfaceName: string;
+  interfaceKind: 'veth' | 'tun' | 'ethernet';
+  /** Canonical unicast Ethernet address, or null for an L3 TUN. */
+  macAddress: string | null;
+  interfaceLinkIndex: number;
+  requiredIpv4Addresses: string[];
+}
+
+export interface IManagedNftPlatformEndpointV2 {
+  id: string;
+  address: string;
+  protocol: 'tcp' | 'udp';
+  port: number;
+}
+
+/** Caller-authenticated complete protected authority; hashing does not attest completeness. */
+export interface IManagedNftProtectionV2 {
+  authorityDigest: string;
+  prefixes: string[];
+  platformEndpoints: IManagedNftPlatformEndpointV2[];
+}
+
+export interface IManagedNftHandoffPortRangeV2 {
+  protocol: 'tcp' | 'udp';
+  first: number;
+  last: number;
+}
+
+export interface IManagedNftHandoffAllocationV2 {
+  lease: { id: string; generation: number; digest: string };
+  transitSourceAddress: string;
+  sourcePortRanges: IManagedNftHandoffPortRangeV2[];
+}
+
+export interface IManagedNftEgressGrantV2 {
+  /** A workload veth endpoint, or the actual router-local host for DNS/relay sockets. */
+  sourceEndpoint: string | null;
+  sourcePrefix: string;
+  destination: { kind: 'public'; prefix: string } | { kind: 'platform'; endpointId: string };
+  protocol: 'tcp' | 'udp';
+  sourcePort: number | null;
+  destinationPort: number | null;
+  /** One exact range from this generation's lease; selects the SNAT range for this grant. */
+  sourcePortRange: { first: number; last: number };
+}
+
+export interface IManagedNftEgressGenerationV2 extends IManagedNftHandoffAllocationV2 {
+  conntrackZone: number;
+  conntrackLabel: string;
+  grants: IManagedNftEgressGrantV2[];
+}
+
+/** One combined private/TUN/local/egress table; never compose a second ACCEPT over v1 terminal drops. */
+export interface IManagedNftRouterEgressScopeV2 {
+  kind: 'routerEgress';
+  endpoints: IManagedNftEndpoint[];
+  rules: IManagedNftRule[];
+  /** One exact local binding for every private endpoint. */
+  links: IManagedNftLocalLinkV2[];
+  handoff: IManagedNftLocalLinkV2;
+  protection: IManagedNftProtectionV2;
+  /** Empty retains private/local enforcement while denying external egress. */
+  generations: IManagedNftEgressGenerationV2[];
+}
+
+/** Shared-host capture barrier and explicit outer SNAT; Docker forwarding remains a separate owner. */
+export interface IManagedNftHostTransitScopeV2 {
+  kind: 'hostTransit';
+  protection: IManagedNftProtectionV2;
+  handoffs: Array<{ link: IManagedNftLocalLinkV2; allocations: IManagedNftHandoffAllocationV2[] }>;
+  uplink: IManagedNftLocalLinkV2;
+  /** Exact current address present on uplink. No masquerade or default-route inference. */
+  snatAddress: string;
+}
+
+export interface IManagedNftPolicyV2 {
+  schemaVersion: 2;
+  revision: number;
+  scope: IManagedNftRouterEgressScopeV2 | IManagedNftHostTransitScopeV2;
+}

package/ts/managed.types.ts

@@ -1,3 +1,5 @@
+import type { IManagedNftPolicyV2 } from './managed.egress.types.js';
+
 /** The caller owns these workload links and keeps them disabled until apply is confirmed. */
 export interface IManagedNftEndpoint {
   id: string;
@@ -26,8 +28,8 @@ export interface IManagedNftPolicy {
   rules: IManagedNftRule[];
 }
 
-export interface IPreparedManagedNftPolicy {
-  policy: IManagedNftPolicy;
+export interface IPreparedManagedNftPolicy<TPolicy extends TManagedNftPolicy = IManagedNftPolicy> {
+  policy: TPolicy;
   digest: string;
 }
 
@@ -47,23 +49,23 @@ export interface IManagedNftReceipt {
   digest: string;
 }
 
-export interface IAppliedManagedNftPolicy {
+export interface IAppliedManagedNftPolicy<TPolicy extends TManagedNftPolicy = IManagedNftPolicy> {
   receipt: IManagedNftReceipt;
-  prepared: IPreparedManagedNftPolicy;
+  prepared: IPreparedManagedNftPolicy<TPolicy>;
 }
 
 /** Persist this complete command before reconcile, then retain its complete result. */
-export interface IManagedNftTransition {
-  previous: IAppliedManagedNftPolicy | null;
-  target: IPreparedManagedNftPolicy;
+export interface IManagedNftTransition<TPolicy extends TManagedNftPolicy = IManagedNftPolicy> {
+  previous: IAppliedManagedNftPolicy<TPolicy> | null;
+  target: IPreparedManagedNftPolicy<TPolicy>;
 }
 
-export interface IManagedNftStatus {
+export interface IManagedNftStatus<TPolicy extends TManagedNftPolicy = IManagedNftPolicy> {
   identity: IManagedNftIdentity;
   state: 'idle' | 'applied' | 'failed-owned' | 'released';
   enforced: boolean;
-  applied: IAppliedManagedNftPolicy | null;
-  pending: IManagedNftTransition | null;
+  applied: IAppliedManagedNftPolicy<TPolicy> | null;
+  pending: IManagedNftTransition<TPolicy> | null;
   error: string | null;
 }
 
@@ -75,13 +77,19 @@ export interface IManagedNftOptions {
   tableName: string;
   /** Explicit executable selection for qualified distributions and isolated tests. */
   binaryPath?: string;
+  /** Linux network namespace descriptor, owned by the caller and valid through start().
+   * The native process enters before readiness or netlink activity. Keep a namespace
+   * owner alive for policy lifetime and recovery; this process option is not durable authority. */
+  networkNamespaceFd?: number;
 }
 
-export type TManagedNftCommands = {
-  preparePolicy: { params: IManagedNftPolicy; result: IPreparedManagedNftPolicy };
-  openOwner: { params: Omit<IManagedNftOptions, 'binaryPath'>; result: IManagedNftStatus };
-  reconcilePolicy: { params: IManagedNftTransition; result: IAppliedManagedNftPolicy };
-  inspectPolicy: { params: Record<string, never>; result: IManagedNftStatus };
-  releasePolicy: { params: IAppliedManagedNftPolicy; result: { released: true } };
+export type TManagedNftPolicy = IManagedNftPolicy | IManagedNftPolicyV2;
+
+export type TManagedNftCommands<TPolicy extends TManagedNftPolicy = IManagedNftPolicy> = {
+  preparePolicy: { params: TPolicy; result: IPreparedManagedNftPolicy<TPolicy> };
+  openOwner: { params: Pick<IManagedNftOptions, 'ownerId' | 'instanceId' | 'tableName'>; result: IManagedNftStatus<TPolicy> };
+  reconcilePolicy: { params: IManagedNftTransition<TPolicy>; result: IAppliedManagedNftPolicy<TPolicy> };
+  inspectPolicy: { params: Record<string, never>; result: IManagedNftStatus<TPolicy> };
+  releasePolicy: { params: IAppliedManagedNftPolicy<TPolicy>; result: { released: true } };
   closeOwner: { params: Record<string, never>; result: { released: true } };
 };