nftables-napi 0.0.1

package/README.md

@@ -0,0 +1,104 @@
+# nftables-napi
+
+Native Node.js binding for nftables via libnftnl + libmnl. Manages IPv4/IPv6 blacklist tables with timeout support through direct netlink communication — no shell commands, no `nft` CLI.
+
+Requires Linux with `CAP_NET_ADMIN` or root.
+
+## Install
+
+```bash
+npm install nftables-napi
+```
+
+Prebuilt binaries are included for `linux-x64` and `linux-arm64`. If a prebuild is not available for your platform, the package will compile from source (requires `libnftnl-dev`, `libmnl-dev`, `pkg-config`, and a C++20 compiler).
+
+### Runtime dependencies
+
+The module dynamically links against `libnftnl` and `libmnl`. These must be present in the runtime environment. The `nft` CLI is **not** required — the module talks to the kernel directly via netlink.
+
+**Alpine:**
+
+```dockerfile
+RUN apk add --no-cache libnftnl libmnl
+```
+
+**Debian/Ubuntu:**
+
+```dockerfile
+RUN apt-get update && apt-get install -y libnftnl13 libmnl0 && rm -rf /var/lib/apt/lists/*
+```
+
+## Usage
+
+```js
+const { NftManager } = require("nftables-napi");
+
+const nft = new NftManager({
+  tableName: "tablename",
+  blacklistSetName: "blacklist",
+  droplistSetName: "droplist",
+});
+
+await nft.createTable();
+
+// Add with timeout (seconds)
+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" });
+
+await nft.deleteTable();
+```
+
+## API
+
+### `new NftManager(options)`
+
+| Option             | Type     | Required | Description                                  |
+| ------------------ | -------- | -------- | -------------------------------------------- |
+| `tableName`        | `string` | Yes      | Base table name (IPv6 auto-appends `'6'`)    |
+| `blacklistSetName` | `string` | Yes      | Blacklist set name (IPv6 auto-appends `'6'`) |
+| `droplistSetName`  | `string` | Yes      | Droplist set name (IPv6 auto-appends `'6'`)  |
+
+Log prefixes are auto-generated: `'{setName}: '` for each set.
+
+### Methods
+
+All methods return `Promise<void>`.
+
+| Method                                 | Description                                                           |
+| -------------------------------------- | --------------------------------------------------------------------- |
+| `createTable()`                        | Create IPv4/IPv6 tables with blacklist and droplist sets. 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.                                     |
+
+## Building from source
+
+```bash
+# Dependencies (Debian/Ubuntu)
+sudo apt install pkg-config libnftnl-dev libmnl-dev build-essential
+
+# Build
+npm run build
+
+# Prebuild for current platform
+npx prebuildify --napi --strip
+
+# Prebuild for linux/amd64 + linux/arm64 via Docker
+npm run prebuild:all
+```
+
+## License
+
+AGPL-3.0-only

package/binding.gyp

@@ -0,0 +1,45 @@
+{
+  "targets": [
+    {
+      "target_name": "remnawave_nft",
+      "sources": [
+        "src/addon.cpp",
+        "src/nft_manager.cpp",
+        "src/validation.cpp",
+        "src/netlink/nl_batch.cpp",
+        "src/netlink/nl_socket.cpp",
+        "src/netlink/set_ops.cpp",
+        "src/netlink/table_ops.cpp",
+        "src/workers/nft_worker.cpp"
+      ],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")",
+        "<!@(pkg-config --cflags-only-I libnftnl libmnl | sed 's/-I//g')"
+      ],
+      "libraries": [
+        "<!@(pkg-config --libs libnftnl libmnl)"
+      ],
+      "defines": [
+        "NAPI_VERSION=9",
+        "NAPI_DISABLE_CPP_EXCEPTIONS"
+      ],
+      "cflags_cc": [
+        "-std=c++20",
+        "-Wall",
+        "-Wextra",
+        "-Wpedantic",
+        "-Wno-unused-parameter"
+      ],
+      "ldflags": [
+        "-Wl,-z,relro",
+        "-Wl,-z,now",
+        "-Wl,-z,noexecstack"
+      ],
+      "conditions": [
+        ["OS!='linux'", {
+          "defines": ["UNSUPPORTED_PLATFORM"]
+        }]
+      ]
+    }
+  ]
+}

