@push.rocks/smartnftables 1.0.1

package/ts/nft.manager.nat.ts

@@ -0,0 +1,76 @@
+import type { SmartNftables } from './nft.manager.js';
+import type { INftDnatRule, INftSnatRule, INftMasqueradeRule, TNftProtocol } from './nft.types.js';
+import { buildDnatRules, buildSnatRule, buildMasqueradeRule } from './nft.rulebuilder.nat.js';
+
+/**
+ * Manages NAT (DNAT/SNAT/masquerade) rules.
+ */
+export class NatManager {
+  constructor(private parent: SmartNftables) {}
+
+  /**
+   * Add a port forwarding rule (DNAT + optional masquerade).
+   */
+  public async addPortForwarding(groupId: string, rule: INftDnatRule): Promise<void> {
+    const commands = buildDnatRules(this.parent.tableName, this.parent.family, rule);
+    await this.parent.applyRuleGroup(`nat:${groupId}`, commands);
+  }
+
+  /**
+   * Remove a previously added port forwarding group.
+   */
+  public async removePortForwarding(groupId: string): Promise<void> {
+    await this.parent.removeRuleGroup(`nat:${groupId}`);
+  }
+
+  /**
+   * Add SNAT (source NAT) rule.
+   */
+  public async addSnat(groupId: string, rule: INftSnatRule): Promise<void> {
+    const commands = buildSnatRule(this.parent.tableName, this.parent.family, rule);
+    await this.parent.applyRuleGroup(`nat:snat:${groupId}`, commands);
+  }
+
+  /**
+   * Add masquerade rule for outgoing traffic.
+   */
+  public async addMasquerade(groupId: string, rule: INftMasqueradeRule): Promise<void> {
+    const commands = buildMasqueradeRule(this.parent.tableName, this.parent.family, rule);
+    await this.parent.applyRuleGroup(`nat:masq:${groupId}`, commands);
+  }
+
+  /**
+   * Add port forwarding for a range of ports.
+   * Maps sourceStart..sourceStart+count to targetStart..targetStart+count.
+   */
+  public async addPortRange(
+    groupId: string,
+    sourceStart: number,
+    sourceEnd: number,
+    targetHost: string,
+    targetStart: number,
+    protocol?: TNftProtocol,
+  ): Promise<void> {
+    const allCommands: string[] = [];
+    const count = sourceEnd - sourceStart;
+
+    for (let i = 0; i <= count; i++) {
+      const commands = buildDnatRules(this.parent.tableName, this.parent.family, {
+        sourcePort: sourceStart + i,
+        targetHost,
+        targetPort: targetStart + i,
+        protocol,
+      });
+      allCommands.push(...commands);
+    }
+
+    await this.parent.applyRuleGroup(`nat:range:${groupId}`, allCommands);
+  }
+
+  /**
+   * Remove a port range forwarding group.
+   */
+  public async removePortRange(groupId: string): Promise<void> {
+    await this.parent.removeRuleGroup(`nat:range:${groupId}`);
+  }
+}

package/ts/nft.manager.ratelimit.ts

@@ -0,0 +1,43 @@
+import type { SmartNftables } from './nft.manager.js';
+import type { INftRateLimitRule, INftConnectionRateRule } from './nft.types.js';
+import { buildRateLimitRule, buildConnectionRateRule } from './nft.rulebuilder.ratelimit.js';
+
+/**
+ * Manages rate limiting rules using nft meters and limit expressions.
+ */
+export class RateLimitManager {
+  constructor(private parent: SmartNftables) {}
+
+  /**
+   * Add a rate limit rule (global or per-IP).
+   */
+  public async addRateLimit(groupId: string, rule: INftRateLimitRule): Promise<void> {
+    await this.parent.ensureFilterChains();
+    const commands = buildRateLimitRule(this.parent.tableName, this.parent.family, rule);
+    await this.parent.applyRuleGroup(`ratelimit:${groupId}`, commands);
+  }
+
+  /**
+   * Remove a rate limit rule group.
+   */
+  public async removeRateLimit(groupId: string): Promise<void> {
+    await this.parent.removeRuleGroup(`ratelimit:${groupId}`);
+  }
+
+  /**
+   * Add a new-connection rate limit rule.
+   * Limits the rate of new TCP/UDP connections (ct state new).
+   */
+  public async addConnectionRateLimit(groupId: string, rule: INftConnectionRateRule): Promise<void> {
+    await this.parent.ensureFilterChains();
+    const commands = buildConnectionRateRule(this.parent.tableName, this.parent.family, rule);
+    await this.parent.applyRuleGroup(`connrate:${groupId}`, commands);
+  }
+
+  /**
+   * Remove a connection rate limit rule group.
+   */
+  public async removeConnectionRateLimit(groupId: string): Promise<void> {
+    await this.parent.removeRuleGroup(`connrate:${groupId}`);
+  }
+}

