docs: document gateway node policies

steipete · steipete · commit 2da49ef4acbf · 2026-06-04T17:14:38.000-04:00
diff --git a/src/gateway/hooks-policy.ts b/src/gateway/hooks-policy.ts
@@ -1,3 +1,5 @@
+// Gateway hook routing policy helpers.
+// Normalizes configured agent allowlists for hook dispatch.
 import { normalizeAgentId } from "../routing/session-key.js";
 
 // Hook policy config narrows hooks to explicit agent ids. A wildcard means no
diff --git a/src/gateway/hooks.types.ts b/src/gateway/hooks.types.ts
@@ -1,3 +1,5 @@
+// Gateway hook payload type aliases.
+// Keeps hook-facing channel ids on public plugin channel contracts.
 import type { ChannelId } from "../channels/plugins/types.public.js";
 
 // Gateway hooks use public channel ids so hook payloads stay aligned with plugin
diff --git a/src/gateway/node-command-policy.ts b/src/gateway/node-command-policy.ts
@@ -1,3 +1,5 @@
+// Gateway node command policy.
+// Computes per-platform allowlists from built-in, plugin, runtime, and config inputs.
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import { normalizeUniqueStringEntries } from "@openclaw/normalization-core/string-normalization";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
@@ -292,6 +294,8 @@ function filterApprovedRuntimeCommands(params: {
   if (!isDesktopPlatformId(params.platformId)) {
     return [];
   }
+  // Desktop host commands are not default-enabled for normal node sessions.
+  // A live node can still expose approved commands from its runtime handshake.
   return params.commands.filter((command) => DESKTOP_HOST_COMMANDS.has(command.trim()));
 }
 
@@ -338,6 +342,8 @@ function resolveNodeCommandAllowlistInternal(
   const extra = cfg.gateway?.nodes?.allowCommands ?? [];
   const deny = new Set(cfg.gateway?.nodes?.denyCommands ?? []);
   const dangerousPluginCommands = new Set(listDangerousPluginNodeCommands());
+  // Dangerous plugin commands are excluded from plugin defaults. Explicit
+  // gateway.nodes.allowCommands below can still opt them in for operators.
   const allow = new Set(
     [...base, ...talkCommands, ...pluginDefaults, ...approved, ...extra]
       .map((cmd) => cmd.trim())
diff --git a/src/gateway/node-invoke-plugin-policy.ts b/src/gateway/node-invoke-plugin-policy.ts
@@ -1,3 +1,5 @@
+// Plugin-provided node.invoke policy adapter.
+// Lets plugin policies gate dangerous node commands before transport dispatch.
 import { randomUUID } from "node:crypto";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { PluginApprovalRequestPayload } from "../infra/plugin-approvals.js";
@@ -86,6 +88,8 @@ function createApprovalRuntime(params: {
         record,
         excludeConnId: params.client?.connId,
       });
+      // Approval requests are routed to eligible operator clients only. Falling
+      // back to broadcast is safe because the event payload carries no secret.
       if (approvalClientConnIds) {
         params.context.broadcastToConnIds(
           "plugin.approval.requested",
diff --git a/src/gateway/node-invoke-sanitize.ts b/src/gateway/node-invoke-sanitize.ts
@@ -1,3 +1,5 @@
+// Node invocation forwarding sanitizer.
+// Strips or validates gateway-only control fields before node transport.
 import type { ExecApprovalManager } from "./exec-approval-manager.js";
 import { sanitizeSystemRunParamsForForwarding } from "./node-invoke-system-run-approval.js";
 import type { GatewayClient } from "./server-methods/types.js";
diff --git a/src/gateway/node-invoke-system-run-approval.ts b/src/gateway/node-invoke-system-run-approval.ts
@@ -1,3 +1,5 @@
+// system.run approval sanitizer.
+// Verifies forwarded node exec approvals against stored operator decisions.
 import { asNullableRecord } from "@openclaw/normalization-core/record-coerce";
 import { normalizeNullableString } from "@openclaw/normalization-core/string-coerce";
 import {
diff --git a/src/gateway/resolve-configured-secret-input-string.ts b/src/gateway/resolve-configured-secret-input-string.ts
@@ -1,3 +1,5 @@
+// SecretRef-aware Gateway config string resolver.
+// Resolves configured secret inputs and fallback values without leaking values.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { resolveSecretInputRef } from "../config/types.secrets.js";
@@ -142,6 +144,8 @@ export async function resolveConfiguredSecretInputWithFallback(params: {
   if (!resolved.refConfigured) {
     const fallback = params.readFallback?.();
     if (fallback) {
+      // Fallbacks are only returned after direct config is absent, preserving
+      // explicit config precedence while still allowing credential stores.
       return {
         value: fallback,
         source: "fallback",
@@ -161,6 +165,8 @@ export async function resolveConfiguredSecretInputWithFallback(params: {
 
   const fallback = params.readFallback?.();
   if (fallback) {
+    // An unresolved SecretRef does not block fallback credentials. Callers get
+    // both the source and secretRefConfigured flag for warning policy.
     return {
       value: fallback,
       source: "fallback",
diff --git a/src/gateway/secret-input-paths.ts b/src/gateway/secret-input-paths.ts
@@ -1,3 +1,5 @@
+// Gateway secret-input path helpers.
+// Lists config locations that may contain plaintext values or SecretRefs.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 
 /** Canonical Gateway config paths whose values may be plaintext or secret refs. */

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Gateway hook routing policy helpers.`
	`2`	`+// Normalizes configured agent allowlists for hook dispatch.`
`1`	`3`	`import { normalizeAgentId } from "../routing/session-key.js";`
`2`	`4`
`3`	`5`	`// Hook policy config narrows hooks to explicit agent ids. A wildcard means no`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Gateway hook payload type aliases.`
	`2`	`+// Keeps hook-facing channel ids on public plugin channel contracts.`
`1`	`3`	`import type { ChannelId } from "../channels/plugins/types.public.js";`
`2`	`4`
`3`	`5`	`// Gateway hooks use public channel ids so hook payloads stay aligned with plugin`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Node invocation forwarding sanitizer.`
	`2`	`+// Strips or validates gateway-only control fields before node transport.`
`1`	`3`	`import type { ExecApprovalManager } from "./exec-approval-manager.js";`
`2`	`4`	`import { sanitizeSystemRunParamsForForwarding } from "./node-invoke-system-run-approval.js";`
`3`	`5`	`import type { GatewayClient } from "./server-methods/types.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// system.run approval sanitizer.`
	`2`	`+// Verifies forwarded node exec approvals against stored operator decisions.`
`1`	`3`	`import { asNullableRecord } from "@openclaw/normalization-core/record-coerce";`
`2`	`4`	`import { normalizeNullableString } from "@openclaw/normalization-core/string-coerce";`
`3`	`5`	`import {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Gateway secret-input path helpers.`
	`2`	`+// Lists config locations that may contain plaintext values or SecretRefs.`
`1`	`3`	`import type { OpenClawConfig } from "../config/types.openclaw.js";`
`2`	`4`
`3`	`5`	`/** Canonical Gateway config paths whose values may be plaintext or secret refs. */`