From 11d17b3c38db861fa574ecdb3f8dc188d73ad9db Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 4 Apr 2026 13:52:19 +0100
Subject: [PATCH] docs: refresh control ui device identity refs

---
 docs/gateway/protocol.md       |  1 +
 docs/gateway/security/index.md |  5 +++++
 docs/web/control-ui.md         | 14 ++++++++++++++
 3 files changed, 20 insertions(+)

diff --git a/docs/gateway/protocol.md b/docs/gateway/protocol.md
index 8712a00e3f0..58c8a650818 100644
--- a/docs/gateway/protocol.md
+++ b/docs/gateway/protocol.md
@@ -300,6 +300,7 @@ The Gateway treats these as **claims** and enforces server-side allowlists.
 - All WS clients must include `device` identity during `connect` (operator + node).
   Control UI can omit it only in these modes:
   - `gateway.controlUi.allowInsecureAuth=true` for localhost-only insecure HTTP compatibility.
+  - successful `gateway.auth.mode: "trusted-proxy"` operator Control UI auth.
   - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (break-glass, severe security downgrade).
 - All connections must sign the server-provided `connect.challenge` nonce.
 
diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md
index 154129e71bb..55a326ac3c5 100644
--- a/docs/gateway/security/index.md
+++ b/docs/gateway/security/index.md
@@ -359,6 +359,11 @@ For break-glass scenarios only, `gateway.controlUi.dangerouslyDisableDeviceAuth`
 disables device identity checks entirely. This is a severe security downgrade;
 keep it off unless you are actively debugging and can revert quickly.
 
+Separate from those dangerous flags, successful `gateway.auth.mode: "trusted-proxy"`
+can admit **operator** Control UI sessions without device identity. That is an
+intentional auth-mode behavior, not an `allowInsecureAuth` shortcut, and it still
+does not extend to node-role Control UI sessions.
+
 `openclaw security audit` warns when this setting is enabled.
 
 ## Insecure or dangerous flags summary
diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md
index 044d833d04e..45d3b208215 100644
--- a/docs/web/control-ui.md
+++ b/docs/web/control-ui.md
@@ -164,6 +164,12 @@ If you open the dashboard over plain HTTP (`http://<lan-ip>` or `http://<tailsca
 the browser runs in a **non-secure context** and blocks WebCrypto. By default,
 OpenClaw **blocks** Control UI connections without device identity.
 
+Documented exceptions:
+
+- localhost-only insecure HTTP compatibility with `gateway.controlUi.allowInsecureAuth=true`
+- successful operator Control UI auth through `gateway.auth.mode: "trusted-proxy"`
+- break-glass `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
+
 **Recommended fix:** use HTTPS (Tailscale Serve) or open the UI locally:
 
 - `https://<magicdns>/` (Serve)
@@ -203,6 +209,14 @@ OpenClaw **blocks** Control UI connections without device identity.
 `dangerouslyDisableDeviceAuth` disables Control UI device identity checks and is a
 severe security downgrade. Revert quickly after emergency use.
 
+Trusted-proxy note:
+
+- successful trusted-proxy auth can admit **operator** Control UI sessions without
+  device identity
+- this does **not** extend to node-role Control UI sessions
+- same-host loopback reverse proxies still do not satisfy trusted-proxy auth; see
+  [Trusted Proxy Auth](/gateway/trusted-proxy-auth)
+
 See [Tailscale](/gateway/tailscale) for HTTPS setup guidance.
 
 ## Building the UI