docs: explain how to gate the socket upgrade in a host server

[erkamyaman]

The security guide says to keep auth: false on loopback, but doesn't say how to put a check of your own in front of the socket. We're building Angular DevTools on devframe, and we wrapped the upgrade listeners after setup and missed the one devframe adds later through the server option, so LAN clients could reach the hub socket on Vite with host: true. Switching to handleUpgrade from our own listener fixed it.

This adds a short practice to the security guide and one sentence to the WebSocket binding section of the initiate adapter page, so other integrators don't hit the same thing.

[coldtea-pr-lens]

◈ PR Lens

Note

The title starts with docs:, so PR Lens left this pull request undrawn. Comment @pr-lens draw to draw it

_{github.comment.notice: false in .github/pr-lens.yml turns this note off}

[vercel]

@erkamyaman is attempting to deploy a commit to the NuxtLabs Team on Vercel.

A member of the Team first needs to authorize it.

[Copilot]

Copilot review overview

🟡 Changes recommended

The security guidance incorrectly presents the client-controlled Host header as an access-control check.

Review effort: Balanced
Findings: 1

Open (1)

• Do not use client-controlled Host header as LAN access control · New

What changed in this PR

Documents how integrators can securely control WebSocket upgrades before passing them to a devframe.

Changes:

• Explains when to use handleUpgrade.
• Adds socket-gating security guidance.

File	Description
docs/​content/​2.adapters/​1.initiate.md	Clarifies custom WebSocket upgrade handling.
docs/​content/​1.guide/​14.security.md	Adds security guidance for owned upgrade listeners.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The rejection path must close failed upgrade sockets, and the added adapter text violates the documentation rules.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Do not use client-controlled Host header as LAN access control

Previously missed (2)

In code that hasn't changed since last review

Reject and destroy sockets when upgrade access checks fail

docs/​content/​1.guide/​14.security.md:78

When this access check fails, returning without calling handleUpgrade does not reject the HTTP upgrade. Node leaves the raw socket open, so rejected clients can consume connections indefinitely. Tell the listener owner to send a rejection and destroy the socket on the failure path.

Shorten documentation sentence and remove contraction

docs/​content/​2.adapters/​1.initiate.md:124

The added sentence is 29 words and uses a contraction. This violates the repository's required plain-English documentation rules, which limit descriptive sentences to 25 words and prohibit contractions. Split the binding warning into short statements.

[Copilot]

Copilot review overview

🟡 Changes recommended

The rejection guidance omits raw-socket error handling, which can allow connection errors to crash the host process.

Review effort: Balanced
Findings: 1

Open (1)

• Handle socket errors before rejecting WebSocket upgrades · New

[Copilot]

Copilot review overview

🔵 Needs a closer look

The guidance must prevent custom listeners from rejecting unrelated host WebSocket upgrades.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Handle socket errors before rejecting WebSocket upgrades

Previously missed (2)

In code that hasn't changed since last review

Filter upgrade events before rejecting non-devframe WebSockets

docs/​content/​1.guide/​14.security.md:78

An owned upgrade listener receives every WebSocket upgrade on the shared server, not only the devframe route. As written, a failed check sends 403 and destroys unrelated sockets such as Vite HMR before handleUpgrade gets a chance to apply its internal path filter. Require checking the pathname against ${devtools.base}__ws first and leaving non-matching sockets untouched.

Avoid interfering with host framework WebSocket upgrades

docs/​content/​2.adapters/​1.initiate.md:124

This also needs to state that the host listener sees upgrades for every route. Without filtering for <base>__ws before the custom check, an integrator may reject or otherwise interfere with the host framework's own WebSocket upgrades; handleUpgrade only performs its route filter after the check passes.

[erkamyaman]

Good point from the last review: a custom listener sees every upgrade on the server. Both pages now say to act only on <base>__ws and leave the host framework's own upgrades (like Vite HMR) alone.

[Copilot]

Copilot review overview

🟢 Approval recommended

The guidance accurately reflects the upgrade binding and socket error-handling implementation.

Review effort: Balanced
Findings: None