package/lib/index.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Native nftables manager for Linux firewall.
+ * Manages IPv4/IPv6 blacklist/droplist tables via libnftnl + libmnl (direct netlink, no nft CLI).
+ * Requires CAP_NET_ADMIN or root privileges.
+ */
+
+/** Target set for address operations. */
+export type TargetSet = 'blacklist' | 'droplist';
+
+/** Constructor options. All fields are required — no defaults. */
+export interface NftManagerOptions {
+    /** Base table name. IPv6 table auto-appends '6'. */
+    tableName: string;
+    /** Blacklist set name. IPv6 set auto-appends '6'. */
+    blacklistSetName: string;
+    /** Droplist set name. IPv6 set auto-appends '6'. */
+    droplistSetName: 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: 'blacklist' or 'droplist'. */
+    set: TargetSet;
+    /** Timeout in seconds. Omit for permanent ban. */
+    timeout?: number;
+}
+
+/** Options for removing a single address. */
+export interface RemoveAddressOptions {
+    /** IPv4 or IPv6 address to remove. */
+    ip: string;
+    /** Target set: 'blacklist' or 'droplist'. */
+    set: TargetSet;
+}
+
+/** Options for bulk adding addresses. */
+export interface AddAddressesOptions {
+    /** Array of IPv4/IPv6 addresses. */
+    ips: string[];
+    /** Target set: 'blacklist' or 'droplist'. */
+    set: TargetSet;
+    /** Timeout in seconds. Omit for permanent ban. */
+    timeout?: number;
+}
+
+/** Options for bulk removing addresses. */
+export interface RemoveAddressesOptions {
+    /** Array of IPv4/IPv6 addresses to remove. */
+    ips: string[];
+    /** Target set: 'blacklist' or 'droplist'. */
+    set: TargetSet;
+}
+
+export class NftManager {
+    /**
+     * Creates a new NftManager instance.
+     * Opens a netlink socket and validates configuration.
+     *
+     * @param options - Required configuration with table and set names.
+     * @throws {TypeError} if options are missing or have wrong types
+     * @throws {Error} if netlink socket cannot be opened (missing CAP_NET_ADMIN)
+     */
+    constructor(options: NftManagerOptions);
+
+    /**
+     * Creates IPv4 and IPv6 tables with blacklist/droplist sets and filter chains.
+     * Idempotent — destroys existing tables first, then recreates.
+     */
+    createTable(): Promise<void>;
+
+    /**
+     * Deletes both IPv4 and IPv6 tables.
+     * Idempotent — no error if tables don't exist.
+     */
+    deleteTable(): Promise<void>;
+
+    /**
+     * Adds an IP address to a set.
+     * Auto-detects IPv4 vs IPv6 and routes to the correct table/set.
+     *
+     * @param options - Address, target set, and optional timeout
+     * @throws {TypeError} if options are invalid
+     * @throws {Error} if IP is invalid or nftables operation fails
+     */
+    addAddress(options: AddAddressOptions): Promise<void>;
+
+    /**
+     * Removes an IP address from a set.
+     * Idempotent — no error if IP is not in the set.
+     *
+     * @param options - Address and target set
+     * @throws {TypeError} if options are invalid
+     * @throws {Error} if IP is invalid or nftables operation fails
+     */
+    removeAddress(options: RemoveAddressOptions): Promise<void>;
+
+    /**
+     * Adds multiple IP addresses to a set in bulk.
+     * Addresses are chunked for efficient netlink communication.
+     * Empty arrays are a no-op.
+     *
+     * @param options - Addresses, target set, and optional timeout
+     * @throws {TypeError} if options are invalid
+     * @throws {Error} if any IP is invalid or nftables operation fails
+     */
+    addAddresses(options: AddAddressesOptions): Promise<void>;
+
+    /**
+     * Removes multiple IP addresses from a set in bulk.
+     * Idempotent — no error if IPs are not in the set.
+     * Empty arrays are a no-op.
+     *
+     * @param options - Addresses and target set
+     * @throws {TypeError} if options are invalid
+     * @throws {Error} if any IP is invalid or nftables operation fails
+     */
+    removeAddresses(options: RemoveAddressesOptions): Promise<void>;
+}

