quic: add block list support for endpoints

Signed-off-by: James M Snell <jasnell@gmail.com>
Assisted-by: Opencode/Opus 4.6

Author: jasnell

doc/api/quic.md

@@ -189,6 +189,50 @@ object. Each rate limiter has a corresponding counter
 were dropped. A non-zero value indicates the rate limiter is actively
 protecting the endpoint.
 
+#### Block lists
+
+Endpoints can filter incoming packets by source address using a
+[`net.BlockList`][]. The block list is checked before any QUIC processing
+occurs, so blocked packets consume no resources beyond the check itself.
+
+In **deny** mode (the default), packets from addresses in the list are dropped:
+
+```mjs
+import { BlockList } from 'node:net';
+import { listen } from 'node:quic';
+
+const blocked = new BlockList();
+blocked.addSubnet('192.168.1.0', 24);  // Block an entire subnet
+blocked.addAddress('10.0.0.5');        // Block a specific address
+
+const endpoint = await listen(onSession, {
+  endpoint: {
+    blockList: blocked,
+    blockListPolicy: 'deny',
+  },
+  // ...
+});
+```
+
+In **allow** mode, only packets from addresses in the list are accepted:
+
+```mjs
+const trusted = new BlockList();
+trusted.addSubnet('10.0.0.0', 8);
+
+const endpoint = await listen(onSession, {
+  endpoint: {
+    blockList: trusted,
+    blockListPolicy: 'allow',
+  },
+  // ...
+});
+```
+
+The block list is evaluated live — rules added or removed after the endpoint
+is created take effect immediately. The `endpoint.stats.packetsBlocked`
+counter tracks how many packets have been dropped by the filter.
+
 ### Applications
 
 Every `QuicSession` is associated with a single application protocol, negotiated
@@ -851,6 +895,11 @@ added: v23.8.0
   per-host rate limiter. Read only. A non-zero value indicates one or more
   remote addresses are creating sessions faster than the configured rate allows.
 
+### `endpointStats.packetsBlocked`
+
+* Type: {bigint} The total number of incoming packets dropped by the
+  block list filter. Read only.
+
 ## Class: `QuicSession`
 
 <!-- YAML
@@ -2449,6 +2498,34 @@ added: v23.8.0
 
 If not specified the endpoint will bind to IPv4 `localhost` on a random port.
 
+#### `endpointOptions.blockList`
+
+* Type: {net.BlockList}
+
+An optional [`net.BlockList`][] instance for filtering incoming packets by
+source address. When configured, every received UDP packet is checked against
+the block list before any QUIC processing occurs, minimizing resource
+expenditure on blocked sources. The block list is evaluated live — rules
+added to the `BlockList` object after the endpoint is created take effect
+immediately.
+
+See [`endpointOptions.blockListPolicy`][] for how matches are interpreted.
+
+#### `endpointOptions.blockListPolicy`
+
+* Type: {string} One of `'deny'` or `'allow'`.
+* **Default:** `'deny'`
+
+Controls how the [`endpointOptions.blockList`][] is interpreted:
+
+* `'deny'` — Packets from addresses matching the block list are dropped.
+  All other addresses are accepted. This is the typical blocklist mode.
+* `'allow'` — Only packets from addresses matching the block list are
+  accepted. All other addresses are dropped. This is an allowlist mode
+  for restricting access to known clients.
+
+If no block list is configured, this option has no effect.
+
 #### `endpointOptions.addressLRUSize`
 
 <!-- YAML
@@ -4303,6 +4380,8 @@ throughput issues caused by flow control.
 [`endpoint.busy`]: #endpointbusy
 [`endpoint.maxConnectionsPerHost`]: #endpointmaxconnectionsperhost
 [`endpoint.maxConnectionsTotal`]: #endpointmaxconnectionstotal
+[`endpointOptions.blockListPolicy`]: #endpointoptionsblocklistpolicy
+[`endpointOptions.blockList`]: #endpointoptionsblocklist
 [`endpointOptions.immediateCloseBurst`]: #endpointoptionsimmediatecloseburst
 [`endpointOptions.immediateCloseRate`]: #endpointoptionsimmediatecloserate
 [`endpointOptions.retryBurst`]: #endpointoptionsretryburst