package/ts/nft.manager.ts

@@ -0,0 +1,157 @@
+import { NftExecutor } from './nft.executor.js';
+import { buildTableSetup, buildFilterChains, buildTableCleanup } from './nft.rulebuilder.table.js';
+import { NatManager } from './nft.manager.nat.js';
+import { FirewallManager } from './nft.manager.firewall.js';
+import { RateLimitManager } from './nft.manager.ratelimit.js';
+import type { TNftFamily, INftRuleGroup, INftStatus, ISmartNftablesOptions } from './nft.types.js';
+
+/**
+ * SmartNftables — high-level facade for managing nftables rules.
+ *
+ * Provides sub-managers for NAT, firewall, and rate limiting.
+ * All rules are tracked in logical groups and can be removed individually or cleaned up entirely.
+ */
+export class SmartNftables {
+  public readonly nat: NatManager;
+  public readonly firewall: FirewallManager;
+  public readonly rateLimit: RateLimitManager;
+
+  public readonly tableName: string;
+  public readonly family: TNftFamily;
+  public readonly executor: NftExecutor;
+
+  private initialized = false;
+  private hasFilterChains = false;
+  private warnedNonRoot = false;
+  private ruleGroups: Map<string, INftRuleGroup> = new Map();
+
+  constructor(options?: ISmartNftablesOptions) {
+    this.tableName = options?.tableName ?? 'smartnftables';
+    this.family = options?.family ?? 'ip';
+    this.executor = new NftExecutor({ dryRun: options?.dryRun });
+
+    this.nat = new NatManager(this);
+    this.firewall = new FirewallManager(this);
+    this.rateLimit = new RateLimitManager(this);
+  }
+
+  /**
+   * Initialize the nftables table and NAT chains. Idempotent.
+   */
+  public async initialize(): Promise<void> {
+    if (this.initialized) return;
+
+    if (!this.executor.isRoot()) {
+      if (!this.warnedNonRoot) {
+        console.warn('smartnftables: not running as root. Rules are tracked but not applied to kernel.');
+        this.warnedNonRoot = true;
+      }
+      this.initialized = true;
+      return;
+    }
+
+    const commands = buildTableSetup(this.tableName, this.family);
+    await this.executor.execBatch(commands);
+    this.initialized = true;
+  }
+
+  /**
+   * Ensure filter chains (input/forward/output) are created.
+   * Called automatically when firewall or rate-limit rules are added.
+   */
+  public async ensureFilterChains(): Promise<void> {
+    if (this.hasFilterChains) return;
+    await this.ensureInitialized();
+
+    if (this.executor.isRoot()) {
+      const commands = buildFilterChains(this.tableName, this.family);
+      await this.executor.execBatch(commands);
+    }
+
+    this.hasFilterChains = true;
+  }
+
+  /**
+   * Ensure the table is initialized before applying rules.
+   */
+  public async ensureInitialized(): Promise<void> {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+  }
+
+  /**
+   * Apply a group of nft commands and track them under the given ID.
+   */
+  public async applyRuleGroup(groupId: string, commands: string[]): Promise<void> {
+    // Always track the group locally
+    this.ruleGroups.set(groupId, {
+      id: groupId,
+      commands,
+      createdAt: Date.now(),
+    });
+
+    if (!this.executor.isRoot()) {
+      if (!this.warnedNonRoot) {
+        console.warn('smartnftables: not running as root. Rules are tracked but not applied to kernel.');
+        this.warnedNonRoot = true;
+      }
+      return;
+    }
+
+    await this.ensureInitialized();
+    await this.executor.execBatch(commands);
+  }
+
+  /**
+   * Remove a tracked rule group. Removes from tracking.
+   * Note: full kernel cleanup requires cleanup() — individual rule removal
+   * would require handle-based tracking.
+   */
+  public async removeRuleGroup(groupId: string): Promise<void> {
+    this.ruleGroups.delete(groupId);
+  }
+
+  /**
+   * Get a tracked rule group by ID.
+   */
+  public getRuleGroup(groupId: string): INftRuleGroup | undefined {
+    return this.ruleGroups.get(groupId);
+  }
+
+  /**
+   * Delete the entire nftables table and clear all tracking.
+   */
+  public async cleanup(): Promise<void> {
+    if (this.executor.isRoot() && this.initialized) {
+      const commands = buildTableCleanup(this.tableName, this.family);
+      await this.executor.execBatch(commands, { continueOnError: true });
+    }
+
+    this.ruleGroups.clear();
+    this.initialized = false;
+    this.hasFilterChains = false;
+  }
+
+  /**
+   * Get status report of the managed nftables state.
+   */
+  public status(): INftStatus {
+    const groups: Record<string, { ruleCount: number; createdAt: number }> = {};
+    for (const [id, group] of this.ruleGroups) {
+      groups[id] = {
+        ruleCount: group.commands.length,
+        createdAt: group.createdAt,
+      };
+    }
+
+    return {
+      initialized: this.initialized,
+      tableName: this.tableName,
+      family: this.family,
+      isRoot: this.executor.isRoot(),
+      activeGroups: this.ruleGroups.size,
+      groups,
+    };
+  }
+}

