Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.pyindex 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 = Nonediff --git a/openviking/server/config.py b/openviking/server/config.pyindex 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:returndiff --git a/tests/server/test_auth.py b/tests/server/test_auth.pyindex 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)