docs(security): address documentation gaps for auth, credentials, and policies

docs/deployment/authentication.md

@@ -0,0 +1,93 @@
+---
+title:
+  page: "Authentication Configuration"
+  nav: "Authentication"
+description:
+  main: "Configure device authentication for the OpenClaw gateway, including the NEMOCLAW_DISABLE_DEVICE_AUTH build argument."
+  agent: "Documents the NEMOCLAW_DISABLE_DEVICE_AUTH build argument and device authentication configuration. Use when configuring gateway authentication, disabling device auth, or reviewing auth security implications."
+keywords: ["nemoclaw authentication", "device auth disable build arg"]
+topics: ["generative_ai", "ai_agents"]
+tags: ["nemoclaw", "security", "authentication", "deployment"]
+content:
+  type: reference
+  difficulty: intermediate
+  audience: ["developer", "engineer", "security_engineer"]
+status: published
+---
+
+<!--
+  SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+  SPDX-License-Identifier: Apache-2.0
+-->
+
+# Authentication Configuration
+
+This page documents the device authentication settings for the OpenClaw gateway, including the `NEMOCLAW_DISABLE_DEVICE_AUTH` build argument and related security controls.
+
+## `NEMOCLAW_DISABLE_DEVICE_AUTH`
+
+**Location**: Dockerfile build argument (line 59), propagated to `openclaw.json` as `dangerouslyDisableDeviceAuth`.
+**Default**: `0` (device auth enabled — secure by default).
+
+### What It Does
+
+When set to `1`, the OpenClaw gateway skips the OAuth 2.0 Device Authorization Grant flow.
+Users are not prompted to authenticate via browser-based device code approval before accessing the gateway API.
+
+The setting is baked into `openclaw.json` at image build time and verified by a SHA256 integrity hash at container startup.
+It cannot be changed at runtime.
+
+### When to Disable (Set to `1`)
+
+Disable device auth only when:
+
+- The sandbox runs locally with no network exposure (single-user, localhost only).
+- The environment is headless with no browser available to complete the device auth flow.
+- The NemoClaw Docker sandbox is the only consumer (the default `nemoclaw onboard` flow handles this automatically).
+
+```console
+$ docker build --build-arg NEMOCLAW_DISABLE_DEVICE_AUTH=1 -t nemoclaw-sandbox .
+```
+
+### When to Keep Enabled (Default `0`)
+
+Keep device auth enabled when:
+
+- The gateway is network-accessible beyond localhost.
+- Multiple users or external clients connect to the same instance.
+- The sandbox is exposed via a tunnel (for example, cloudflared) or LAN binding.
+- You need per-device audit trails.
+
+### Security Implications
+
+| Setting | Risk | Use Case |
+|---------|------|----------|
+| `0` (enabled, default) | Requires browser-based approval; gateway generates per-device tokens | Multi-user, external access, production |
+| `1` (disabled) | Anyone with network access to the gateway can use it without authentication | Single-user local/Docker, headless development |
+
+:::{warning}
+Disabling device auth on a network-accessible gateway creates an unauthenticated endpoint.
+Combined with a cloudflared tunnel or LAN-bind changes in remote deployments, this results in a publicly reachable, unauthenticated dashboard.
+:::
+
+### Related Settings
+
+`allowInsecureAuth`
+: Derived automatically from the `CHAT_UI_URL` scheme at build time.
+  When the URL uses `http://` (local development), insecure auth is allowed.
+  When it uses `https://`, insecure auth is blocked.
+  See [Security Best Practices](../security/best-practices.md) for details.
+
+`auth.token`
+: A gateway bearer token generated at build time using `secrets.token_hex(32)`.
+  Unique per image build.
+
+`trustedProxies`
+: IPs allowed to set `X-Forwarded-For` headers.
+  Defaults to `127.0.0.1` and `::1`.
+
+## Next Steps
+
+- [Security Best Practices](../security/best-practices.md) for the full gateway authentication controls reference.
+- [Sandbox Hardening](sandbox-hardening.md) for container-level security measures.
+- [Deploy to a Remote GPU Instance](deploy-to-remote-gpu.md) for remote deployment considerations.

docs/index.md

@@ -271,6 +271,7 @@ Credential Storage <security/credential-storage>
 Deploy to a Remote GPU Instance <deployment/deploy-to-remote-gpu>
 Set Up Telegram <deployment/set-up-telegram-bridge>
 Sandbox Hardening <deployment/sandbox-hardening>
