nftables-napi 0.3.0 → 0.4.2

package/lib/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * Native nftables manager for Linux firewall.
- * Manages IPv4/IPv6 tables with dynamic sets via libnftnl + libmnl (direct netlink, no nft CLI).
+ * Manages IPv4/IPv6 tables with dynamic sets and CIDR ranges via libnftnl + libmnl (direct netlink, no nft CLI).
  * Requires CAP_NET_ADMIN or root privileges.
  */
 
@@ -31,7 +31,7 @@ export interface NftManagerOptions {
 
 /** Options for adding a single address. */
 export interface AddAddressOptions {
-    /** IPv4 or IPv6 address (e.g., "1.2.3.4" or "2001:db8::1"). */
+    /** IPv4/IPv6 address or CIDR (e.g., "1.2.3.4", "10.0.0.0/8", "2001:db8::/32"). */
     ip: string;
     /** Target set name (must match one from constructor's ingressAddrSets or egressAddrSets). */
     set: string;
@@ -41,7 +41,7 @@ export interface AddAddressOptions {
 
 /** Options for removing a single address. */
 export interface RemoveAddressOptions {
-    /** IPv4 or IPv6 address to remove. */
+    /** IPv4/IPv6 address or CIDR to remove (must match exactly as added). */
     ip: string;
     /** Target set name (must match one from constructor's ingressAddrSets or egressAddrSets). */
     set: string;
@@ -49,7 +49,7 @@ export interface RemoveAddressOptions {
 
 /** Options for bulk adding addresses. */
 export interface AddAddressesOptions {
-    /** Array of IPv4/IPv6 addresses. */
+    /** Array of IPv4/IPv6 addresses or CIDRs. */
     ips: string[];
     /** Target set name (must match one from constructor's ingressAddrSets or egressAddrSets). */
     set: string;
@@ -59,7 +59,7 @@ export interface AddAddressesOptions {
 
 /** Options for bulk removing addresses. */
 export interface RemoveAddressesOptions {
-    /** Array of IPv4/IPv6 addresses to remove. */
+    /** Array of IPv4/IPv6 addresses or CIDRs to remove. */
     ips: string[];
     /** Target set name (must match one from constructor's ingressAddrSets or egressAddrSets). */
     set: string;
@@ -145,8 +145,8 @@ export class NftManager {
     deleteTable(): Promise<void>;
 
     /**
-     * Adds an IP address to a set.
-     * Auto-detects IPv4 vs IPv6 and routes to the correct table/set.
+     * Adds an IP address or CIDR range to a set.
+     * Auto-detects IPv4 vs IPv6 and routes to the correct table/set. Accepts CIDR notation (e.g., "10.0.0.0/8").
      * Works with both input sets (ingressAddrSets) and output sets (egressAddrSets).
      *
      * @param options - Address, target set name, and optional timeout.
@@ -156,7 +156,7 @@ export class NftManager {
     addAddress(options: AddAddressOptions): Promise<void>;
 
     /**
-     * Removes an IP address from a set.
+     * Removes an IP address or CIDR range from a set.
      * Idempotent — no error if IP is not in the set.
      * Works with both input sets (ingressAddrSets) and output sets (egressAddrSets).
      *
@@ -167,7 +167,7 @@ export class NftManager {
     removeAddress(options: RemoveAddressOptions): Promise<void>;
 
     /**
-     * Adds multiple IP addresses to a set in bulk.
+     * Adds multiple IP addresses or CIDR ranges to a set in bulk.
      * Empty arrays are a no-op.
      *
      * @param options - Array of addresses, target set name, and optional timeout.
@@ -177,7 +177,7 @@ export class NftManager {
     addAddresses(options: AddAddressesOptions): Promise<void>;
 
     /**
-     * Removes multiple IP addresses from a set in bulk.
+     * Removes multiple IP addresses or CIDR ranges from a set in bulk.
      * Idempotent — no error if IPs are not in the set.
      * Empty arrays are a no-op.
      *

package/package.json

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

package/src/netlink/constants.h

@@ -54,6 +54,12 @@ inline constexpr uint32_t TRANSPORT_DPORT_LEN = 2;
 inline constexpr uint32_t DATATYPE_PROTO_SERVICE = (12 << 6 | 13);
 inline constexpr uint32_t PROTO_SERVICE_KEY_LEN = 8;
 
+// Byte offsets within the 8-byte concatenated (proto . port) key
+// Layout: [proto:1][pad:3][port_hi:1][port_lo:1][pad:2]
+inline constexpr uint32_t PORT_KEY_PROTO_OFFSET = 0;
+inline constexpr uint32_t PORT_KEY_PORT_HI_OFFSET = 4;
+inline constexpr uint32_t PORT_KEY_PORT_LO_OFFSET = 5;
+
 // L4 protocol numbers
 inline constexpr uint8_t PROTO_TCP = 6;
 inline constexpr uint8_t PROTO_UDP = 17;

package/src/netlink/parsed_addr.h

@@ -4,7 +4,8 @@
 
 struct ParsedAddr {
     uint32_t family;       // nft::FAMILY_IPV4 or nft::FAMILY_IPV6 (== NFPROTO_IPV4/IPV6)
-    uint8_t bytes[16];
+    uint8_t bytes[16];     // key (start of interval)
+    uint8_t end_bytes[16]; // key_end (exclusive end of interval)
     uint32_t len;          // 4 for IPv4, 16 for IPv6
 };
 

package/src/netlink/set_ops.cpp

@@ -64,13 +64,21 @@ static NlResult bulk_set_elem_op(
             nftnl_set_set_u32(s.get(), NFTNL_SET_KEY_LEN, key_len);
 
             for (size_t i = offset; i < end; ++i) {
-                auto* e = nftnl_set_elem_alloc();
-                if (!e) return {false, "nftnl_set_elem_alloc failed"};
-                nftnl_set_elem_set(e, NFTNL_SET_ELEM_KEY, family_addrs[i]->bytes, family_addrs[i]->len);
+                // Start element: carries the key, timeout, and counters
+                auto* e_start = nftnl_set_elem_alloc();
+                if (!e_start) return {false, "nftnl_set_elem_alloc failed"};
+                nftnl_set_elem_set(e_start, NFTNL_SET_ELEM_KEY, family_addrs[i]->bytes, family_addrs[i]->len);
                 if (timeout_ms > 0) {
-                    nftnl_set_elem_set_u64(e, NFTNL_SET_ELEM_TIMEOUT, timeout_ms);
+                    nftnl_set_elem_set_u64(e_start, NFTNL_SET_ELEM_TIMEOUT, timeout_ms);
                 }
-                nftnl_set_elem_add(s.get(), e);
+                nftnl_set_elem_add(s.get(), e_start);
+
+                // End element: exclusive upper bound with INTERVAL_END flag
+                auto* e_end = nftnl_set_elem_alloc();
+                if (!e_end) return {false, "nftnl_set_elem_alloc failed"};
+                nftnl_set_elem_set(e_end, NFTNL_SET_ELEM_KEY, family_addrs[i]->end_bytes, family_addrs[i]->len);
+                nftnl_set_elem_set_u32(e_end, NFTNL_SET_ELEM_FLAGS, NFT_SET_ELEM_INTERVAL_END);
+                nftnl_set_elem_add(s.get(), e_end);
             }
 
             NlBatch batch;
@@ -154,9 +162,9 @@ static NlResult bulk_port_elem_op(
                 if (!e) return {false, "nftnl_set_elem_alloc failed"};
                 // 8-byte concatenated key: [proto][pad:3][port_hi][port_lo][pad:2]
                 uint8_t key[8] = {};
-                key[0] = elems[i].proto;
-                key[4] = static_cast<uint8_t>(elems[i].port >> 8);
-                key[5] = static_cast<uint8_t>(elems[i].port & 0xFF);
+                key[nft::PORT_KEY_PROTO_OFFSET] = elems[i].proto;
+                key[nft::PORT_KEY_PORT_HI_OFFSET] = static_cast<uint8_t>(elems[i].port >> 8);
+                key[nft::PORT_KEY_PORT_LO_OFFSET] = static_cast<uint8_t>(elems[i].port & 0xFF);
                 nftnl_set_elem_set(e, NFTNL_SET_ELEM_KEY, key, sizeof(key));
                 if (timeout_ms > 0) {
                     nftnl_set_elem_set_u64(e, NFTNL_SET_ELEM_TIMEOUT, timeout_ms);

package/src/netlink/table_ops.cpp

@@ -69,7 +69,7 @@ static bool add_counter_obj(NlBatch& batch, uint32_t family, const char* table,
 
 static bool add_set(NlBatch& batch, uint32_t family, const char* table,
                     const char* name, uint32_t key_type, uint32_t key_len,
-                    uint32_t set_id,
+                    uint32_t set_id, bool interval = false,
                     const uint8_t* concat_field_lens = nullptr,
                     size_t concat_field_count = 0) {
     auto s = nft::make_set();
@@ -81,6 +81,8 @@ static bool add_set(NlBatch& batch, uint32_t family, const char* table,
     nftnl_set_set_u32(s.get(), NFTNL_SET_KEY_LEN, key_len);
 
     uint32_t set_flags = NFT_SET_TIMEOUT | NFT_SET_EXPR;
+    if (interval)
+        set_flags |= NFT_SET_INTERVAL;
     if (concat_field_lens && concat_field_count > 0)
         set_flags |= NFT_SET_CONCAT;
     nftnl_set_set_u32(s.get(), NFTNL_SET_FLAGS, set_flags);
@@ -297,10 +299,11 @@ NlResult CreateTableOp::execute(NlSocket& sock) {
             key_len_v4 = IPV4_ADDR_LEN;
             key_len_v6 = IPV6_ADDR_LEN;
         }
+        bool is_interval = (sd.kind != SetKind::OutPort);
         if (!add_set(batch, NFPROTO_IPV4, cfg_->table_v4.c_str(), sd.name.c_str(),
-                     key_type_v4, key_len_v4, sid++, concat_fields, concat_count)
+                     key_type_v4, key_len_v4, sid++, is_interval, concat_fields, concat_count)
             || !add_set(batch, NFPROTO_IPV6, cfg_->table_v6.c_str(), sd.name_v6.c_str(),
-                        key_type_v6, key_len_v6, sid++, concat_fields, concat_count))
+                        key_type_v6, key_len_v6, sid++, is_interval, concat_fields, concat_count))
             return {false, "failed to build set '" + sd.name + "'"};
     }
 

package/src/nft_manager.cpp

@@ -13,11 +13,12 @@
 
 static constexpr double MAX_TIMEOUT_SEC = 4294967295.0; // UINT32_MAX seconds (~136 years)
 
-static ParsedAddr to_parsed_addr(const IpAddr& addr) {
+static ParsedAddr to_parsed_addr(const CidrAddr& cidr) {
     ParsedAddr pa{};
-    pa.family = (addr.family == IpFamily::IPv4) ? nft::FAMILY_IPV4 : nft::FAMILY_IPV6;
-    pa.len = addr.len;
-    std::memcpy(pa.bytes, addr.bytes.data(), addr.len);
+    pa.family = (cidr.network.family == IpFamily::IPv4) ? nft::FAMILY_IPV4 : nft::FAMILY_IPV6;
+    pa.len = cidr.network.len;
+    std::memcpy(pa.bytes, cidr.network.bytes.data(), cidr.network.len);
+    std::memcpy(pa.end_bytes, cidr.end.bytes.data(), cidr.end.len);
     return pa;
 }
 
@@ -34,14 +35,14 @@ static std::vector<ParsedAddr> parse_ip_array(Napi::Env env, Napi::Array arr) {
         }
 
         std::string ip = val.As<Napi::String>().Utf8Value();
-        IpAddr addr = parse_ip(ip);
-        if (addr.family == IpFamily::Invalid) {
-            Napi::Error::New(env, "Invalid IP address at index " + std::to_string(i) + ": " + ip)
+        CidrAddr cidr = parse_ip_or_cidr(ip);
+        if (cidr.network.family == IpFamily::Invalid) {
+            Napi::Error::New(env, "Invalid IP address or CIDR at index " + std::to_string(i) + ": " + ip)
                 .ThrowAsJavaScriptException();
             return {};
         }
 
-        addrs.push_back(to_parsed_addr(addr));
+        addrs.push_back(to_parsed_addr(cidr));
     }
 
     return addrs;
@@ -147,23 +148,23 @@ static std::vector<uint16_t> parse_port_array(Napi::Env env, Napi::Array arr,
 
 // Parse optional protocol: 'tcp', 'udp', or absent (both).
 // Returns 0 for both, PROTO_TCP for tcp, PROTO_UDP for udp.
-// Returns 255 on error (after throwing JS exception).
-static uint8_t parse_protocol(Napi::Env env, Napi::Object opts, const char* method_name) {
+// Returns std::nullopt on error (after throwing JS exception).
+static std::optional<uint8_t> parse_protocol(Napi::Env env, Napi::Object opts, const char* method_name) {
     if (!opts.Has("protocol") || opts.Get("protocol").IsUndefined() || opts.Get("protocol").IsNull()) {
-        return 0; // both
+        return uint8_t{0}; // both
     }
     Napi::Value pv = opts.Get("protocol");
     if (!pv.IsString()) {
         std::string msg = std::string(method_name) + ": 'protocol' must be 'tcp' or 'udp'";
         Napi::TypeError::New(env, msg).ThrowAsJavaScriptException();
-        return 255;
+        return std::nullopt;
     }
     std::string proto = pv.As<Napi::String>().Utf8Value();
     if (proto == "tcp") return nft::PROTO_TCP;
     if (proto == "udp") return nft::PROTO_UDP;
     std::string msg = std::string(method_name) + ": 'protocol' must be 'tcp' or 'udp'";
     Napi::Error::New(env, msg).ThrowAsJavaScriptException();
-    return 255;
+    return std::nullopt;
 }
 
 static std::vector<PortElem> make_port_elems(uint16_t port, uint8_t proto) {
@@ -393,14 +394,14 @@ Napi::Value NftManager::AddAddress(const Napi::CallbackInfo& info) {
     auto timeout_ms = parse_timeout(env, opts, "addAddress");
     if (!timeout_ms) return env.Undefined();
 
-    IpAddr addr = parse_ip(ip);
-    if (addr.family == IpFamily::Invalid) {
-        Napi::Error::New(env, "Invalid IP address: " + ip).ThrowAsJavaScriptException();
+    CidrAddr cidr = parse_ip_or_cidr(ip);
+    if (cidr.network.family == IpFamily::Invalid) {
+        Napi::Error::New(env, "Invalid IP address or CIDR: " + ip).ThrowAsJavaScriptException();
         return env.Undefined();
     }
 
     std::vector<ParsedAddr> addrs;
-    addrs.push_back(to_parsed_addr(addr));
+    addrs.push_back(to_parsed_addr(cidr));
     auto op = std::make_unique<BulkAddSetElemOp>(std::move(addrs), *timeout_ms, config_, *set_idx);
 
     auto deferred = Napi::Promise::Deferred::New(env);
@@ -432,14 +433,14 @@ Napi::Value NftManager::RemoveAddress(const Napi::CallbackInfo& info) {
     auto set_idx = parse_set_name(env, opts, "removeAddress", *config_, true, false);
     if (!set_idx) return env.Undefined();
 
-    IpAddr addr = parse_ip(ip);
-    if (addr.family == IpFamily::Invalid) {
-        Napi::Error::New(env, "Invalid IP address: " + ip).ThrowAsJavaScriptException();
+    CidrAddr cidr = parse_ip_or_cidr(ip);
+    if (cidr.network.family == IpFamily::Invalid) {
+        Napi::Error::New(env, "Invalid IP address or CIDR: " + ip).ThrowAsJavaScriptException();
         return env.Undefined();
     }
 
     std::vector<ParsedAddr> addrs;
-    addrs.push_back(to_parsed_addr(addr));
+    addrs.push_back(to_parsed_addr(cidr));
     auto op = std::make_unique<BulkDelSetElemOp>(std::move(addrs), config_, *set_idx);
 
     auto deferred = Napi::Promise::Deferred::New(env);
@@ -552,13 +553,13 @@ Napi::Value NftManager::AddPort(const Napi::CallbackInfo& info) {
     auto set_idx = parse_set_name(env, opts, "addPort", *config_, false, true);
     if (!set_idx) return env.Undefined();
 
-    uint8_t proto = parse_protocol(env, opts, "addPort");
-    if (proto == 255) return env.Undefined();
+    auto proto = parse_protocol(env, opts, "addPort");
+    if (!proto) return env.Undefined();
 
     auto timeout_ms = parse_timeout(env, opts, "addPort");
     if (!timeout_ms) return env.Undefined();
 
-    auto elems = make_port_elems(*port, proto);
+    auto elems = make_port_elems(*port, *proto);
     auto op = std::make_unique<BulkAddPortElemOp>(std::move(elems), *timeout_ms, config_, *set_idx);
 
     auto deferred = Napi::Promise::Deferred::New(env);
@@ -586,10 +587,10 @@ Napi::Value NftManager::RemovePort(const Napi::CallbackInfo& info) {
     auto set_idx = parse_set_name(env, opts, "removePort", *config_, false, true);
     if (!set_idx) return env.Undefined();
 
-    uint8_t proto = parse_protocol(env, opts, "removePort");
-    if (proto == 255) return env.Undefined();
+    auto proto = parse_protocol(env, opts, "removePort");
+    if (!proto) return env.Undefined();
 
-    auto elems = make_port_elems(*port, proto);
+    auto elems = make_port_elems(*port, *proto);
     auto op = std::make_unique<BulkDelPortElemOp>(std::move(elems), config_, *set_idx);
 
     auto deferred = Napi::Promise::Deferred::New(env);
@@ -621,8 +622,8 @@ Napi::Value NftManager::AddPorts(const Napi::CallbackInfo& info) {
     auto set_idx = parse_set_name(env, opts, "addPorts", *config_, false, true);
     if (!set_idx) return env.Undefined();
 
-    uint8_t proto = parse_protocol(env, opts, "addPorts");
-    if (proto == 255) return env.Undefined();
+    auto proto = parse_protocol(env, opts, "addPorts");
+    if (!proto) return env.Undefined();
 
     auto timeout_ms = parse_timeout(env, opts, "addPorts");
     if (!timeout_ms) return env.Undefined();
@@ -637,7 +638,7 @@ Napi::Value NftManager::AddPorts(const Napi::CallbackInfo& info) {
         return promise;
     }
 
-    auto elems = make_port_elems_bulk(ports, proto);
+    auto elems = make_port_elems_bulk(ports, *proto);
     auto op = std::make_unique<BulkAddPortElemOp>(std::move(elems), *timeout_ms, config_, *set_idx);
     auto deferred = Napi::Promise::Deferred::New(env);
     auto promise = deferred.Promise();
@@ -668,8 +669,8 @@ Napi::Value NftManager::RemovePorts(const Napi::CallbackInfo& info) {
     auto set_idx = parse_set_name(env, opts, "removePorts", *config_, false, true);
     if (!set_idx) return env.Undefined();
 
-    uint8_t proto = parse_protocol(env, opts, "removePorts");
-    if (proto == 255) return env.Undefined();
+    auto proto = parse_protocol(env, opts, "removePorts");
+    if (!proto) return env.Undefined();
 
     std::vector<uint16_t> ports = parse_port_array(env, arr, "removePorts");
     if (env.IsExceptionPending()) return env.Undefined();
@@ -681,7 +682,7 @@ Napi::Value NftManager::RemovePorts(const Napi::CallbackInfo& info) {
         return promise;
     }
 
-    auto elems = make_port_elems_bulk(ports, proto);
+    auto elems = make_port_elems_bulk(ports, *proto);
     auto op = std::make_unique<BulkDelPortElemOp>(std::move(elems), config_, *set_idx);
     auto deferred = Napi::Promise::Deferred::New(env);
     auto promise = deferred.Promise();

package/src/validation.cpp

@@ -4,6 +4,10 @@
 #include <cmath>
 #include <cstring>
 
+namespace {
+
+// Parse IP string, validate via inet_pton, store binary form.
+// Returns IpAddr with family=Invalid on failure.
 IpAddr parse_ip(const std::string& ip) {
     IpAddr result;
 
@@ -26,6 +30,157 @@ IpAddr parse_ip(const std::string& ip) {
     return result;
 }
 
+// Big-endian increment by 1 with carry propagation.
+void increment_ip(uint8_t* bytes, uint32_t len) {
+    for (int i = static_cast<int>(len) - 1; i >= 0; --i) {
+        if (++bytes[i] != 0) {
+            return; // no carry
+        }
+    }
+    // Full overflow (e.g., 255.255.255.255 + 1) — bytes wrap to all zeros.
+}
+
+// Compute exclusive end address from network + prefix_len.
+// end = network address with host bits zeroed, then the prefix portion incremented.
+// For /8 on 10.0.0.0: byte[0]=10, increment -> 11, rest stays 0 -> 11.0.0.0
+void compute_cidr_end(const IpAddr& network, uint8_t prefix_len, IpAddr& end) {
+    end.family = network.family;
+    end.len = network.len;
+
+    uint32_t full_bytes = prefix_len / 8;
+    uint32_t remainder_bits = prefix_len % 8;
+
+    // Copy prefix bytes
+    for (uint32_t i = 0; i < full_bytes && i < network.len; ++i) {
+        end.bytes[i] = network.bytes[i];
+    }
+
+    if (remainder_bits > 0 && full_bytes < network.len) {
+        // Mask off host bits in the boundary byte
+        uint8_t mask = static_cast<uint8_t>(0xFF << (8 - remainder_bits));
+        end.bytes[full_bytes] = network.bytes[full_bytes] & mask;
+    }
+
+    // Zero all bytes after the prefix boundary
+    uint32_t start_zero = full_bytes + (remainder_bits > 0 ? 1 : 0);
+    for (uint32_t i = start_zero; i < network.len; ++i) {
+        end.bytes[i] = 0;
+    }
+
+    // Increment the prefix portion to get the exclusive end.
+    // We increment at bit position prefix_len. This is equivalent to adding
+    // 1 to the (prefix_len)-bit number formed by the first prefix_len bits.
+    if (remainder_bits > 0) {
+        // The boundary byte has some prefix bits. We need to increment
+        // at the bit position. Add (1 << (8 - remainder_bits)) to that byte,
+        // with carry propagation into earlier bytes.
+        uint8_t add_val = static_cast<uint8_t>(1 << (8 - remainder_bits));
+        uint16_t carry = add_val;
+        for (int i = static_cast<int>(full_bytes); i >= 0 && carry > 0; --i) {
+            carry += end.bytes[i];
+            end.bytes[i] = static_cast<uint8_t>(carry & 0xFF);
+            carry >>= 8;
+        }
+    } else {
+        // Prefix ends on a byte boundary. Increment the last prefix byte
+        // with carry into earlier bytes.
+        if (full_bytes > 0) {
+            uint16_t carry = 1;
+            for (int i = static_cast<int>(full_bytes) - 1; i >= 0 && carry > 0; --i) {
+                carry += end.bytes[i];
+                end.bytes[i] = static_cast<uint8_t>(carry & 0xFF);
+                carry >>= 8;
+            }
+        }
+    }
+}
+
+} // namespace
+
+CidrAddr parse_ip_or_cidr(const std::string& input) {
+    CidrAddr result{};
+
+    auto slash_pos = input.find('/');
+
+    if (slash_pos == std::string::npos) {
+        // Plain IP address
+        IpAddr ip = parse_ip(input);
+        if (ip.family == IpFamily::Invalid) {
+            return result;
+        }
+
+        result.network = ip;
+
+        // end = ip + 1
+        result.end = ip;
+        increment_ip(result.end.bytes.data(), result.end.len);
+        return result;
+    }
+
+    // CIDR notation: "base/prefix"
+    std::string base_str = input.substr(0, slash_pos);
+    std::string prefix_str = input.substr(slash_pos + 1);
+
+    // Reject empty prefix or non-numeric prefix
+    if (prefix_str.empty()) {
+        return result;
+    }
+    for (char c : prefix_str) {
+        if (c < '0' || c > '9') {
+            return result;
+        }
+    }
+
+    // Manual parse — no exceptions needed (digits already validated above).
+    // Reject prefix strings longer than 3 chars (max valid: "128").
+    if (prefix_str.size() > 3) {
+        return result;
+    }
+    int prefix = 0;
+    for (char c : prefix_str) {
+        prefix = prefix * 10 + (c - '0');
+    }
+
+    IpAddr ip = parse_ip(base_str);
+    if (ip.family == IpFamily::Invalid) {
+        return result;
+    }
+
+    uint8_t max_prefix = (ip.family == IpFamily::IPv4) ? 32 : 128;
+
+    // Reject /0 (too dangerous) and prefix > max
+    if (prefix < 1 || prefix > max_prefix) {
+        return result;
+    }
+
+    auto prefix_len = static_cast<uint8_t>(prefix);
+
+    // Verify host bits are zero
+    uint32_t full_bytes = prefix_len / 8;
+    uint32_t remainder_bits = prefix_len % 8;
+
+    // Check boundary byte: host bits must be zero
+    if (remainder_bits > 0 && full_bytes < ip.len) {
+        uint8_t mask = static_cast<uint8_t>(0xFF >> remainder_bits);
+        if ((ip.bytes[full_bytes] & mask) != 0) {
+            return result; // host bits set in boundary byte
+        }
+    }
+
+    // Check all bytes after the prefix boundary must be zero
+    uint32_t start_check = full_bytes + (remainder_bits > 0 ? 1 : 0);
+    for (uint32_t i = start_check; i < ip.len; ++i) {
+        if (ip.bytes[i] != 0) {
+            return result; // host bits set
+        }
+    }
+
+    result.network = ip;
+
+    compute_cidr_end(ip, prefix_len, result.end);
+    return result;
+}
+
 PortVal parse_port(double value) {
     if (std::isnan(value) || value < 0.0 || value > 65535.0) {
         return {0, false};

package/src/validation.h

@@ -16,9 +16,18 @@ struct IpAddr {
     uint32_t len = 0;
 };
 
-// Parse IP string, validate via inet_pton, store binary form.
-// Returns IpAddr with family=Invalid on failure.
-[[nodiscard]] IpAddr parse_ip(const std::string& ip);
+struct CidrAddr {
+    IpAddr network;       // network address (e.g., 10.0.0.0)
+    IpAddr end;           // exclusive end address (e.g., 11.0.0.0 for /8)
+};
+
+// Parse IP string or CIDR notation. Accepts:
+//   "1.2.3.4"       -> CidrAddr{network=1.2.3.4, end=1.2.3.5}
+//   "10.0.0.0/8"    -> CidrAddr{network=10.0.0.0, end=11.0.0.0}
+//   "2001:db8::/32" -> CidrAddr{network=2001:db8::, end=2001:db9::}
+// Returns CidrAddr with network.family=Invalid on failure.
+// Rejects: host bits set (192.168.1.1/24), prefix > 32/128, /0 (too dangerous).
+[[nodiscard]] CidrAddr parse_ip_or_cidr(const std::string& input);
 
 struct PortVal {
     uint16_t port;