nftables-napi 0.1.1 → 0.3.0

package/README.md

@@ -1,8 +1,8 @@
 # nftables-napi
 
-Native Node.js binding for nftables via libnftnl + libmnl. Manages IPv4/IPv6 tables with dynamic sets and timeout support through direct netlink communication — no shell commands, no `nft` CLI.
+Native Node.js binding for nftables via libnftnl + libmnl. Manages IPv4/IPv6 firewall tables with dynamic IP sets, port blocking, named counters, and timeout support through direct netlink communication — no shell commands, no `nft` CLI.
 
-Requires Linux with `CAP_NET_ADMIN` or root.
+Requires Linux kernel ≥ 5.7 with `CAP_NET_ADMIN` or root.
 
 ## Install
 
@@ -34,26 +34,44 @@ RUN apt-get update && apt-get install -y libnftnl13 libmnl0 && rm -rf /var/lib/a
 const { NftManager } = require("nftables-napi");
 
 const nft = new NftManager({
-  tableName: "tablename",
-  sets: ["blacklist", "droplist"],
+  tableName: "myfw",
+  ingressAddrSets: ["blacklist"],
+  egressAddrSets: ["blocklist"],
+  egressPortSets: ["blocked_ports"],
 });
 
 await nft.createTable();
 
-// Add with timeout (seconds)
+// ── IP blocking (input/forward) ──
+
 await nft.addAddress({ ip: "1.2.3.4", set: "blacklist", timeout: 1800 });
 await nft.addAddress({ ip: "2001:db8::1", set: "blacklist", timeout: 3600 });
-
-// Add permanent (no timeout)
-await nft.addAddress({ ip: "5.6.7.8", set: "droplist" });
-
-// Bulk add
 await nft.addAddresses({ ips: ["10.0.0.1", "10.0.0.2"], set: "blacklist", timeout: 7200 });
 
-// Remove
 await nft.removeAddress({ ip: "1.2.3.4", set: "blacklist" });
 await nft.removeAddresses({ ips: ["10.0.0.1", "10.0.0.2"], set: "blacklist" });
 
