From 55c6b8efb7da82438d71775917f4a41dfd287b90 Mon Sep 17 00:00:00 2001 From: Rodrigo Uroz Date: Thu, 29 Jan 2026 18:32:19 +0000 Subject: [PATCH] docs(gateway): document autoApproveNodes configuration Add comprehensive documentation for the new gateway.nodes.autoApprove feature: - New section in configuration.md covering: - Full gateway.nodes config with browser, commands, and autoApprove - Field reference table with defaults and descriptions - Security considerations and defense-in-depth explanation - Practical examples for Kubernetes and local development - Updated pairing.md with: - Expanded auto-approval section covering both mechanisms - Configuration-based auto-approval example - Security layers explanation - Cross-reference to configuration docs Co-Authored-By: Claude Opus 4.5 --- docs/gateway/configuration.md | 121 ++++++++++++++++++++++++++++++++++ docs/gateway/pairing.md | 38 ++++++++++- 2 files changed, 157 insertions(+), 2 deletions(-) diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index 1d270974d..908707530 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -2990,6 +2990,127 @@ CLAWDBOT_STATE_DIR=~/.clawdbot-a \ moltbot gateway --port 19001 ``` +### `gateway.nodes` (Node management) + +Configure node-related behavior including browser proxy routing, command allowlists, and auto-approval for node pairing. + +```json5 +{ + gateway: { + nodes: { + // Browser proxy routing (for remote browser control via nodes) + browser: { + mode: "auto", // "auto" | "manual" | "off" + node: "living-room-ipad" // pin a specific node (optional) + }, + // Command allowlist/denylist for node-invoked commands + allowCommands: ["system.run", "browser.*"], + denyCommands: ["system.run.sudo"], + // Auto-approval for node pairing (see below) + autoApprove: { + enabled: false, + roles: ["node"], + ipAllowlist: ["10.0.0.0/8"], + requireToken: true, + auditLog: true + } + } + } +} +``` + +#### `gateway.nodes.autoApprove` (Auto-approval for node pairing) + +Allows trusted nodes to connect without manual approval. Useful for automated deployments (e.g., Kubernetes pods, CI runners) where interactive approval is impractical. + +**Security:** This feature is disabled by default and implements defense-in-depth with multiple independent checks that must all pass. + +```json5 +{ + gateway: { + nodes: { + autoApprove: { + // Master switch - must be explicitly enabled + enabled: true, + // Roles that can be auto-approved (e.g., ["node"]) + // SECURITY: "operator" should typically NOT be included + roles: ["node"], + // IP CIDR allowlist - only these networks are auto-approved + // If empty/unset, only localhost (127.0.0.1, ::1) is allowed + ipAllowlist: [ + "10.0.0.0/8", // Private Class A + "172.16.0.0/12", // Private Class B + "192.168.0.0/16" // Private Class C + ], + // Require valid gateway token for auto-approval (default: true) + // SECURITY: Should almost always be true + requireToken: true, + // Log all auto-approved pairings for audit trail (default: true) + auditLog: true + } + } + } +} +``` + +Field reference: + +| Field | Default | Description | +|-------|---------|-------------| +| `enabled` | `false` | Master switch for auto-approval. Secure default is off. | +| `roles` | `[]` | Roles that can be auto-approved. Empty means no roles. | +| `ipAllowlist` | `[]` | CIDR ranges for allowed IPs. Empty means localhost only. | +| `requireToken` | `true` | Require valid gateway token. Should almost always be true. | +| `auditLog` | `true` | Log auto-approvals with device ID, role, IP, and client info. | + +**Security considerations:** + +- **Disabled by default**: Requires explicit opt-in via `enabled: true`. +- **Role restrictions**: Only roles in the `roles` array are auto-approved. Keep `operator` out unless you have a specific need. +- **IP allowlist**: If not configured, only localhost connections are auto-approved. Use CIDR notation for network ranges. +- **Token validation**: With `requireToken: true` (default), the connecting node must present a valid gateway token. +- **Audit logging**: When `auditLog: true` (default), all non-localhost auto-approvals are logged with full context for security review. + +**Example: Kubernetes cluster** + +```json5 +{ + gateway: { + nodes: { + autoApprove: { + enabled: true, + roles: ["node"], + ipAllowlist: ["10.244.0.0/16"], // Kubernetes pod CIDR + requireToken: true, + auditLog: true + } + } + } +} +``` + +**Example: Local development (localhost only)** + +```json5 +{ + gateway: { + nodes: { + autoApprove: { + enabled: true, + roles: ["node"], + // No ipAllowlist = localhost only (127.0.0.1, ::1) + requireToken: false // OK for local dev + } + } + } +} +``` + +Related docs: +- [Gateway pairing](/gateway/pairing) +- [Nodes CLI](/cli/nodes) +- [Gateway security](/gateway/security) + ### `hooks` (Gateway webhooks) Enable a simple HTTP webhook endpoint on the Gateway HTTP server. diff --git a/docs/gateway/pairing.md b/docs/gateway/pairing.md index 2954e0ae7..7a6487bb2 100644 --- a/docs/gateway/pairing.md +++ b/docs/gateway/pairing.md @@ -64,13 +64,47 @@ Notes: `node.pair.request`. - Requests may include `silent: true` as a hint for auto-approval flows. -## Auto-approval (macOS app) +## Auto-approval + +Auto-approval allows trusted nodes to connect without manual intervention. There are two mechanisms: + +### macOS app (SSH verification) The macOS app can optionally attempt a **silent approval** when: - the request is marked `silent`, and - the app can verify an SSH connection to the gateway host using the same user. -If silent approval fails, it falls back to the normal “Approve/Reject” prompt. +If silent approval fails, it falls back to the normal "Approve/Reject" prompt. + +### Configuration-based auto-approval + +For automated deployments (Kubernetes, CI runners, etc.), you can configure the gateway to auto-approve nodes based on role, IP address, and token validation. + +```json5 +{ + gateway: { + nodes: { + autoApprove: { + enabled: true, + roles: ["node"], // Only auto-approve "node" role + ipAllowlist: ["10.0.0.0/8"], // Only from private network + requireToken: true, // Must have valid gateway token + auditLog: true // Log all auto-approvals + } + } + } +} +``` + +**Security layers (all must pass):** +1. `enabled: true` - Feature must be explicitly enabled +2. Role must be in `roles` array +3. Client IP must match `ipAllowlist` (or be localhost if empty) +4. Valid gateway token required (when `requireToken: true`) + +Localhost connections (127.0.0.1, ::1) are always auto-approved for backward compatibility. + +See [gateway.nodes.autoApprove](/gateway/configuration#gatewaynodes-node-management) for the full configuration reference. ## Storage (local, private)