package/lib/index.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const path = require('path');
+
+let binding;
+try {
+  binding = require('node-gyp-build')(path.join(__dirname, '..'));
+} catch (e) {
+  // On non-Linux platforms, the native addon may fail to load
+  binding = null;
+}
+
+if (binding) {
+  module.exports = binding;
+} else {
+  class NftManager {
+    constructor() {
+      throw new Error(
+        'remnawave-nft only works on Linux with CAP_NET_ADMIN. Native binding failed to load.'
+      );
+    }
+  }
+  module.exports = { NftManager };
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "nftables-napi",
+  "version": "0.0.1",
+  "description": "Native Node.js binding for nftables via libnftnl+libmnl — nftables firewall management",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "gypfile": true,
+  "files": [
+    "lib/",
+    "src/",
+    "prebuilds/",
+    "binding.gyp"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kastov/nftables-napi.git"
+  },
+  "homepage": "https://github.com/kastov/nftables-napi#readme",
+  "scripts": {
+    "install": "node-gyp-build || true",
+    "build": "node-gyp rebuild",
+    "rebuild": "node-gyp rebuild",
+    "test": "node --test test/test.mjs",
+    "prebuild:all": "./prebuild-all.sh"
+  },
+  "dependencies": {
+    "node-gyp-build": "^4.8.4",
+    "node-addon-api": "^8.3.0"
+  },
+  "devDependencies": {
+    "node-gyp": "^12.2.0",
+    "prebuildify": "^6.0.1",
+    "@types/node": "^22.0.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "license": "AGPL-3.0-only"
+}

package/src/addon.cpp

@@ -0,0 +1,9 @@
+#include <napi.h>
+#include "nft_manager.h"
+
+Napi::Object Init(Napi::Env env, Napi::Object exports) {
+    NftManager::Init(env, exports);
+    return exports;
+}
+
+NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init)

package/src/netlink/constants.h

@@ -0,0 +1,39 @@
+#pragma once
+
+#include <cstdint>
+
+namespace nft {
+
+// Chain names
+inline constexpr const char* CHAIN_INPUT = "input";
+inline constexpr const char* CHAIN_FORWARD = "forward";
+
+// Chain type
+inline constexpr const char* CHAIN_TYPE_FILTER = "filter";
+
+// Data types
+inline constexpr uint32_t DATATYPE_IPADDR = 7;
+inline constexpr uint32_t DATATYPE_IP6ADDR = 8;
+
+// Network header offsets and address lengths
+// Offset of source address in IPv4 header (bytes)
+inline constexpr uint32_t IPV4_SRC_OFFSET = 12;
+// Offset of source address in IPv6 header (bytes)
+inline constexpr uint32_t IPV6_SRC_OFFSET = 8;
+inline constexpr uint32_t IPV4_ADDR_LEN = 4;
+inline constexpr uint32_t IPV6_ADDR_LEN = 16;
+
+// Chain priority
+inline constexpr int32_t CHAIN_PRIORITY = -10;
+
+// Bulk operation parameters
+// Conservative chunk size for bulk set element operations
+inline constexpr uint32_t BULK_CHUNK_SIZE = 200;
+
+// Sequence number block size allocated per batch
+inline constexpr uint32_t SEQ_BLOCK_SIZE = 256;
+
+// Number of pages for default batch buffer (pagesize * 32 ≈ 128KB)
+inline constexpr uint32_t DEFAULT_BUF_PAGES = 32;
+
+} // namespace nft

package/src/netlink/nft_config.h