+// ── IP blocking (output) ──
+
+await nft.addAddress({ ip: "93.184.216.34", set: "blocklist" });
+await nft.removeAddress({ ip: "93.184.216.34", set: "blocklist" });
+
+// ── Port blocking (output, tcp/udp) ──
+
+// Block port 80 for both TCP and UDP
+await nft.addPort({ port: 80, set: "blocked_ports", timeout: 3600 });
+
+// Block port 443 for TCP only
+await nft.addPort({ port: 443, set: "blocked_ports", protocol: "tcp" });
+
+// Bulk port operations
+await nft.addPorts({ ports: [8080, 8443], set: "blocked_ports", protocol: "tcp" });
+await nft.removePorts({ ports: [8080, 8443], set: "blocked_ports", protocol: "tcp" });
+
+await nft.removePort({ port: 80, set: "blocked_ports" });
+
+// ── Cleanup ──
+
 await nft.deleteTable();
 ```
 
@@ -61,23 +79,119 @@ await nft.deleteTable();
 
 ### `new NftManager(options)`
 
-| Option      | Type       | Required | Description                                                                                      |
-| ----------- | ---------- | -------- | ------------------------------------------------------------------------------------------------ |
-| `tableName` | `string`   | Yes      | Base table name (IPv6 table auto-appends `'6'`)                                                  |
-| `sets`      | `string[]` | Yes      | Set names (1+, unique, non-empty). IPv6 sets auto-append `'6'`. Log prefix: `'{name}: '` |
+| Option | Type | Required | Description |
+| --- | --- | --- | --- |
+| `tableName` | `string` | Yes | Base table name. IPv6 table auto-appends `'6'`. |
+| `ingressAddrSets` | `string[]` | Yes | Input/forward IP set names (≥1). Block by **source** address on input and forward chains. Rules: log + named counter + drop. IPv6 sets auto-append `'6'`. |
+| `egressAddrSets` | `string[]` | No | Output IP set names. Block by **destination** address on output chain. Rules: named counter + drop (no log). IPv6 sets auto-append `'6'`. |
+| `egressPortSets` | `string[]` | No | Output port set names. Block by **destination port** (TCP/UDP) on output chain using concatenated `inet_proto . inet_service` sets. Ports are added to both IPv4 and IPv6 tables. IPv6 sets auto-append `'6'`. |
 
 ### Methods
 
-All methods return `Promise<void>`.
+All methods return `Promise<void>` and throw on error.
+
+#### Table management
+
+| Method | Description |
+| --- | --- |
+| `createTable()` | Create IPv4/IPv6 tables with all configured sets, chains, named counters, and filter rules. Idempotent — deletes existing tables first. |
+| `deleteTable()` | Delete both tables. Idempotent — no error if tables don't exist. |
+
+#### IP address operations
+
+Work with both `ingressAddrSets` (input/forward) and `egressAddrSets` (output).
 
-| Method                                 | Description                                                           |
-| -------------------------------------- | --------------------------------------------------------------------- |
-| `createTable()`                        | Create IPv4/IPv6 tables with all configured sets and filter chains. Idempotent. |
-| `deleteTable()`                        | Delete both tables. Idempotent.                                                 |
-| `addAddress({ ip, set, timeout? })`    | Add IP to set. `timeout` in seconds, omit for permanent.              |
-| `removeAddress({ ip, set })`           | Remove IP from set. Idempotent.                                       |
-| `addAddresses({ ips, set, timeout? })` | Bulk add to set. Chunked for efficient netlink communication.         |
-| `removeAddresses({ ips, set })`        | Bulk remove from set. Idempotent.                                     |
+| Method | Description |
+| --- | --- |
+| `addAddress({ ip, set, timeout? })` | Add IP to set. Auto-detects IPv4/IPv6. `timeout` in seconds, omit for permanent. |
+| `removeAddress({ ip, set })` | Remove IP from set. Idempotent. |
+| `addAddresses({ ips, set, timeout? })` | Bulk add. Chunked internally for efficient netlink communication. Empty array is a no-op. |
+| `removeAddresses({ ips, set })` | Bulk remove. Idempotent. Empty array is a no-op. |
+
+#### Port operations
+
+Work with `egressPortSets` only. Ports are added to both IPv4 and IPv6 tables.
+
+| Method | Description |
+| --- | --- |
+| `addPort({ port, set, protocol?, timeout? })` | Add port to set. `protocol`: `'tcp'`, `'udp'`, or omit for both. `timeout` in seconds. |
+| `removePort({ port, set, protocol? })` | Remove port from set. Idempotent. |
+| `addPorts({ ports, set, protocol?, timeout? })` | Bulk add ports. Empty array is a no-op. |
+| `removePorts({ ports, set, protocol? })` | Bulk remove ports. Idempotent. Empty array is a no-op. |
+
+### What `createTable()` builds
+
+For a config with `ingressAddrSets: ["bl"]`, `egressAddrSets: ["out"]`, `egressPortSets: ["ports"]`:
+
+```
+table ip myfw {
+    counter "processed" { packets 0 bytes 0 }
+    counter "bl"        { packets 0 bytes 0 }
+    counter "out"       { packets 0 bytes 0 }
+    counter "ports"     { packets 0 bytes 0 }
+
+    set bl {
+        type ipv4_addr
+        flags timeout
+        counter
+    }
+
+    set out {
+        type ipv4_addr
+        flags timeout
+        counter
+    }
+
+    set ports {
+        type inet_proto . inet_service
+        flags timeout
+        counter
+    }
+
+    chain input {
+        type filter hook input priority -10; policy accept;
+        counter name "processed"
+        ip saddr @bl log prefix "bl: " counter name "bl" drop
+    }
+
+    chain forward {
+        type filter hook forward priority -10; policy accept;
+        counter name "processed"
+        ip saddr @bl log prefix "bl: " counter name "bl" drop
+    }
+
+    chain output {
+        type filter hook output priority -10; policy accept;
+        ip daddr @out counter name "out" drop
+        meta l4proto . th dport @ports counter name "ports" drop
+    }
+}
+```
+
+IPv6 table (`myfw6`) mirrors the same structure with `ipv6_addr` sets and corresponding offsets.
+
+## Kernel compatibility
+
+Minimum: **Linux 5.7**
+
+| Feature | Kernel | Used for |
+| --- | --- | --- |
+| nftables core | 3.13 | tables, chains, sets, rules |
+| Set timeouts | 4.1 | element expiration |
+| Named counters | 4.10 | traffic accounting |
+| Concatenated sets | 5.6 | port blocking (`inet_proto . inet_service`) |
+| Per-element set expressions | 5.7 | per-element counters |
+
+| Distro | Kernel | Compatible |
+| --- | --- | --- |
+| Ubuntu 22.04+ | 5.15+ | Yes |
+| Ubuntu 20.04 (HWE) | 5.15 | Yes |
+| Ubuntu 20.04 (GA) | 5.4 | No |
+| Debian 11+ | 5.10+ | Yes |
+| Debian 10 | 4.19 | No |
+| RHEL / Rocky 9 | 5.14 | Yes |
+| RHEL / Rocky 8 | 4.18 | No |
+| Alpine 3.16+ | 5.15+ | Yes |
 
 ## Building from source
 
@@ -85,9 +199,15 @@ All methods return `Promise<void>`.
 # Dependencies (Debian/Ubuntu)
 sudo apt install pkg-config libnftnl-dev libmnl-dev build-essential
 
+# Dependencies (Alpine)
+apk add pkgconfig libnftnl-dev libmnl-dev build-base python3
+
 # Build
 npm run build
 
+# Run tests (requires root / CAP_NET_ADMIN)
+npm test
+
 # Prebuild for current platform
 npx prebuildify --napi --strip
 

package/binding.gyp

@@ -1,7 +1,7 @@
 {
   "targets": [
     {
-      "target_name": "remnawave_nft",
+      "target_name": "nftables_napi",
       "sources": [
         "src/addon.cpp",
         "src/nft_manager.cpp",

package/lib/index.d.ts

@@ -9,31 +9,31 @@ export interface NftManagerOptions {
     /** Base table name. IPv6 table auto-appends '6'. */
     tableName: string;
     /**
-     * Input/forward IP set names (≥1 required). Block by source address.
+     * Ingress IP set names (≥1 required). Block by source address.
      * Rules: log prefix "<setName>: " + named counter + drop on input and forward chains.
      * IPv6 sets auto-append '6'.
      */
-    sets: string[];
+    ingressAddrSets: string[];
     /**
-     * Output IP set names (optional). Block by destination address.
+     * Egress IP set names (optional). Block by destination address.
      * Rules: named counter + drop on output chain (no log).
      * IPv6 sets auto-append '6'.
      */
-    outSets?: string[];
+    egressAddrSets?: string[];
     /**
-     * Output port set names (optional). Block by tcp/udp destination port.
+     * Egress port set names (optional). Block by tcp/udp destination port.
      * Rules: single concatenated (proto . port) lookup + named counter + drop on output chain (no log).
      * Port is added to BOTH IPv4 and IPv6 tables (ports are family-independent).
      * IPv6 sets auto-append '6'.
      */
-    outPortSets?: string[];
+    egressPortSets?: string[];
 }
 
 /** Options for adding a single address. */
 export interface AddAddressOptions {
     /** IPv4 or IPv6 address (e.g., "1.2.3.4" or "2001:db8::1"). */
     ip: string;
-    /** Target set name (must match one from constructor's sets or outSets). */
+    /** Target set name (must match one from constructor's ingressAddrSets or egressAddrSets). */
     set: string;
     /** Timeout in seconds. Omit for permanent. */
     timeout?: number;
@@ -43,7 +43,7 @@ export interface AddAddressOptions {
 export interface RemoveAddressOptions {
     /** IPv4 or IPv6 address to remove. */
     ip: string;
-    /** Target set name (must match one from constructor's sets or outSets). */
+    /** Target set name (must match one from constructor's ingressAddrSets or egressAddrSets). */
     set: string;
 }
 
@@ -51,7 +51,7 @@ export interface RemoveAddressOptions {
 export interface AddAddressesOptions {
     /** Array of IPv4/IPv6 addresses. */
     ips: string[];
-    /** Target set name (must match one from constructor's sets or outSets). */
+    /** Target set name (must match one from constructor's ingressAddrSets or egressAddrSets). */
     set: string;
     /** Timeout in seconds. Omit for permanent. */
     timeout?: number;
@@ -61,7 +61,7 @@ export interface AddAddressesOptions {
 export interface RemoveAddressesOptions {
     /** Array of IPv4/IPv6 addresses to remove. */
     ips: string[];
-    /** Target set name (must match one from constructor's sets or outSets). */
+    /** Target set name (must match one from constructor's ingressAddrSets or egressAddrSets). */
     set: string;
 }
 
@@ -69,7 +69,7 @@ export interface RemoveAddressesOptions {
 export interface AddPortOptions {
     /** Port number (0-65535). */
     port: number;
-    /** Target port set name (must match one from constructor's outPortSets). */
+    /** Target port set name (must match one from constructor's egressPortSets). */
     set: string;
     /** Protocol: 'tcp', 'udp', or omit for both. Default: both. */
     protocol?: 'tcp' | 'udp';
@@ -81,7 +81,7 @@ export interface AddPortOptions {
 export interface RemovePortOptions {
     /** Port number (0-65535). */
     port: number;
-    /** Target port set name (must match one from constructor's outPortSets). */
+    /** Target port set name (must match one from constructor's egressPortSets). */
     set: string;
     /** Protocol: 'tcp', 'udp', or omit for both. Default: both. */
     protocol?: 'tcp' | 'udp';
@@ -91,7 +91,7 @@ export interface RemovePortOptions {
 export interface AddPortsOptions {
     /** Array of port numbers (0-65535). */
     ports: number[];
-    /** Target port set name (must match one from constructor's outPortSets). */
+    /** Target port set name (must match one from constructor's egressPortSets). */
     set: string;
     /** Protocol: 'tcp', 'udp', or omit for both. Default: both. */
     protocol?: 'tcp' | 'udp';
@@ -103,7 +103,7 @@ export interface AddPortsOptions {
 export interface RemovePortsOptions {
     /** Array of port numbers (0-65535). */
     ports: number[];
-    /** Target port set name (must match one from constructor's outPortSets). */
+    /** Target port set name (must match one from constructor's egressPortSets). */
     set: string;
     /** Protocol: 'tcp', 'udp', or omit for both. Default: both. */
     protocol?: 'tcp' | 'udp';
@@ -127,9 +127,9 @@ export class NftManager {
      * Creates:
      * - Named counter "processed" (global traffic counter per chain)
      * - Named counter per set (blocked traffic counter)
-     * - Input chain with log + counter + drop rules (for sets)
-     * - Forward chain with log + counter + drop rules (for sets)
-     * - Output chain with counter + drop rules (for outSets and outPortSets, no log)
+     * - Input chain with log + counter + drop rules (for ingressAddrSets)
+     * - Forward chain with log + counter + drop rules (for ingressAddrSets)
+     * - Output chain with counter + drop rules (for egressAddrSets and egressPortSets, no log)
      * - Per-element counters on all sets
      *
      * @throws {Error} if nftables operation fails
@@ -147,7 +147,7 @@ export class NftManager {
     /**
      * Adds an IP address to a set.
      * Auto-detects IPv4 vs IPv6 and routes to the correct table/set.
-     * Works with both input sets (sets) and output sets (outSets).
+     * Works with both input sets (ingressAddrSets) and output sets (egressAddrSets).
      *
      * @param options - Address, target set name, and optional timeout.
      * @throws {TypeError} if options or fields have wrong types
@@ -158,7 +158,7 @@ export class NftManager {
     /**
      * Removes an IP address from a set.
      * Idempotent — no error if IP is not in the set.
-     * Works with both input sets (sets) and output sets (outSets).
+     * Works with both input sets (ingressAddrSets) and output sets (egressAddrSets).
      *
      * @param options - Address and target set name.
      * @throws {TypeError} if options or fields have wrong types

package/lib/index.js

@@ -6,7 +6,6 @@ let binding;
 try {
   binding = require('node-gyp-build')(path.join(__dirname, '..'));
 } catch (e) {
-  if (process.platform === 'linux') throw e;
   binding = null;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nftables-napi",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Native Node.js binding for nftables via libnftnl+libmnl — nftables firewall management",
   "author": {
     "name": "kastov",

package/src/nft_manager.cpp

@@ -250,7 +250,7 @@ NftManager::NftManager(const Napi::CallbackInfo& info)
 
     if (info.Length() < 1 || !info[0].IsObject()) {
         Napi::TypeError::New(env,
-            "NftManager requires options object with tableName and sets")
+            "NftManager requires options object with tableName and ingressAddrSets")
             .ThrowAsJavaScriptException();
         return;
     }
@@ -264,18 +264,18 @@ NftManager::NftManager(const Napi::CallbackInfo& info)
         return;
     }
 
-    // sets — required non-empty array
-    if (!opts.Has("sets") || !opts.Get("sets").IsArray()) {
-        Napi::TypeError::New(env, "NftManager: 'sets' is required and must be an array of strings")
+    // ingressAddrSets — required non-empty array
+    if (!opts.Has("ingressAddrSets") || !opts.Get("ingressAddrSets").IsArray()) {
+        Napi::TypeError::New(env, "NftManager: 'ingressAddrSets' is required and must be an array of strings")
             .ThrowAsJavaScriptException();
         return;
     }
 
-    Napi::Array sets_arr = opts.Get("sets").As<Napi::Array>();
+    Napi::Array sets_arr = opts.Get("ingressAddrSets").As<Napi::Array>();
     uint32_t len = sets_arr.Length();
 
     if (len == 0) {
-        Napi::Error::New(env, "NftManager: 'sets' must contain at least one set name")
+        Napi::Error::New(env, "NftManager: 'ingressAddrSets' must contain at least one set name")
             .ThrowAsJavaScriptException();
         return;
     }
@@ -286,25 +286,25 @@ NftManager::NftManager(const Napi::CallbackInfo& info)
     for (uint32_t i = 0; i < len; ++i) {
         Napi::Value val = sets_arr[i];
         if (!val.IsString()) {
-            Napi::TypeError::New(env, "NftManager: 'sets[" + std::to_string(i) + "]' must be a string")
+            Napi::TypeError::New(env, "NftManager: 'ingressAddrSets[" + std::to_string(i) + "]' must be a string")
                 .ThrowAsJavaScriptException();
             return;
         }
         std::string name = val.As<Napi::String>().Utf8Value();
         if (name.empty()) {
-            Napi::Error::New(env, "NftManager: 'sets[" + std::to_string(i) + "]' must not be empty")
+            Napi::Error::New(env, "NftManager: 'ingressAddrSets[" + std::to_string(i) + "]' must not be empty")
                 .ThrowAsJavaScriptException();
             return;
         }
         in_sets.push_back(std::move(name));
     }
 
-    // Parse optional outSets (OutIP)
-    std::vector<std::string> out_sets = parse_optional_string_array(env, opts, "outSets", "NftManager");
+    // Parse optional egressAddrSets (OutIP)
+    std::vector<std::string> out_sets = parse_optional_string_array(env, opts, "egressAddrSets", "NftManager");
     if (env.IsExceptionPending()) return;
 
-    // Parse optional outPortSets (OutPort)
-    std::vector<std::string> out_port_sets = parse_optional_string_array(env, opts, "outPortSets", "NftManager");
+    // Parse optional egressPortSets (OutPort)
+    std::vector<std::string> out_port_sets = parse_optional_string_array(env, opts, "egressPortSets", "NftManager");
     if (env.IsExceptionPending()) return;
 
     // Cross-array duplicate check: all names must be unique across all arrays