Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(cli): support tenant identity defaults and overrides (#1019)
Jiahui Zhouc5033b0bcdd5
diff --git a/crates/ov_cli/README.md b/crates/ov_cli/README.mdindex 133e4120c..a8382b55b 100644--- a/crates/ov_cli/README.md+++ b/crates/ov_cli/README.md@@ -25,10 +25,15 @@ Create `~/.openviking/ovcli.conf`:```json{"url": "http://localhost:1933",- "api_key": "your-api-key"+ "api_key": "your-api-key",+ "account": "acme",+ "user": "alice",+ "agent_id": "assistant-1"}```+`account` and `user` are optional with a regular user key because the server can derive them from the key. They are recommended when you use `trusted` auth mode or a root key against tenant-scoped APIs.+## Quick Start```bash@@ -126,6 +131,9 @@ ov find "API authentication" --threshold 0.7 --limit 5# Recursive listov ls viking://resources --recursive+# Temporarily override identity from CLI flags+ov --account acme --user alice --agent-id assistant-2 ls viking://+# Glob searchov glob "**/*.md" --uri viking://resourcesdiff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rsindex 2fa6467f9..5f9c670bf 100644--- a/crates/ov_cli/src/client.rs+++ b/crates/ov_cli/src/client.rs@@ -4,8 +4,8 @@ use serde_json::Value;use std::fs::File;use std::path::Path;use tempfile::NamedTempFile;-use zip::write::FileOptions;use zip::CompressionMethod;+use zip::write::FileOptions;use crate::error::{Error, Result};@@ -15,6 +15,8 @@ pub struct HttpClient {http: ReqwestClient,base_url: String,api_key: Option<String>,+ account: Option<String>,+ user: Option<String>,agent_id: Option<String>,}@@ -24,6 +26,8 @@ impl HttpClient {base_url: impl Into<String>,api_key: Option<String>,agent_id: Option<String>,+ account: Option<String>,+ user: Option<String>,timeout_secs: f64,) -> Self {let http = ReqwestClient::builder()@@ -35,6 +39,8 @@ impl HttpClient {http,base_url: base_url.into().trim_end_matches('/').to_string(),api_key,+ account,+ user,agent_id,}}@@ -51,7 +57,8 @@ impl HttpClient {let temp_file = NamedTempFile::new()?;let file = File::create(temp_file.path())?;let mut zip = zip::ZipWriter::new(file);- let options: FileOptions<'_, ()> = FileOptions::default().compression_method(CompressionMethod::Deflated);+ let options: FileOptions<'_, ()> =+ FileOptions::default().compression_method(CompressionMethod::Deflated);let walkdir = walkdir::WalkDir::new(dir_path);for entry in walkdir.into_iter().filter_map(|e| e.ok()) {@@ -78,14 +85,13 @@ impl HttpClient {// Read file contentlet file_content = tokio::fs::read(file_path).await?;-+// Create multipart form- let part = reqwest::multipart::Part::bytes(file_content)- .file_name(file_name.to_string());-- let part = part.mime_str("application/octet-stream").map_err(|e| {- Error::Network(format!("Failed to set mime type: {}", e))- })?;+ let part = reqwest::multipart::Part::bytes(file_content).file_name(file_name.to_string());++ let part = part+ .mime_str("application/octet-stream")+ .map_err(|e| Error::Network(format!("Failed to set mime type: {}", e)))?;let form = reqwest::multipart::Form::new().part("file", part);@@ -126,6 +132,16 @@ impl HttpClient {headers.insert("X-OpenViking-Agent", value);}}+ if let Some(account) = &self.account {+ if let Ok(value) = reqwest::header::HeaderValue::from_str(account) {+ headers.insert("X-OpenViking-Account", value);+ }+ }+ if let Some(user) = &self.user {+ if let Ok(value) = reqwest::header::HeaderValue::from_str(user) {+ headers.insert("X-OpenViking-User", value);+ }+ }headers}@@ -224,10 +240,7 @@ impl HttpClient {self.handle_response(response).await}- async fn handle_response<T: DeserializeOwned>(- &self,- response: reqwest::Response,- ) -> Result<T> {+ async fn handle_response<T: DeserializeOwned>(&self, response: reqwest::Response) -> Result<T> {let status = response.status();// Handle empty response (204 No Content, etc.)@@ -248,7 +261,11 @@ impl HttpClient {.and_then(|e| e.get("message")).and_then(|m| m.as_str()).map(|s| s.to_string())- .or_else(|| json.get("detail").and_then(|d| d.as_str()).map(|s| s.to_string()))+ .or_else(|| {+ json.get("detail")+ .and_then(|d| d.as_str())+ .map(|s| s.to_string())+ }).unwrap_or_else(|| format!("HTTP error {}", status));return Err(Error::Api(error_msg));}@@ -296,7 +313,12 @@ impl HttpClient {self.get("/api/v1/content/overview", ¶ms).await}- pub async fn reindex(&self, uri: &str, regenerate: bool, wait: bool) -> Result<serde_json::Value> {+ pub async fn reindex(+ &self,+ uri: &str,+ regenerate: bool,+ wait: bool,+ ) -> Result<serde_json::Value> {let body = serde_json::json!({"uri": uri,"regenerate": regenerate,@@ -309,7 +331,7 @@ impl HttpClient {pub async fn get_bytes(&self, uri: &str) -> Result<Vec<u8>> {let url = format!("{}/api/v1/content/download", self.base_url);let params = vec![("uri".to_string(), uri.to_string())];-+let response = self.http.get(&url)@@ -326,20 +348,22 @@ impl HttpClient {.json().await.map_err(|e| Error::Network(format!("Failed to parse error response: {}", e)));-+let error_msg = match json_result {- Ok(json) => {- json- .get("error")- .and_then(|e| e.get("message"))- .and_then(|m| m.as_str())- .map(|s| s.to_string())- .or_else(|| json.get("detail").and_then(|d| d.as_str()).map(|s| s.to_string()))- .unwrap_or_else(|| format!("HTTP error {}", status))- }+ Ok(json) => json+ .get("error")+ .and_then(|e| e.get("message"))+ .and_then(|m| m.as_str())+ .map(|s| s.to_string())+ .or_else(|| {+ json.get("detail")+ .and_then(|d| d.as_str())+ .map(|s| s.to_string())+ })+ .unwrap_or_else(|| format!("HTTP error {}", status)),Err(_) => format!("HTTP error {}", status),};-+return Err(Error::Api(error_msg));}@@ -352,7 +376,16 @@ impl HttpClient {// ============ Filesystem Methods ============- pub async fn ls(&self, uri: &str, simple: bool, recursive: bool, output: &str, abs_limit: i32, show_all_hidden: bool, node_limit: i32) -> Result<serde_json::Value> {+ pub async fn ls(+ &self,+ uri: &str,+ simple: bool,+ recursive: bool,+ output: &str,+ abs_limit: i32,+ show_all_hidden: bool,+ node_limit: i32,+ ) -> Result<serde_json::Value> {let params = vec![("uri".to_string(), uri.to_string()),("simple".to_string(), simple.to_string()),@@ -365,7 +398,15 @@ impl HttpClient {self.get("/api/v1/fs/ls", ¶ms).await}- pub async fn tree(&self, uri: &str, output: &str, abs_limit: i32, show_all_hidden: bool, node_limit: i32, level_limit: i32) -> Result<serde_json::Value> {+ pub async fn tree(+ &self,+ uri: &str,+ output: &str,+ abs_limit: i32,+ show_all_hidden: bool,+ node_limit: i32,+ level_limit: i32,+ ) -> Result<serde_json::Value> {let params = vec![("uri".to_string(), uri.to_string()),("output".to_string(), output.to_string()),@@ -442,7 +483,13 @@ impl HttpClient {self.post("/api/v1/search/search", &body).await}- pub async fn grep(&self, uri: &str, pattern: &str, ignore_case: bool, node_limit: i32) -> Result<serde_json::Value> {+ pub async fn grep(+ &self,+ uri: &str,+ pattern: &str,+ ignore_case: bool,+ node_limit: i32,+ ) -> Result<serde_json::Value> {let body = serde_json::json!({"uri": uri,"pattern": pattern,@@ -452,8 +499,12 @@ impl HttpClient {self.post("/api/v1/search/grep", &body).await}-- pub async fn glob(&self, pattern: &str, uri: &str, node_limit: i32) -> Result<serde_json::Value> {+ pub async fn glob(+ &self,+ pattern: &str,+ uri: &str,+ node_limit: i32,+ ) -> Result<serde_json::Value> {let body = serde_json::json!({"pattern": pattern,"uri": uri,@@ -726,11 +777,7 @@ impl HttpClient {self.put(&path, &body).await}- pub async fn admin_regenerate_key(- &self,- account_id: &str,- user_id: &str,- ) -> Result<Value> {+ pub async fn admin_regenerate_key(&self, account_id: &str, user_id: &str) -> Result<Value> {let path = format!("/api/v1/admin/accounts/{}/users/{}/key",account_id, user_id@@ -790,3 +837,47 @@ impl HttpClient {Ok(count)}}++#[cfg(test)]+mod tests {+ use super::HttpClient;++ #[test]+ fn build_headers_includes_tenant_identity_headers() {+ 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,+ );++ let headers = client.build_headers();++ assert_eq!(+ headers+ .get("X-API-Key")+ .and_then(|value| value.to_str().ok()),+ Some("test-key")+ );+ assert_eq!(+ headers+ .get("X-OpenViking-Agent")+ .and_then(|value| value.to_str().ok()),+ Some("assistant-1")+ );+ assert_eq!(+ headers+ .get("X-OpenViking-Account")+ .and_then(|value| value.to_str().ok()),+ Some("acme")+ );+ assert_eq!(+ headers+ .get("X-OpenViking-User")+ .and_then(|value| value.to_str().ok()),+ Some("alice")+ );+ }+}diff --git a/crates/ov_cli/src/config.rs b/crates/ov_cli/src/config.rsindex e27b3a650..ca1c613f1 100644--- a/crates/ov_cli/src/config.rs+++ b/crates/ov_cli/src/config.rs@@ -10,6 +10,8 @@ pub struct Config {#[serde(default = "default_url")]pub url: String,pub api_key: Option<String>,+ pub account: Option<String>,+ pub user: Option<String>,pub agent_id: Option<String>,#[serde(default = "default_timeout")]pub timeout: f64,@@ -40,6 +42,8 @@ impl Default for Config {Self {url: "http://localhost:1933".to_string(),api_key: None,+ account: None,+ user: None,agent_id: None,timeout: 60.0,output: "table".to_string(),@@ -108,3 +112,26 @@ pub fn get_or_create_machine_id() -> Result<String> {Err(_) => Ok("default".to_string()),}}++#[cfg(test)]+mod tests {+ use super::Config;++ #[test]+ fn config_deserializes_account_and_user_fields() {+ let config: Config = serde_json::from_str(+ r#"{+ "url": "http://localhost:1933",+ "api_key": "test-key",+ "account": "acme",+ "user": "alice",+ "agent_id": "assistant-1"+ }"#,+ )+ .expect("config should deserialize");++ assert_eq!(config.account.as_deref(), Some("acme"));+ assert_eq!(config.user.as_deref(), Some("alice"));+ assert_eq!(config.agent_id.as_deref(), Some("assistant-1"));+ }+}diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rsindex 5e49d0319..240d30434 100644--- a/crates/ov_cli/src/main.rs+++ b/crates/ov_cli/src/main.rs@@ -20,13 +20,46 @@ pub struct CliContext {}impl CliContext {- pub fn new(output_format: OutputFormat, compact: bool) -> Result<Self> {+ pub fn new(+ output_format: OutputFormat,+ compact: bool,+ account: Option<String>,+ user: Option<String>,+ agent_id: Option<String>,+ ) -> Result<Self> {let config = Config::load()?;- Ok(Self {+ Ok(Self::from_config(config,output_format,compact,- })+ account,+ user,+ agent_id,+ ))+ }++ fn from_config(+ mut config: Config,+ output_format: OutputFormat,+ compact: bool,+ account: Option<String>,+ user: Option<String>,+ agent_id: Option<String>,+ ) -> Self {+ if account.is_some() {+ config.account = account;+ }+ if user.is_some() {+ config.user = user;+ }+ if agent_id.is_some() {+ config.agent_id = agent_id;+ }+ Self {+ config,+ output_format,+ compact,+ }}pub fn get_client(&self) -> client::HttpClient {@@ -34,6 +67,8 @@ impl CliContext {&self.config.url,self.config.api_key.clone(),self.config.agent_id.clone(),+ self.config.account.clone(),+ self.config.user.clone(),self.config.timeout,)}@@ -53,6 +88,18 @@ struct Cli {#[arg(short, long, global = true, default_value = "true")]compact: bool,+ /// Account identifier to send as X-OpenViking-Account+ #[arg(long, global = true)]+ account: Option<String>,++ /// User identifier to send as X-OpenViking-User+ #[arg(long, global = true)]+ user: Option<String>,++ /// Agent identifier to send as X-OpenViking-Agent+ #[arg(long = "agent-id", global = true)]+ agent_id: Option<String>,+#[command(subcommand)]command: Commands,}@@ -202,7 +249,12 @@ enum Commands {#[arg(short, long)]all: bool,/// Maximum number of nodes to list- #[arg(long = "node-limit", short = 'n', alias = "limit", default_value = "256")]+ #[arg(+ long = "node-limit",+ short = 'n',+ alias = "limit",+ default_value = "256"+ )]node_limit: i32,},/// Get directory tree@@ -216,7 +268,12 @@ enum Commands {#[arg(short, long)]all: bool,/// Maximum number of nodes to list- #[arg(long = "node-limit", short = 'n', alias = "limit", default_value = "256")]+ #[arg(+ long = "node-limit",+ short = 'n',+ alias = "limit",+ default_value = "256"+ )]node_limit: i32,/// Maximum depth level to traverse (default: 3)#[arg(short = 'L', long = "level-limit", default_value = "3")]@@ -290,7 +347,12 @@ enum Commands {#[arg(short, long, default_value = "")]uri: String,/// Maximum number of results- #[arg(short = 'n', long = "node-limit", alias = "limit", default_value = "10")]+ #[arg(+ short = 'n',+ long = "node-limit",+ alias = "limit",+ default_value = "10"+ )]node_limit: i32,/// Score threshold#[arg(short, long)]@@ -307,7 +369,12 @@ enum Commands {#[arg(long)]session_id: Option<String>,/// Maximum number of results- #[arg(short = 'n', long = "node-limit", alias = "limit", default_value = "10")]+ #[arg(+ short = 'n',+ long = "node-limit",+ alias = "limit",+ default_value = "10"+ )]node_limit: i32,/// Score threshold#[arg(short, long)]@@ -324,7 +391,12 @@ enum Commands {#[arg(short, long)]ignore_case: bool,/// Maximum number of results- #[arg(short = 'n', long = "node-limit", alias = "limit", default_value = "256")]+ #[arg(+ short = 'n',+ long = "node-limit",+ alias = "limit",+ default_value = "256"+ )]node_limit: i32,},/// Run file glob pattern search@@ -335,7 +407,12 @@ enum Commands {#[arg(short, long, default_value = "viking://")]uri: String,/// Maximum number of results- #[arg(short = 'n', long = "node-limit", alias = "limit", default_value = "256")]+ #[arg(+ short = 'n',+ long = "node-limit",+ alias = "limit",+ default_value = "256"+ )]node_limit: i32,},/// Add memory in one shot (creates session, adds messages, commits)@@ -522,7 +599,13 @@ async fn main() {let output_format = cli.output;let compact = cli.compact;- let ctx = match CliContext::new(output_format, compact) {+ let ctx = match CliContext::new(+ output_format,+ compact,+ cli.account.clone(),+ cli.user.clone(),+ cli.agent_id.clone(),+ ) {Ok(ctx) => ctx,Err(e) => {eprintln!("Error: {}", e);@@ -564,65 +647,71 @@ async fn main() {).await}- Commands::AddSkill { data, wait, timeout } => {- handle_add_skill(data, wait, timeout, ctx).await- }- Commands::Relations { uri } => {- handle_relations(uri, ctx).await- }- Commands::Link { from_uri, to_uris, reason } => {- handle_link(from_uri, to_uris, reason, ctx).await- }- Commands::Unlink { from_uri, to_uri } => {- handle_unlink(from_uri, to_uri, ctx).await- }- Commands::Export { uri, to } => {- handle_export(uri, to, ctx).await- }- Commands::Import { file_path, target_uri, force, no_vectorize } => {- handle_import(file_path, target_uri, force, no_vectorize, ctx).await- }+ Commands::AddSkill {+ data,+ wait,+ timeout,+ } => handle_add_skill(data, wait, timeout, ctx).await,+ Commands::Relations { uri } => handle_relations(uri, ctx).await,+ Commands::Link {+ from_uri,+ to_uris,+ reason,+ } => handle_link(from_uri, to_uris, reason, ctx).await,+ Commands::Unlink { from_uri, to_uri } => handle_unlink(from_uri, to_uri, ctx).await,+ Commands::Export { uri, to } => handle_export(uri, to, ctx).await,+ Commands::Import {+ file_path,+ target_uri,+ force,+ no_vectorize,+ } => handle_import(file_path, target_uri, force, no_vectorize, ctx).await,Commands::Wait { timeout } => {let client = ctx.get_client();commands::system::wait(&client, timeout, ctx.output_format, ctx.compact).await- },+ }Commands::Status => {let client = ctx.get_client();commands::observer::system(&client, ctx.output_format, ctx.compact).await- },+ }Commands::Health => handle_health(ctx).await,Commands::System { action } => handle_system(action, ctx).await,Commands::Observer { action } => handle_observer(action, ctx).await,Commands::Session { action } => handle_session(action, ctx).await,Commands::Admin { action } => handle_admin(action, ctx).await,- Commands::Ls { uri, simple, recursive, abs_limit, all, node_limit } => {- handle_ls(uri, simple, recursive, abs_limit, all, node_limit, ctx).await- }- Commands::Tree { uri, abs_limit, all, node_limit, level_limit } => {- handle_tree(uri, abs_limit, all, node_limit, level_limit, ctx).await- }- Commands::Mkdir { uri } => {- handle_mkdir(uri, ctx).await- }- Commands::Rm { uri, recursive } => {- handle_rm(uri, recursive, ctx).await- }- Commands::Mv { from_uri, to_uri } => {- handle_mv(from_uri, to_uri, ctx).await- }- Commands::Stat { uri } => {- handle_stat(uri, ctx).await- }- Commands::AddMemory { content } => {- handle_add_memory(content, ctx).await- }- Commands::Tui { uri } => {- handle_tui(uri, ctx).await- }- Commands::Chat { message, session, sender, stream, no_format, no_history } => {+ Commands::Ls {+ uri,+ simple,+ recursive,+ abs_limit,+ all,+ node_limit,+ } => handle_ls(uri, simple, recursive, abs_limit, all, node_limit, ctx).await,+ Commands::Tree {+ uri,+ abs_limit,+ all,+ node_limit,+ level_limit,+ } => handle_tree(uri, abs_limit, all, node_limit, level_limit, ctx).await,+ Commands::Mkdir { uri } => handle_mkdir(uri, ctx).await,+ Commands::Rm { uri, recursive } => handle_rm(uri, recursive, ctx).await,+ Commands::Mv { from_uri, to_uri } => handle_mv(from_uri, to_uri, ctx).await,+ Commands::Stat { uri } => handle_stat(uri, ctx).await,+ Commands::AddMemory { content } => handle_add_memory(content, ctx).await,+ Commands::Tui { uri } => handle_tui(uri, ctx).await,+ Commands::Chat {+ message,+ session,+ sender,+ stream,+ no_format,+ no_history,+ } => {let session_id = session.or_else(|| config::get_or_create_machine_id().ok());let cmd = commands::chat::ChatCommand {- endpoint: std::env::var("VIKINGBOT_ENDPOINT").unwrap_or_else(|_| "http://localhost:1933/bot/v1".to_string()),+ endpoint: std::env::var("VIKINGBOT_ENDPOINT")+ .unwrap_or_else(|_| "http://localhost:1933/bot/v1".to_string()),api_key: std::env::var("VIKINGBOT_API_KEY").ok(),session: session_id,sender,@@ -641,23 +730,37 @@ async fn main() {Commands::Read { uri } => handle_read(uri, ctx).await,Commands::Abstract { uri } => handle_abstract(uri, ctx).await,Commands::Overview { uri } => handle_overview(uri, ctx).await,- Commands::Reindex { uri, regenerate, wait } => {- handle_reindex(uri, regenerate, wait, ctx).await- }+ Commands::Reindex {+ uri,+ regenerate,+ wait,+ } => handle_reindex(uri, regenerate, wait, ctx).await,Commands::Get { uri, local_path } => handle_get(uri, local_path, ctx).await,- Commands::Find { query, uri, node_limit, threshold } => {- handle_find(query, uri, node_limit, threshold, ctx).await- }- Commands::Search { query, uri, session_id, node_limit, threshold } => {- handle_search(query, uri, session_id, node_limit, threshold, ctx).await- }- Commands::Grep { uri, pattern, ignore_case, node_limit } => {- handle_grep(uri, pattern, ignore_case, node_limit, ctx).await- }+ Commands::Find {+ query,+ uri,+ node_limit,+ threshold,+ } => handle_find(query, uri, node_limit, threshold, ctx).await,+ Commands::Search {+ query,+ uri,+ session_id,+ node_limit,+ threshold,+ } => handle_search(query, uri, session_id, node_limit, threshold, ctx).await,+ Commands::Grep {+ uri,+ pattern,+ ignore_case,+ node_limit,+ } => handle_grep(uri, pattern, ignore_case, node_limit, ctx).await,- Commands::Glob { pattern, uri, node_limit } => {- handle_glob(pattern, uri, node_limit, ctx).await- }+ Commands::Glob {+ pattern,+ uri,+ node_limit,+ } => handle_glob(pattern, uri, node_limit, ctx).await,};if let Err(e) = result {@@ -682,32 +785,35 @@ async fn handle_add_resource(watch_interval: f64,ctx: CliContext,) -> Result<()> {- let is_url = path.starts_with("http://")- || path.starts_with("https://")- || path.starts_with("git@");-+ let is_url =+ path.starts_with("http://") || path.starts_with("https://") || path.starts_with("git@");+if !is_url {use std::path::Path;-+// Unescape path: replace backslash followed by space with just spacelet unescaped_path = path.replace("\\ ", " ");let path_obj = Path::new(&unescaped_path);if !path_obj.exists() {eprintln!("Error: Path '{}' does not exist.", path);-+// Check if there might be unquoted spacesuse std::env;let args: Vec<String> = env::args().collect();-- if let Some(add_resource_pos) = args.iter().position(|s| s == "add-resource" || s == "add") {++ if let Some(add_resource_pos) =+ args.iter().position(|s| s == "add-resource" || s == "add")+ {if args.len() > add_resource_pos + 2 {let extra_args = &args[add_resource_pos + 2..];let suggested_path = format!("{} {}", path, extra_args.join(" "));- eprintln!("\nIt looks like you may have forgotten to quote a path with spaces.");+ eprintln!(+ "\nIt looks like you may have forgotten to quote a path with spaces."+ );eprintln!("Suggested command: ov add-resource \"{}\"", suggested_path);}}-+std::process::exit(1);}path = unescaped_path;@@ -731,6 +837,8 @@ async fn handle_add_resource(&ctx.config.url,ctx.config.api_key.clone(),ctx.config.agent_id.clone(),+ ctx.config.account.clone(),+ ctx.config.user.clone(),effective_timeout,);commands::resources::add_resource(@@ -750,7 +858,8 @@ async fn handle_add_resource(watch_interval,ctx.output_format,ctx.compact,- ).await+ )+ .await}async fn handle_add_skill(@@ -761,14 +870,19 @@ async fn handle_add_skill() -> Result<()> {let client = ctx.get_client();commands::resources::add_skill(- &client, &data, wait, timeout, ctx.output_format, ctx.compact- ).await+ &client,+ &data,+ wait,+ timeout,+ ctx.output_format,+ ctx.compact,+ )+ .await}async fn handle_relations(uri: String, ctx: CliContext) -> Result<()> {let client = ctx.get_client();- commands::relations::list_relations(&client, &uri, ctx.output_format, ctx.compact- ).await+ commands::relations::list_relations(&client, &uri, ctx.output_format, ctx.compact).await}async fn handle_link(@@ -779,25 +893,24 @@ async fn handle_link() -> Result<()> {let client = ctx.get_client();commands::relations::link(- &client, &from_uri, &to_uris, &reason, ctx.output_format, ctx.compact- ).await+ &client,+ &from_uri,+ &to_uris,+ &reason,+ ctx.output_format,+ ctx.compact,+ )+ .await}-async fn handle_unlink(- from_uri: String,- to_uri: String,- ctx: CliContext,-) -> Result<()> {+async fn handle_unlink(from_uri: String, to_uri: String, ctx: CliContext) -> Result<()> {let client = ctx.get_client();- commands::relations::unlink(- &client, &from_uri, &to_uri, ctx.output_format, ctx.compact- ).await+ commands::relations::unlink(&client, &from_uri, &to_uri, ctx.output_format, ctx.compact).await}async fn handle_export(uri: String, to: String, ctx: CliContext) -> Result<()> {let client = ctx.get_client();- commands::pack::export(&client, &uri, &to, ctx.output_format, ctx.compact- ).await+ commands::pack::export(&client, &uri, &to, ctx.output_format, ctx.compact).await}async fn handle_import(@@ -809,8 +922,15 @@ async fn handle_import() -> Result<()> {let client = ctx.get_client();commands::pack::import(- &client, &file_path, &target_uri, force, no_vectorize, ctx.output_format, ctx.compact- ).await+ &client,+ &file_path,+ &target_uri,+ force,+ no_vectorize,+ ctx.output_format,+ ctx.compact,+ )+ .await}async fn handle_system(cmd: SystemCommands, ctx: CliContext) -> Result<()> {@@ -823,8 +943,7 @@ async fn handle_system(cmd: SystemCommands, ctx: CliContext) -> Result<()> {commands::system::status(&client, ctx.output_format, ctx.compact).await}SystemCommands::Health => {- let _ =- commands::system::health(&client, ctx.output_format, ctx.compact).await?;+ let _ = commands::system::health(&client, ctx.output_format, ctx.compact).await?;Ok(())}SystemCommands::Crypto { action } => commands::crypto::handle_crypto(action).await,@@ -865,21 +984,31 @@ async fn handle_session(cmd: SessionCommands, ctx: CliContext) -> Result<()> {commands::session::list_sessions(&client, ctx.output_format, ctx.compact).await}SessionCommands::Get { session_id } => {- commands::session::get_session(&client, &session_id, ctx.output_format, ctx.compact- ).await+ commands::session::get_session(&client, &session_id, ctx.output_format, ctx.compact)+ .await}SessionCommands::Delete { session_id } => {- commands::session::delete_session(&client, &session_id, ctx.output_format, ctx.compact- ).await+ commands::session::delete_session(&client, &session_id, ctx.output_format, ctx.compact)+ .await}- SessionCommands::AddMessage { session_id, role, content } => {+ SessionCommands::AddMessage {+ session_id,+ role,+ content,+ } => {commands::session::add_message(- &client, &session_id, &role, &content, ctx.output_format, ctx.compact- ).await+ &client,+ &session_id,+ &role,+ &content,+ ctx.output_format,+ ctx.compact,+ )+ .await}SessionCommands::Commit { session_id } => {- commands::session::commit_session(&client, &session_id, ctx.output_format, ctx.compact- ).await+ commands::session::commit_session(&client, &session_id, ctx.output_format, ctx.compact)+ .await}}}@@ -887,43 +1016,84 @@ async fn handle_session(cmd: SessionCommands, ctx: CliContext) -> Result<()> {async fn handle_admin(cmd: AdminCommands, ctx: CliContext) -> Result<()> {let client = ctx.get_client();match cmd {- AdminCommands::CreateAccount { account_id, admin_user_id } => {+ AdminCommands::CreateAccount {+ account_id,+ admin_user_id,+ } => {commands::admin::create_account(- &client, &account_id, &admin_user_id, ctx.output_format, ctx.compact,- ).await+ &client,+ &account_id,+ &admin_user_id,+ ctx.output_format,+ ctx.compact,+ )+ .await}AdminCommands::ListAccounts => {commands::admin::list_accounts(&client, ctx.output_format, ctx.compact).await}AdminCommands::DeleteAccount { account_id } => {- commands::admin::delete_account(- &client, &account_id, ctx.output_format, ctx.compact,- ).await+ commands::admin::delete_account(&client, &account_id, ctx.output_format, ctx.compact)+ .await}- AdminCommands::RegisterUser { account_id, user_id, role } => {+ AdminCommands::RegisterUser {+ account_id,+ user_id,+ role,+ } => {commands::admin::register_user(- &client, &account_id, &user_id, &role, ctx.output_format, ctx.compact,- ).await+ &client,+ &account_id,+ &user_id,+ &role,+ ctx.output_format,+ ctx.compact,+ )+ .await}AdminCommands::ListUsers { account_id } => {- commands::admin::list_users(- &client, &account_id, ctx.output_format, ctx.compact,- ).await+ commands::admin::list_users(&client, &account_id, ctx.output_format, ctx.compact).await}- AdminCommands::RemoveUser { account_id, user_id } => {+ AdminCommands::RemoveUser {+ account_id,+ user_id,+ } => {commands::admin::remove_user(- &client, &account_id, &user_id, ctx.output_format, ctx.compact,- ).await+ &client,+ &account_id,+ &user_id,+ ctx.output_format,+ ctx.compact,+ )+ .await}- AdminCommands::SetRole { account_id, user_id, role } => {+ AdminCommands::SetRole {+ account_id,+ user_id,+ role,+ } => {commands::admin::set_role(- &client, &account_id, &user_id, &role, ctx.output_format, ctx.compact,- ).await+ &client,+ &account_id,+ &user_id,+ &role,+ ctx.output_format,+ ctx.compact,+ )+ .await}- AdminCommands::RegenerateKey { account_id, user_id } => {+ AdminCommands::RegenerateKey {+ account_id,+ user_id,+ } => {commands::admin::regenerate_key(- &client, &account_id, &user_id, ctx.output_format, ctx.compact,- ).await+ &client,+ &account_id,+ &user_id,+ ctx.output_format,+ ctx.compact,+ )+ .await}}}@@ -940,21 +1110,17 @@ async fn handle_config(cmd: ConfigCommands, _ctx: CliContext) -> Result<()> {output::output_success(&serde_json::to_value(config).unwrap(),output::OutputFormat::Json,- true+ true,);Ok(())}- ConfigCommands::Validate => {- match Config::load() {- Ok(_) => {- println!("Configuration is valid");- Ok(())- }- Err(e) => {- Err(Error::Config(e.to_string()))- }+ ConfigCommands::Validate => match Config::load() {+ Ok(_) => {+ println!("Configuration is valid");+ Ok(())}- }+ Err(e) => Err(Error::Config(e.to_string())),+ },}}@@ -975,7 +1141,15 @@ async fn handle_overview(uri: String, ctx: CliContext) -> Result<()> {async fn handle_reindex(uri: String, regenerate: bool, wait: bool, ctx: CliContext) -> Result<()> {let client = ctx.get_client();- commands::content::reindex(&client, &uri, regenerate, wait, ctx.output_format, ctx.compact).await+ commands::content::reindex(+ &client,+ &uri,+ regenerate,+ wait,+ ctx.output_format,+ ctx.compact,+ )+ .await}async fn handle_get(uri: String, local_path: String, ctx: CliContext) -> Result<()> {@@ -997,7 +1171,16 @@ async fn handle_find(params.push(format!("\"{}\"", query));print_command_echo("ov find", ¶ms.join(" "), ctx.config.echo_command);let client = ctx.get_client();- commands::search::find(&client, &query, &uri, node_limit, threshold, ctx.output_format, ctx.compact).await+ commands::search::find(+ &client,+ &query,+ &uri,+ node_limit,+ threshold,+ ctx.output_format,+ ctx.compact,+ )+ .await}async fn handle_search(@@ -1018,7 +1201,17 @@ async fn handle_search(params.push(format!("\"{}\"", query));print_command_echo("ov search", ¶ms.join(" "), ctx.config.echo_command);let client = ctx.get_client();- commands::search::search(&client, &query, &uri, session_id, node_limit, threshold, ctx.output_format, ctx.compact).await+ commands::search::search(+ &client,+ &query,+ &uri,+ session_id,+ node_limit,+ threshold,+ ctx.output_format,+ ctx.compact,+ )+ .await}/// Print command with specified parameters for debugging@@ -1028,35 +1221,81 @@ fn print_command_echo(command: &str, params: &str, echo_enabled: bool) {}}-async fn handle_ls(uri: String, simple: bool, recursive: bool, abs_limit: i32, show_all_hidden: bool, node_limit: i32, ctx: CliContext) -> Result<()> {+async fn handle_ls(+ uri: String,+ simple: bool,+ recursive: bool,+ abs_limit: i32,+ show_all_hidden: bool,+ node_limit: i32,+ ctx: CliContext,+) -> Result<()> {let mut params = vec![uri.clone(),format!("-l {}", abs_limit),format!("-n {}", node_limit),];- if simple { params.push("-s".to_string()); }- if recursive { params.push("-r".to_string()); }- if show_all_hidden { params.push("-a".to_string()); }+ if simple {+ params.push("-s".to_string());+ }+ if recursive {+ params.push("-r".to_string());+ }+ if show_all_hidden {+ params.push("-a".to_string());+ }print_command_echo("ov ls", ¶ms.join(" "), ctx.config.echo_command);let client = ctx.get_client();let api_output = if ctx.compact { "agent" } else { "original" };- commands::filesystem::ls(&client, &uri, simple, recursive, api_output, abs_limit, show_all_hidden, node_limit, ctx.output_format, ctx.compact).await+ commands::filesystem::ls(+ &client,+ &uri,+ simple,+ recursive,+ api_output,+ abs_limit,+ show_all_hidden,+ node_limit,+ ctx.output_format,+ ctx.compact,+ )+ .await}-async fn handle_tree(uri: String, abs_limit: i32, show_all_hidden: bool, node_limit: i32, level_limit: i32, ctx: CliContext) -> Result<()> {+async fn handle_tree(+ uri: String,+ abs_limit: i32,+ show_all_hidden: bool,+ node_limit: i32,+ level_limit: i32,+ ctx: CliContext,+) -> Result<()> {let mut params = vec![uri.clone(),format!("-l {}", abs_limit),format!("-n {}", node_limit),format!("-L {}", level_limit),];- if show_all_hidden { params.push("-a".to_string()); }+ if show_all_hidden {+ params.push("-a".to_string());+ }print_command_echo("ov tree", ¶ms.join(" "), ctx.config.echo_command);let client = ctx.get_client();let api_output = if ctx.compact { "agent" } else { "original" };- commands::filesystem::tree(&client, &uri, api_output, abs_limit, show_all_hidden, node_limit, level_limit, ctx.output_format, ctx.compact).await+ commands::filesystem::tree(+ &client,+ &uri,+ api_output,+ abs_limit,+ show_all_hidden,+ node_limit,+ level_limit,+ ctx.output_format,+ ctx.compact,+ )+ .await}async fn handle_mkdir(uri: String, ctx: CliContext) -> Result<()> {@@ -1079,29 +1318,57 @@ async fn handle_stat(uri: String, ctx: CliContext) -> Result<()> {commands::filesystem::stat(&client, &uri, ctx.output_format, ctx.compact).await}-async fn handle_grep(uri: String, pattern: String, ignore_case: bool, node_limit: i32, ctx: CliContext) -> Result<()> {+async fn handle_grep(+ uri: String,+ pattern: String,+ ignore_case: bool,+ node_limit: i32,+ ctx: CliContext,+) -> Result<()> {let mut params = vec![format!("--uri={}", uri), format!("-n {}", node_limit)];- if ignore_case { params.push("-i".to_string()); }+ if ignore_case {+ params.push("-i".to_string());+ }params.push(format!("\"{}\"", pattern));print_command_echo("ov grep", ¶ms.join(" "), ctx.config.echo_command);let client = ctx.get_client();- commands::search::grep(&client, &uri, &pattern, ignore_case, node_limit, ctx.output_format, ctx.compact).await+ commands::search::grep(+ &client,+ &uri,+ &pattern,+ ignore_case,+ node_limit,+ ctx.output_format,+ ctx.compact,+ )+ .await}-async fn handle_glob(pattern: String, uri: String, node_limit: i32, ctx: CliContext) -> Result<()> {- let params = vec![format!("--uri={}", uri), format!("-n {}", node_limit), format!("\"{}\"", pattern)];+ let params = vec![+ format!("--uri={}", uri),+ format!("-n {}", node_limit),+ format!("\"{}\"", pattern),+ ];print_command_echo("ov glob", ¶ms.join(" "), ctx.config.echo_command);let client = ctx.get_client();- commands::search::glob(&client, &pattern, &uri, node_limit, ctx.output_format, ctx.compact).await+ commands::search::glob(+ &client,+ &pattern,+ &uri,+ node_limit,+ ctx.output_format,+ ctx.compact,+ )+ .await}async fn handle_health(ctx: CliContext) -> Result<()> {let client = ctx.get_client();-+// Reuse the system health commandlet _ = commands::system::health(&client, ctx.output_format, ctx.compact).await?;-+Ok(())}@@ -1109,3 +1376,57 @@ async fn handle_tui(uri: String, ctx: CliContext) -> Result<()> {let client = ctx.get_client();tui::run_tui(client, &uri).await}++#[cfg(test)]+mod tests {+ use super::{Cli, CliContext};+ use crate::config::Config;+ use crate::output::OutputFormat;+ use clap::Parser;++ #[test]+ fn cli_parses_global_identity_override_flags() {+ let cli = Cli::try_parse_from([+ "ov",+ "--account",+ "acme",+ "--user",+ "alice",+ "--agent-id",+ "assistant-1",+ "ls",+ ])+ .expect("cli should parse");++ assert_eq!(cli.account.as_deref(), Some("acme"));+ assert_eq!(cli.user.as_deref(), Some("alice"));+ assert_eq!(cli.agent_id.as_deref(), Some("assistant-1"));+ }++ #[test]+ fn cli_context_overrides_identity_from_cli_flags() {+ let config = Config {+ url: "http://localhost:1933".to_string(),+ api_key: Some("test-key".to_string()),+ account: Some("from-config-account".to_string()),+ user: Some("from-config-user".to_string()),+ agent_id: Some("from-config-agent".to_string()),+ timeout: 60.0,+ output: "table".to_string(),+ echo_command: true,+ };++ let ctx = CliContext::from_config(+ config,+ OutputFormat::Json,+ true,+ Some("from-cli-account".to_string()),+ Some("from-cli-user".to_string()),+ Some("from-cli-agent".to_string()),+ );++ assert_eq!(ctx.config.account.as_deref(), Some("from-cli-account"));+ assert_eq!(ctx.config.user.as_deref(), Some("from-cli-user"));+ assert_eq!(ctx.config.agent_id.as_deref(), Some("from-cli-agent"));+ }+}diff --git a/docs/en/api/01-overview.md b/docs/en/api/01-overview.mdindex ae4ddbd44..f9bf74f87 100644--- a/docs/en/api/01-overview.md+++ b/docs/en/api/01-overview.md@@ -73,6 +73,8 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf{"url": "http://localhost:1933","api_key": "your-key",+ "account": "acme",+ "user": "alice","agent_id": "my-agent"}```@@ -81,6 +83,9 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf|-------|-------------|---------|| `url` | Server address | (required) || `api_key` | API key | `null` (no auth) |+| `account` | Default account header for tenant-scoped requests | `null` |+| `user` | Default user header for tenant-scoped requests | `null` |+| `agent_id` | Agent identifier header | `null` || `timeout` | HTTP request timeout in seconds | `60.0` || `output` | Default output format: `"table"` or `"json"` | `"table"` |diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex bd6fe9d55..47dc551e5 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -766,6 +766,8 @@ Config file for the HTTP client (`SyncHTTPClient` / `AsyncHTTPClient`) and CLI t{"url": "http://localhost:1933","api_key": "your-secret-key",+ "account": "acme",+ "user": "alice","agent_id": "my-agent","output": "table"}@@ -775,9 +777,17 @@ Config file for the HTTP client (`SyncHTTPClient` / `AsyncHTTPClient`) and CLI t|-------|-------------|---------|| `url` | Server address | (required) || `api_key` | API key for authentication (root key or user key) | `null` (no auth) |+| `account` | Default account sent as `X-OpenViking-Account` | `null` |+| `user` | Default user sent as `X-OpenViking-User` | `null` || `agent_id` | Agent identifier for agent space isolation | `null` || `output` | Default output format: `"table"` or `"json"` | `"table"` |+CLI flags can override these identity fields per command:++```bash+openviking --account acme --user alice --agent-id assistant-2 ls viking://+```+See [Deployment](./03-deployment.md) for details.## server Section@@ -789,6 +799,7 @@ When running OpenViking as an HTTP service, add a `server` section to `ov.conf`:"server": {"host": "0.0.0.0","port": 1933,+ "auth_mode": "api_key","root_api_key": "your-secret-root-key","cors_origins": ["*"]}@@ -799,10 +810,13 @@ When running OpenViking as an HTTP service, add a `server` section to `ov.conf`:|-------|------|-------------|---------|| `host` | str | Bind address | `0.0.0.0` || `port` | int | Bind port | `1933` |-| `root_api_key` | str | Root API key for multi-tenant auth, disabled if not set | `null` |+| `auth_mode` | str | Authentication mode: `"api_key"` or `"trusted"` | `"api_key"` |+| `root_api_key` | str | Root API key for multi-tenant auth in `api_key` mode | `null` || `cors_origins` | list | Allowed CORS origins | `["*"]` |-When `root_api_key` is configured, the server enables multi-tenant authentication. Use the Admin API to create accounts and user keys. When not set, the server runs in dev mode with no authentication.+`api_key` mode uses API keys. `trusted` mode trusts `X-OpenViking-Account` / `X-OpenViking-User` headers from a trusted gateway or internal caller.++When `root_api_key` is configured, the server enables multi-tenant authentication. Use the Admin API to create accounts and user keys. Development mode only applies when `auth_mode = "api_key"` and `root_api_key` is not set.For startup and deployment details see [Deployment](./03-deployment.md), for authentication see [Authentication](./04-authentication.md).diff --git a/docs/en/guides/04-authentication.md b/docs/en/guides/04-authentication.mdindex 950c35990..f7f68be20 100644--- a/docs/en/guides/04-authentication.md+++ b/docs/en/guides/04-authentication.md@@ -1,6 +1,6 @@# Authentication-OpenViking Server supports multi-tenant API key authentication with role-based access control.+OpenViking Server supports two authentication modes with role-based access control: `api_key` and `trusted`.## Overview@@ -13,13 +13,21 @@ OpenViking uses a two-layer API key system:All API keys are plain random tokens with no embedded identity. The server resolves identity by first comparing against the root key, then looking up the user key index.+## Authentication Modes++| Mode | `server.auth_mode` | Identity Source | Typical Use |+|------|--------------------|-----------------|-------------|+| API key mode | `"api_key"` | API key, with optional tenant headers for root requests | Standard multi-tenant deployment |+| Trusted mode | `"trusted"` | `X-OpenViking-Account` / `X-OpenViking-User` / optional `X-OpenViking-Agent` headers | Behind a trusted gateway or internal network boundary |+## Setting Up (Server Side)-Configure the root API key in the `server` section of `ov.conf`:+Configure the authentication mode in the `server` section of `ov.conf`:```json{"server": {+ "auth_mode": "api_key","root_api_key": "your-secret-root-key"}}@@ -87,10 +95,20 @@ client = ov.SyncHTTPClient({"url": "http://localhost:1933","api_key": "<user-key>",+ "account": "acme",+ "user": "alice","agent_id": "my-agent"}```+When you use a regular user key, `account` and `user` are optional because the server can derive them from the key. They are recommended when you use `trusted` mode or a root key against tenant-scoped APIs.++**CLI override flags**++```bash+openviking --account acme --user alice --agent-id my-agent ls viking://+```+### Accessing Tenant Data with Root KeyWhen using the root key to access tenant-scoped data APIs (e.g. `ls`, `find`, `sessions`), you must specify the target account and user. The server will reject the request otherwise. Admin API and system status endpoints are not affected.@@ -124,10 +142,53 @@ client = ov.SyncHTTPClient("url": "http://localhost:1933","api_key": "your-secret-root-key","account": "acme",- "user": "alice"+ "user": "alice",+ "agent_id": "my-agent"+}+```++## Trusted Mode++Trusted mode skips user-key lookup and instead trusts explicit identity headers on each request:++```json+{+ "server": {+ "auth_mode": "trusted",+ "host": "127.0.0.1"+ }}```+Rules in trusted mode:++- `X-OpenViking-Account` and `X-OpenViking-User` are required on tenant-scoped requests.+- `X-OpenViking-Agent` is optional and defaults to `default`.+- If `root_api_key` is also configured, every request must still provide a matching API key.+- Only expose this mode behind a trusted network boundary or an identity-injecting gateway.++**curl**++```bash+curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \+ -H "X-OpenViking-Account: acme" \+ -H "X-OpenViking-User: alice" \+ -H "X-OpenViking-Agent: my-agent"+```++**Python SDK**++```python+import openviking as ov++client = ov.SyncHTTPClient(+ url="http://localhost:1933",+ account="acme",+ user="alice",+ agent_id="my-agent",+)+```+## Roles and Permissions| Role | Scope | Capabilities |@@ -138,7 +199,7 @@ client = ov.SyncHTTPClient(## Development Mode-When no `root_api_key` is configured, authentication is disabled. All requests are accepted as ROOT with the default account. **This is only allowed when the server binds to localhost** (`127.0.0.1`, `localhost`, or `::1`). If `host` is set to a non-loopback address (e.g. `0.0.0.0`) without a `root_api_key`, the server will refuse to start.+When `auth_mode = "api_key"` and no `root_api_key` is configured, authentication is disabled. All requests are accepted as ROOT with the default account. **This is only allowed when the server binds to localhost** (`127.0.0.1`, `localhost`, or `::1`). If `host` is set to a non-loopback address (e.g. `0.0.0.0`) without a `root_api_key`, the server will refuse to start.```json{diff --git a/docs/zh/api/01-overview.md b/docs/zh/api/01-overview.mdindex 3b1346098..48675085a 100644--- a/docs/zh/api/01-overview.md+++ b/docs/zh/api/01-overview.md@@ -73,6 +73,8 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf{"url": "http://localhost:1933","api_key": "your-key",+ "account": "acme",+ "user": "alice","agent_id": "my-agent"}```@@ -81,6 +83,8 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf|------|------|--------|| `url` | 服务端地址 | (必填) || `api_key` | API Key | `null`(无认证) |+| `account` | 面向租户请求的默认 account 请求头 | `null` |+| `user` | 面向租户请求的默认 user 请求头 | `null` || `agent_id` | Agent 标识符 | `null` || `timeout` | HTTP 请求超时时间(秒) | `60.0` || `output` | 默认输出格式:`"table"` 或 `"json"` | `"table"` |diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex 675c34234..e357e42f6 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -743,6 +743,8 @@ HTTP 客户端(`SyncHTTPClient` / `AsyncHTTPClient`)和 CLI 工具连接远{"url": "http://localhost:1933","api_key": "your-secret-key",+ "account": "acme",+ "user": "alice","agent_id": "my-agent","output": "table"}@@ -752,9 +754,17 @@ HTTP 客户端(`SyncHTTPClient` / `AsyncHTTPClient`)和 CLI 工具连接远|------|------|--------|| `url` | 服务端地址 | (必填) || `api_key` | API Key 认证(root key 或 user key) | `null`(无认证) |+| `account` | 默认发送为 `X-OpenViking-Account` 的租户标识 | `null` |+| `user` | 默认发送为 `X-OpenViking-User` 的用户标识 | `null` || `agent_id` | Agent 标识,用于 agent space 隔离 | `null` || `output` | 默认输出格式:`"table"` 或 `"json"` | `"table"` |+也可以在单次命令里用 CLI 参数覆盖这些身份字段:++```bash+openviking --account acme --user alice --agent-id assistant-2 ls viking://+```+详见 [服务部署](./03-deployment.md)。## server 段@@ -766,6 +776,7 @@ HTTP 客户端(`SyncHTTPClient` / `AsyncHTTPClient`)和 CLI 工具连接远"server": {"host": "0.0.0.0","port": 1933,+ "auth_mode": "api_key","root_api_key": "your-secret-root-key","cors_origins": ["*"]}@@ -776,10 +787,13 @@ HTTP 客户端(`SyncHTTPClient` / `AsyncHTTPClient`)和 CLI 工具连接远|------|------|------|--------|| `host` | str | 绑定地址 | `0.0.0.0` || `port` | int | 绑定端口 | `1933` |-| `root_api_key` | str | Root API Key,启用多租户认证,不设则为开发模式 | `null` |+| `auth_mode` | str | 认证模式:`"api_key"` 或 `"trusted"` | `"api_key"` |+| `root_api_key` | str | Root API Key。在 `api_key` 模式下启用多租户认证 | `null` || `cors_origins` | list | CORS 允许的来源 | `["*"]` |-配置 `root_api_key` 后,服务端启用多租户认证。通过 Admin API 创建工作区和用户 key。不配置时为开发模式,不需要认证。+`api_key` 模式使用 API Key 认证;`trusted` 模式信任上游网关或受信调用方注入的 `X-OpenViking-Account` / `X-OpenViking-User` 请求头。++配置 `root_api_key` 后,服务端启用多租户认证。通过 Admin API 创建工作区和用户 key。只有在 `auth_mode = "api_key"` 且未配置 `root_api_key` 时,服务端才会进入开发模式。启动方式和部署详情见 [服务部署](./03-deployment.md),认证详情见 [认证](./04-authentication.md)。diff --git a/docs/zh/guides/04-authentication.md b/docs/zh/guides/04-authentication.mdindex cf937104d..d1d5d7159 100644--- a/docs/zh/guides/04-authentication.md+++ b/docs/zh/guides/04-authentication.md@@ -1,6 +1,6 @@# 认证-OpenViking Server 支持多租户 API Key 认证和基于角色的访问控制。+OpenViking Server 支持两种认证模式,并带有基于角色的访问控制:`api_key` 和 `trusted`。## 概述@@ -13,13 +13,21 @@ OpenViking 使用两层 API Key 体系:所有 API Key 均为纯随机 token,不携带身份信息。服务端通过先比对 root key、再查 user key 索引的方式确定身份。+## 认证模式++| 模式 | `server.auth_mode` | 身份来源 | 典型使用场景 |+|------|--------------------|----------|--------------|+| API Key 模式 | `"api_key"` | API Key,root 请求可附带租户请求头 | 标准多租户部署 |+| Trusted 模式 | `"trusted"` | `X-OpenViking-Account` / `X-OpenViking-User` / 可选 `X-OpenViking-Agent` 请求头 | 部署在受信网关或内网边界之后 |+## 服务端配置-在 `ov.conf` 的 `server` 段配置 root API key:+在 `ov.conf` 的 `server` 段配置认证模式:```json{"server": {+ "auth_mode": "api_key","root_api_key": "your-secret-root-key"}}@@ -87,10 +95,20 @@ client = ov.SyncHTTPClient({"url": "http://localhost:1933","api_key": "<user-key>",+ "account": "acme",+ "user": "alice","agent_id": "my-agent"}```+如果使用普通 `user key`,`account` 和 `user` 可以省略,因为服务端可以从 key 反查出来;如果使用 `trusted` 模式,或者用 `root key` 访问租户级 API,则建议明确配置。++**CLI 覆盖参数**++```bash+openviking --account acme --user alice --agent-id my-agent ls viking://+```+### 使用 Root Key 访问租户数据使用 root key 访问租户级数据 API(如 `ls`、`find`、`sessions` 等)时,必须指定目标 account 和 user,否则服务端将拒绝请求。Admin API 和系统状态端点不受此限制。@@ -124,10 +142,53 @@ client = ov.SyncHTTPClient("url": "http://localhost:1933","api_key": "your-secret-root-key","account": "acme",- "user": "alice"+ "user": "alice",+ "agent_id": "my-agent"+}+```++## Trusted 模式++Trusted 模式不会查 user key,而是直接信任每个请求显式携带的身份请求头:++```json+{+ "server": {+ "auth_mode": "trusted",+ "host": "127.0.0.1"+ }}```+Trusted 模式规则:++- 租户级请求必须包含 `X-OpenViking-Account` 和 `X-OpenViking-User`+- `X-OpenViking-Agent` 可选,缺省为 `default`+- 如果同时配置了 `root_api_key`,每个请求仍然必须带匹配的 API Key+- 只应部署在受信网络边界之后,或由身份注入网关统一转发++**curl**++```bash+curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \+ -H "X-OpenViking-Account: acme" \+ -H "X-OpenViking-User: alice" \+ -H "X-OpenViking-Agent: my-agent"+```++**Python SDK**++```python+import openviking as ov++client = ov.SyncHTTPClient(+ url="http://localhost:1933",+ account="acme",+ user="alice",+ agent_id="my-agent",+)+```+## 角色与权限| 角色 | 作用域 | 能力 |@@ -138,7 +199,7 @@ client = ov.SyncHTTPClient(## 开发模式-不配置 `root_api_key` 时,认证禁用,所有请求以 ROOT 身份访问 default account。**此模式仅允许在服务器绑定 localhost 时使用**(`127.0.0.1`、`localhost` 或 `::1`)。如果 `host` 设置为非回环地址(如 `0.0.0.0`)且未配置 `root_api_key`,服务器将拒绝启动。+当 `auth_mode = "api_key"` 且未配置 `root_api_key` 时,认证禁用,所有请求以 ROOT 身份访问 default account。**此模式仅允许在服务器绑定 localhost 时使用**(`127.0.0.1`、`localhost` 或 `::1`)。如果 `host` 设置为非回环地址(如 `0.0.0.0`)且未配置 `root_api_key`,服务器将拒绝启动。```json{diff --git a/examples/ovcli.conf.example b/examples/ovcli.conf.exampleindex c0a6227ba..e9d8c0b37 100644--- a/examples/ovcli.conf.example+++ b/examples/ovcli.conf.example@@ -1,6 +1,8 @@{"url": "http://localhost:1933","api_key": null,+ "account": null,+ "user": null,"agent_id": null,"timeout": 60.0,"output": "table",