docs: document gateway connection helpers

src/gateway/server/__tests__/test-utils.ts

@@ -1,3 +1,4 @@
+// Gateway server test utilities build plugin-registry fixtures for nested server suites.
 import { createEmptyPluginRegistry, type PluginRegistry } from "../../../plugins/registry.js";
 
 /**

src/gateway/server/plugins-http/path-context.ts

@@ -1,3 +1,4 @@
+// Plugin HTTP path context canonicalizes request paths for route matching and protected-route auth checks.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import {
   PROTECTED_PLUGIN_ROUTE_PREFIXES,

src/gateway/server/plugins-http/route-auth.ts

@@ -1,3 +1,4 @@
+// Plugin HTTP route auth helpers decide when gateway auth must protect a plugin route path.
 import type { PluginRegistry } from "../../../plugins/registry.js";
 import {
   isProtectedPluginRoutePathFromContext,

src/gateway/server/plugins-http/route-capability.ts

@@ -1,3 +1,4 @@
+// Plugin HTTP route capability helpers discover node-authorized route surfaces from plugin registrations.
 import type { PluginRegistry } from "../../../plugins/registry.js";
 import {
   resolvePluginNodeCapabilityTtlMs,

src/gateway/server/plugins-http/route-match.ts

@@ -1,3 +1,4 @@
+// Plugin HTTP route matching orders registered exact and prefix routes against canonical path candidates.
 import type { PluginRegistry } from "../../../plugins/registry.js";
 import { canonicalizePathVariant } from "../../security-path.js";
 import {

src/gateway/server/ws-connection/auth-context.state.test.ts

@@ -1,3 +1,4 @@
+// WebSocket auth-context state tests cover shared-auth fallback and device-token candidate selection.
 import { describe, expect, it, vi } from "vitest";
 import type { AuthRateLimiter } from "../../auth-rate-limit.js";
 import type { ResolvedGatewayAuth } from "../../auth.js";

src/gateway/server/ws-connection/auth-context.test.ts

@@ -1,3 +1,4 @@
+// WebSocket auth-context tests cover token, password, bootstrap, and device-token decision state.
 import { describe, expect, it, vi } from "vitest";
 import { createAuthRateLimiter, type AuthRateLimiter } from "../../auth-rate-limit.js";
 import { resolveConnectAuthDecision, type ConnectAuthState } from "./auth-context.js";

src/gateway/server/ws-connection/auth-context.ts

@@ -1,3 +1,4 @@
+// WebSocket auth context resolves handshake credentials before device pairing and capability checks run.
 import type { IncomingMessage } from "node:http";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import {

src/gateway/server/ws-connection/auth-messages.ts

@@ -1,3 +1,4 @@
+// WebSocket auth messages format client-specific handshake failures without exposing secret material.
 import {
   isGatewayCliClient,
   isOperatorUiClient,

src/gateway/server/ws-connection/connect-policy.test.ts

@@ -1,3 +1,4 @@
+// WebSocket connect-policy tests cover Control UI pairing, trusted proxy auth, and device identity policy.
 import { describe, expect, test } from "vitest";
 import {
   evaluateMissingDeviceIdentity,

src/gateway/server/ws-connection/connect-policy.ts

@@ -1,3 +1,4 @@
+// WebSocket connect policy resolves Control UI pairing bypasses and missing-device identity decisions.
 import type { ConnectParams } from "../../../../packages/gateway-protocol/src/index.js";
 import type { GatewayRole } from "../../role-policy.js";
 import { roleCanSkipDeviceIdentity } from "../../role-policy.js";

src/gateway/server/ws-connection/handshake-auth-helpers.test.ts

@@ -1,3 +1,4 @@
+// Handshake auth helper tests cover browser-origin security, pairing locality, and auth error details.
 import { describe, expect, it } from "vitest";
 import {
   GATEWAY_CLIENT_IDS,

src/gateway/server/ws-connection/handshake-auth-helpers.ts

@@ -1,3 +1,4 @@
+// Handshake auth helpers classify browser security context, pairing locality, and connect auth details.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import {
   GATEWAY_CLIENT_IDS,

src/gateway/server/ws-connection/message-handler.post-connect-health.test.ts

@@ -1,3 +1,4 @@
+// WebSocket message-handler health tests cover post-connect startup-unavailable and health-gated dispatch.
 import type { IncomingMessage } from "node:http";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { WebSocket } from "ws";

src/gateway/server/ws-connection/message-handler.ts

@@ -1,3 +1,4 @@
+// WebSocket message handler validates frames, dispatches gateway RPCs, manages pairing, and reports responses.
 import fs from "node:fs";
 import type { IncomingMessage } from "node:http";
 import os from "node:os";

src/gateway/server/ws-connection/unauthorized-flood-guard.ts

@@ -1,3 +1,4 @@
+// Unauthorized flood guard rate-limits repeated unauthorized role errors on one WebSocket connection.
 import { resolveIntegerOption } from "@openclaw/normalization-core/number-coercion";
 import { ErrorCodes, type ErrorShape } from "../../../../packages/gateway-protocol/src/index.js";