@@ -4316,6 +4395,7 @@ throughput issues caused by flow control.
 [`error.errorCode`]: #errorerrorcode
 [`fs.promises.open(path, 'r')`]: fs.md#fspromisesopenpath-flags-mode
 [`maxDatagramFrameSize`]: #transportparamsmaxdatagramframesize
+[`net.BlockList`]: net.md#class-netblocklist
 [`quic.connect()`]: #quicconnectaddress-options
 [`quic.listen()`]: #quiclistenonsession-options
 [`session.close()`]: #sessioncloseoptions

lib/internal/blocklist.js

@@ -296,4 +296,5 @@ ObjectSetPrototypeOf(InternalBlockList.prototype, BlockList.prototype);
 module.exports = {
   BlockList,
   InternalBlockList,
+  kHandle,
 };

lib/internal/quic/quic.js

@@ -36,6 +36,10 @@ if (!process.features.quic || !getOptionValue('--experimental-quic')) {
 }
 
 const { inspect } = require('internal/util/inspect');
+const {
+  BlockList,
+  kHandle: kBlockListHandle,
+} = require('internal/blocklist');
 
 let debug = require('internal/util/debuglog').debuglog('quic', (fn) => {
   debug = fn;
@@ -318,6 +322,8 @@ const endpointRegistry = new SafeSet();
  * @property {number} [immediateCloseBurst] Burst capacity for immediate close rate limiter
  * @property {number} [sessionCreationRate] Per-host rate limit for session creation (per second)
  * @property {number} [sessionCreationBurst] Per-host burst capacity for session creation rate limiter
+ * @property {net.BlockList} [blockList] Block list for filtering incoming packets by source address
+ * @property {'deny'|'allow'} [blockListPolicy='deny'] How to interpret the block list
  * @property {ArrayBufferView} [resetTokenSecret] The reset token secret
  * @property {bigint|number} [retryTokenExpiration] The retry token expiration
  * @property {number} [rxDiagnosticLoss] The receive diagnostic loss probability (range 0.0-1.0)
@@ -4048,6 +4054,8 @@ class QuicEndpoint {
       immediateCloseBurst,
       sessionCreationRate,
       sessionCreationBurst,
+      blockList,
+      blockListPolicy = 'deny',
       rxDiagnosticLoss,
       txDiagnosticLoss,
       udpReceiveBufferSize,
@@ -4062,6 +4070,16 @@ class QuicEndpoint {
       tokenSecret,
     } = options;
 
+    if (blockList !== undefined) {
+      if (!BlockList.isBlockList(blockList)) {
+        throw new ERR_INVALID_ARG_TYPE('options.blockList',
+                                       'net.BlockList', blockList);
+      }
+    }
+
+    validateOneOf(blockListPolicy, 'options.blockListPolicy',
+                  ['deny', 'allow']);
+
     // All of the other options will be validated internally by the C++ code
     if (address !== undefined && !SocketAddress.isSocketAddress(address)) {
       if (typeof address === 'string') {
@@ -4093,6 +4111,9 @@ class QuicEndpoint {
       immediateCloseBurst,
       sessionCreationRate,
       sessionCreationBurst,
+      // Pass the C++ handle, not the JS BlockList wrapper.
+      blockList: blockList?.[kBlockListHandle],
+      blockListPolicy,
       rxDiagnosticLoss,
       txDiagnosticLoss,
       udpReceiveBufferSize,

lib/internal/quic/stats.js

@@ -68,6 +68,7 @@ const {
   IDX_STATS_ENDPOINT_IMMEDIATE_CLOSE_COUNT,
   IDX_STATS_ENDPOINT_IMMEDIATE_CLOSE_RATE_LIMITED,
   IDX_STATS_ENDPOINT_SESSION_CREATION_RATE_LIMITED,
+  IDX_STATS_ENDPOINT_PACKETS_BLOCKED,
 
   IDX_STATS_SESSION_CREATED_AT,
   IDX_STATS_SESSION_DESTROYED_AT,
@@ -136,6 +137,7 @@ assert(IDX_STATS_ENDPOINT_STATELESS_RESET_RATE_LIMITED !== undefined);
 assert(IDX_STATS_ENDPOINT_IMMEDIATE_CLOSE_COUNT !== undefined);
 assert(IDX_STATS_ENDPOINT_IMMEDIATE_CLOSE_RATE_LIMITED !== undefined);
 assert(IDX_STATS_ENDPOINT_SESSION_CREATION_RATE_LIMITED !== undefined);
+assert(IDX_STATS_ENDPOINT_PACKETS_BLOCKED !== undefined);
 assert(IDX_STATS_SESSION_CREATED_AT !== undefined);
 assert(IDX_STATS_SESSION_DESTROYED_AT !== undefined);
 assert(IDX_STATS_SESSION_CLOSING_AT !== undefined);
@@ -338,6 +340,12 @@ class QuicEndpointStats {
     return this.#handle[IDX_STATS_ENDPOINT_SESSION_CREATION_RATE_LIMITED];
   }
 
+  /** @type {bigint} */
+  get packetsBlocked() {
+    assertIsQuicEndpointStats(this);
+    return this.#handle[IDX_STATS_ENDPOINT_PACKETS_BLOCKED];
+  }
+
   toString() {
     return JSONStringify(this.toJSON());
   }
@@ -363,6 +371,7 @@ class QuicEndpointStats {
       immediateCloseCount,
       immediateCloseRateLimited,
       sessionCreationRateLimited,
+      packetsBlocked,
     } = this;
     return {
       __proto__: null,
@@ -387,6 +396,7 @@ class QuicEndpointStats {
       immediateCloseCount: `${immediateCloseCount}`,
       immediateCloseRateLimited: `${immediateCloseRateLimited}`,
       sessionCreationRateLimited: `${sessionCreationRateLimited}`,
+      packetsBlocked: `${packetsBlocked}`,
     };
   }
 
@@ -421,6 +431,7 @@ class QuicEndpointStats {
       immediateCloseCount,
       immediateCloseRateLimited,
       sessionCreationRateLimited,
+      packetsBlocked,
     } = this;
 
     return `QuicEndpointStats ${inspect({
@@ -443,6 +454,7 @@ class QuicEndpointStats {
       immediateCloseCount,
       immediateCloseRateLimited,
       sessionCreationRateLimited,
+      packetsBlocked,
     }, opts)}`;
   }
 

src/node_sockaddr.cc

@@ -434,8 +434,7 @@ void SocketAddressBlockList::AddSocketAddressMask(
   rules_.emplace_front(std::move(rule));
 }
 
-bool SocketAddressBlockList::Apply(
-    const std::shared_ptr<SocketAddress>& address) {
+bool SocketAddressBlockList::Apply(const SocketAddress& address) {
   Mutex::ScopedLock lock(mutex_);
   for (const auto& rule : rules_) {
     if (rule->Apply(address)) return true;
@@ -457,8 +456,8 @@ SocketAddressBlockList::SocketAddressMaskRule::SocketAddressMaskRule(
     : network(network_), prefix(prefix_) {}
 
 bool SocketAddressBlockList::SocketAddressRule::Apply(
-    const std::shared_ptr<SocketAddress>& address) {
-  return this->address->is_match(*address.get());
+    const SocketAddress& address) {
+  return this->address->is_match(address);
 }
 
 std::string SocketAddressBlockList::SocketAddressRule::ToString() {
@@ -470,8 +469,8 @@ std::string SocketAddressBlockList::SocketAddressRule::ToString() {
 }
 
 bool SocketAddressBlockList::SocketAddressRangeRule::Apply(
-    const std::shared_ptr<SocketAddress>& address) {
-  return *address.get() >= *start.get() && *address.get() <= *end.get();
+    const SocketAddress& address) {
+  return address >= *start.get() && address <= *end.get();
 }
 
 std::string SocketAddressBlockList::SocketAddressRangeRule::ToString() {
@@ -485,8 +484,8 @@ std::string SocketAddressBlockList::SocketAddressRangeRule::ToString() {
 }
 
 bool SocketAddressBlockList::SocketAddressMaskRule::Apply(
-    const std::shared_ptr<SocketAddress>& address) {
-  return address->is_in_network(*network.get(), prefix);
+    const SocketAddress& address) {
+  return address.is_in_network(*network.get(), prefix);
 }
 
 std::string SocketAddressBlockList::SocketAddressMaskRule::ToString() {
@@ -656,7 +655,7 @@ void SocketAddressBlockListWrap::Check(
   SocketAddressBase* addr;
   ASSIGN_OR_RETURN_UNWRAP(&addr, args[0]);
 
-  args.GetReturnValue().Set(wrap->blocklist_->Apply(addr->address()));
+  args.GetReturnValue().Set(wrap->blocklist_->Apply(*addr->address()));
 }
 
 void SocketAddressBlockListWrap::GetRules(

src/node_sockaddr.h

@@ -258,14 +258,14 @@ class SocketAddressBlockList : public MemoryRetainer {
   void AddSocketAddressMask(const std::shared_ptr<SocketAddress>& address,
                             int prefix);
 
-  bool Apply(const std::shared_ptr<SocketAddress>& address);
+  bool Apply(const SocketAddress& address);
 
   size_t size() const { return rules_.size(); }
 
   v8::MaybeLocal<v8::Array> ListRules(Environment* env);
 
   struct Rule : public MemoryRetainer {
-    virtual bool Apply(const std::shared_ptr<SocketAddress>& address) = 0;
+    virtual bool Apply(const SocketAddress& address) = 0;
     inline v8::MaybeLocal<v8::Value> ToV8String(Environment* env);
     virtual std::string ToString() = 0;
   };
@@ -275,7 +275,7 @@ class SocketAddressBlockList : public MemoryRetainer {
 
     explicit SocketAddressRule(const std::shared_ptr<SocketAddress>& address);
 
-    bool Apply(const std::shared_ptr<SocketAddress>& address) override;
+    bool Apply(const SocketAddress& address) override;
     std::string ToString() override;
 
     void MemoryInfo(node::MemoryTracker* tracker) const override;
@@ -290,7 +290,7 @@ class SocketAddressBlockList : public MemoryRetainer {
     SocketAddressRangeRule(const std::shared_ptr<SocketAddress>& start,
                            const std::shared_ptr<SocketAddress>& end);
 
-    bool Apply(const std::shared_ptr<SocketAddress>& address) override;
+    bool Apply(const SocketAddress& address) override;
     std::string ToString() override;
 
     void MemoryInfo(node::MemoryTracker* tracker) const override;
@@ -305,7 +305,7 @@ class SocketAddressBlockList : public MemoryRetainer {
     SocketAddressMaskRule(const std::shared_ptr<SocketAddress>& address,
                           int prefix);
 
-    bool Apply(const std::shared_ptr<SocketAddress>& address) override;
+    bool Apply(const SocketAddress& address) override;
     std::string ToString() override;
 
     void MemoryInfo(node::MemoryTracker* tracker) const override;
@@ -353,6 +353,10 @@ class SocketAddressBlockListWrap : public BaseObject {
                              std::shared_ptr<SocketAddressBlockList> blocklist =
                                  std::make_shared<SocketAddressBlockList>());
 
+  inline const std::shared_ptr<SocketAddressBlockList>& blocklist() const {
+    return blocklist_;
+  }
+
   void MemoryInfo(node::MemoryTracker* tracker) const override;
   SET_MEMORY_INFO_NAME(SocketAddressBlockListWrap)
   SET_SELF_SIZE(SocketAddressBlockListWrap)

src/quic/bindingdata.h

@@ -70,6 +70,7 @@ class SessionManager;
   V(ack_delay_exponent, "ackDelayExponent")                                    \
   V(active_connection_id_limit, "activeConnectionIDLimit")                     \
   V(address_lru_size, "addressLRUSize")                                        \
+  V(allow, "allow")                                                            \
   V(application, "application")                                                \
   V(authoritative, "authoritative")                                            \
   V(bbr, "bbr")                                                                \
@@ -81,6 +82,7 @@ class SessionManager;
   V(crl, "crl")                                                                \
   V(cubic, "cubic")                                                            \
   V(datagram_drop_policy, "datagramDropPolicy")                                \
+  V(deny, "deny")                                                              \
   V(disable_stateless_reset, "disableStatelessReset")                          \
   V(draining_period_multiplier, "drainingPeriodMultiplier")                    \
   V(enable_connect_protocol, "enableConnectProtocol")                          \
@@ -127,6 +129,8 @@ class SessionManager;
   V(immediate_close_burst, "immediateCloseBurst")                              \
   V(session_creation_rate, "sessionCreationRate")                              \
   V(session_creation_burst, "sessionCreationBurst")                            \
+  V(block_list, "blockList")                                                   \
+  V(block_list_policy, "blockListPolicy")                                      \
   V(max_stream_window, "maxStreamWindow")                                      \
   V(max_window, "maxWindow")                                                   \
   V(min_version, "minVersion")                                                 \