Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(auth): Restrict trusted mode without API key to localhost (#1279)

Jiahui Zhou1a3bd311996c
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index f088bd90f..5dc7d0970 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -854,12 +854,12 @@ When running OpenViking as an HTTP service, add a `server` section to `ov.conf`:
| `host` | str | Bind address | `0.0.0.0` |
| `port` | int | Bind port | `1933` |
| `auth_mode` | str | Authentication mode: `"api_key"` or `"trusted"`. Default is `"api_key"` | `"api_key"` |
-| `root_api_key` | str | Root API key for multi-tenant auth in `api_key` mode. In `trusted` mode it is optional extra protection, not the source of user identity | `null` |
+| `root_api_key` | str | Root API key for multi-tenant auth in `api_key` mode. In `trusted` mode it is optional on localhost, but required for any non-localhost deployment; it does not become the source of user identity | `null` |
| `cors_origins` | list | Allowed CORS origins | `["*"]` |
`api_key` mode uses API keys and is the default. `trusted` mode trusts `X-OpenViking-Account` / `X-OpenViking-User` headers from a trusted gateway or internal caller.
-When `root_api_key` is configured in `api_key` mode, the server enables multi-tenant authentication. Use the Admin API to create accounts and user keys. In `trusted` mode, ordinary requests do not require user registration first; each request is resolved as `USER` from the injected identity headers. Development mode only applies when `auth_mode = "api_key"` and `root_api_key` is not set.
+When `root_api_key` is configured in `api_key` mode, the server enables multi-tenant authentication. Use the Admin API to create accounts and user keys. In `trusted` mode, ordinary requests do not require user registration first; each request is resolved as `USER` from the injected identity headers. However, skipping `root_api_key` in `trusted` mode is allowed only on localhost. Development mode only applies when `auth_mode = "api_key"` and `root_api_key` is not set.
For startup and deployment details see [Deployment](./03-deployment.md), for authentication see [Authentication](./04-authentication.md).
diff --git a/docs/en/guides/04-authentication.md b/docs/en/guides/04-authentication.md
index 2343bb9cb..8adb5ccd6 100644
--- a/docs/en/guides/04-authentication.md
+++ b/docs/en/guides/04-authentication.md
@@ -18,9 +18,9 @@ All API keys are plain random tokens with no embedded identity. The server resol
| Mode | `server.auth_mode` | Identity Source | Typical Use |
|------|--------------------|-----------------|-------------|
| API key mode | `"api_key"` | API key, with optional tenant headers for root requests | Standard multi-tenant deployment |
-| Trusted mode | `"trusted"` | `X-OpenViking-Account` / `X-OpenViking-User` / optional `X-OpenViking-Agent` headers | Behind a trusted gateway or internal network boundary |
+| Trusted mode | `"trusted"` | `X-OpenViking-Account` / `X-OpenViking-User` / optional `X-OpenViking-Agent` headers, plus `root_api_key` on non-localhost deployments | Behind a trusted gateway or internal network boundary |
-`api_key` is the default and standard production mode. `trusted` is an alternative mode for deployments where an upstream gateway or trusted internal caller injects identity headers on every request.
+`api_key` is the default and standard production mode. `trusted` is an alternative mode for deployments where an upstream gateway or trusted internal caller injects identity headers on every request. In `trusted` mode, running without `root_api_key` is allowed only when the server binds to localhost; non-localhost `trusted` deployments must configure `root_api_key`.
## Setting Up (Server Side)
diff --git a/docs/zh/guides/04-authentication.md b/docs/zh/guides/04-authentication.md
index 3101df057..40e6d3a1a 100644
--- a/docs/zh/guides/04-authentication.md
+++ b/docs/zh/guides/04-authentication.md
@@ -18,9 +18,9 @@ OpenViking 使用两层 API Key 体系:
| 模式 | `server.auth_mode` | 身份来源 | 典型使用场景 |
|------|--------------------|----------|--------------|
| API Key 模式 | `"api_key"` | API Key,root 请求可附带租户请求头 | 标准多租户部署 |
-| Trusted 模式 | `"trusted"` | `X-OpenViking-Account` / `X-OpenViking-User` / 可选 `X-OpenViking-Agent` 请求头 | 部署在受信网关或内网边界之后 |
+| Trusted 模式 | `"trusted"` | `X-OpenViking-Account` / `X-OpenViking-User` / 可选 `X-OpenViking-Agent` 请求头;非 localhost 部署还必须配置 `root_api_key` | 部署在受信网关或内网边界之后 |
-`api_key` 是默认模式,也是标准生产部署方式。`trusted` 是替代模式,适合由上游网关或受信内网调用方在每个请求里显式注入身份头。
+`api_key` 是默认模式,也是标准生产部署方式。`trusted` 是替代模式,适合由上游网关或受信内网调用方在每个请求里显式注入身份头。在 `trusted` 模式下,只有服务绑定到 localhost 时才允许不配置 `root_api_key`;只要是非 localhost 部署,就必须配置 `root_api_key`。
## 服务端配置
diff --git a/openviking/console/README.md b/openviking/console/README.md
index 09d19ba8d..0dd8be6de 100644
--- a/openviking/console/README.md
+++ b/openviking/console/README.md
@@ -30,7 +30,7 @@ http://127.0.0.1:8020/
```
4. In **Settings**, configure headers for your upstream auth mode.
-`api_key` is the default server mode, so in that mode you normally paste `X-API-Key` and click **Save** (or press Enter). If the upstream server runs in `trusted` mode, you usually do not need `X-API-Key` for ordinary requests; instead set `X-OpenViking-Account` and `X-OpenViking-User` (and optionally `X-OpenViking-Agent`).
+`api_key` is the default server mode, so in that mode you normally paste `X-API-Key` and click **Save** (or press Enter). If the upstream server runs in `trusted` mode, you can omit `X-API-Key` for ordinary requests only when that server is localhost-only and has no `root_api_key`; otherwise you still need `X-API-Key`, and you should also set `X-OpenViking-Account` and `X-OpenViking-User` (and optionally `X-OpenViking-Agent`).
`X-API-Key` is stored locally in the browser and restored into the current tab.
When the upstream server runs in `trusted` mode, ordinary access does not require user registration first. If you try account or user management actions against Admin API endpoints in `trusted` mode, the server now returns an explicit error explaining that `trusted` mode resolves requests as `USER` and that account/user management requires `api_key` mode with `root_api_key`.
diff --git a/openviking/server/app.py b/openviking/server/app.py
index fed0b128b..5e1a0e287 100644
--- a/openviking/server/app.py
+++ b/openviking/server/app.py
@@ -96,8 +96,9 @@ def create_app(
else:
logger.warning(
"Trusted mode enabled: authentication uses X-OpenViking-Account/User/Agent "
- "headers without API keys. Only expose this server behind a trusted "
- "network boundary or identity-injecting gateway."
+ "headers without API keys. This is only allowed on localhost. "
+ "Only expose this server behind a trusted network boundary or "
+ "identity-injecting gateway after configuring server.root_api_key."
)
else:
app.state.api_key_manager = None
diff --git a/openviking/server/config.py b/openviking/server/config.py
index 5e68f1d58..551141b83 100644
--- a/openviking/server/config.py
+++ b/openviking/server/config.py
@@ -135,13 +135,22 @@ def validate_server_config(config: ServerConfig) -> None:
sys.exit(1)
if config.auth_mode == "trusted":
- if not _is_localhost(config.host):
- logger.warning(
- "SECURITY: server.auth_mode='trusted' on non-localhost host '%s'. "
- "Only use this behind a trusted network boundary or identity-injecting gateway.",
- config.host,
- )
- return
+ if config.root_api_key:
+ return
+ if _is_localhost(config.host):
+ return
+ logger.error(
+ "SECURITY: server.auth_mode='trusted' requires server.root_api_key when "
+ "server.host is '%s' (non-localhost). Only localhost trusted mode may run "
+ "without an API key.",
+ config.host,
+ )
+ logger.error(
+ "To fix, either:\n"
+ " 1. Set server.root_api_key in ov.conf, or\n"
+ ' 2. Bind trusted mode to localhost (server.host = "127.0.0.1")'
+ )
+ sys.exit(1)
if config.root_api_key:
return
diff --git a/tests/server/test_auth.py b/tests/server/test_auth.py
index dd36b1a90..aa3a7e152 100644
--- a/tests/server/test_auth.py
+++ b/tests/server/test_auth.py
@@ -784,7 +784,15 @@ def test_validate_with_key_any_host_passes():
validate_server_config(config) # should not raise
-def test_validate_trusted_mode_without_key_non_localhost_passes():
- """Trusted mode should bypass the localhost-only dev-mode restriction."""
+def test_validate_trusted_mode_without_key_localhost_passes():
+ """Trusted mode without root_api_key should still be allowed on localhost only."""
+ for host in ("127.0.0.1", "localhost", "::1"):
+ config = ServerConfig(host=host, root_api_key=None, auth_mode="trusted")
+ validate_server_config(config)
+
+
+def test_validate_trusted_mode_without_key_non_localhost_raises():
+ """Trusted mode without root_api_key should be rejected off localhost."""
config = ServerConfig(host="0.0.0.0", root_api_key=None, auth_mode="trusted")
- validate_server_config(config)
+ with pytest.raises(SystemExit):
+ validate_server_config(config)