fix(net-websockets): the WebSocket nonce and masking key come from a CSPRNG (#2401)

Found by asking #2398's own question once more rather than by opening another
module: #2228 put a real CSPRNG behind Guid::NewGuid, so WHAT ELSE IN THIS
RUNTIME NEEDS UNPREDICTABLE BYTES, AND WHERE DOES IT GET THEM? ClientWebSocket
drew BOTH its Sec-WebSocket-Key nonce and its PER-FRAME MASKING KEY from
std::random_device.

THAT IS A DEFECT RATHER THAN A STYLE POINT, AND THIS REPOSITORY HAD ALREADY
MEASURED WHY. The standard explicitly permits a deterministic
std::random_device, and Random.cpp:69-70 records in its own comment "on a
platform whose random_device is deterministic (MinGW-w64's historically was)" --
MinGW-w64 being a supported compile target under CLAUDE.md's platform policy. On
such a platform every connection sends the SAME Sec-WebSocket-Key and every
frame's masking key is PREDICTABLE.

RFC 6455 does not leave this to taste. Section 5.3: "The masking key needs to be
unpredictable; thus, the masking key MUST be derived from a strong source of
entropy, and the masking key for a given frame MUST NOT make it simple for a
server/proxy to predict the masking key for a subsequent frame." Masking exists
to stop cache-poisoning of intermediaries (section 10.3), so a predictable key
defeats the one attack it was introduced for.

.NET'S TWO ROUTES ARE DIFFERENT AND ARE TRANSCRIBED SEPARATELY RATHER THAN
HARMONISED INTO ONE: the nonce is Guid.NewGuid().TryWriteBytes base64-encoded
(WebSocketHandle.Managed.cs:490-494) and the mask is RandomNumberGenerator.Fill
(ManagedWebSocket.cs:762-763). THE NONCE COST NO COMPONENT EDGE AT ALL, because
#2228 already put the CSPRNG behind Guid::NewGuid and Core.Base was already a
public dependency here.

Module graph 41/93 -> 41/94: Security.Cryptography.Random becomes a PRIVATE
dependency of Net.WebSockets, private because the only caller is a file-local
helper so no public header names the type. Catalogue regenerated;
scripts/check_selective_components.sh Net.WebSockets net_websockets.cpp passes
with its 107 tests. CALLING getentropy() DIRECTLY FROM net-websockets WAS
REJECTED ON A RECORDED PRECEDENT: it would be a third copy of the platform
entropy call, the duplication #2354 spent a ticket removing.

WHAT CANNOT BE OBSERVED HERE IS STATED RATHER THAN IMPLIED. On glibc,
std::random_device reads /dev/urandom, so the SOURCE change is not behaviourally
visible on this platform. The evidence is the reference, the RFC, this
repository's own MinGW-w64 measurement, and SYMBOL INSPECTION, which is
precisely discriminating (the #1983 idiom):

    after the repair   random_device=0   NewGuid=1   Fill=1
    nonce reverted     random_device=16  NewGuid=0   Fill=1
    mask reverted      random_device=16  NewGuid=1   Fill=0

Five mutations. THE TWO SOURCE REVERSIONS ARE NOT CAUGHT BY TESTS AND ARE CAUGHT
BY THE SYMBOL TABLE, reported as such rather than as passes. The three
RFC-property mutations -- one mask cached per connection, a constant mask, and a
nonce cached for the process lifetime -- are ALL CAUGHT, and each is the
PLAUSIBLE OPTIMISATION rather than a contrived defect: a cached mask still
unmasks correctly at the server, because both ends agree on whatever key was
sent, so it passes every other assertion in the file. One mutation was INVALID
AS FIRST WRITTEN and was reformulated rather than counted: zeroing the mask left
randomMaskingKey() unreferenced and -Werror=unused-function rejected it.

WHAT IS NEWLY PINNED ARE THE RFC PROPERTIES THEMSELVES, which nothing pinned
before: a 16-byte nonce differing between connections (section 4.1) and a fresh
masking key per frame (section 5.3), plus a separate assertion that no mask is
all zeroes, which the freshness check alone would not catch for a single frame.
Both are reachable from the existing mock-server harness.

Landed under SA-5. No public signature, layout, vtable or noexcept change and no
outlawed spelling -- both helpers are file-local to the .cpp -- so no negative
fixture was owed; the set stays 49/248.

Gate 17,629 / 38 executables: 17,629 run, 17,629 passed, 0 failed, 0 skipped,
recounted from the per-executable logs with every executable run separately and
continuing past failures. +2 on 17,627, in SharpRuntimeTests_Net_WebSockets
(105 -> 107); no other executable moved. Zero build warnings at --parallel 2;
module boundaries green at 41/94.

Author: robertvokac

CLAUDE.md

@@ -3,8 +3,8 @@
 
 # NEXT.md
 
-> **Test-count floor, 2026-08-19 — 17,627 / 38, AND THE GATE IS GREEN.** The complete
-> 38-executable gate reads **17,627 run: 17,627 passed, 0 failed, 0 skipped**, recounted from the
+> **Test-count floor, 2026-08-19 — 17,629 / 38, AND THE GATE IS GREEN.** The complete
+> 38-executable gate reads **17,629 run: 17,629 passed, 0 failed, 0 skipped**, recounted from the
 > per-executable logs with every executable run separately and continuing past failures, zero build
 > warnings at `--parallel 2`. Every checkpoint below this one ends with *"the gate is not green"*;
 > this one does not. Two of the three historical failure sources were environmental and are simply
@@ -28,15 +28,24 @@
 > could not have caught it** — two cases asserting `buffer.size()` after filling a buffer whose size
 > was fixed before the call, both of which pass against a generator that writes nothing.
 >
-> **That is the pattern worth carrying forward**: a module with no test sources is where an
-> undetected divergence survives, and a test that cannot fail is how it survives there. §4b lists
-> the two remaining candidates and says plainly which is and is not worth the measurement.
+> **#2401 — `ClientWebSocket`'s entropy.** Found by asking #2398's question **once more** rather
+> than by opening another module: *#2228 put a real CSPRNG behind `Guid::NewGuid` — what else needs
+> unpredictable bytes, and where does it get them?* `ClientWebSocket` drew **both** its
+> `Sec-WebSocket-Key` nonce and its **per-frame masking key** from `std::random_device`, which the
+> standard permits to be deterministic and which **`Random.cpp:69-70` already records as
+> deterministic on MinGW-w64**, a supported target. RFC 6455 §5.3 requires the mask to come from a
+> strong source of entropy by name.
 >
-> **BOTH WORK QUEUES ARE EMPTY AGAIN.** #2399 closed the same day it was filed (`RNGCryptoServiceProvider`
-> is now `final` and `[[deprecated]]`, with two of .NET's three missing constructors and the third
-> pinned as unreachable), and #2400 is its downstream record. `ticket` has **0 `todo`**; `task` has
-> **0** unclassified (14,979 ignored / 1,082 ported / 140 ignore). Ticket totals: **2,383 done, 9
-> blocked, 1 needs_user, 5 wontfix**. What remains *blocked* needs the user or an external event,
+> **Three patterns worth carrying forward, in order of yield.** (1) **Ask a repaired subsystem's
+> question of its neighbours** — that alone found #2398 and #2401. (2) **A module with no test
+> sources** is where an undetected divergence survives. (3) **A test that cannot fail** is how it
+> survives there: every defect these tickets found sat under one. §4b has the remaining candidates.
+>
+> **BOTH WORK QUEUES ARE EMPTY AGAIN.** Five tickets were filed and closed on 2026-08-19 by this
+> sweep — #2397, #2398, #2399, #2400 (downstream record) and #2401. `ticket` has **0 `todo`**;
+> `task` has **0** unclassified (14,979 ignored / 1,082 ported / 140 ignore). Ticket totals:
+> **2,384 done, 9 blocked, 1 needs_user, 5 wontfix**. Graph **41 / 94** (#2401 added one private
+> edge), negative fixtures **49 / 248** (#2399 added one). What remains *blocked* needs the user or an external event,
 > and each is itemised in §2 below. **§4b says where to look next, and the method that found all
 > three of today's tickets.**
 

NEXT.md

@@ -8,7 +8,7 @@ This file is generated from the CMake component registrations. Run
 `python3 scripts/generate_component_catalog.py` after changing module
 metadata, or use `--check` to verify that the committed catalogue is current.
 
-The graph contains **41 physical modules** and **93 direct production dependency edges**.
+The graph contains **41 physical modules** and **94 direct production dependency edges**.
 
 For each row, the component name and representative public header form a
 minimal consumer example using the template below:
@@ -63,7 +63,7 @@ for maintainers and are not part of the consumer include surface.
 | `Net.Mime` | `modules/net-mime` | static | `Collections.Core`, `Core.Base` | — | — | — | `System/Net/Mime/ContentType.hpp` |
 | `Net.NetworkInformation` | `modules/net-network-information` | static | `ComponentModel`, `Core.Base`, `Net`, `Threading.Tasks` | — | — | — | `System/Net/NetworkInformation/IPStatus.hpp` |
 | `Net.Security` | `modules/net-security` | interface | `Core.Base` | — | — | — | `System/Net/Security/AuthenticationLevel.hpp` |
-| `Net.WebSockets` | `modules/net-websockets` | static | `ComponentModel`, `Core.Base`, `Net`, `Net.Sockets`, `Threading`, `Threading.Tasks`, `Uri` | — | — | — | `System/Net/WebSockets/ClientWebSocket.hpp` |
+| `Net.WebSockets` | `modules/net-websockets` | static | `ComponentModel`, `Core.Base`, `Net`, `Net.Sockets`, `Threading`, `Threading.Tasks`, `Uri` | `Security.Cryptography.Random` | — | — | `System/Net/WebSockets/ClientWebSocket.hpp` |
 | `Security` | `modules/security` | interface | `Core.Base` | — | — | — | `System/Security/Authentication/AuthenticationException.hpp` |
 | `Security.Cryptography` | `modules/security-cryptography` | static | `Core.Base` | — | — | — | `System/Security/Cryptography/AuthenticationTagMismatchException.hpp` |
 | `Security.Cryptography.Random` | `modules/security-cryptography-random` | static | `Core.Base` | — | — | `bcrypt` on Windows (private) | `System/Security/Cryptography/RNGCryptoServiceProvider.hpp` |

docs/ComponentCatalog.md

@@ -0,0 +1,88 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- Copyright (c) Robert Vokac and contributors -->
+
+# Migration — the WebSocket nonce and masking key come from a CSPRNG (ticket #2401)
+
+*2026-08-19.* `ClientWebSocket` drew its `Sec-WebSocket-Key` nonce **and** its per-frame masking key
+from `std::random_device`. Both now come from the platform CSPRNG, by .NET's own two routes.
+
+Landed under **SA-5**. **No public signature, layout, vtable or `noexcept` change** — both helpers
+are file-local to `ClientWebSocket.cpp`. **Nothing a caller can observe changed**; what changed is
+where the bytes come from, plus one declared component edge.
+
+---
+
+## 1. Why `std::random_device` was wrong here
+
+`std::random_device` is **not required to be a CSPRNG**. The standard explicitly permits a
+deterministic implementation, and **this repository has already measured one**: `Random.cpp:69-70`
+records, in its own comment, *"on a platform whose random_device is deterministic (MinGW-w64's
+historically was)"* — and MinGW-w64 is a supported compile target under `CLAUDE.md`'s platform
+policy. On such a platform every connection would have sent the **same** `Sec-WebSocket-Key`, and
+every frame's masking key would have been **predictable**.
+
+RFC 6455 does not leave this to taste. §5.3:
+
+> The masking key needs to be unpredictable; thus, the masking key MUST be derived from a strong
+> source of entropy, and the masking key for a given frame MUST NOT make it simple for a
+> server/proxy to predict the masking key for a subsequent frame.
+
+Masking exists to stop cache-poisoning of intermediaries (§10.3), so a predictable key defeats the
+one attack it was introduced for. §4.1 requires the nonce to be *"selected randomly for each
+connection"*.
+
+## 2. The two routes are .NET's, and they are different
+
+| | Source | Reference |
+|---|---|---|
+| `Sec-WebSocket-Key` nonce | `Guid::NewGuid().ToByteArray()` | `WebSocketHandle.Managed.cs:490-494` — `Guid.NewGuid().TryWriteBytes(bytes)`, base64-encoded |
+| per-frame masking key | `RandomNumberGenerator::Fill` | `ManagedWebSocket.cs:762-763` — `WriteRandomMask` is `RandomNumberGenerator.Fill(...)` |
+
+They are transcribed **separately rather than harmonised into one**, because that is how .NET has
+them. Since **#2228** this port's `Guid::NewGuid()` draws from the platform CSPRNG, so the nonce
+route costs **no component edge at all** — `Core.Base` was already a public dependency.
+
+A v4 GUID fixes 6 of its 128 bits (version and variant), so the nonce carries **122 bits of entropy
+rather than 128**. That is .NET's own arithmetic here, not a shortcut this port took.
+
+## 3. The one build-facing change: a new component edge
+
+`Net.WebSockets` gains **`Security.Cryptography.Random` as a `PRIVATE` dependency**. The module
+graph goes **41 / 93 → 41 / 94** and `docs/ComponentCatalog.md` is regenerated.
+
+It is `PRIVATE` because the only caller is a file-local helper in `ClientWebSocket.cpp`: no public
+header names the type, and no consumer inherits the include path. A consumer doing a **selective
+component build** of `Net.WebSockets` will now also configure and link
+`Security.Cryptography.Random`; verified by running
+`scripts/check_selective_components.sh Net.WebSockets net_websockets.cpp`, which passes with its
+107 tests.
+
+**The alternative was rejected on a recorded precedent.** Calling `getentropy()` directly from
+`net-websockets` would avoid the edge and would be a **third** copy of the platform entropy call —
+the duplication #2354 spent a whole ticket removing.
+
+## 4. What can and cannot be verified here
+
+**Stated rather than implied.** On glibc, `std::random_device` reads `/dev/urandom`, so **the source
+change is not behaviourally observable on this platform**. Its evidence is the reference, RFC 6455,
+this repository's own MinGW-w64 measurement, and **symbol inspection**, which is precisely
+discriminating:
+
+| Build | `random_device` | `Guid::NewGuid` | `RandomNumberGenerator::Fill` |
+|---|---|---|---|
+| after the repair | **0** | 1 | 1 |
+| nonce reverted | 16 | **0** | 1 |
+| mask reverted | 16 | 1 | **0** |
+
+**What is newly pinned are the RFC properties themselves**, which nothing pinned before: a 16-byte
+nonce that differs between connections, and a **fresh** masking key per frame. Both are reachable
+from the existing mock-server harness, which already reads the key out of the handshake and the
+4-byte mask out of each frame.
+
+Five mutations. The two source reversions are **not caught by tests and are caught by the symbol
+table** — reported as such rather than as passes. The three RFC-property mutations — caching one
+mask per connection, a constant mask, and caching the nonce for the process lifetime — are **all
+caught**, and each is the plausible optimisation rather than a contrived defect: a cached mask still
+unmasks correctly at the server, because both ends agree on whatever key was sent. One mutation was
+**invalid as first written and was reformulated rather than counted**: zeroing the mask left
+`randomMaskingKey()` unreferenced, so `-Werror=unused-function` rejected it at compile time.

docs/Migration-WebSocketEntropySource.md

@@ -19,4 +19,13 @@ sharp_runtime_register_module(
         Threading
         Threading.Tasks
         Uri
+    # Security.Cryptography.Random became a PRIVATE dependency with ticket #2401: the per-frame
+    # masking key must come from a CSPRNG (RFC 6455 section 5.3 -- "MUST be derived from a strong
+    # source of entropy"), and .NET spells that RandomNumberGenerator.Fill
+    # (ManagedWebSocket.cs:762-763). It is PRIVATE because the only caller is a file-local helper
+    # in ClientWebSocket.cpp, so no public header names the type and no consumer inherits the
+    # edge. The Sec-WebSocket-Key nonce needed no edge at all: .NET builds it from Guid.NewGuid()
+    # (WebSocketHandle.Managed.cs:490-494), and Core.Base is already public here.
+    PRIVATE_DEPENDENCIES
+        Security.Cryptography.Random
 )

modules/net-websockets/CMakeLists.txt

@@ -9,15 +9,16 @@
 #include <array>
 #include <cstring>
 #include <map>
-#include <random>
 #include "System/ArgumentException.hpp"
 #include "System/ArgumentOutOfRangeException.hpp"
 #include "System/Convert.hpp"
+#include "System/Guid.hpp"
 #include "System/InvalidOperationException.hpp"
 #include "System/Net/IPEndPoint.hpp"
 #include "System/Net/detail/ProtocolFieldValidation.hpp"
 #include "System/Net/WebSockets/WebSocketException.hpp"
 #include "System/PlatformNotSupportedException.hpp"
+#include "System/Security/Cryptography/RandomNumberGenerator.hpp"
 #include "System/Threading/Tasks/TaskCanceledException.hpp"
 #include <chrono>
 #include <condition_variable>
@@ -101,16 +102,41 @@ namespace {
 
     constexpr const char* kWebSocketGuid = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
 
-    std::array<bytecs, 16> randomBytes16() {
-        std::random_device rd;
-        std::array<bytecs, 16> bytes{};
-        for (auto& b : bytes) b = static_cast<bytecs>(rd() & 0xFF);
-        return bytes;
-    }
-
+    // BOTH OF THESE USED `std::random_device`, AND THAT IS A DEFECT RATHER THAN A STYLE POINT
+    // (#2401). The standard explicitly permits a deterministic `std::random_device`, and THIS
+    // REPOSITORY HAS ALREADY MEASURED ONE: `Random.cpp:69-70` records "on a platform whose
+    // random_device is deterministic (MinGW-w64's historically was)", and MinGW-w64 is a
+    // supported compile target of this project. On such a platform every connection would send
+    // the SAME Sec-WebSocket-Key and every frame's masking key would be predictable.
+    //
+    // RFC 6455 does not leave that to taste. Section 5.3: "The masking key needs to be
+    // unpredictable; thus, the masking key MUST be derived from a strong source of entropy, and
+    // the masking key for a given frame MUST NOT make it simple for a server/proxy to predict the
+    // masking key for a subsequent frame." Masking exists to stop cache-poisoning of
+    // intermediaries (RFC 6455 section 10.3), so a predictable key defeats the one attack it was
+    // introduced for.
+    //
+    // .NET USES A CSPRNG FOR BOTH, BY TWO DIFFERENT ROUTES, and each is transcribed as it stands
+    // rather than harmonised into one.
+
+    /// The Sec-WebSocket-Key nonce. `WebSocketHandle.Managed.cs:490-494` --
+    /// `Guid.NewGuid().TryWriteBytes(bytes)`, base64-encoded. Since #2228 this port's
+    /// `Guid::NewGuid()` draws from the platform CSPRNG, so this route costs no component edge:
+    /// `Core.Base` is already a public dependency. A v4 GUID fixes 6 of its 128 bits (version and
+    /// variant), so the nonce carries 122 bits of entropy rather than 128 -- which is .NET's own
+    /// arithmetic here, not a shortcut taken by this port.
+    std::array<bytecs, 16> randomBytes16() { return System::Guid::NewGuid().ToByteArray(); }
+
+    /// The per-frame masking key. `ManagedWebSocket.cs:762-763` -- `WriteRandomMask` is
+    /// `RandomNumberGenerator.Fill(buffer.AsSpan(offset, MaskLength))`. That is what the
+    /// `Security.Cryptography.Random` PRIVATE dependency buys; calling `getentropy()` directly from
+    /// here instead would be a third copy of the platform entropy call, which is the duplication
+    /// #2354 spent a ticket removing.
     uint32_t randomMaskingKey() {
-        std::random_device rd;
-        return rd();
+        std::vector<bytecs> key(4);
+        System::Security::Cryptography::RandomNumberGenerator::Fill(key);
+        return static_cast<uint32_t>(key[0]) | (static_cast<uint32_t>(key[1]) << 8) |
+               (static_cast<uint32_t>(key[2]) << 16) | (static_cast<uint32_t>(key[3]) << 24);
     }
 
 } // namespace