package/ts/nft.rulebuilder.firewall.ts

@@ -0,0 +1,173 @@
+import type { TNftFamily, INftFirewallRule, INftIPSetConfig } from './nft.types.js';
+
+/**
+ * Build an nft firewall rule for input/output/forward chains.
+ */
+export function buildFirewallRule(
+  tableName: string,
+  family: TNftFamily,
+  rule: INftFirewallRule,
+): string[] {
+  const chain = rule.direction;
+  const parts: string[] = [`nft add rule ${family} ${tableName} ${chain}`];
+
+  // Connection tracking states
+  if (rule.ctStates && rule.ctStates.length > 0) {
+    parts.push(`ct state { ${rule.ctStates.join(', ')} }`);
+  }
+
+  // Protocol and port matching
+  const protocols = expandProtocols(rule.protocol);
+  const commands: string[] = [];
+
+  for (const proto of protocols) {
+    const ruleParts = [...parts];
+
+    if (rule.protocol) {
+      ruleParts.push(proto);
+    }
+
+    if (rule.sourceIP) {
+      ruleParts.push(`ip saddr ${rule.sourceIP}`);
+    }
+
+    if (rule.destIP) {
+      ruleParts.push(`ip daddr ${rule.destIP}`);
+    }
+
+    if (rule.sourcePort != null) {
+      ruleParts.push(`${proto} sport ${rule.sourcePort}`);
+    }
+
+    if (rule.destPort != null) {
+      // If protocol wasn't explicitly set but we have a port, we need the protocol
+      if (!rule.protocol) {
+        ruleParts.push(`tcp dport ${rule.destPort}`);
+      } else {
+        ruleParts.push(`${proto} dport ${rule.destPort}`);
+      }
+    }
+
+    if (rule.comment) {
+      ruleParts.push(`comment "${rule.comment}"`);
+    }
+
+    ruleParts.push(rule.action);
+    commands.push(ruleParts.join(' '));
+  }
+
+  // If no protocol expansion needed (no protocol-specific fields)
+  if (commands.length === 0) {
+    const ruleParts = [...parts];
+    if (rule.sourceIP) {
+      ruleParts.push(`ip saddr ${rule.sourceIP}`);
+    }
+    if (rule.destIP) {
+      ruleParts.push(`ip daddr ${rule.destIP}`);
+    }
+    if (rule.comment) {
+      ruleParts.push(`comment "${rule.comment}"`);
+    }
+    ruleParts.push(rule.action);
+    commands.push(ruleParts.join(' '));
+  }
+
+  return commands;
+}
+
+/**
+ * Build commands to create an nft named set (IP set).
+ */
+export function buildIPSetCreate(
+  tableName: string,
+  family: TNftFamily,
+  config: INftIPSetConfig,
+): string[] {
+  const commands: string[] = [];
+
+  // Create the set
+  commands.push(
+    `nft add set ${family} ${tableName} ${config.name} { type ${config.type} \\; }`
+  );
+
+  // Add initial elements if provided
+  if (config.elements && config.elements.length > 0) {
+    commands.push(
+      `nft add element ${family} ${tableName} ${config.name} { ${config.elements.join(', ')} }`
+    );
+  }
+
+  return commands;
+}
+
+/**
+ * Build command to add elements to an existing set.
+ */
+export function buildIPSetAddElements(
+  tableName: string,
+  family: TNftFamily,
+  setName: string,
+  elements: string[],
+): string[] {
+  if (elements.length === 0) return [];
+  return [
+    `nft add element ${family} ${tableName} ${setName} { ${elements.join(', ')} }`
+  ];
+}
+
+/**
+ * Build command to remove elements from a set.
+ */
+export function buildIPSetRemoveElements(
+  tableName: string,
+  family: TNftFamily,
+  setName: string,
+  elements: string[],
+): string[] {
+  if (elements.length === 0) return [];
+  return [
+    `nft delete element ${family} ${tableName} ${setName} { ${elements.join(', ')} }`
+  ];
+}
+
+/**
+ * Build command to delete an entire set.
+ */
+export function buildIPSetDelete(
+  tableName: string,
+  family: TNftFamily,
+  setName: string,
+): string[] {
+  return [
+    `nft delete set ${family} ${tableName} ${setName}`
+  ];
+}
+
+/**
+ * Build a rule that matches against a named set.
+ */
+export function buildIPSetMatchRule(
+  tableName: string,
+  family: TNftFamily,
+  options: {
+    setName: string;
+    direction: 'input' | 'output' | 'forward';
+    matchField: 'saddr' | 'daddr';
+    action: 'accept' | 'drop' | 'reject';
+  },
+): string[] {
+  return [
+    `nft add rule ${family} ${tableName} ${options.direction} ip ${options.matchField} @${options.setName} ${options.action}`
+  ];
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────
+
+function expandProtocols(protocol?: 'tcp' | 'udp' | 'both'): string[] {
+  if (!protocol) return [];
+  switch (protocol) {
+    case 'tcp': return ['tcp'];
+    case 'udp': return ['udp'];
+    case 'both': return ['tcp', 'udp'];
+  }
+}

package/ts/nft.rulebuilder.nat.ts

@@ -0,0 +1,82 @@
+import type { TNftFamily, TNftProtocol, INftDnatRule, INftSnatRule, INftMasqueradeRule } from './nft.types.js';
+
+/**
+ * Expand a protocol spec into concrete protocol strings.
+ */
+function expandProtocols(protocol?: TNftProtocol): string[] {
+  switch (protocol ?? 'tcp') {
+    case 'tcp': return ['tcp'];
+    case 'udp': return ['udp'];
+    case 'both': return ['tcp', 'udp'];
+  }
+}
+
+/**
+ * Build DNAT rules for port forwarding.
+ * Generates DNAT + optional masquerade for each protocol.
+ * Direct port of Rust build_dnat_rule.
+ */
+export function buildDnatRules(
+  tableName: string,
+  family: TNftFamily,
+  rule: INftDnatRule,
+): string[] {
+  const protocols = expandProtocols(rule.protocol);
+  const commands: string[] = [];
+
+  for (const proto of protocols) {
+    // DNAT rule
+    commands.push(
+      `nft add rule ${family} ${tableName} prerouting ${proto} dport ${rule.sourcePort} dnat to ${rule.targetHost}:${rule.targetPort}`
+    );
+
+    // Masquerade (SNAT) unless preserveSourceIP is set
+    if (!rule.preserveSourceIP) {
+      commands.push(
+        `nft add rule ${family} ${tableName} postrouting ${proto} dport ${rule.targetPort} masquerade`
+      );
+    }
+  }
+
+  return commands;
+}
+
+/**
+ * Build an SNAT rule to rewrite source address.
+ */
+export function buildSnatRule(
+  tableName: string,
+  family: TNftFamily,
+  rule: INftSnatRule,
+): string[] {
+  const protocols = expandProtocols(rule.protocol);
+  const commands: string[] = [];
+
+  for (const proto of protocols) {
+    commands.push(
+      `nft add rule ${family} ${tableName} postrouting ${proto} dport ${rule.targetPort} snat to ${rule.sourceAddress}`
+    );
+  }
+
+  return commands;
+}
+
+/**
+ * Build a masquerade rule for outgoing NAT.
+ */
+export function buildMasqueradeRule(
+  tableName: string,
+  family: TNftFamily,
+  rule: INftMasqueradeRule,
+): string[] {
+  const protocols = expandProtocols(rule.protocol);
+  const commands: string[] = [];
+
+  for (const proto of protocols) {
+    commands.push(
+      `nft add rule ${family} ${tableName} postrouting ${proto} dport ${rule.targetPort} masquerade`
+    );
+  }
+
+  return commands;
+}

package/ts/nft.rulebuilder.ratelimit.ts

@@ -0,0 +1,89 @@
+import type { TNftFamily, INftRateLimitRule, INftConnectionRateRule } from './nft.types.js';
+
+/**
+ * Expand a protocol spec into concrete protocol strings.
+ */
+function expandProtocols(protocol?: 'tcp' | 'udp' | 'both'): string[] {
+  switch (protocol ?? 'tcp') {
+    case 'tcp': return ['tcp'];
+    case 'udp': return ['udp'];
+    case 'both': return ['tcp', 'udp'];
+  }
+}
+
+/**
+ * Build a rate limit rule.
+ * Packets exceeding the rate are subjected to the specified action (default: drop).
+ */
+export function buildRateLimitRule(
+  tableName: string,
+  family: TNftFamily,
+  rule: INftRateLimitRule,
+): string[] {
+  const protocols = expandProtocols(rule.protocol);
+  const chain = rule.chain ?? 'input';
+  const action = rule.action ?? 'drop';
+  const commands: string[] = [];
+
+  for (const proto of protocols) {
+    const portMatch = rule.port != null ? ` ${proto} dport ${rule.port}` : '';
+    const burstClause = rule.burst != null ? ` burst ${rule.burst} packets` : '';
+
+    if (rule.perSourceIP) {
+      // Per-IP rate limiting using nft meters
+      const meterName = `meter_${proto}_${rule.port ?? 'all'}`;
+      commands.push(
+        `nft add rule ${family} ${tableName} ${chain}${portMatch} meter ${meterName} { ip saddr limit rate over ${rule.rate}${burstClause} } ${action}`
+      );
+    } else {
+      // Global rate limiting
+      commands.push(
+        `nft add rule ${family} ${tableName} ${chain}${portMatch} limit rate over ${rule.rate}${burstClause} ${action}`
+      );
+    }
+  }
+
+  return commands;
+}
+
+/**
+ * Build a per-IP rate limit rule using nft meters.
+ * Convenience wrapper around buildRateLimitRule with perSourceIP=true.
+ */
+export function buildPerIpRateLimitRule(
+  tableName: string,
+  family: TNftFamily,
+  rule: Omit<INftRateLimitRule, 'perSourceIP'>,
+): string[] {
+  return buildRateLimitRule(tableName, family, { ...rule, perSourceIP: true });
+}
+
+/**
+ * Build a new-connection rate limit rule.
+ * Limits the rate of new connections (ct state new) on the given port.
+ */
+export function buildConnectionRateRule(
+  tableName: string,
+  family: TNftFamily,
+  rule: INftConnectionRateRule,
+): string[] {
+  const protocols = expandProtocols(rule.protocol);
+  const commands: string[] = [];
+
+  for (const proto of protocols) {
+    const portMatch = rule.port != null ? ` ${proto} dport ${rule.port}` : '';
+
+    if (rule.perSourceIP) {
+      const meterName = `connrate_${proto}_${rule.port ?? 'all'}`;
+      commands.push(
+        `nft add rule ${family} ${tableName} input ct state new${portMatch} meter ${meterName} { ip saddr limit rate over ${rule.rate} } drop`
+      );
+    } else {
+      commands.push(
+        `nft add rule ${family} ${tableName} input ct state new${portMatch} limit rate over ${rule.rate} drop`
+      );
+    }
+  }
+
+  return commands;
+}

package/ts/nft.rulebuilder.table.ts

@@ -0,0 +1,30 @@
+import type { TNftFamily } from './nft.types.js';
+
+/**
+ * Build commands to create the nftables table and NAT chains (prerouting + postrouting).
+ */
+export function buildTableSetup(tableName: string, family: TNftFamily = 'ip'): string[] {
+  return [
+    `nft add table ${family} ${tableName}`,
+    `nft add chain ${family} ${tableName} prerouting { type nat hook prerouting priority 0 \\; }`,
+    `nft add chain ${family} ${tableName} postrouting { type nat hook postrouting priority 100 \\; }`,
+  ];
+}
+
+/**
+ * Build commands to create filter chains (input, forward, output).
+ */
+export function buildFilterChains(tableName: string, family: TNftFamily = 'ip'): string[] {
+  return [
+    `nft add chain ${family} ${tableName} input { type filter hook input priority 0 \\; policy accept \\; }`,
+    `nft add chain ${family} ${tableName} forward { type filter hook forward priority 0 \\; policy accept \\; }`,
+    `nft add chain ${family} ${tableName} output { type filter hook output priority 0 \\; policy accept \\; }`,
+  ];
+}
+
+/**
+ * Build command to delete the entire nftables table.
+ */
+export function buildTableCleanup(tableName: string, family: TNftFamily = 'ip'): string[] {
+  return [`nft delete table ${family} ${tableName}`];
+}