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
fix: apikey security: API Key 管理重构与安全增强 (#1686)
MaojiaSheng85986a91bd25
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rsindex 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.rsindex 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.rsindex 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.rsindex 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_keydiff --git a/docs/design/multi-tenant-design.md b/docs/design/multi-tenant-design.mdindex 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 为首个 adminPOST /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",再验证 secret3. 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 泄露 → 重新生成即可,只影响 bob6. alice 移除 bobDELETE /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**:```pythonclass 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.exampleindex 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__.pynew file mode 100644index 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.pysimilarity index 94%rename from openviking/server/api_keys.pyrename to openviking/server/api_keys/legacy.pyindex 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 hmacimport jsonimport secrets-from dataclasses import dataclass, fieldfrom datetime import datetime, timezonefrom typing import Dict, Optionalfrom argon2 import PasswordHasherfrom argon2.exceptions import VerifyMismatchError+from openviking.server.api_keys.models import AccountInfo, UserKeyEntryfrom openviking.server.identity import AccountNamespacePolicy, ResolvedIdentity, Rolefrom openviking.storage.viking_fs import VikingFSfrom openviking_cli.exceptions import (AlreadyExistsError,+ InvalidArgumentError,NotFoundError,UnauthenticatedError,)+from openviking_cli.session.user_id import validate_account_id, validate_user_idfrom openviking_cli.utils import get_loggerlogger = 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.pyARGON2_TIME_COST = 3ARGON2_MEMORY_COST = 65536ARGON2_PARALLELISM = 2ARGON2_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 keyasync 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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 loggingimport timefrom contextlib import asynccontextmanagerfrom 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.pyindex 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 keyto 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 Noneor user is Noneor 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.userif timeout == 60.0: # only override default with config valuetimeout = cli_config.timeout+ if extra_headers is None:+ extra_headers = cli_config.extra_headersif not url:raise ValueError("url is required. Pass it explicitly or configure in "@@ -178,6 +183,7 @@ class AsyncHTTPClient(BaseClient):self._user_id = userself._user = UserIdentifier.the_default_user()self._timeout = timeout+ self._extra_headers = extra_headersself._http: Optional[httpx.AsyncClient] = Noneself._observer: Optional[_HTTPObserver] = None@@ -194,6 +200,8 @@ class AsyncHTTPClient(BaseClient):headers["X-OpenViking-Account"] = self._accountif 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.pyindex 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 = Falsediff --git a/openviking_cli/session/user_id.py b/openviking_cli/session/user_id.pyindex 4d50201ec..e7205b0b5 100644--- a/openviking_cli/session/user_id.py+++ b/openviking_cli/session/user_id.py@@ -1,9 +1,43 @@import hashlibimport loggingimport re+from typing import Optionallogger = 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 verrreturn ""@propertydiff --git a/openviking_cli/utils/config/ovcli_config.py b/openviking_cli/utils/config/ovcli_config.pyindex 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_validatorfrom .config_loader import resolve_config_pathfrom .config_utils import format_validation_error@@ -32,9 +32,25 @@ class OVCLIConfig(BaseModel):user: Optional[str] = Nonetimeout: float = 60.0upload: Optional[OVCLIUploadConfig] = None+ extra_headers: Optional[Dict[str, str]] = Nonemodel_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.pyindex 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, monkeypawith 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.pyindex 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(".") == 2identity = 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()+ "[email protected]",+ ]++ 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")