@@ -0,0 +1,43 @@
+#pragma once
+
+#include <string>
+
+namespace nft {
+
+enum class TargetSet {
+    Blacklist,
+    Droplist
+};
+
+struct NftConfig {
+    std::string table_v4;
+    std::string table_v6;
+    std::string set_v4;
+    std::string set_v6;
+    std::string drop_set_v4;
+    std::string drop_set_v6;
+    std::string blacklist_log_prefix;
+    std::string droplist_log_prefix;
+
+    static NftConfig from_names(const std::string& table_name,
+                                const std::string& blacklist_set_name,
+                                const std::string& droplist_set_name) {
+        return {table_name, table_name + "6",
+                blacklist_set_name, blacklist_set_name + "6",
+                droplist_set_name, droplist_set_name + "6",
+                blacklist_set_name + ": ",
+                droplist_set_name + ": "};
+    }
+
+    const std::string& resolve_set_v4(TargetSet ts) const {
+        return (ts == TargetSet::Blacklist) ? set_v4 : drop_set_v4;
+    }
+    const std::string& resolve_set_v6(TargetSet ts) const {
+        return (ts == TargetSet::Blacklist) ? set_v6 : drop_set_v6;
+    }
+    const std::string& resolve_log_prefix(TargetSet ts) const {
+        return (ts == TargetSet::Blacklist) ? blacklist_log_prefix : droplist_log_prefix;
+    }
+};
+
+} // namespace nft

package/src/netlink/nftnl_raii.h

@@ -0,0 +1,69 @@
+#pragma once
+
+// RAII wrappers for libnftnl C objects.
+//
+// These wrappers use std::unique_ptr with custom deleters to ensure that
+// libnftnl objects are properly freed when they go out of scope.
+//
+// Wrapped types:
+//   - nftnl_table  (freed via nftnl_table_free)
+//   - nftnl_chain  (freed via nftnl_chain_free)
+//   - nftnl_set    (freed via nftnl_set_free)
+//   - nftnl_rule   (freed via nftnl_rule_free)
+//
+// Intentionally NOT wrapped:
+//   - nftnl_expr     — nftnl_rule_add_expr(rule, expr) transfers ownership
+//                       of the expr to the rule. Wrapping it would cause a
+//                       double-free when the rule is destroyed.
+//   - nftnl_set_elem — nftnl_set_elem_add(set, elem) transfers ownership
+//                       of the elem to the set. Wrapping it would cause a
+//                       double-free when the set is destroyed.
+
+extern "C" {
+#include <libnftnl/table.h>
+#include <libnftnl/chain.h>
+#include <libnftnl/set.h>
+#include <libnftnl/rule.h>
+}
+
+#include <memory>
+
+namespace nft {
+
+// --- Table -------------------------------------------------------------------
+
+struct NftnlTableDeleter {
+    void operator()(struct nftnl_table* t) const noexcept { nftnl_table_free(t); }
+};
+using UniqueTable = std::unique_ptr<struct nftnl_table, NftnlTableDeleter>;
+
+inline UniqueTable make_table() { return UniqueTable(nftnl_table_alloc()); }
+
+// --- Chain -------------------------------------------------------------------
+
+struct NftnlChainDeleter {
+    void operator()(struct nftnl_chain* c) const noexcept { nftnl_chain_free(c); }
+};
+using UniqueChain = std::unique_ptr<struct nftnl_chain, NftnlChainDeleter>;
+
+inline UniqueChain make_chain() { return UniqueChain(nftnl_chain_alloc()); }
+
+// --- Set ---------------------------------------------------------------------
+
+struct NftnlSetDeleter {
+    void operator()(struct nftnl_set* s) const noexcept { nftnl_set_free(s); }
+};
+using UniqueSet = std::unique_ptr<struct nftnl_set, NftnlSetDeleter>;
+
+inline UniqueSet make_set() { return UniqueSet(nftnl_set_alloc()); }
+
+// --- Rule --------------------------------------------------------------------
+
+struct NftnlRuleDeleter {
+    void operator()(struct nftnl_rule* r) const noexcept { nftnl_rule_free(r); }
+};
+using UniqueRule = std::unique_ptr<struct nftnl_rule, NftnlRuleDeleter>;
+
+inline UniqueRule make_rule() { return UniqueRule(nftnl_rule_alloc()); }
+
+} // namespace nft

