mirror of
https://github.com/moltbot/moltbot.git
synced 2026-04-26 16:06:16 +00:00
docs: refresh gateway auth overview mirrors
This commit is contained in:
Peter Steinberger
@@ -2696,7 +2696,7 @@ See [Plugins](/tools/plugin).
|
||||
- `bind`: `auto`, `loopback` (default), `lan` (`0.0.0.0`), `tailnet` (Tailscale IP only), or `custom`.
|
||||
- **Legacy bind aliases**: use bind mode values in `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), not host aliases (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`).
|
||||
- **Docker note**: the default `loopback` bind listens on `127.0.0.1` inside the container. With Docker bridge networking (`-p 18789:18789`), traffic arrives on `eth0`, so the gateway is unreachable. Use `--network host`, or set `bind: "lan"` (or `bind: "custom"` with `customBindHost: "0.0.0.0"`) to listen on all interfaces.
|
||||
- **Auth**: required by default. Non-loopback binds require a shared token/password. Onboarding wizard generates a token by default.
|
||||
- **Auth**: required by default. Non-loopback binds require gateway auth. In practice that means a shared token/password or an identity-aware reverse proxy with `gateway.auth.mode: "trusted-proxy"`. Onboarding wizard generates a token by default.
|
||||
- If both `gateway.auth.token` and `gateway.auth.password` are configured (including SecretRefs), set `gateway.auth.mode` explicitly to `token` or `password`. Startup and service install/repair flows fail when both are configured and mode is unset.
|
||||
- `gateway.auth.mode: "none"`: explicit no-auth mode. Use only for trusted local loopback setups; this is intentionally not offered by onboarding prompts.
|
||||
- `gateway.auth.mode: "trusted-proxy"`: delegate auth to an identity-aware reverse proxy and trust identity headers from `gateway.trustedProxies` (see [Trusted Proxy Auth](/gateway/trusted-proxy-auth)). This mode expects a **non-loopback** proxy source; same-host loopback reverse proxies do not satisfy trusted-proxy auth.
|
||||
|
||||
@@ -302,7 +302,7 @@ Events are not replayed. On sequence gaps, refresh state (`health`, `system-pres
|
||||
|
||||
| Signature | Likely issue |
|
||||
| -------------------------------------------------------------- | ------------------------------------------------------------------------------- |
|
||||
| `refusing to bind gateway ... without auth` | Non-loopback bind without token/password |
|
||||
| `refusing to bind gateway ... without auth` | Non-loopback bind without a valid gateway auth path |
|
||||
| `another gateway instance is already listening` / `EADDRINUSE` | Port conflict |
|
||||
| `Gateway start blocked: set gateway.mode=local` | Config set to remote mode, or local-mode stamp is missing from a damaged config |
|
||||
| `unauthorized` during connect | Auth mismatch between client and gateway |
|
||||
|
||||
@@ -104,14 +104,14 @@ If you need hostile-user isolation, split trust boundaries by OS user/host and r
|
||||
|
||||
Use this as the quick model when triaging risk:
|
||||
|
||||
| Boundary or control | What it means | Common misread |
|
||||
| ------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------- |
|
||||
| `gateway.auth` (token/password/device auth) | Authenticates callers to gateway APIs | "Needs per-message signatures on every frame to be secure" |
|
||||
| `sessionKey` | Routing key for context/session selection | "Session key is a user auth boundary" |
|
||||
| Prompt/content guardrails | Reduce model abuse risk | "Prompt injection alone proves auth bypass" |
|
||||
| `canvas.eval` / browser evaluate | Intentional operator capability when enabled | "Any JS eval primitive is automatically a vuln in this trust model" |
|
||||
| Local TUI `!` shell | Explicit operator-triggered local execution | "Local shell convenience command is remote injection" |
|
||||
| Node pairing and node commands | Operator-level remote execution on paired devices | "Remote device control should be treated as untrusted user access by default" |
|
||||
| Boundary or control | What it means | Common misread |
|
||||
| --------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------- |
|
||||
| `gateway.auth` (token/password/trusted-proxy/device auth) | Authenticates callers to gateway APIs | "Needs per-message signatures on every frame to be secure" |
|
||||
| `sessionKey` | Routing key for context/session selection | "Session key is a user auth boundary" |
|
||||
| Prompt/content guardrails | Reduce model abuse risk | "Prompt injection alone proves auth bypass" |
|
||||
| `canvas.eval` / browser evaluate | Intentional operator capability when enabled | "Any JS eval primitive is automatically a vuln in this trust model" |
|
||||
| Local TUI `!` shell | Explicit operator-triggered local execution | "Local shell convenience command is remote injection" |
|
||||
| Node pairing and node commands | Operator-level remote execution on paired devices | "Remote device control should be treated as untrusted user access by default" |
|
||||
|
||||
## Not vulnerabilities by design
|
||||
|
||||
@@ -758,7 +758,7 @@ If you load canvas content in a normal browser, treat it like any other untruste
|
||||
Bind mode controls where the Gateway listens:
|
||||
|
||||
- `gateway.bind: "loopback"` (default): only local clients can connect.
|
||||
- Non-loopback binds (`"lan"`, `"tailnet"`, `"custom"`) expand the attack surface. Only use them with a shared token/password and a real firewall.
|
||||
- Non-loopback binds (`"lan"`, `"tailnet"`, `"custom"`) expand the attack surface. Only use them with gateway auth (shared token/password or a correctly configured non-loopback trusted proxy) and a real firewall.
|
||||
|
||||
Rules of thumb:
|
||||
|
||||
@@ -863,7 +863,7 @@ In minimal mode, the Gateway still broadcasts enough for device discovery (`role
|
||||
|
||||
### 0.5) Lock down the Gateway WebSocket (local auth)
|
||||
|
||||
Gateway auth is **required by default**. If no token/password is configured,
|
||||
Gateway auth is **required by default**. If no valid gateway auth path is configured,
|
||||
the Gateway refuses WebSocket connections (fail‑closed).
|
||||
|
||||
Onboarding generates a token by default (even for loopback) so
|
||||
|
||||
@@ -177,7 +177,7 @@ Look for:
|
||||
Common signatures:
|
||||
|
||||
- `Gateway start blocked: set gateway.mode=local` or `existing config is missing gateway.mode` → local gateway mode is not enabled, or the config file was clobbered and lost `gateway.mode`. Fix: set `gateway.mode="local"` in your config, or re-run `openclaw onboard --mode local` / `openclaw setup` to restamp the expected local-mode config. If you are running OpenClaw via Podman, the default config path is `~/.openclaw/openclaw.json`.
|
||||
- `refusing to bind gateway ... without auth` → non-loopback bind without token/password.
|
||||
- `refusing to bind gateway ... without auth` → non-loopback bind without a valid gateway auth path (token/password, or trusted-proxy where configured).
|
||||
- `another gateway instance is already listening` / `EADDRINUSE` → port conflict.
|
||||
|
||||
Related:
|
||||
|
||||
@@ -171,7 +171,7 @@ flowchart TD
|
||||
Common log signatures:
|
||||
|
||||
- `Gateway start blocked: set gateway.mode=local` or `existing config is missing gateway.mode` → gateway mode is remote, or the config file is missing the local-mode stamp and should be repaired.
|
||||
- `refusing to bind gateway ... without auth` → non-loopback bind without token/password.
|
||||
- `refusing to bind gateway ... without auth` → non-loopback bind without a valid gateway auth path (token/password, or trusted-proxy where configured).
|
||||
- `another gateway instance is already listening` or `EADDRINUSE` → port already taken.
|
||||
|
||||
Deep pages:
|
||||
|
||||
@@ -95,8 +95,8 @@ Open:
|
||||
|
||||
## Security notes
|
||||
|
||||
- Gateway auth is required by default (token/password or Tailscale identity headers).
|
||||
- Non-loopback binds still **require** a shared token/password (`gateway.auth` or env).
|
||||
- Gateway auth is required by default (token, password, trusted-proxy, or Tailscale Serve identity headers when enabled).
|
||||
- Non-loopback binds still **require** gateway auth. In practice that means token/password auth or an identity-aware reverse proxy with `gateway.auth.mode: "trusted-proxy"`.
|
||||
- The wizard generates a gateway token by default (even on loopback).
|
||||
- The UI sends `connect.params.auth.token` or `connect.params.auth.password`.
|
||||
- For non-loopback Control UI deployments, set `gateway.controlUi.allowedOrigins`
|
||||
|
||||
Reference in New Issue
Block a user