Skip to content

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

fix: apikey security: API Key 管理重构与安全增强 (#1686)

MaojiaSheng85986a91bd25
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rs
index 9e934f07d..b538ddabc 100644
--- a/crates/ov_cli/src/client.rs
+++ b/crates/ov_cli/src/client.rs
@@ -3,6 +3,7 @@ use serde::de::DeserializeOwned;
use serde_json::Value;
use std::fs::File;
use std::path::Path;
+use std::str::FromStr;
use tempfile::{Builder, NamedTempFile};
use zip::CompressionMethod;
use zip::write::FileOptions;
@@ -18,6 +19,7 @@ pub struct HttpClient {
account: Option<String>,
user: Option<String>,
agent_id: Option<String>,
+ extra_headers: Option<std::collections::HashMap<String, String>>,
}
impl HttpClient {
@@ -29,6 +31,7 @@ impl HttpClient {
account: Option<String>,
user: Option<String>,
timeout_secs: f64,
+ extra_headers: Option<std::collections::HashMap<String, String>>,
) -> Self {
let http = ReqwestClient::builder()
.timeout(std::time::Duration::from_secs_f64(timeout_secs))
@@ -42,6 +45,7 @@ impl HttpClient {
account,
user,
agent_id,
+ extra_headers,
}
}
@@ -165,6 +169,15 @@ impl HttpClient {
headers.insert("X-OpenViking-User", value);
}
}
+ if let Some(extra_headers) = &self.extra_headers {
+ for (key, value) in extra_headers {
+ if let Ok(header_name) = reqwest::header::HeaderName::from_str(key) {
+ if let Ok(header_value) = reqwest::header::HeaderValue::from_str(value) {
+ headers.insert(header_name, header_value);
+ }
+ }
+ }
+ }
headers
}
@@ -1007,6 +1020,7 @@ impl HttpClient {
mod tests {
use super::HttpClient;
use serde_json::json;
+ use std::collections::HashMap;
#[test]
fn build_headers_includes_tenant_identity_headers() {
@@ -1017,6 +1031,7 @@ mod tests {
Some("acme".to_string()),
Some("alice".to_string()),
5.0,
+ None,
);
let headers = client.build_headers();
@@ -1047,6 +1062,34 @@ mod tests {
);
}
+ #[test]
+ fn build_headers_includes_extra_headers() {
+ let mut extra_headers = HashMap::new();
+ extra_headers.insert("X-Custom-Header".to_string(), "custom-value".to_string());
+ extra_headers.insert("Authorization".to_string(), "Bearer token".to_string());
+
+ let client = HttpClient::new(
+ "http://localhost:1933",
+ Some("test-key".to_string()),
+ Some("assistant-1".to_string()),
+ Some("acme".to_string()),
+ Some("alice".to_string()),
+ 5.0,
+ Some(extra_headers),
+ );
+
+ let headers = client.build_headers();
+
+ assert_eq!(
+ headers.get("X-Custom-Header").and_then(|value| value.to_str().ok()),
+ Some("custom-value")
+ );
+ assert_eq!(
+ headers.get("Authorization").and_then(|value| value.to_str().ok()),
+ Some("Bearer token")
+ );
+ }
+
#[test]
fn build_write_body_omits_removed_semantic_flags() {
let body = HttpClient::build_write_body(
diff --git a/crates/ov_cli/src/config.rs b/crates/ov_cli/src/config.rs
index d22217f26..917a91578 100644
--- a/crates/ov_cli/src/config.rs
+++ b/crates/ov_cli/src/config.rs
@@ -41,6 +41,8 @@ pub struct Config {
pub echo_command: bool,
#[serde(default)]
pub upload: UploadConfig,
+ #[serde(default, alias = "extra_header")]
+ pub extra_headers: Option<std::collections::HashMap<String, String>>,
}
fn default_url() -> String {
@@ -72,6 +74,7 @@ impl Default for Config {
output: "table".to_string(),
echo_command: true,
upload: UploadConfig::default(),
+ extra_headers: None,
}
}
}
@@ -284,4 +287,52 @@ mod tests {
);
assert_eq!(merge_csv_options(None, None), None);
}
+
+ #[test]
+ fn config_deserializes_extra_headers() {
+ let config: Config = serde_json::from_str(
+ r#"{
+ "url": "http://localhost:1933",
+ "extra_headers": {
+ "X-Custom-Header": "custom-value",
+ "Authorization": "Bearer token"
+ }
+ }"#,
+ )
+ .expect("config should deserialize with extra_headers");
+
+ let headers = config.extra_headers.expect("extra_headers should be present");
+ assert_eq!(headers.get("X-Custom-Header"), Some(&"custom-value".to_string()));
+ assert_eq!(headers.get("Authorization"), Some(&"Bearer token".to_string()));
+ }
+
+ #[test]
+ fn config_deserializes_extra_headers_none_when_missing() {
+ let config: Config = serde_json::from_str(
+ r#"{
+ "url": "http://localhost:1933"
+ }"#,
+ )
+ .expect("config should deserialize");
+
+ assert!(config.extra_headers.is_none());
+ }
+
+ #[test]
+ fn config_deserializes_extra_header_alias() {
+ let config: Config = serde_json::from_str(
+ r#"{
+ "url": "http://localhost:1933",
+ "extra_header": {
+ "X-Custom-Header": "custom-value",
+ "Authorization": "Bearer token"
+ }
+ }"#,
+ )
+ .expect("config should deserialize with alias");
+
+ let headers = config.extra_headers.expect("extra_headers should be present");
+ assert_eq!(headers.get("X-Custom-Header"), Some(&"custom-value".to_string()));
+ assert_eq!(headers.get("Authorization"), Some(&"Bearer token".to_string()));
+ }
}
diff --git a/crates/ov_cli/src/handlers.rs b/crates/ov_cli/src/handlers.rs
index 5e7541a4e..82c927835 100644
--- a/crates/ov_cli/src/handlers.rs
+++ b/crates/ov_cli/src/handlers.rs
@@ -81,6 +81,7 @@ pub async fn handle_add_resource(
ctx.config.account.clone(),
ctx.config.user.clone(),
effective_timeout,
+ ctx.config.extra_headers.clone(),
);
commands::resources::add_resource(
&client,
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rs
index 676711a46..6c052dfbc 100644
--- a/crates/ov_cli/src/main.rs
+++ b/crates/ov_cli/src/main.rs
@@ -85,6 +85,7 @@ impl CliContext {
self.config.account.clone(),
self.config.user.clone(),
timeout_secs.unwrap_or(self.config.timeout),
+ self.config.extra_headers.clone(),
)
}
}
@@ -994,6 +995,7 @@ mod tests {
output: "table".to_string(),
echo_command: true,
upload: Default::default(),
+ extra_headers: None,
};
let ctx = CliContext::from_config(
@@ -1024,6 +1026,7 @@ mod tests {
output: "table".to_string(),
echo_command: true,
upload: Default::default(),
+ extra_headers: None,
};
// Without sudo: use api_key
diff --git a/docs/design/multi-tenant-design.md b/docs/design/multi-tenant-design.md
index 23015461a..32f75e7f7 100644
--- a/docs/design/multi-tenant-design.md
+++ b/docs/design/multi-tenant-design.md
@@ -53,41 +53,53 @@ Request
| 类型 | 格式 | 解析结果 | 存储位置 |
|------|------|----------|----------|
| Root Key | `secrets.token_hex(32)` | role=ROOT | `ov.conf` server 段 |
-| User Key | `secrets.token_hex(32)` | (account_id, user_id, role) | per-account `/{account_id}/_system/users.json` |
+| User Key (Legacy) | `secrets.token_hex(32)` | (account_id, user_id, role) | per-account `/{account_id}/_system/users.json` |
+| User Key (New) | `base64url(account_id).base64url(user_id).base64url(secret)` | (account_id, user_id, role) | per-account `/{account_id}/_system/users.json` |
-所有 API Key 均为纯随机 token,不带前缀,不携带任何身份信息。Key 本身不区分 root 还是 user —— 服务端通过查表确定身份:先比对 root key,不匹配则查 user key 索引。
+**新版 API Key 格式**:`base64url(account_id).base64url(user_id).base64url(secret)`
+- 可直接从 key 中解码出 account_id 和 user_id(快速路径)
+- 最后一段 secret 为 32 字节随机数(`secrets.token_hex(32)`)的 base64url 编码
+- key 可通过前缀索引(key 前 8 字符)快速查找,也可直接解析身份
+- 支持两种格式完全兼容:新 key 可通过直接解析或前缀索引解析,旧 key 继续通过前缀索引解析
用户的角色(ADMIN / USER)不由 key 决定,而是存储在 account 内的用户注册表中。
+**Key 加密存储**:
+- 支持 Argon2id 哈希存储 User Key(可选,通过 `encryption_enabled` 启用)
+- 加密时存储:`key_prefix`(前 8 字符) + `key_hash`(Argon2id 哈希)
+- 验证时:先用 key_prefix 快速定位候选 entry,再用 Argon2id 验证
+
### 2.2 User Key 机制
-注册用户时生成随机 key,存入对应 account 的 `users.json`。验证时查表匹配。
+注册用户时生成新版格式 key,存入对应 account 的 `users.json`。验证时优先走快速路径(直接解析),回退到前缀索引查找。
-**生成**:`secrets.token_hex(32)` → `7f3a9c1e...`(存入 users.json)
-**验证**:先比对 root key → 不匹配 → 在内存索引中查找 → 得到 `(account_id, user_id, role)`
+**生成(新版)**:`generate_api_key(account_id, user_id)` → `base64url(account_id).base64url(user_id).base64url(secret)`
+**生成(旧版)**:`secrets.token_hex(32)` → `7f3a9c1e...`(仅用于兼容)
+**验证**:先比对 root key → 不匹配 → 检查是否为新版格式 → 直接解析并验证 → 失败则走前缀索引查找
**完整场景**:
```
1. Root 创建工作区 acme,指定 alice 为首个 admin
POST /api/v1/admin/accounts {"account_id": "acme", "admin_user_id": "alice"}
- → 创建工作区 + 注册 alice(role=admin) + 返回 alice 的 key: 7f3a9c1e...
+ → 创建工作区 + 注册 alice(role=admin) + 返回 alice 的 user key: YWNtZQ==.YWxpY2U=.OWFmZTEyMjc2YTU3Njkz...
2. alice 用 key 访问 API
- GET /api/v1/fs/ls?uri=viking:// -H "X-API-Key: 7f3a9c1e..." → 200 OK
+ GET /api/v1/fs/ls?uri=viking:// -H "X-API-Key: YWNtZQ==.YWxpY2U=.OWFmZTEyMjc2YTU3Njkz..." → 200 OK
+ → 服务端直接从 key 解析出 account_id="acme", user_id="alice",再验证 secret
3. alice(admin)注册普通用户 bob
- POST /api/v1/admin/accounts/acme/users {"user_id": "bob"} → 注册成功 + 返回 key: d91f5b2a...
+ POST /api/v1/admin/accounts/acme/users {"user_id": "bob"} → 注册成功 + 返回 key: YWNtZQ==.Ym9i.5b2a...
-4. bob 丢了 key,alice 重新生成(旧 key 立即失效)
- POST /api/v1/admin/accounts/acme/users/bob/key → e82d4e0f...(新 key)
- bob 用旧的 d91f5b2a... 访问 → 401(已失效)
+4. bob 丢了 key,alice 重新生成(旧 key 立即失效,新 key 为新版格式)
+ POST /api/v1/admin/accounts/acme/users/bob/key → YWNtZQ==.Ym9i.ZWgyZDRm...(新 key)
+ bob 用旧 key 访问 → 401(已失效)
5. bob 的 key 泄露 → 重新生成即可,只影响 bob
6. alice 移除 bob
DELETE /api/v1/admin/accounts/acme/users/bob → 注册表和 key 一起删除
- bob 再用 key 访问 → 查表找不到 → 401
+ bob 再用 key 访问 → 解析验证/查表找不到 → 401
```
### 2.3 Key 存储
@@ -107,11 +119,19 @@ Request
}
}
-// /acme/_system/users.json —— acme 工作区的用户注册表
+// /acme/_system/users.json —— acme 工作区的用户注册表(未加密)
{
"users": {
- "alice": { "role": "admin", "key": "7f3a9c1e..." },
- "bob": { "role": "user", "key": "d91f5b2a..." }
+ "alice": { "role": "admin", "key": "YWNtZQ==.YWxpY2U=.OWFmZTEy..." },
+ "bob": { "role": "user", "key": "YWNtZQ==.Ym9i.ZWgyZDRm..." }
+ }
+}
+
+// /acme/_system/users.json —— acme 工作区的用户注册表(已加密)
+{
+ "users": {
+ "alice": { "role": "admin", "key": "$argon2id$v=19$m=65536,t=3,p=2$...", "key_prefix": "YWNtZQ==" },
+ "bob": { "role": "user", "key": "$argon2id$v=19$m=65536,t=3,p=2$...", "key_prefix": "YWNtZQ==" }
}
}
```
@@ -120,24 +140,58 @@ Request
**为什么存 AGFS**:User key 是运行时通过 Admin API 动态增删的,不能放 ov.conf。选择 AGFS 的核心理由是多节点一致性——多个 server 共享同一个 AGFS 后端时,一个节点创建的用户其他节点立即可见。
-### 2.4 新模块 `openviking/server/api_keys.py`
+### 2.4 新模块 `openviking/server/api_keys/`
+
+API Key 管理重构为模块化结构:
+
+```
+openviking/server/api_keys/
+├── __init__.py # 统一对外接口,导出 APIKeyManager(默认 NewAPIKeyManager)
+├── legacy.py # 原版 APIKeyManager(保留兼容,重命名为 LegacyAPIKeyManager)
+└── new.py # 新版 NewAPIKeyManager,支持新版三段式 Key 格式
+```
+
+**导出接口(`__init__.py`)**:
+```python
+# 默认使用新版实现
+from .new import NewAPIKeyManager as APIKeyManager
+
+# 同时导出工具函数和 Legacy 实现
+from .new import is_new_format_key, parse_api_key, generate_api_key
+from .legacy import LegacyAPIKeyManager
+```
+**核心类 APIKeyManager**:
```python
class APIKeyManager:
- """API Key 生命周期管理与解析"""
+ """API Key 生命周期管理与解析(新版实现)"""
- def __init__(self, root_key: str, agfs_client: AGFSClient)
+ def __init__(self, root_key: str, viking_fs: VikingFS, encryption_enabled: bool = False)
async def load() # 加载所有 account 的 users.json 到内存
- async def save_account(account_id: str) # 持久化指定 account 的 users.json
- def resolve(api_key: str) -> ResolvedIdentity # Key → 身份 + 角色
- def create_account(account_id: str, admin_user_id: str) -> str # 创建工作区 + 首个 admin,返回 admin 的 user key
- def delete_account(account_id: str) # 删除工作区
- def register_user(account_id, user_id, role) -> str # 注册用户,返回 user key
- def remove_user(account_id, user_id) # 移除用户
- def regenerate_key(account_id, user_id) -> str # 重新生成 user key(旧 key 失效)
- def set_role(account_id, user_id, role) # 修改用户角色(仅 ROOT)
+ def resolve(api_key: str) -> ResolvedIdentity # Key → 身份 + 角色(支持新版/旧版两种格式)
+ async def create_account(account_id: str, admin_user_id: str, namespace_policy=None) -> str
+ async def delete_account(account_id: str)
+ async def register_user(account_id, user_id, role="user") -> str
+ async def remove_user(account_id, user_id)
+ async def regenerate_key(account_id, user_id) -> str # 重新生成 key(升级为新版格式)
+ async def set_role(account_id, user_id, role)
+ def get_accounts() -> list
+ def get_users(account_id) -> list
+ def get_account_policy(account_id) -> AccountNamespacePolicy
+```
+
+**新版 Key 工具函数**:
+```python
+def is_new_format_key(api_key: str) -> bool
+def parse_api_key(api_key: str) -> Tuple[str, str, str] # (account_id, user_id, secret)
+def generate_api_key(account_id: str, user_id: str) -> str
```
+**兼容策略**:
+- `resolve()` 自动检测 key 格式,新版走快速解析路径,旧版走前缀索引
+- `regenerate_key()` 总是生成新版格式 key,可用于存量 key 升级
+- 存储格式与 Legacy 完全兼容,可无缝切换
+
---
## 三、认证流程
@@ -689,9 +743,9 @@ config = ServerConfig(
#### T2: API Key Manager
-**新建** `openviking/server/api_keys.py`,依赖:T1
+**重构** `openviking/server/api_keys.py` → `openviking/server/api_keys/` 目录,依赖:T1
-##### 存储结构
+##### 存储结构(与 Legacy 兼容)
Per-account 存储,两级文件:
@@ -704,83 +758,112 @@ Per-account 存储,两级文件:
}
}
-# /{account_id}/_system/users.json — 该 account 的用户注册表
+# /{account_id}/_system/users.json — 该 account 的用户注册表(未加密)
{
"users": {
- "alice": {"role": "admin", "key": "7f3a9c1e..."},
- "bob": {"role": "user", "key": "d91f5b2a..."}
+ "alice": {"role": "admin", "key": "YWNtZQ==.YWxpY2U=.OWFmZTEy..."},
+ "bob": {"role": "user", "key": "YWNtZQ==.Ym9i.ZWgyZDRm..."}
+ }
+}
+
+# /{account_id}/_system/users.json — 该 account 的用户注册表(已加密)
+{
+ "users": {
+ "alice": {"role": "admin", "key": "$argon2id$v=19$...", "key_prefix": "YWNtZQ=="},
+ "bob": {"role": "user", "key": "$argon2id$v=19$...", "key_prefix": "YWNtZQ=="}
}
}
```
内存索引(启动时从所有 account 加载):
```python
-self._user_keys: Dict[str, UserKeyEntry] = {} # {key_str -> (account_id, user_id, role)}
-self._accounts: Dict[str, AccountInfo] = {} # {account_id -> AccountInfo(users)}
+self._prefix_index: Dict[str, List[UserKeyEntry]] = {} # {key_prefix -> [entries]}
+self._accounts: Dict[str, AccountInfo] = {} # {account_id -> AccountInfo(users)}
```
-##### 方法逻辑
+##### 方法逻辑(新版 NewAPIKeyManager)
-**`__init__(root_key, agfs_url)`**:
+**`__init__(root_key, viking_fs, encryption_enabled=False)`**:
- 存储 root_key
-- 创建 pyagfs.AGFSClient(agfs_url) 用于读写 AGFS 文件
+- 接收 VikingFS 实例(而非 AGFS URL)
+- 可选启用 Argon2id 加密存储
**`async load()`**:
- 从 AGFS 读取 `/_system/accounts.json`,若不存在则创建 default account
- 遍历每个 account,读取 `/{account_id}/_system/users.json`
-- 构建全局 key → (account_id, user_id, role) 索引
-
-**`async save_account(account_id)`**:
-- 将指定 account 的用户数据写回 `/{account_id}/_system/users.json`
-- 同时更新 `/_system/accounts.json`(若 account 列表有变化)
+- 构建前缀索引:key 前 8 字符 → [UserKeyEntry]
+- 支持自动迁移:plaintext key → hashed key(当 encryption_enabled=True 时)
**`resolve(api_key) -> ResolvedIdentity`**:
```
-# Key 无前缀,顺序匹配
+# 快速路径 + 兼容路径
if hmac.compare_digest(key, self._root_key):
→ ResolvedIdentity(role=ROOT)
-entry = self._user_keys.get(key)
-if entry:
- → ResolvedIdentity(role=entry.role, account_id=entry.account_id, user_id=entry.user_id)
+
+# 新版格式:直接解析 identity
+if is_new_format_key(api_key):
+ try:
+ account_id, user_id, secret = parse_api_key(api_key)
+ account = self._accounts.get(account_id)
+ if account and user_id in account.users:
+ # 验证 secret(支持 plaintext 或 hashed)
+ if verify_secret(api_key, account.users[user_id]):
+ → ResolvedIdentity(role, account_id, user_id)
+ except:
+ pass # 解析失败回退到前缀索引
+
+# Legacy 格式:前缀索引查找
+key_prefix = key[:8]
+for entry in self._prefix_index.get(key_prefix, []):
+ if verify_api_key(key, entry):
+ → ResolvedIdentity(role=entry.role, account_id=entry.account_id, user_id=entry.user_id)
+
raise UnauthenticatedError
```
-**`create_account(account_id, admin_user_id) -> str`**:
+**`async create_account(account_id, admin_user_id, namespace_policy=None) -> str`**:
- 验证 account_id 格式
- 检查 account_id 不重复
- 创建 account 记录到 `_accounts`
-- 注册首个 admin 用户,生成 `secrets.token_hex(32)` 作为 key
-- 持久化 `/_system/accounts.json` 和 `/{account_id}/_system/users.json`
+- 注册首个 admin 用户,生成 `generate_api_key(account_id, admin_user_id)`(新版格式)
+- 可选存储 namespace_policy
+- 持久化 `/_system/accounts.json`、`/{account_id}/_system/users.json` 和 setting.json
- 返回 admin 的 user key
-**`delete_account(account_id)`**:
+**`async delete_account(account_id)`**:
- 从 `_accounts` 删除
-- 从 `_user_keys` 中删除该 account 的所有 key
+- 从 `_prefix_index` 中删除该 account 的所有 key
- 删除 `/_system/accounts.json` 中的记录
- **注意**:AGFS 数据和 VectorDB 数据的级联清理由 Admin Router 调用方负责
-**`register_user(account_id, user_id, role="user") -> str`**:
+**`async register_user(account_id, user_id, role="user") -> str`**:
- 检查 account_id 存在
-- 生成 `secrets.token_hex(32)` 作为 key
-- 写入 account 用户表和全局索引
-- 调用 `save_account(account_id)`
+- 生成 `generate_api_key(account_id, user_id)`(新版格式)
+- 写入 account 用户表和前缀索引
+- 持久化 `/{account_id}/_system/users.json`
- 返回 user key
-**`remove_user(account_id, user_id)`**:
-- 从 account 用户表和全局索引中移除
-- 调用 `save_account(account_id)`
+**`async remove_user(account_id, user_id)`**:
+- 从 account 用户表和前缀索引中移除
+- 持久化 `/{account_id}/_system/users.json`
-**`regenerate_key(account_id, user_id) -> str`**:
-- 删除旧 key 的全局索引
-- 生成新随机 key
-- 更新用户表和全局索引
-- 调用 `save_account(account_id)`
+**`async regenerate_key(account_id, user_id) -> str`**:
+- 删除旧 key 的前缀索引
+- 生成 `generate_api_key(account_id, user_id)`(新版格式,用于升级)
+- 更新用户表和前缀索引
+- 持久化 `/{account_id}/_system/users.json`
- 返回新 key
-**`set_role(account_id, user_id, role)`**:
+**`async set_role(account_id, user_id, role)`**:
- 更新用户角色(仅 ROOT 可调用)
-- 更新全局索引中的 role
-- 调用 `save_account(account_id)`
+- 更新前缀索引中的 role
+- 持久化 `/{account_id}/_system/users.json`
+
+##### 兼容策略
+
+- `LegacyAPIKeyManager` 保留在 `api_keys/legacy.py` 中,完整保留原行为
+- `NewAPIKeyManager` 完整支持旧格式 key 的解析和存储
+- `regenerate_key()` 可用于将旧格式 key 升级为新版格式
---
@@ -1428,7 +1511,10 @@ Phase 2 涉及存储隔离,需新增隔离相关示例:
| 文件 | 改动类型 | 阶段 | 说明 |
|------|----------|------|------|
| `openviking/server/identity.py` | **新建** | P1 | Role(ROOT/ADMIN/USER), ResolvedIdentity, RequestContext |
-| `openviking/server/api_keys.py` | **新建** | P1 | APIKeyManager(per-account 存储,全局索引) |
+| `openviking/server/api_keys.py` | **删除** | - | 原文件重构为目录结构 |
+| `openviking/server/api_keys/__init__.py` | **新建** | P1 | 统一对外接口,导出 APIKeyManager = NewAPIKeyManager |
+| `openviking/server/api_keys/legacy.py` | **新建** | P1 | 原 APIKeyManager 完整迁移,重命名为 LegacyAPIKeyManager |
+| `openviking/server/api_keys/new.py` | **新建** | P1 | 新版 NewAPIKeyManager,支持三段式 key、加密存储 |
| `openviking/server/routers/admin.py` | **新建** | P1 | Admin 管理端点(account/user CRUD、角色管理) |
| `openviking/server/auth.py` | 重写 | P1 | verify_api_key → resolve_identity + require_role + get_request_context |
| `openviking/server/config.py` | 修改 | P1 | api_key → root_api_key |
diff --git a/examples/ovcli.conf.example b/examples/ovcli.conf.example
index 73d272b2e..e76480926 100644
--- a/examples/ovcli.conf.example
+++ b/examples/ovcli.conf.example
@@ -7,5 +7,6 @@
"agent_id": null,
"timeout": 60.0,
"output": "table",
- "echo_command": true
+ "echo_command": true,
+ "extra_headers": null
}
diff --git a/openviking/server/api_keys/__init__.py b/openviking/server/api_keys/__init__.py
new file mode 100644
index 000000000..1ae104348
--- /dev/null
+++ b/openviking/server/api_keys/__init__.py
@@ -0,0 +1,28 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Unified API Key management with support for both legacy and new formats.
+
+This module exports APIKeyManager which internally uses NewAPIKeyManager that:
+- Generates new keys in the new format: base64url(account_id).base64url(user_id).base64url(secret)
+- Can resolve both legacy and new format keys
+- Maintains full backward compatibility
+"""
+
+# Also export legacy components for reference
+from openviking.server.api_keys.legacy import LegacyAPIKeyManager
+from openviking.server.api_keys.new import (
+ NewAPIKeyManager as APIKeyManager,
+)
+from openviking.server.api_keys.new import (
+ generate_api_key,
+ is_new_format_key,
+ parse_api_key,
+)
+
+__all__ = [
+ "APIKeyManager",
+ "LegacyAPIKeyManager",
+ "is_new_format_key",
+ "parse_api_key",
+ "generate_api_key",
+]
diff --git a/openviking/server/api_keys.py b/openviking/server/api_keys/legacy.py
similarity index 94%
rename from openviking/server/api_keys.py
rename to openviking/server/api_keys/legacy.py
index 361690733..22212c7a4 100644
--- a/openviking/server/api_keys.py
+++ b/openviking/server/api_keys/legacy.py
@@ -1,24 +1,26 @@
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
-"""API Key management for OpenViking multi-tenant HTTP Server."""
+"""Legacy API Key management (original implementation)."""
import hmac
import json
import secrets
-from dataclasses import dataclass, field
from datetime import datetime, timezone
from typing import Dict, Optional
from argon2 import PasswordHasher
from argon2.exceptions import VerifyMismatchError
+from openviking.server.api_keys.models import AccountInfo, UserKeyEntry
from openviking.server.identity import AccountNamespacePolicy, ResolvedIdentity, Role
from openviking.storage.viking_fs import VikingFS
from openviking_cli.exceptions import (
AlreadyExistsError,
+ InvalidArgumentError,
NotFoundError,
UnauthenticatedError,
)
+from openviking_cli.session.user_id import validate_account_id, validate_user_id
from openviking_cli.utils import get_logger
logger = get_logger(__name__)
@@ -28,43 +30,21 @@ USERS_PATH_TEMPLATE = "/local/{account_id}/_system/users.json"
SETTINGS_PATH_TEMPLATE = "/local/{account_id}/_system/setting.json"
-# Argon2id parameters
+# Argon2id parameters - export with LEGACY_ prefix for reuse in new.py
ARGON2_TIME_COST = 3
ARGON2_MEMORY_COST = 65536
ARGON2_PARALLELISM = 2
ARGON2_HASH_LENGTH = 32
+# Also export with LEGACY_ prefix for clarity when imported by new.py
+LEGACY_ARGON2_TIME_COST = ARGON2_TIME_COST
+LEGACY_ARGON2_MEMORY_COST = ARGON2_MEMORY_COST
+LEGACY_ARGON2_PARALLELISM = ARGON2_PARALLELISM
+LEGACY_ARGON2_HASH_LENGTH = ARGON2_HASH_LENGTH
-@dataclass
-class UserKeyEntry:
- """In-memory index entry for a user key."""
- account_id: str
- user_id: str
- role: Role
- key_or_hash: str
- is_hashed: bool
-
-
-@dataclass
-class AccountInfo:
- """In-memory account info."""
-
- created_at: str
- users: Dict[str, dict] = field(default_factory=dict)
- namespace_policy: AccountNamespacePolicy = field(default_factory=AccountNamespacePolicy)
-
-
-class APIKeyManager:
- """Manages API keys for multi-tenant authentication.
-
- Two-level storage:
- - /_system/accounts.json: global workspace list
- - /{account_id}/_system/users.json: per-account user registry
-
- In-memory index for fast key lookup.
- Uses Argon2id for secure API key hashing.
- """
+class LegacyAPIKeyManager:
+ """Manages API keys for multi-tenant authentication (legacy implementation)."""
def __init__(
self,
@@ -168,7 +148,7 @@ class APIKeyManager:
self._prefix_index[key_prefix].append(entry)
logger.info(
- "APIKeyManager loaded: %d accounts, %d user keys",
+ "LegacyAPIKeyManager loaded: %d accounts, %d user keys",
len(self._accounts),
sum(len(info.users) for info in self._accounts.values()),
)
@@ -238,8 +218,16 @@ class APIKeyManager:
) -> str:
"""Create a new account (workspace) with its first admin user.
- Returns the admin user's API key.
+ Returns the admin user's API key (legacy format).
"""
+ # Validate account_id and user_id format
+ verr = validate_account_id(account_id)
+ if verr:
+ raise InvalidArgumentError(verr)
+ verr = validate_user_id(admin_user_id)
+ if verr:
+ raise InvalidArgumentError(verr)
+
if account_id in self._accounts:
raise AlreadyExistsError(account_id, "account")
@@ -289,10 +277,7 @@ class APIKeyManager:
return key
async def delete_account(self, account_id: str) -> None:
- """Delete an account and remove all its user keys from the index.
-
- Note: AGFS data and VectorDB cleanup is the caller's responsibility.
- """
+ """Delete an account and remove all its user keys from the index."""
if account_id not in self._accounts:
raise NotFoundError(account_id, "account")
@@ -319,7 +304,12 @@ class APIKeyManager:
await self._save_accounts_json()
async def register_user(self, account_id: str, user_id: str, role: str = "user") -> str:
- """Register a new user in an account. Returns the user's API key."""
+ """Register a new user in an account. Returns the user's API key (legacy format)."""
+ # Validate user_id format
+ verr = validate_user_id(user_id)
+ if verr:
+ raise InvalidArgumentError(verr)
+
account = self._accounts.get(account_id)
if account is None:
raise NotFoundError(account_id, "account")
@@ -545,7 +535,7 @@ class APIKeyManager:
# ---- internal helpers ----
def _generate_api_key(self) -> str:
- """Generate new API Key."""
+ """Generate new API Key (legacy format - hex)."""
return secrets.token_hex(32)
def _get_key_prefix(self, api_key: str) -> str:
diff --git a/openviking/server/api_keys/models.py b/openviking/server/api_keys/models.py
new file mode 100644
index 000000000..cb95298a0
--- /dev/null
+++ b/openviking/server/api_keys/models.py
@@ -0,0 +1,28 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""共享的数据模型定义。"""
+
+from dataclasses import dataclass, field
+from typing import Dict
+
+from openviking.server.identity import AccountNamespacePolicy, Role
+
+
+@dataclass
+class UserKeyEntry:
+ """内存中的用户密钥索引条目。"""
+
+ account_id: str
+ user_id: str
+ role: Role
+ key_or_hash: str
+ is_hashed: bool
+
+
+@dataclass
+class AccountInfo:
+ """内存中的账户信息。"""
+
+ created_at: str
+ users: Dict[str, dict] = field(default_factory=dict)
+ namespace_policy: AccountNamespacePolicy = field(default_factory=AccountNamespacePolicy)
diff --git a/openviking/server/api_keys/new.py b/openviking/server/api_keys/new.py
new file mode 100644
index 000000000..0b8da44d8
--- /dev/null
+++ b/openviking/server/api_keys/new.py
@@ -0,0 +1,443 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""New format API Key implementation with directly decodable identity.
+
+This implementation delegates legacy format support to LegacyAPIKeyManager
+to avoid code duplication, while adding new format key generation.
+"""
+
+import base64
+import hmac
+import secrets
+from typing import Optional, Tuple
+
+from openviking.server.api_keys.legacy import (
+ LegacyAPIKeyManager,
+)
+from openviking.server.api_keys.models import AccountInfo, UserKeyEntry
+from openviking.server.identity import AccountNamespacePolicy, ResolvedIdentity, Role
+from openviking.storage.viking_fs import VikingFS
+from openviking_cli.exceptions import InvalidArgumentError, UnauthenticatedError
+from openviking_cli.session.user_id import validate_account_id, validate_user_id
+from openviking_cli.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+def _encode_segment(data: str) -> str:
+ """Encode a string segment using URL-safe base64 without padding."""
+ encoded = base64.urlsafe_b64encode(data.encode("utf-8"))
+ return encoded.decode("utf-8").rstrip("=")
+
+
+def _decode_segment(encoded: str) -> str:
+ """Decode a URL-safe base64 segment, adding padding if needed."""
+ padding_needed = 4 - (len(encoded) % 4)
+ if padding_needed != 4:
+ encoded += "=" * padding_needed
+ decoded = base64.urlsafe_b64decode(encoded.encode("utf-8"))
+ return decoded.decode("utf-8")
+
+
+def is_new_format_key(api_key: str) -> bool:
+ """Check if the API key is in the new format (three base64 segments separated by dots)."""
+ if not api_key:
+ return False
+ parts = api_key.split(".")
+ return len(parts) == 3
+
+
+def parse_api_key(api_key: str) -> Tuple[str, str, str]:
+ """Parse a new format API key into (account_id, user_id, secret)."""
+ if not is_new_format_key(api_key):
+ raise ValueError("Not a new format API key")
+ parts = api_key.split(".")
+ account_id = _decode_segment(parts[0])
+ user_id = _decode_segment(parts[1])
+ secret = _decode_segment(parts[2])
+ return account_id, user_id, secret
+
+
+def generate_api_key(account_id: str, user_id: str) -> str:
+ """Generate a new format API key."""
+ account_segment = _encode_segment(account_id)
+ user_segment = _encode_segment(user_id)
+ # Generate a 32-byte random secret and encode it
+ secret = secrets.token_hex(32)
+ secret_segment = _encode_segment(secret)
+ return f"{account_segment}.{user_segment}.{secret_segment}"
+
+
+class NewAPIKeyManager:
+ """Manages API keys for multi-tenant authentication with new key format.
+
+ New key format: base64url(account_id).base64url(user_id).base64url(secret)
+ - Can directly decode account_id and user_id without prefix lookup
+ - Still uses Argon2id for secure secret verification
+ - Delegates legacy functionality to LegacyAPIKeyManager to avoid code duplication
+ """
+
+ def __init__(
+ self,
+ root_key: str,
+ viking_fs: VikingFS,
+ encryption_enabled: bool = False,
+ ):
+ """Initialize NewAPIKeyManager.
+
+ Args:
+ root_key: Global root API key for administrative access.
+ viking_fs: VikingFS client for persistent storage of user keys.
+ encryption_enabled: Whether API key hashing is enabled.
+ """
+ # Delegate to legacy manager for all core functionality
+ self._legacy = LegacyAPIKeyManager(root_key, viking_fs, encryption_enabled)
+
+ async def load(self) -> None:
+ """Load accounts and user keys from VikingFS into memory."""
+ await self._legacy.load()
+ logger.info(
+ "NewAPIKeyManager loaded: %d accounts, %d user keys",
+ len(self._legacy.get_accounts()),
+ sum(len(info.users) for info in self._legacy._accounts.values()),
+ )
+
+ def resolve(self, api_key: str) -> ResolvedIdentity:
+ """Resolve an API key to identity.
+
+ First checks for root key.
+ Then checks if it's a new format key (fast decode path).
+ Then falls back to legacy prefix index lookup.
+ """
+ if not api_key:
+ raise UnauthenticatedError("Missing API Key")
+
+ # Check root key first - use legacy's root key
+ if hmac.compare_digest(api_key, self._legacy._root_key):
+ return ResolvedIdentity(role=Role.ROOT)
+
+ # Fast path for new format keys - decode identity directly from key
+ if is_new_format_key(api_key):
+ try:
+ account_id, user_id, _ = parse_api_key(api_key)
+
+ # Verify the user exists in the account using legacy's data
+ account = self._legacy._accounts.get(account_id)
+ if account and user_id in account.users:
+ user_info = account.users[user_id]
+ stored_key_or_hash = user_info.get("key", "")
+
+ # Verify the secret part matches using legacy's verify method
+ if stored_key_or_hash:
+ if user_info.get("key_prefix", "").startswith(
+ "$argon2"
+ ) or stored_key_or_hash.startswith("$argon2"):
+ # Hashed key
+ if self._legacy._verify_api_key(api_key, stored_key_or_hash):
+ return ResolvedIdentity(
+ role=Role(user_info.get("role", "user")),
+ account_id=account_id,
+ user_id=user_id,
+ namespace_policy=self.get_account_policy(account_id),
+ )
+ else:
+ # Plaintext key
+ if hmac.compare_digest(api_key, stored_key_or_hash):
+ return ResolvedIdentity(
+ role=Role(user_info.get("role", "user")),
+ account_id=account_id,
+ user_id=user_id,
+ namespace_policy=self.get_account_policy(account_id),
+ )
+ except Exception:
+ # If parsing fails or verification fails, fall through to try legacy path
+ pass
+
+ # Fall back to legacy resolver for legacy keys
+ return self._legacy.resolve(api_key)
+
+ async def create_account(
+ self,
+ account_id: str,
+ admin_user_id: str,
+ *,
+ namespace_policy: Optional[AccountNamespacePolicy] = None,
+ ) -> str:
+ """Create a new account (workspace) with its first admin user.
+
+ Returns the admin user's API key in new format.
+ """
+ # Validate account_id and user_id format
+ verr = validate_account_id(account_id)
+ if verr:
+ raise InvalidArgumentError(verr)
+ verr = validate_user_id(admin_user_id)
+ if verr:
+ raise InvalidArgumentError(verr)
+
+ # Generate new format key
+ key = generate_api_key(account_id, admin_user_id)
+ policy = namespace_policy or AccountNamespacePolicy()
+
+ # Use legacy to create account but with our new key
+ # We temporarily replace the generate method, call, then restore
+ # Instead, we implement the create_account with new key format
+
+ # Check existence first
+ if account_id in self._legacy._accounts:
+ from openviking_cli.exceptions import AlreadyExistsError
+
+ raise AlreadyExistsError(account_id, "account")
+
+ # Copy the legacy implementation but use new key format
+ from datetime import datetime, timezone
+
+ now = datetime.now(timezone.utc).isoformat()
+
+ if self._legacy._encryption_enabled:
+ stored_key = self._legacy._hash_api_key(key)
+ is_hashed = True
+ key_prefix = self._legacy._get_key_prefix(key)
+ else:
+ stored_key = key
+ is_hashed = False
+ key_prefix = self._legacy._get_key_prefix(key)
+
+ user_info = {
+ "role": "admin",
+ "key": stored_key,
+ }
+ if self._legacy._encryption_enabled:
+ user_info["key_prefix"] = key_prefix
+
+ # Add to legacy's data structures
+ self._legacy._accounts[account_id] = AccountInfo(
+ created_at=now,
+ users={admin_user_id: user_info},
+ namespace_policy=policy,
+ )
+
+ entry = UserKeyEntry(
+ account_id=account_id,
+ user_id=admin_user_id,
+ role=Role.ADMIN,
+ key_or_hash=stored_key,
+ is_hashed=is_hashed,
+ )
+
+ if key_prefix:
+ if key_prefix not in self._legacy._prefix_index:
+ self._legacy._prefix_index[key_prefix] = []
+ self._legacy._prefix_index[key_prefix].append(entry)
+
+ await self._legacy._save_accounts_json()
+ await self._legacy._save_users_json(account_id)
+ await self._legacy._save_settings_json(account_id)
+ return key
+
+ async def delete_account(self, account_id: str) -> None:
+ """Delete an account and remove all its user keys from the index."""
+ await self._legacy.delete_account(account_id)
+
+ async def register_user(self, account_id: str, user_id: str, role: str = "user") -> str:
+ """Register a new user in an account. Returns the user's API key in new format."""
+ # Validate user_id format
+ verr = validate_user_id(user_id)
+ if verr:
+ raise InvalidArgumentError(verr)
+
+ # Check account exists first
+ account = self._legacy._accounts.get(account_id)
+ if account is None:
+ from openviking_cli.exceptions import NotFoundError
+
+ raise NotFoundError(account_id, "account")
+ if user_id in account.users:
+ from openviking_cli.exceptions import AlreadyExistsError
+
+ raise AlreadyExistsError(user_id, "user")
+
+ # Generate new format key
+ key = generate_api_key(account_id, user_id)
+
+ if self._legacy._encryption_enabled:
+ stored_key = self._legacy._hash_api_key(key)
+ is_hashed = True
+ key_prefix = self._legacy._get_key_prefix(key)
+ else:
+ stored_key = key
+ is_hashed = False
+ key_prefix = self._legacy._get_key_prefix(key)
+
+ user_info = {
+ "role": role,
+ "key": stored_key,
+ }
+ if self._legacy._encryption_enabled:
+ user_info["key_prefix"] = key_prefix
+
+ account.users[user_id] = user_info
+
+ entry = UserKeyEntry(
+ account_id=account_id,
+ user_id=user_id,
+ role=Role(role),
+ key_or_hash=stored_key,
+ is_hashed=is_hashed,
+ )
+
+ if key_prefix:
+ if key_prefix not in self._legacy._prefix_index:
+ self._legacy._prefix_index[key_prefix] = []
+ self._legacy._prefix_index[key_prefix].append(entry)
+
+ await self._legacy._save_users_json(account_id)
+ return key
+
+ async def remove_user(self, account_id: str, user_id: str) -> None:
+ """Remove a user from an account."""
+ await self._legacy.remove_user(account_id, user_id)
+
+ async def regenerate_key(self, account_id: str, user_id: str) -> str:
+ """Regenerate a user's API key. Old key is immediately invalidated.
+
+ Generates new format key regardless of original format.
+ """
+ # Check account and user exist
+ account = self._legacy._accounts.get(account_id)
+ if account is None:
+ from openviking_cli.exceptions import NotFoundError
+
+ raise NotFoundError(account_id, "account")
+ if user_id not in account.users:
+ from openviking_cli.exceptions import NotFoundError
+
+ raise NotFoundError(user_id, "user")
+
+ old_user_info = account.users[user_id]
+ old_key_or_hash = old_user_info.get("key", "")
+
+ # Get old key_prefix
+ old_key_prefix = old_user_info.get("key_prefix", "")
+ if not old_key_prefix and old_key_or_hash:
+ old_key_prefix = self._legacy._get_key_prefix(old_key_or_hash)
+
+ # Remove old key from prefix index
+ if old_key_prefix in self._legacy._prefix_index:
+ self._legacy._prefix_index[old_key_prefix] = [
+ entry
+ for entry in self._legacy._prefix_index[old_key_prefix]
+ if not (entry.account_id == account_id and entry.user_id == user_id)
+ ]
+ if not self._legacy._prefix_index[old_key_prefix]:
+ del self._legacy._prefix_index[old_key_prefix]
+
+ # Generate new key in new format
+ new_key = generate_api_key(account_id, user_id)
+
+ if self._legacy._encryption_enabled:
+ new_stored_key = self._legacy._hash_api_key(new_key)
+ new_is_hashed = True
+ new_key_prefix = self._legacy._get_key_prefix(new_key)
+ else:
+ new_stored_key = new_key
+ new_is_hashed = False
+ new_key_prefix = self._legacy._get_key_prefix(new_key)
+
+ # Update user info
+ account.users[user_id]["key"] = new_stored_key
+ if self._legacy._encryption_enabled:
+ account.users[user_id]["key_prefix"] = new_key_prefix
+ else:
+ if "key_prefix" in account.users[user_id]:
+ del account.users[user_id]["key_prefix"]
+
+ entry = UserKeyEntry(
+ account_id=account_id,
+ user_id=user_id,
+ role=Role(account.users[user_id]["role"]),
+ key_or_hash=new_stored_key,
+ is_hashed=new_is_hashed,
+ )
+
+ if new_key_prefix:
+ if new_key_prefix not in self._legacy._prefix_index:
+ self._legacy._prefix_index[new_key_prefix] = []
+ self._legacy._prefix_index[new_key_prefix].append(entry)
+
+ await self._legacy._save_users_json(account_id)
+ return new_key
+
+ async def set_role(self, account_id: str, user_id: str, role: str) -> None:
+ """Update a user's role."""
+ await self._legacy.set_role(account_id, user_id, role)
+
+ def get_accounts(self) -> list:
+ """List all accounts."""
+ return self._legacy.get_accounts()
+
+ def get_account_policy(self, account_id: Optional[str]) -> AccountNamespacePolicy:
+ return self._legacy.get_account_policy(account_id)
+
+ def get_users(self, account_id: str) -> list:
+ """List all users in an account."""
+ return self._legacy.get_users(account_id)
+
+ def has_user(self, account_id: str, user_id: str) -> bool:
+ """Return True when the account registry contains the given user."""
+ return self._legacy.has_user(account_id, user_id)
+
+ # ---- Property proxies for backward compatibility with tests ----
+
+ @property
+ def _accounts(self):
+ return self._legacy._accounts
+
+ @property
+ def _prefix_index(self):
+ return self._legacy._prefix_index
+
+ @property
+ def _root_key(self):
+ return self._legacy._root_key
+
+ @property
+ def _encryption_enabled(self):
+ return self._legacy._encryption_enabled
+
+ # ---- Helper method proxies for backward compatibility ----
+
+ def _get_key_prefix(self, api_key: str) -> str:
+ return self._legacy._get_key_prefix(api_key)
+
+ def _hash_api_key(self, api_key: str) -> str:
+ return self._legacy._hash_api_key(api_key)
+
+ def _verify_api_key(self, api_key: str, hashed_key: str) -> bool:
+ return self._legacy._verify_api_key(api_key, hashed_key)
+
+ async def _read_json(self, path: str) -> Optional[dict]:
+ return await self._legacy._read_json(path)
+
+ async def _write_json(self, path: str, data: dict) -> None:
+ return await self._legacy._write_json(path, data)
+
+ def _ensure_parent_dirs(self, path: str) -> None:
+ return self._legacy._ensure_parent_dirs(path)
+
+ async def _save_accounts_json(self) -> None:
+ return await self._legacy._save_accounts_json()
+
+ async def _save_users_json(self, account_id: str) -> None:
+ return await self._legacy._save_users_json(account_id)
+
+ async def _save_settings_json(
+ self,
+ account_id: str,
+ *,
+ settings_data: Optional[dict] = None,
+ ) -> None:
+ return await self._legacy._save_settings_json(
+ account_id,
+ settings_data=settings_data,
+ )
diff --git a/openviking/server/app.py b/openviking/server/app.py
index a9cf57212..6e1cb00ee 100644
--- a/openviking/server/app.py
+++ b/openviking/server/app.py
@@ -3,6 +3,7 @@
"""FastAPI application for OpenViking HTTP Server."""
import asyncio
+import logging
import time
from contextlib import asynccontextmanager
from typing import Callable, Optional
@@ -164,6 +165,19 @@ def create_app(
allow_headers=["*"],
)
+ # Add request header logging middleware (for debug)
+ @app.middleware("http")
+ async def log_request_headers(request: Request, call_next: Callable):
+ access_logger = logging.getLogger("uvicorn.access")
+ if access_logger.isEnabledFor(logging.DEBUG):
+ headers = dict(request.headers)
+ header_names = ", ".join(sorted(headers.keys()))
+ access_logger.debug(
+ f"Request headers for {request.method} {request.url.path}: {header_names}"
+ )
+ response = await call_next(request)
+ return response
+
# Add request timing middleware
@app.middleware("http")
async def add_timing(request: Request, call_next: Callable):
diff --git a/openviking_cli/client/http.py b/openviking_cli/client/http.py
index 86e23468b..97652993e 100644
--- a/openviking_cli/client/http.py
+++ b/openviking_cli/client/http.py
@@ -134,6 +134,7 @@ class AsyncHTTPClient(BaseClient):
account: Optional[str] = None,
user: Optional[str] = None,
timeout: float = 60.0,
+ extra_headers: Optional[Dict[str, str]] = None,
):
"""Initialize AsyncHTTPClient.
@@ -147,6 +148,7 @@ class AsyncHTTPClient(BaseClient):
user: User identifier for multi-tenant auth. Required when using root key
to access tenant-scoped APIs. If not provided, reads from ovcli.conf.
timeout: HTTP request timeout in seconds. Default 60.0.
+ extra_headers: Additional HTTP headers to send with requests. If not provided, reads from ovcli.conf.
"""
should_load_cli_config = (
url is None
@@ -155,6 +157,7 @@ class AsyncHTTPClient(BaseClient):
or account is None
or user is None
or timeout == 60.0
+ or extra_headers is None
)
if should_load_cli_config:
cli_config = load_ovcli_config()
@@ -166,6 +169,8 @@ class AsyncHTTPClient(BaseClient):
user = user or cli_config.user
if timeout == 60.0: # only override default with config value
timeout = cli_config.timeout
+ if extra_headers is None:
+ extra_headers = cli_config.extra_headers
if not url:
raise ValueError(
"url is required. Pass it explicitly or configure in "
@@ -178,6 +183,7 @@ class AsyncHTTPClient(BaseClient):
self._user_id = user
self._user = UserIdentifier.the_default_user()
self._timeout = timeout
+ self._extra_headers = extra_headers
self._http: Optional[httpx.AsyncClient] = None
self._observer: Optional[_HTTPObserver] = None
@@ -194,6 +200,8 @@ class AsyncHTTPClient(BaseClient):
headers["X-OpenViking-Account"] = self._account
if self._user_id:
headers["X-OpenViking-User"] = self._user_id
+ if self._extra_headers:
+ headers.update(self._extra_headers)
self._http = httpx.AsyncClient(
base_url=self._url,
headers=headers,
diff --git a/openviking_cli/client/sync_http.py b/openviking_cli/client/sync_http.py
index 1e3cd3a92..6af7c892e 100644
--- a/openviking_cli/client/sync_http.py
+++ b/openviking_cli/client/sync_http.py
@@ -32,18 +32,22 @@ class SyncHTTPClient:
self,
url: Optional[str] = None,
api_key: Optional[str] = None,
+ user_id: Optional[str] = None,
agent_id: Optional[str] = None,
account: Optional[str] = None,
user: Optional[str] = None,
timeout: float = 60.0,
+ extra_headers: Optional[Dict[str, str]] = None,
):
self._async_client = AsyncHTTPClient(
url=url,
api_key=api_key,
+ user_id=user_id,
agent_id=agent_id,
account=account,
user=user,
timeout=timeout,
+ extra_headers=extra_headers,
)
self._initialized = False
diff --git a/openviking_cli/session/user_id.py b/openviking_cli/session/user_id.py
index 4d50201ec..e7205b0b5 100644
--- a/openviking_cli/session/user_id.py
+++ b/openviking_cli/session/user_id.py
@@ -1,9 +1,43 @@
import hashlib
import logging
import re
+from typing import Optional
logger = logging.getLogger(__name__)
+# Validation pattern reused across different modules
+# Note: hyphen (-) must be at the end or escaped to avoid being interpreted as a range
+_VALIDATION_PATTERN = re.compile(r"^[a-zA-Z0-9_.@-]+$")
+
+
+def validate_identifier_part(part: str, part_name: str) -> Optional[str]:
+ """Validate a single part of an identifier (account_id, user_id, or agent_id).
+
+ Returns an error message if invalid, None if valid.
+ """
+ if not part:
+ return f"{part_name} is empty"
+ if not _VALIDATION_PATTERN.match(part):
+ return f"{part_name} must be alpha_numeric string."
+ if part.count("@") > 1:
+ return f"{part_name} must have at most one @."
+ return None
+
+
+def validate_account_id(account_id: str) -> Optional[str]:
+ """Validate an account_id. Returns an error message if invalid, None if valid."""
+ return validate_identifier_part(account_id, "account_id")
+
+
+def validate_user_id(user_id: str) -> Optional[str]:
+ """Validate a user_id. Returns an error message if invalid, None if valid."""
+ return validate_identifier_part(user_id, "user_id")
+
+
+def validate_agent_id(agent_id: str) -> Optional[str]:
+ """Validate an agent_id. Returns an error message if invalid, None if valid."""
+ return validate_identifier_part(agent_id, "agent_id")
+
class UserIdentifier(object):
def __init__(self, account_id: str, user_id: str, agent_id: str):
@@ -23,20 +57,16 @@ class UserIdentifier(object):
return cls("default", default_username, "default")
def _validate_error(self) -> str:
- """Validate the user identifier. all fields must be non-empty strings, and chars only in [a-zA-Z0-9_.-]."""
- pattern = re.compile(r"^[a-zA-Z0-9_.-]+$")
- if not self._account_id:
- return "account_id is empty"
- if not pattern.match(self._account_id):
- return "account_id must be alpha-numeric string."
- if not self._user_id:
- return "user_id is empty"
- if not pattern.match(self._user_id):
- return "user_id must be alpha-numeric string."
- if not self._agent_id:
- return "agent_id is empty"
- if not pattern.match(self._agent_id):
- return "agent_id must be alpha-numeric string."
+ """Validate the user identifier using shared validation functions."""
+ verr = validate_account_id(self._account_id)
+ if verr:
+ return verr
+ verr = validate_user_id(self._user_id)
+ if verr:
+ return verr
+ verr = validate_agent_id(self._agent_id)
+ if verr:
+ return verr
return ""
@property
diff --git a/openviking_cli/utils/config/ovcli_config.py b/openviking_cli/utils/config/ovcli_config.py
index a8ac66d95..493f86172 100644
--- a/openviking_cli/utils/config/ovcli_config.py
+++ b/openviking_cli/utils/config/ovcli_config.py
@@ -3,9 +3,9 @@
"""Configuration schema and loader for ovcli.conf."""
from pathlib import Path
-from typing import Optional
+from typing import Any, Dict, Optional
-from pydantic import BaseModel, ValidationError
+from pydantic import BaseModel, ValidationError, model_validator
from .config_loader import resolve_config_path
from .config_utils import format_validation_error
@@ -32,9 +32,25 @@ class OVCLIConfig(BaseModel):
user: Optional[str] = None
timeout: float = 60.0
upload: Optional[OVCLIUploadConfig] = None
+ extra_headers: Optional[Dict[str, str]] = None
model_config = {"extra": "forbid"}
+ @model_validator(mode="before")
+ @classmethod
+ def handle_extra_headers_aliases(cls, data: Any) -> Any:
+ if isinstance(data, dict):
+ # 支持 extra_header 作为 extra_headers 的别名
+ if "extra_header" in data and "extra_headers" not in data:
+ # 复制字典并移除 extra_header,避免 extra: "forbid" 报错
+ new_data = {k: v for k, v in data.items() if k != "extra_header"}
+ new_data["extra_headers"] = data["extra_header"]
+ data = new_data
+ elif "extra_headers" in data and "extra_header" in data:
+ # 优先使用 extra_headers,移除 extra_header
+ data = {k: v for k, v in data.items() if k != "extra_header"}
+ return data
+
def load_ovcli_config(config_path: Optional[str] = None) -> Optional[OVCLIConfig]:
"""Load ovcli.conf if present and validate it strictly."""
diff --git a/tests/client/test_http_client_config.py b/tests/client/test_http_client_config.py
index 7d6204be6..92e4718dd 100644
--- a/tests/client/test_http_client_config.py
+++ b/tests/client/test_http_client_config.py
@@ -119,3 +119,96 @@ def test_async_http_client_rejects_unknown_ovcli_upload_field(tmp_path, monkeypa
with pytest.raises(ValueError, match=r"ovcli\.upload\.unknown"):
AsyncHTTPClient()
+
+
+def test_async_http_client_loads_extra_headers_from_ovcli_config(tmp_path, monkeypatch):
+ config_path = tmp_path / "ovcli.conf"
+ config_path.write_text(
+ json.dumps(
+ {
+ "url": "http://config-host:1933",
+ "api_key": "config-key",
+ "extra_headers": {
+ "X-Custom-Header": "custom-value",
+ "Authorization": "Bearer token",
+ },
+ }
+ )
+ )
+ monkeypatch.setenv(OPENVIKING_CLI_CONFIG_ENV, str(config_path))
+
+ client = AsyncHTTPClient()
+
+ assert client._url == "http://config-host:1933"
+ assert client._extra_headers == {
+ "X-Custom-Header": "custom-value",
+ "Authorization": "Bearer token",
+ }
+
+
+def test_async_http_client_explicit_extra_headers_override_ovcli_config(tmp_path, monkeypatch):
+ config_path = tmp_path / "ovcli.conf"
+ config_path.write_text(
+ json.dumps(
+ {
+ "url": "http://localhost:1933",
+ "api_key": "config-key",
+ "extra_headers": {"X-Custom-Header": "from-config"},
+ }
+ )
+ )
+ monkeypatch.setenv(OPENVIKING_CLI_CONFIG_ENV, str(config_path))
+
+ client = AsyncHTTPClient(
+ extra_headers={"X-Custom-Header": "from-explicit", "Another-Header": "another-value"}
+ )
+
+ assert client._extra_headers == {
+ "X-Custom-Header": "from-explicit",
+ "Another-Header": "another-value",
+ }
+
+
+def test_async_http_client_loads_extra_header_alias_from_ovcli_config(tmp_path, monkeypatch):
+ config_path = tmp_path / "ovcli.conf"
+ config_path.write_text(
+ json.dumps(
+ {
+ "url": "http://config-host:1933",
+ "api_key": "config-key",
+ "extra_header": {
+ "X-Custom-Header": "custom-value",
+ "Authorization": "Bearer token",
+ },
+ }
+ )
+ )
+ monkeypatch.setenv(OPENVIKING_CLI_CONFIG_ENV, str(config_path))
+
+ client = AsyncHTTPClient()
+
+ assert client._url == "http://config-host:1933"
+ assert client._extra_headers == {
+ "X-Custom-Header": "custom-value",
+ "Authorization": "Bearer token",
+ }
+
+
+def test_async_http_client_prefers_extra_headers_over_alias(tmp_path, monkeypatch):
+ config_path = tmp_path / "ovcli.conf"
+ config_path.write_text(
+ json.dumps(
+ {
+ "url": "http://config-host:1933",
+ "api_key": "config-key",
+ "extra_headers": {"X-Custom-Header": "from-plural"},
+ "extra_header": {"X-Custom-Header": "from-singular"},
+ }
+ )
+ )
+ monkeypatch.setenv(OPENVIKING_CLI_CONFIG_ENV, str(config_path))
+
+ client = AsyncHTTPClient()
+
+ # extra_headers 优先
+ assert client._extra_headers == {"X-Custom-Header": "from-plural"}
diff --git a/tests/server/test_api_key_manager.py b/tests/server/test_api_key_manager.py
index 85eed2136..b7e2d63cc 100644
--- a/tests/server/test_api_key_manager.py
+++ b/tests/server/test_api_key_manager.py
@@ -73,7 +73,9 @@ async def test_create_account(manager: APIKeyManager):
acct = _uid()
key = await manager.create_account(acct, "alice")
assert isinstance(key, str)
- assert len(key) == 64 # hex(32)
+ # New format: base64url(account_id).base64url(user_id).base64url(secret)
+ # Length varies based on account_id and user_id, but should have two dots
+ assert key.count(".") == 2
identity = manager.resolve(key)
assert identity.role == Role.ADMIN
@@ -275,7 +277,7 @@ async def test_create_account_with_encryption_enabled(manager_service):
_print_api_key_info("创建账号", acct, "alice", key, stored_hash)
assert isinstance(key, str)
- assert len(key) == 64 # hex(32)
+ assert key.count(".") == 2 # New format has two dots
_assert_argon2_hash(stored_hash)
identity = mgr.resolve(key)
@@ -454,3 +456,199 @@ def _get_stored_hash(mgr: APIKeyManager, account_id: str, user_id: str) -> str:
assert account_info is not None, f"账号 {account_id} 不存在"
assert user_id in account_info.users, f"用户 {user_id} 不存在"
return account_info.users[user_id]["key"]
+
+
+# ---- New format API Key tests ----
+
+
+async def test_new_format_key_generation(manager: APIKeyManager):
+ """Test that new keys are generated in the new format with three segments."""
+ from openviking.server.api_keys import is_new_format_key, parse_api_key
+
+ acct = _uid()
+ key = await manager.create_account(acct, "alice")
+
+ # Verify new format
+ assert is_new_format_key(key)
+ assert key.count(".") == 2
+
+ # Verify we can parse identity directly from the key
+ account_id, user_id, secret = parse_api_key(key)
+ assert account_id == acct
+ assert user_id == "alice"
+ assert len(secret) > 0
+
+
+async def test_new_format_key_resolve_fast_path(manager: APIKeyManager):
+ """Test that new format keys use the fast decode path without prefix lookup."""
+ acct = _uid()
+ key = await manager.create_account(acct, "alice")
+
+ # Resolve should work and return correct identity
+ identity = manager.resolve(key)
+ assert identity.role == Role.ADMIN
+ assert identity.account_id == acct
+ assert identity.user_id == "alice"
+
+
+async def test_register_user_generates_new_format(manager: APIKeyManager):
+ """Test that register_user generates keys in new format."""
+ from openviking.server.api_keys import is_new_format_key
+
+ acct = _uid()
+ await manager.create_account(acct, "alice")
+ key = await manager.register_user(acct, "bob", "user")
+
+ assert is_new_format_key(key)
+ identity = manager.resolve(key)
+ assert identity.role == Role.USER
+ assert identity.account_id == acct
+ assert identity.user_id == "bob"
+
+
+async def test_regenerate_key_upgrades_to_new_format(manager_service):
+ """Test that regenerate_key upgrades legacy keys to new format."""
+ from openviking.server.api_keys import LegacyAPIKeyManager, is_new_format_key
+
+ acct = _uid()
+
+ # First create a legacy key using LegacyAPIKeyManager
+ legacy_mgr = LegacyAPIKeyManager(
+ root_key=ROOT_KEY, viking_fs=manager_service.viking_fs, encryption_enabled=False
+ )
+ await legacy_mgr.load()
+ legacy_key = await legacy_mgr.create_account(acct, "alice")
+ assert not is_new_format_key(legacy_key)
+ assert len(legacy_key) == 64
+
+ # Now load with NewAPIKeyManager and regenerate
+ new_mgr = APIKeyManager(
+ root_key=ROOT_KEY, viking_fs=manager_service.viking_fs, encryption_enabled=False
+ )
+ await new_mgr.load()
+
+ # Legacy key should still work
+ identity = new_mgr.resolve(legacy_key)
+ assert identity.user_id == "alice"
+
+ # Regenerate should give a new format key
+ new_key = await new_mgr.regenerate_key(acct, "alice")
+ assert is_new_format_key(new_key)
+ assert new_key != legacy_key
+
+ # Old key should no longer work
+ from openviking_cli.exceptions import UnauthenticatedError
+
+ with pytest.raises(UnauthenticatedError):
+ new_mgr.resolve(legacy_key)
+
+ # New key should work
+ identity2 = new_mgr.resolve(new_key)
+ assert identity2.user_id == "alice"
+ assert identity2.account_id == acct
+
+
+async def test_mixed_key_formats(manager_service):
+ """Test that both legacy and new format keys can coexist."""
+ from openviking.server.api_keys import APIKeyManager, LegacyAPIKeyManager, is_new_format_key
+
+ acct = _uid()
+
+ # Create account with legacy manager
+ legacy_mgr = LegacyAPIKeyManager(
+ root_key=ROOT_KEY, viking_fs=manager_service.viking_fs, encryption_enabled=False
+ )
+ await legacy_mgr.load()
+ legacy_key = await legacy_mgr.create_account(acct, "alice")
+ assert not is_new_format_key(legacy_key)
+
+ # Add another user with new format using NewAPIKeyManager
+ new_mgr = APIKeyManager(
+ root_key=ROOT_KEY, viking_fs=manager_service.viking_fs, encryption_enabled=False
+ )
+ await new_mgr.load()
+ new_key = await new_mgr.register_user(acct, "bob", "user")
+ assert is_new_format_key(new_key)
+
+ # Both keys should work
+ identity1 = new_mgr.resolve(legacy_key)
+ assert identity1.user_id == "alice"
+
+ identity2 = new_mgr.resolve(new_key)
+ assert identity2.user_id == "bob"
+
+
+async def test_new_format_with_encryption(manager_service):
+ """Test new format key generation and verification with encryption enabled."""
+ from openviking.server.api_keys import is_new_format_key
+
+ acct = _uid()
+ mgr = APIKeyManager(
+ root_key=ROOT_KEY, viking_fs=manager_service.viking_fs, encryption_enabled=True
+ )
+ await mgr.load()
+
+ key = await mgr.create_account(acct, "alice")
+ assert is_new_format_key(key)
+
+ stored_hash = _get_stored_hash(mgr, acct, "alice")
+ _assert_argon2_hash(stored_hash)
+
+ # Key should still resolve correctly
+ identity = mgr.resolve(key)
+ assert identity.user_id == "alice"
+ assert identity.account_id == acct
+
+
+async def test_parse_api_key_edge_cases():
+ """Test parse_api_key with various edge cases."""
+ # Test with simple ASCII values
+ # First generate some test keys using the utility functions
+ from openviking.server.api_keys import generate_api_key, is_new_format_key, parse_api_key
+
+ key = generate_api_key("test-account", "test-user")
+ assert is_new_format_key(key)
+
+ account_id, user_id, secret = parse_api_key(key)
+ assert account_id == "test-account"
+ assert user_id == "test-user"
+ assert len(secret) == 64 # 32 bytes as hex
+
+
+async def test_encode_decode_roundtrip():
+ """Test that encode and decode operations are inverses."""
+ from openviking.server.api_keys.new import _decode_segment, _encode_segment
+
+ test_cases = [
+ "simple",
+ "with-hyphens",
+ "with_underscores",
+ "with@special!chars",
+ "acme_12345678", # Typical account format from _uid()
+ ]
+
+ for test_str in test_cases:
+ encoded = _encode_segment(test_str)
+ decoded = _decode_segment(encoded)
+ assert decoded == test_str, f"Failed for: {test_str}"
+
+
+async def test_is_new_format_key_validation():
+ """Test is_new_format_key correctly identifies key format."""
+ from openviking.server.api_keys import generate_api_key, is_new_format_key
+
+ # Valid new format
+ valid_key = generate_api_key("account", "user")
+ assert is_new_format_key(valid_key)
+
+ # Legacy format (64 hex chars)
+ assert not is_new_format_key("a" * 64)
+
+ # Empty string
+ assert not is_new_format_key("")
+
+ # Wrong number of segments
+ assert not is_new_format_key("onepart")
+ assert not is_new_format_key("two.parts")
+ assert not is_new_format_key("too.many.parts.here")