package/src/netlink/nl_batch.cpp

@@ -0,0 +1,67 @@
+#include "nl_batch.h"
+#include "constants.h"
+#include "nl_socket.h"
+
+#include <atomic>
+#include <ctime>
+#include <unistd.h>
+
+static uint32_t alloc_seq_block() {
+    static std::atomic<uint32_t> counter{static_cast<uint32_t>(time(nullptr))};
+    return counter.fetch_add(nft::SEQ_BLOCK_SIZE);
+}
+
+NlBatch::NlBatch() : NlBatch([]() -> size_t {
+    long ps = sysconf(_SC_PAGESIZE);
+    if (ps <= 0) ps = 4096;
+    return static_cast<size_t>(ps) * nft::DEFAULT_BUF_PAGES;
+}()) {}
+
+NlBatch::NlBatch(size_t buf_size)
+    : buf_(std::make_unique<char[]>(buf_size)),
+      batch_(nullptr),
+      seq_(0) {
+    batch_ = mnl_nlmsg_batch_start(buf_.get(), buf_size);
+    if (!batch_)
+        return;
+
+    seq_ = alloc_seq_block();
+    nftnl_batch_begin(static_cast<char*>(mnl_nlmsg_batch_current(batch_)), seq_++);
+    mnl_nlmsg_batch_next(batch_);
+}
+
+NlBatch::~NlBatch() {
+    if (batch_)
+        mnl_nlmsg_batch_stop(batch_);
+}
+
+bool NlBatch::is_valid() const {
+    return batch_ != nullptr;
+}
+
+struct nlmsghdr* NlBatch::add_msg(uint16_t type, uint16_t family, uint16_t flags) {
+    if (!batch_) return nullptr;
+
+    return nftnl_nlmsg_build_hdr(
+        static_cast<char*>(mnl_nlmsg_batch_current(batch_)),
+        type,
+        family,
+        flags,
+        seq_++
+    );
+}
+
+bool NlBatch::advance() {
+    if (!batch_) return false;
+    return mnl_nlmsg_batch_next(batch_);
+}
+
+NlResult NlBatch::execute(NlSocket& sock, bool ignore_enoent) {
+    if (!batch_)
+        return {false, "batch not initialized"};
+
+    nftnl_batch_end(static_cast<char*>(mnl_nlmsg_batch_current(batch_)), seq_++);
+    mnl_nlmsg_batch_next(batch_);
+
+    return sock.send_batch(batch_, ignore_enoent);
+}

package/src/netlink/nl_batch.h

@@ -0,0 +1,36 @@
+#pragma once
+
+extern "C" {
+#include <libmnl/libmnl.h>
+#include <libnftnl/batch.h>
+#include <libnftnl/common.h>
+}
+
+#include <cstdint>
+#include <memory>
+
+#include "nl_result.h"
+
+class NlSocket;
+
+class NlBatch {
+public:
+    NlBatch();
+    explicit NlBatch(size_t buf_size);
+    ~NlBatch();
+
+    NlBatch(const NlBatch&) = delete;
+    NlBatch& operator=(const NlBatch&) = delete;
+    NlBatch(NlBatch&&) = delete;
+    NlBatch& operator=(NlBatch&&) = delete;
+
+    bool is_valid() const;
+    struct nlmsghdr* add_msg(uint16_t type, uint16_t family, uint16_t flags);
+    bool advance();
+    NlResult execute(NlSocket& sock, bool ignore_enoent = false);
+
+private:
+    std::unique_ptr<char[]> buf_;
+    struct mnl_nlmsg_batch* batch_;
+    uint32_t seq_;
+};

package/src/netlink/nl_result.h

@@ -0,0 +1,8 @@
+#pragma once
+
+#include <string>
+
+struct NlResult {
+    bool success;
+    std::string error;
+};