+Authentication <deployment/authentication>
 ```
 
 ```{toctree}

docs/network-policy/customize-network-policy.md

@@ -51,6 +51,52 @@ Each entry in the `network` section defines an endpoint group with the following
 `rules`
 : HTTP methods and paths that are permitted.
 
+### Access Modes
+
+Each endpoint supports two access modes that control how OpenShell inspects traffic:
+
+:::{list-table}
+:header-rows: 1
+:widths: 15 15 70
+
+* - Field
+  - Value
+  - Behavior
+
+* - `protocol`
+  - `rest`
+  - OpenShell terminates TLS and inspects HTTP method/path against `rules`.
+    Only matching requests are forwarded.
+
+* - `access`
+  - `full`
+  - OpenShell creates a raw CONNECT tunnel.
+    No HTTP inspection — all traffic to the host:port is allowed.
+    Use only when protocol-level inspection is not possible, such as `git` SSH-over-HTTPS or WebSocket upgrades.
+
+:::
+
+#### Enforcement and TLS Fields
+
+```yaml
+endpoints:
+  - host: api.example.com
+    port: 443
+    protocol: rest        # Enable HTTP inspection
+    enforcement: enforce  # Block non-matching requests (vs "audit" = log only)
+    tls: terminate        # OpenShell terminates TLS to inspect HTTP layer
+    rules:
+      - allow: { method: GET, path: "/v1/**" }
+      - allow: { method: POST, path: "/v1/chat/completions" }
+```
+
+:::{note}
+`access: full` bypasses all HTTP-layer rules.
+The `github` policy uses `access: full` because `git` requires CONNECT tunneling.
+This means method and path restrictions cannot be enforced on `api.github.com` — the agent has full API access.
+See [Security Best Practices](../security/best-practices.md) for hardening options.
+:::
+
 ### Re-Run Onboard
 
 Apply the updated policy by re-running the onboard wizard:
@@ -103,7 +149,7 @@ Available presets:
 
 | Preset | Endpoints |
 |--------|-----------|
-| `discord` | Discord webhook API |
+| `discord` | Discord REST API, WebSocket gateway, CDN |
 | `docker` | Docker Hub, NVIDIA container registry |
 | `huggingface` | Hugging Face model registry |
 | `jira` | Atlassian Jira API |

docs/reference/network-policies.md

@@ -64,14 +64,9 @@ The following endpoint groups are allowed by default:
   - All methods
 
 * - `github`
-  - `github.com:443`
+  - `github.com:443`, `api.github.com:443`
   - `/usr/bin/gh`, `/usr/bin/git`
-  - All methods, all paths
-
-* - `github_rest_api`
-  - `api.github.com:443`
-  - `/usr/bin/gh`
-  - GET, POST, PATCH, PUT, DELETE
+  - `access: full` (no HTTP inspection — CONNECT tunnel)
 
 * - `clawhub`
   - `clawhub.ai:443`
@@ -91,13 +86,27 @@ The following endpoint groups are allowed by default:
 * - `npm_registry`
   - `registry.npmjs.org:443`
   - `/usr/local/bin/openclaw`, `/usr/local/bin/npm`, `/usr/local/bin/node`
-  - All methods, all paths
+  - `access: full` (no HTTP inspection — CONNECT tunnel)
 
 * - `telegram`
   - `api.telegram.org:443`
-  - Any binary
+  - `/usr/local/bin/node`
   - GET, POST on `/bot*/**`
 
+* - `discord`
+  - `discord.com:443`, `gateway.discord.gg:443`, `cdn.discordapp.com:443`
+  - `/usr/local/bin/node`
+  - REST API allows GET and POST.
+    WebSocket gateway uses `access: full`.
+    CDN allows GET only.
+
+:::
+
+:::{note}
+Endpoints with `access: full` use a raw CONNECT tunnel with no HTTP-layer inspection.
+Method and path restrictions cannot be enforced on these endpoints.
+The `github` policy uses `access: full` because `git` requires CONNECT tunneling.
+See [Security Best Practices](../security/best-practices.md) for details on the L4-only vs L7 inspection trade-off.
 :::
 
 All endpoints use TLS termination and are enforced at port 443.