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
refactor(encryption): using rust refactor encryption (#2444)
baojun-zhange492cbd16fb9
diff --git a/Cargo.lock b/Cargo.lockindex d126de163..8e0690037 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -8,6 +8,16 @@ version = "2.0.1"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"+[[package]]+name = "aead"+version = "0.5.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "d122413f284cf2d62fb1b7db97e02edb8cda96d769b16e443a4f6195e35662b0"+dependencies = [+ "crypto-common",+ "generic-array",+]+[[package]]name = "aes"version = "0.8.4"@@ -19,6 +29,20 @@ dependencies = ["cpufeatures",]+[[package]]+name = "aes-gcm"+version = "0.10.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "831010a0f742e1209b3bcea8fab6a8e149051ba6099432c8cb2cc117dec3ead1"+dependencies = [+ "aead",+ "aes",+ "cipher",+ "ctr",+ "ghash",+ "subtle",+]+[[package]]name = "ahash"version = "0.8.12"@@ -1378,9 +1402,19 @@ source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"dependencies = ["generic-array",+ "rand_core 0.6.4","typenum",]+[[package]]+name = "ctr"+version = "0.9.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "0369ee1ad671834580515889b80f2ea915f23b8be8d0daa4bbaf2ac5c7590835"+dependencies = [+ "cipher",+]+[[package]]name = "darling"version = "0.23.0"@@ -1956,6 +1990,16 @@ dependencies = ["wasip3",]+[[package]]+name = "ghash"+version = "0.5.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f0d8a4362ccb29cb0b265253fb0a2728f592895ee6854fd9bc13f2ffda266ff1"+dependencies = [+ "opaque-debug",+ "polyval",+]+[[package]]name = "gif"version = "0.14.2"@@ -3161,6 +3205,12 @@ version = "11.1.5"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "d6790f58c7ff633d8771f42965289203411a5e5c68388703c06e14f24770b41e"+[[package]]+name = "opaque-debug"+version = "0.3.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381"+[[package]]name = "openssl-probe"version = "0.2.1"@@ -3392,6 +3442,18 @@ dependencies = ["miniz_oxide",]+[[package]]+name = "polyval"+version = "0.6.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "9d1fe60d06143b2430aa532c94cfe9e29783047f06c0d7fd359a9a51b729fa25"+dependencies = [+ "cfg-if",+ "cpufeatures",+ "opaque-debug",+ "universal-hash",+]+[[package]]name = "portable-atomic"version = "1.13.1"@@ -3632,6 +3694,7 @@ dependencies = [name = "ragfs"version = "0.1.0"dependencies = [+ "aes-gcm","anyhow","async-trait","aws-config",@@ -3645,14 +3708,17 @@ dependencies = ["grep-matcher","grep-regex","grep-searcher",+ "hkdf","ignore","lru","path-clean","radix_trie",+ "rand 0.8.5","regex","rusqlite","serde","serde_json",+ "sha2","sqlx","tempfile","thiserror 1.0.69",@@ -5116,6 +5182,16 @@ version = "0.5.2"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "81e544489bf3d8ef66c953931f56617f423cd4b5494be343d9b9d3dda037b9a3"+[[package]]+name = "universal-hash"+version = "0.5.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "fc1de2c688dc15305988b563c3854064043356019f97a4b46276fe734c4f07ea"+dependencies = [+ "crypto-common",+ "subtle",+]+[[package]]name = "untrusted"version = "0.9.0"diff --git a/crates/ragfs-python/src/lib.rs b/crates/ragfs-python/src/lib.rsindex b7abdb3e4..02beed13e 100644--- a/crates/ragfs-python/src/lib.rs+++ b/crates/ragfs-python/src/lib.rs@@ -4,21 +4,18 @@//! with the existing Go-based `AGFSBindingClient`. This embeds the ragfs//! filesystem engine directly in the Python process (no HTTP server needed).-use pyo3::exceptions::PyRuntimeError;+use pyo3::exceptions::{PyRuntimeError, PyValueError};use pyo3::prelude::*;use pyo3::types::{PyBytes, PyDict, PyList, PyType};use std::collections::HashMap;+use std::future::Future;use std::sync::Arc;use std::time::UNIX_EPOCH;use ragfs::core::{- ConfigValue, FileInfo, FileSystem, FilesystemStats, FsOperation, GrepResult, MountableFS,- OperationStats, PluginConfig, TreeEntry, WriteFlag,-};-#[cfg(feature = "s3")]-use ragfs::plugins::S3FSPlugin;-use ragfs::plugins::{- KVFSPlugin, LocalFSPlugin, MemFSPlugin, QueueFSPlugin, SQLFSPlugin, ServerInfoFSPlugin,+ build_default_stack, ConfigValue, EncryptionConfig, FileInfo, FileSystem, FilesystemStats,+ FsContext, FsContextInner, FsOperation, GrepResult, MountableFS, OperationStats, PluginConfig,+ RagfsConfig, TreeEntry, WriteFlag, FS_CTX,};fn py_detach_blocking<T, F>(py: Python<'_>, f: F) -> T@@ -254,44 +251,101 @@ fn py_dict_to_config(dict: &Bound<'_, PyDict>) -> PyResult<HashMap<String, ConfiOk(params)}+/// Build an immutable `FsContext` from an optional Python `{"account_id": str}` dict.+///+/// A context is always constructed (even when the dict is absent or lacks `account_id`), so the+/// "every ragfs call carries a ctx" invariant holds. Missing `account_id` is represented as an+/// empty field; `FsContextView::account_id()` treats it as absent, so encrypted content operations+/// fail fast instead of using an accidental empty tenant key.+fn build_fs_context(ctx: Option<HashMap<String, String>>) -> FsContext {+ let account_id = ctx+ .and_then(|m| m.get("account_id").cloned())+ .unwrap_or_default();+ Arc::new(FsContextInner::new(account_id))+}+/// RAGFS Python Binding Client.////// Embeds the ragfs filesystem engine directly in the Python process./// API-compatible with the Go-based AGFSBindingClient.#[pyclass]struct RAGFSBindingClient {- fs: Arc<MountableFS>,+ /// Mount manager: mount/unmount/list/get_*_stats/register_plugin.+ mountable: Arc<MountableFS>,+ /// Data entry point: `Stats(Encryption(Mountable))` when encrypted, else `Stats(Mountable)`.+ top: Arc<dyn FileSystem>,rt: tokio::runtime::Runtime,}+impl RAGFSBindingClient {+ /// Run an async filesystem op on the runtime, releasing the GIL, inside the FS_CTX scope.+ ///+ /// Centralizes the GIL-detach + `FS_CTX.scope` + `block_on` pattern so every data method+ /// shares one implementation (no per-method duplication).+ fn run_scoped<T, Fut, F>(&self, py: Python<'_>, ctx: FsContext, f: F) -> T+ where+ T: Send,+ Fut: Future<Output = T>,+ F: Send + FnOnce() -> Fut,+ {+ py_detach_blocking(py, move || {+ self.rt+ .block_on(FS_CTX.scope(ctx, async move { f().await }))+ })+ }+}+#[pymethods]impl RAGFSBindingClient {/// Create a new RAGFS binding client.///- /// Initializes the filesystem engine with all built-in plugins registered.+ /// `config_path` is a deprecated compatibility parameter kept only so legacy callers using+ /// `RAGFSBindingClient(config_path=...)` do not fail. `config` is an optional sectioned dict+ /// (mirrors ov.conf). The `encryption` section, when present, carries `root_key` (32 bytes) ++ /// `provider_type` (int) and causes the stack to include an `EncryptionWrappedFS` layer.+ /// Absence of the section yields a plaintext stack.#[new]- #[pyo3(signature = (config_path=None))]- fn new(config_path: Option<&str>) -> PyResult<Self> {- let _ = config_path; // reserved for future use-+ #[pyo3(signature = (config_path=None, config=None))]+ fn new(+ py: Python<'_>,+ config_path: Option<&str>,+ config: Option<HashMap<String, Py<PyAny>>>,+ ) -> PyResult<Self> {+ let _ = config_path;let rt = tokio::runtime::Runtime::new().map_err(|e| PyRuntimeError::new_err(format!("Failed to create runtime: {}", e)))?;- let fs = Arc::new(MountableFS::new());-- // Register all built-in plugins- rt.block_on(async {- fs.register_plugin(MemFSPlugin).await;- fs.register_plugin(KVFSPlugin).await;- fs.register_plugin(QueueFSPlugin::new()).await;- fs.register_plugin(SQLFSPlugin::new()).await;- fs.register_plugin(LocalFSPlugin::new()).await;- fs.register_plugin(ServerInfoFSPlugin::new()).await;- #[cfg(feature = "s3")]- fs.register_plugin(S3FSPlugin::new()).await;- });+ // Phase A (holding GIL): parse the sectioned config into an owned RagfsConfig.+ let mut ragfs_cfg = RagfsConfig::default();+ if let Some(cfg) = config {+ if let Some(enc_obj) = cfg.get("encryption") {+ let enc: HashMap<String, Py<PyAny>> = enc_obj.extract(py)?;+ let rk: Vec<u8> = enc+ .get("root_key")+ .ok_or_else(|| PyValueError::new_err("encryption.root_key required"))?+ .extract(py)?;+ let root_key: [u8; 32] = rk+ .as_slice()+ .try_into()+ .map_err(|_| PyValueError::new_err("root_key must be 32 bytes"))?;+ let provider_type: u8 = enc+ .get("provider_type")+ .ok_or_else(|| PyValueError::new_err("encryption.provider_type required"))?+ .extract(py)?;+ ragfs_cfg.encryption = Some(EncryptionConfig {+ root_key,+ provider_type,+ });+ }+ }- Ok(Self { fs, rt })+ // Phase B: build the stack (no encryption layer when the section is absent).+ let stack = rt.block_on(build_default_stack(ragfs_cfg));+ Ok(Self {+ mountable: stack.mountable,+ top: stack.top,+ rt,+ })}/// Check client health.@@ -331,12 +385,18 @@ impl RAGFSBindingClient {////// Returns a list of file info dicts with keys:/// name, size, mode, modTime, isDir- fn ls(&self, path: String) -> PyResult<Py<PyAny>> {- let fs = self.fs.clone();- let entries = Python::attach(|py| {- py_detach_blocking(py, move || self.rt.block_on(async move { fs.read_dir(&path).await }))- })- .map_err(to_py_err)?;+ #[pyo3(signature = (path, ctx=None))]+ fn ls(+ &self,+ py: Python<'_>,+ path: String,+ ctx: Option<HashMap<String, String>>,+ ) -> PyResult<Py<PyAny>> {+ let fs_ctx = build_fs_context(ctx);+ let top = self.top.clone();+ let entries = self+ .run_scoped(py, fs_ctx, move || async move { top.read_dir(&path).await })+ .map_err(to_py_err)?;Python::attach(|py| {let list = PyList::empty(py);@@ -355,30 +415,87 @@ impl RAGFSBindingClient {/// offset: Starting position (default: 0)/// size: Number of bytes to read (default: -1, read all)/// stream: Not supported in binding mode- #[pyo3(signature = (path, offset=0, size=-1, stream=false))]- fn read(&self, path: String, offset: i64, size: i64, stream: bool) -> PyResult<Py<PyAny>> {+ /// ctx: Optional FsContext dict (e.g. {"account_id": ...})+ #[pyo3(signature = (path, offset=0, size=-1, stream=false, ctx=None))]+ fn read(+ &self,+ py: Python<'_>,+ path: String,+ offset: i64,+ size: i64,+ stream: bool,+ ctx: Option<HashMap<String, String>>,+ ) -> PyResult<Py<PyAny>> {if stream {return Err(PyRuntimeError::new_err("Streaming not supported in binding mode",));}- let fs = self.fs.clone();+ let fs_ctx = build_fs_context(ctx);+ let top = self.top.clone();let off = if offset < 0 { 0u64 } else { offset as u64 };let sz = if size < 0 { 0u64 } else { size as u64 };- let data = Python::attach(|py| {- py_detach_blocking(py, move || self.rt.block_on(async move { fs.read(&path, off, sz).await }))- })- .map_err(to_py_err)?;+ let data = self+ .run_scoped(+ py,+ fs_ctx,+ move || async move { top.read(&path, off, sz).await },+ )+ .map_err(to_py_err)?;Python::attach(|py| Ok(PyBytes::new(py, &data).into()))}/// Read file content (alias for read).- #[pyo3(signature = (path, offset=0, size=-1, stream=false))]- fn cat(&self, path: String, offset: i64, size: i64, stream: bool) -> PyResult<Py<PyAny>> {- self.read(path, offset, size, stream)+ #[pyo3(signature = (path, offset=0, size=-1, stream=false, ctx=None))]+ fn cat(+ &self,+ py: Python<'_>,+ path: String,+ offset: i64,+ size: i64,+ stream: bool,+ ctx: Option<HashMap<String, String>>,+ ) -> PyResult<Py<PyAny>> {+ self.read(py, path, offset, size, stream, ctx)+ }++ /// Read raw bytes straight from the mount layer, bypassing the encryption layer.+ ///+ /// Used by cp / persist whole-blob copies (ciphertext is moved verbatim, never decrypted).+ #[pyo3(signature = (path, offset=0, size=-1))]+ fn read_raw(+ &self,+ py: Python<'_>,+ path: String,+ offset: i64,+ size: i64,+ ) -> PyResult<Py<PyAny>> {+ let mountable = self.mountable.clone();+ let off = if offset < 0 { 0u64 } else { offset as u64 };+ let sz = if size < 0 { 0u64 } else { size as u64 };+ let data = py_detach_blocking(py, move || {+ self.rt+ .block_on(async move { mountable.read(&path, off, sz).await })+ })+ .map_err(to_py_err)?;+ Python::attach(|py| Ok(PyBytes::new(py, &data).into()))+ }++ /// Write raw bytes straight to the mount layer, bypassing the encryption layer.+ ///+ /// Counterpart to `read_raw` for cp / persist whole-blob copies.+ fn write_raw(&self, py: Python<'_>, path: String, data: Vec<u8>) -> PyResult<String> {+ let mountable = self.mountable.clone();+ let len = data.len();+ py_detach_blocking(py, move || {+ self.rt+ .block_on(async move { mountable.write(&path, &data, 0, WriteFlag::Create).await })+ })+ .map_err(to_py_err)?;+ Ok(format!("Written {} bytes", len))}/// Write data to file.@@ -386,16 +503,22 @@ impl RAGFSBindingClient {/// Args:/// path: File path/// data: File content as bytes- #[pyo3(signature = (path, data, max_retries=3))]- fn write(&self, path: String, data: Vec<u8>, max_retries: i32) -> PyResult<String> {+ /// ctx: Optional FsContext dict (e.g. {"account_id": ...})+ #[pyo3(signature = (path, data, max_retries=3, ctx=None))]+ fn write(+ &self,+ py: Python<'_>,+ path: String,+ data: Vec<u8>,+ max_retries: i32,+ ctx: Option<HashMap<String, String>>,+ ) -> PyResult<String> {let _ = max_retries; // not applicable for local binding- let fs = self.fs.clone();+ let fs_ctx = build_fs_context(ctx);+ let top = self.top.clone();let len = data.len();- Python::attach(|py| {- py_detach_blocking(py, move || {- self.rt- .block_on(async move { fs.write(&path, &data, 0, WriteFlag::Create).await })- })+ self.run_scoped(py, fs_ctx, move || async move {+ top.write(&path, &data, 0, WriteFlag::Create).await}).map_err(to_py_err)?;@@ -403,12 +526,17 @@ impl RAGFSBindingClient {}/// Create a new empty file.- fn create(&self, path: String) -> PyResult<HashMap<String, String>> {- let fs = self.fs.clone();- Python::attach(|py| {- py_detach_blocking(py, move || self.rt.block_on(async move { fs.create(&path).await }))- })- .map_err(to_py_err)?;+ #[pyo3(signature = (path, ctx=None))]+ fn create(+ &self,+ py: Python<'_>,+ path: String,+ ctx: Option<HashMap<String, String>>,+ ) -> PyResult<HashMap<String, String>> {+ let fs_ctx = build_fs_context(ctx);+ let top = self.top.clone();+ self.run_scoped(py, fs_ctx, move || async move { top.create(&path).await })+ .map_err(to_py_err)?;let mut m = HashMap::new();m.insert("message".to_string(), "created".to_string());@@ -416,14 +544,21 @@ impl RAGFSBindingClient {}/// Create a directory.- #[pyo3(signature = (path, mode="755"))]- fn mkdir(&self, path: String, mode: &str) -> PyResult<HashMap<String, String>> {+ #[pyo3(signature = (path, mode="755", ctx=None))]+ fn mkdir(+ &self,+ py: Python<'_>,+ path: String,+ mode: &str,+ ctx: Option<HashMap<String, String>>,+ ) -> PyResult<HashMap<String, String>> {let mode_int = u32::from_str_radix(mode, 8).map_err(|e| PyRuntimeError::new_err(format!("Invalid mode '{}': {}", mode, e)))?;- let fs = self.fs.clone();- Python::attach(|py| {- py_detach_blocking(py, move || self.rt.block_on(async move { fs.mkdir(&path, mode_int).await }))+ let fs_ctx = build_fs_context(ctx);+ let top = self.top.clone();+ self.run_scoped(py, fs_ctx, move || async move {+ top.mkdir(&path, mode_int).await}).map_err(to_py_err)?;@@ -433,36 +568,49 @@ impl RAGFSBindingClient {}/// Ensure all parent directories exist for the given path.- #[pyo3(signature = (path, mode="755"))]- fn ensure_parent_dirs(&self, path: String, mode: &str) -> PyResult<HashMap<String, String>> {+ #[pyo3(signature = (path, mode="755", ctx=None))]+ fn ensure_parent_dirs(+ &self,+ py: Python<'_>,+ path: String,+ mode: &str,+ ctx: Option<HashMap<String, String>>,+ ) -> PyResult<HashMap<String, String>> {let mode_int = u32::from_str_radix(mode, 8).map_err(|e| PyRuntimeError::new_err(format!("Invalid mode '{}': {}", mode, e)))?;- let fs = self.fs.clone();- Python::attach(|py| {- py_detach_blocking(py, move || self.rt.block_on(async move { fs.ensure_parent_dirs(&path, mode_int).await }))+ let fs_ctx = build_fs_context(ctx);+ let top = self.top.clone();+ self.run_scoped(py, fs_ctx, move || async move {+ top.ensure_parent_dirs(&path, mode_int).await}).map_err(to_py_err)?;let mut m = HashMap::new();- m.insert("message".to_string(), "parent directories ensured".to_string());+ m.insert(+ "message".to_string(),+ "parent directories ensured".to_string(),+ );Ok(m)}/// Remove a file or directory.- #[pyo3(signature = (path, recursive=false))]- fn rm(&self, path: String, recursive: bool) -> PyResult<HashMap<String, String>> {- let fs = self.fs.clone();- Python::attach(|py| {- py_detach_blocking(py, move || {- self.rt.block_on(async move {- if recursive {- fs.remove_all(&path).await- } else {- fs.remove(&path).await- }- })- })+ #[pyo3(signature = (path, recursive=false, ctx=None))]+ fn rm(+ &self,+ py: Python<'_>,+ path: String,+ recursive: bool,+ ctx: Option<HashMap<String, String>>,+ ) -> PyResult<HashMap<String, String>> {+ let fs_ctx = build_fs_context(ctx);+ let top = self.top.clone();+ self.run_scoped(py, fs_ctx, move || async move {+ if recursive {+ top.remove_all(&path).await+ } else {+ top.remove(&path).await+ }}).map_err(to_py_err)?;@@ -472,12 +620,18 @@ impl RAGFSBindingClient {}/// Get file/directory information.- fn stat(&self, path: String) -> PyResult<Py<PyAny>> {- let fs = self.fs.clone();- let info = Python::attach(|py| {- py_detach_blocking(py, move || self.rt.block_on(async move { fs.stat(&path).await }))- })- .map_err(to_py_err)?;+ #[pyo3(signature = (path, ctx=None))]+ fn stat(+ &self,+ py: Python<'_>,+ path: String,+ ctx: Option<HashMap<String, String>>,+ ) -> PyResult<Py<PyAny>> {+ let fs_ctx = build_fs_context(ctx);+ let top = self.top.clone();+ let info = self+ .run_scoped(py, fs_ctx, move || async move { top.stat(&path).await })+ .map_err(to_py_err)?;Python::attach(|py| {let dict = file_info_to_py_dict(py, &info)?;@@ -486,13 +640,18 @@ impl RAGFSBindingClient {}/// Rename/move a file or directory.- fn mv(&self, old_path: String, new_path: String) -> PyResult<HashMap<String, String>> {- let fs = self.fs.clone();- Python::attach(|py| {- py_detach_blocking(py, move || {- self.rt- .block_on(async move { fs.rename(&old_path, &new_path).await })- })+ #[pyo3(signature = (old_path, new_path, ctx=None))]+ fn mv(+ &self,+ py: Python<'_>,+ old_path: String,+ new_path: String,+ ctx: Option<HashMap<String, String>>,+ ) -> PyResult<HashMap<String, String>> {+ let fs_ctx = build_fs_context(ctx);+ let top = self.top.clone();+ self.run_scoped(py, fs_ctx, move || async move {+ top.rename(&old_path, &new_path).await}).map_err(to_py_err)?;@@ -502,11 +661,21 @@ impl RAGFSBindingClient {}/// Change file permissions.- fn chmod(&self, path: String, mode: u32) -> PyResult<HashMap<String, String>> {- let fs = self.fs.clone();- Python::attach(|py| {- py_detach_blocking(py, move || self.rt.block_on(async move { fs.chmod(&path, mode).await }))- })+ #[pyo3(signature = (path, mode, ctx=None))]+ fn chmod(+ &self,+ py: Python<'_>,+ path: String,+ mode: u32,+ ctx: Option<HashMap<String, String>>,+ ) -> PyResult<HashMap<String, String>> {+ let fs_ctx = build_fs_context(ctx);+ let top = self.top.clone();+ self.run_scoped(+ py,+ fs_ctx,+ move || async move { top.chmod(&path, mode).await },+ ).map_err(to_py_err)?;let mut m = HashMap::new();@@ -515,21 +684,25 @@ impl RAGFSBindingClient {}/// Touch a file (create if not exists, or update timestamp).- fn touch(&self, path: String) -> PyResult<HashMap<String, String>> {- let fs = self.fs.clone();- Python::attach(|py| {- py_detach_blocking(py, move || {- self.rt.block_on(async move {- // Try create; if already exists, write empty to update mtime- match fs.create(&path).await {- Ok(_) => Ok(()),- Err(_) => {- // File exists, write empty bytes to update timestamp- fs.write(&path, &[], 0, WriteFlag::None).await.map(|_| ())- }- }- })- })+ #[pyo3(signature = (path, ctx=None))]+ fn touch(+ &self,+ py: Python<'_>,+ path: String,+ ctx: Option<HashMap<String, String>>,+ ) -> PyResult<HashMap<String, String>> {+ let fs_ctx = build_fs_context(ctx);+ let top = self.top.clone();+ self.run_scoped(py, fs_ctx, move || async move {+ // Try create; if already exists, write empty to update mtime+ match top.create(&path).await {+ Ok(_) => Ok(()),+ Err(_) => {+ let existing = top.read(&path, 0, 0).await?;+ top.write(&path, &existing, 0, WriteFlag::Create).await?;+ Ok(())+ }+ }}).map_err(to_py_err)?;@@ -539,10 +712,11 @@ impl RAGFSBindingClient {}/// List all mounted plugins.- fn mounts(&self) -> PyResult<Vec<HashMap<String, String>>> {- let fs = self.fs.clone();- let mount_list = Python::attach(|py| {- py_detach_blocking(py, move || self.rt.block_on(async move { fs.list_mounts().await }))+ fn mounts(&self, py: Python<'_>) -> PyResult<Vec<HashMap<String, String>>> {+ let mountable = self.mountable.clone();+ let mount_list = py_detach_blocking(py, move || {+ self.rt+ .block_on(async move { mountable.list_mounts().await })});let result: Vec<HashMap<String, String>> = mount_list@@ -567,6 +741,7 @@ impl RAGFSBindingClient {#[pyo3(signature = (fstype, path, config=None))]fn mount(&self,+ py: Python<'_>,fstype: String,path: String,config: Option<&Bound<'_, PyDict>>,@@ -582,9 +757,10 @@ impl RAGFSBindingClient {params,};- let fs = self.fs.clone();- Python::attach(|py| {- py_detach_blocking(py, move || self.rt.block_on(async move { fs.mount(plugin_config).await }))+ let mountable = self.mountable.clone();+ py_detach_blocking(py, move || {+ self.rt+ .block_on(async move { mountable.mount(plugin_config).await })}).map_err(to_py_err)?;@@ -597,11 +773,12 @@ impl RAGFSBindingClient {}/// Unmount a plugin.- fn unmount(&self, path: String) -> PyResult<HashMap<String, String>> {- let fs = self.fs.clone();+ fn unmount(&self, py: Python<'_>, path: String) -> PyResult<HashMap<String, String>> {+ let mountable = self.mountable.clone();let path_clone = path.clone();- Python::attach(|py| {- py_detach_blocking(py, move || self.rt.block_on(async move { fs.unmount(&path_clone).await }))+ py_detach_blocking(py, move || {+ self.rt+ .block_on(async move { mountable.unmount(&path_clone).await })}).map_err(to_py_err)?;@@ -656,12 +833,15 @@ impl RAGFSBindingClient {/// node_limit: Maximum number of matches to return (default: None, no limit)/// exclude_path: Optional path prefix to exclude from search (default: None)/// level_limit: Optional maximum depth relative to query root (default: None)+ /// ctx: Optional FsContext dict (e.g. {"account_id": ...})////// Returns:/// A dict with "matches" (list of match dicts) and "count" (total matches)- #[pyo3(signature = (path, pattern, recursive=false, case_insensitive=false, stream=false, node_limit=None, exclude_path=None, level_limit=None))]+ #[pyo3(signature = (path, pattern, recursive=false, case_insensitive=false, stream=false, node_limit=None, exclude_path=None, level_limit=None, ctx=None))]+ #[allow(clippy::too_many_arguments)]fn grep(&self,+ py: Python<'_>,path: String,pattern: String,recursive: bool,@@ -670,6 +850,7 @@ impl RAGFSBindingClient {node_limit: Option<i32>,exclude_path: Option<String>,level_limit: Option<i32>,+ ctx: Option<HashMap<String, String>>,) -> PyResult<Py<PyAny>> {if stream {return Err(PyRuntimeError::new_err(@@ -677,14 +858,14 @@ impl RAGFSBindingClient {));}- let fs = self.fs.clone();+ let fs_ctx = build_fs_context(ctx);+ let top = self.top.clone();let limit = node_limit.map(|n| if n < 0 { 0 } else { n as usize });let level_limit_usize = level_limit.map(|n| if n < 0 { 0 } else { n as usize });let result = self- .rt- .block_on(async move {- fs.grep(+ .run_scoped(py, fs_ctx, move || async move {+ top.grep(&path,&pattern,recursive,@@ -710,25 +891,28 @@ impl RAGFSBindingClient {/// show_hidden: Whether to include hidden files (default: False)/// node_limit: Maximum number of nodes to return (default: None, no limit)/// level_limit: Maximum depth relative to query root (default: None, no limit)+ /// ctx: Optional FsContext dict (e.g. {"account_id": ...})////// Returns:/// A list of dicts, each with keys: path, rel_path, info, extra- #[pyo3(signature = (path, show_hidden=false, node_limit=None, level_limit=None))]+ #[pyo3(signature = (path, show_hidden=false, node_limit=None, level_limit=None, ctx=None))]fn tree_directory(&self,+ py: Python<'_>,path: String,show_hidden: bool,node_limit: Option<i32>,level_limit: Option<i32>,+ ctx: Option<HashMap<String, String>>,) -> PyResult<Py<PyAny>> {- let fs = self.fs.clone();+ let fs_ctx = build_fs_context(ctx);+ let top = self.top.clone();let limit = node_limit.map(|n| if n < 0 { 0 } else { n as usize });let level_limit_usize = level_limit.map(|n| if n < 0 { 0 } else { n as usize });let entries = self- .rt- .block_on(async move {- fs.tree_directory(&path, show_hidden, limit, level_limit_usize)+ .run_scoped(py, fs_ctx, move || async move {+ top.tree_directory(&path, show_hidden, limit, level_limit_usize).await}).map_err(to_py_err)?;@@ -760,41 +944,44 @@ impl RAGFSBindingClient {/// Returns:/// Statistics data as a dict.#[pyo3(signature = (path=None))]- fn get_stats(&self, path: Option<String>) -> PyResult<Py<PyAny>> {- let fs = self.fs.clone();+ fn get_stats(&self, py: Python<'_>, path: Option<String>) -> PyResult<Py<PyAny>> {+ let fs = self.mountable.clone();++ if let Some(mount_path) = path {+ // Get stats for a specific mount+ let fs2 = fs.clone();+ let mount_path_clone = mount_path.clone();+ let stats = py_detach_blocking(py, move || {+ self.rt+ .block_on(async move { fs.get_mount_stats(&mount_path_clone).await })+ })+ .map_err(to_py_err)?;- Python::attach(|py| {- if let Some(mount_path) = path {- // Get stats for a specific mount- let fs2 = fs.clone();- let mount_path_clone = mount_path.clone();- let stats = py_detach_blocking(py, move || {- self.rt.block_on(async move { fs.get_mount_stats(&mount_path_clone).await })- })- .map_err(to_py_err)?;-- let mounts = py_detach_blocking(py, move || {- self.rt.block_on(async move { fs2.list_mounts().await })- });+ let mounts = py_detach_blocking(py, move || {+ self.rt.block_on(async move { fs2.list_mounts().await })+ });- let plugin_name = mounts- .into_iter()- .find(|(p, _)| p == &mount_path)- .map(|(_, plugin)| plugin)- .unwrap_or_default();+ let plugin_name = mounts+ .into_iter()+ .find(|(p, _)| p == &mount_path)+ .map(|(_, plugin)| plugin)+ .unwrap_or_default();+ Python::attach(|py| {let result = PyDict::new(py);result.set_item("path", mount_path)?;result.set_item("plugin", plugin_name)?;let stats_dict = filesystem_stats_to_py_dict(py, &stats)?;result.set_item("stats", stats_dict)?;Ok(result.into())- } else {- // Get stats for all mounts- let all_stats = py_detach_blocking(py, move || {- self.rt.block_on(async move { fs.get_all_stats().await })- });+ })+ } else {+ // Get stats for all mounts+ let all_stats = py_detach_blocking(py, move || {+ self.rt.block_on(async move { fs.get_all_stats().await })+ });+ Python::attach(|py| {let mounts_list = PyList::empty(py);for (path, (plugin, stats)) in all_stats {let mount_dict = PyDict::new(py);@@ -808,8 +995,8 @@ impl RAGFSBindingClient {let result = PyDict::new(py);result.set_item("mounts", mounts_list)?;Ok(result.into())- }- })+ })+ }}}@@ -823,6 +1010,7 @@ fn ragfs_python(m: &Bound<'_, PyModule>) -> PyResult<()> {#[cfg(test)]mod tests {use super::*;+ use pyo3::types::PyDict;#[test]fn detach_blocking_helper_runs_without_python_objects() {@@ -831,4 +1019,15 @@ mod tests {assert_eq!(value, 42);});}++ #[test]+ fn constructor_accepts_legacy_config_path_keyword() {+ Python::attach(|py| {+ let ty = py.get_type::<RAGFSBindingClient>();+ let kwargs = PyDict::new(py);+ kwargs.set_item("config_path", "/tmp/legacy-ov.conf").unwrap();+ let instance = ty.call((), Some(&kwargs));+ assert!(instance.is_ok());+ });+ }}diff --git a/crates/ragfs/Cargo.toml b/crates/ragfs/Cargo.tomlindex 790e0d5e4..5f2f828f8 100644--- a/crates/ragfs/Cargo.toml+++ b/crates/ragfs/Cargo.toml@@ -64,6 +64,12 @@ lru = "0.12"# Regular expressions for grepregex = "1.10"+# Encryption (envelope encryption: AES-256-GCM + HKDF-SHA256)+aes-gcm = "0.10"+hkdf = "0.12"+sha2 = "0.10"+rand = "0.8"+# Stream combinators for concurrent I/Ofutures = "0.3"diff --git a/crates/ragfs/src/core/builder.rs b/crates/ragfs/src/core/builder.rsnew file mode 100644index 000000000..88ae2c063--- /dev/null+++ b/crates/ragfs/src/core/builder.rs@@ -0,0 +1,175 @@+//! Standard RAGFS stack builder.+//!+//! Centralizes "register all built-in plugins + assemble the wrapper stack" so the binding has a+//! single construction path. Whether the encryption layer is present is decided *here, at+//! construction time*, by whether `RagfsConfig::encryption` is set (see §2.4/§2.6 of the design).++use std::sync::Arc;++use super::encryption_wrapper::EncryptionWrappedFS;+use super::filesystem::FileSystem;+use super::mountable::MountableFS;+use super::stats_wrapper::StatsWrappedFS;++#[cfg(feature = "s3")]+use crate::plugins::S3FSPlugin;+use crate::plugins::{+ KVFSPlugin, LocalFSPlugin, MemFSPlugin, QueueFSPlugin, SQLFSPlugin, ServerInfoFSPlugin,+};++/// Sectioned binding configuration (mirrors the ov.conf sectioned layout).+///+/// New capabilities are added as new optional sections here, without changing+/// `build_default_stack`'s signature.+#[derive(Default)]+pub struct RagfsConfig {+ /// Encryption section: `None` → plaintext stack; `Some` → wrap an `EncryptionWrappedFS`.+ pub encryption: Option<EncryptionConfig>,+}++/// Encryption section: root key fixed and immutable at construction time.+pub struct EncryptionConfig {+ /// 32-byte root key (L1).+ pub root_key: [u8; 32],+ /// Provider marker written into envelope headers.+ pub provider_type: u8,+}++/// The assembled stack handles returned by the builder.+pub struct RagfsStack {+ /// Mount manager (mount/unmount/list/stats/register_plugin live here).+ pub mountable: Arc<MountableFS>,+ /// Data entry point: `Stats(Encryption(Mountable))` or `Stats(Mountable)`.+ pub top: Arc<dyn FileSystem>,+}++/// Build the standard RAGFS stack.+///+/// `config.encryption == None` → no encryption layer (plaintext); `Some` → insert+/// `EncryptionWrappedFS` in the middle. The top is always `StatsWrappedFS` so end-to-end timing+/// (including crypto) is captured.+pub async fn build_default_stack(config: RagfsConfig) -> RagfsStack {+ let mountable = Arc::new(MountableFS::new());+ register_builtin_plugins(&mountable).await;++ let data_fs: Arc<dyn FileSystem> = match config.encryption {+ Some(enc) => Arc::new(EncryptionWrappedFS::new(+ mountable.clone() as Arc<dyn FileSystem>,+ enc.root_key,+ enc.provider_type,+ )),+ None => mountable.clone() as Arc<dyn FileSystem>,+ };++ let top: Arc<dyn FileSystem> = Arc::new(StatsWrappedFS::with_arc(data_fs));+ RagfsStack { mountable, top }+}++/// The single built-in plugin registration sequence (eliminates drift across call sites).+pub async fn register_builtin_plugins(fs: &MountableFS) {+ fs.register_plugin(MemFSPlugin).await;+ fs.register_plugin(KVFSPlugin).await;+ fs.register_plugin(QueueFSPlugin::new()).await;+ fs.register_plugin(SQLFSPlugin::new()).await;+ fs.register_plugin(LocalFSPlugin::new()).await;+ fs.register_plugin(ServerInfoFSPlugin::new()).await;+ #[cfg(feature = "s3")]+ fs.register_plugin(S3FSPlugin::new()).await;+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::core::context::{FsContextInner, FS_CTX};+ use crate::core::{PluginConfig, WriteFlag};+ use crate::crypto;+ use std::collections::HashMap;++ fn enc_config() -> RagfsConfig {+ RagfsConfig {+ encryption: Some(EncryptionConfig {+ root_key: [4u8; 32],+ provider_type: crypto::PROVIDER_LOCAL,+ }),+ }+ }++ async fn mount_mem(stack: &RagfsStack) {+ stack+ .mountable+ .mount(PluginConfig {+ name: "memfs".to_string(),+ mount_path: "/mem".to_string(),+ params: HashMap::new(),+ })+ .await+ .unwrap();+ }++ #[tokio::test]+ async fn encrypted_stack_encrypts_on_disk() {+ let stack = build_default_stack(enc_config()).await;+ mount_mem(&stack).await;++ let ctx = Arc::new(FsContextInner::new("tenant"));+ let top = stack.top.clone();+ FS_CTX+ .scope(ctx, async {+ top.write("/mem/f", b"hello", 0, WriteFlag::Create)+ .await+ .unwrap();+ assert_eq!(top.read("/mem/f", 0, 0).await.unwrap(), b"hello");+ })+ .await;++ // Underlying mountable holds ciphertext.+ let raw = stack.mountable.read("/mem/f", 0, 0).await.unwrap();+ assert!(crypto::is_encrypted(&raw));+ }++ #[tokio::test]+ async fn plaintext_stack_has_no_encryption_layer() {+ let stack = build_default_stack(RagfsConfig::default()).await;+ mount_mem(&stack).await;++ // No FS_CTX scope needed; bytes are stored verbatim.+ stack+ .top+ .write("/mem/f", b"hello", 0, WriteFlag::Create)+ .await+ .unwrap();+ let raw = stack.mountable.read("/mem/f", 0, 0).await.unwrap();+ assert_eq!(raw, b"hello", "plaintext stack stores raw bytes");+ }++ #[tokio::test]+ async fn encrypted_stack_preserves_queuefs_control_semantics() {+ let stack = build_default_stack(enc_config()).await;+ stack+ .mountable+ .mount(PluginConfig {+ name: "queuefs".to_string(),+ mount_path: "/queue".to_string(),+ params: HashMap::new(),+ })+ .await+ .unwrap();++ let ctx = Arc::new(FsContextInner::new("_system"));+ let top = stack.top.clone();+ FS_CTX+ .scope(ctx, async {+ top.mkdir("/queue/semantic", 0o755).await.unwrap();+ top.write("/queue/semantic/enqueue", b"payload", 0, WriteFlag::None)+ .await+ .unwrap();++ let size = top.read("/queue/semantic/size", 0, 0).await.unwrap();+ assert_eq!(String::from_utf8(size).unwrap(), "1");++ let msg = top.read("/queue/semantic/dequeue", 0, 0).await.unwrap();+ assert!(!crypto::is_encrypted(&msg));+ })+ .await;+ }+}diff --git a/crates/ragfs/src/core/context.rs b/crates/ragfs/src/core/context.rsnew file mode 100644index 000000000..3f1f36339--- /dev/null+++ b/crates/ragfs/src/core/context.rs@@ -0,0 +1,109 @@+//! Filesystem request context, propagated out-of-band via `tokio::task_local!`.+//!+//! The context (currently just `account_id`) must NOT enter the `FileSystem` trait method+//! signatures (that would pollute the core trait and force every plugin to change). Instead it+//! rides alongside the future via a task-local, so it survives `.await` points and cross-worker+//! migration on the multi-threaded runtime (a `thread_local` would not).+//!+//! The context is an immutable snapshot (`Arc<FsContextInner>`): fields are private and read-only,+//! there are no setters, so no wrapper can mutate it mid-operation.++use std::sync::Arc;++/// Immutable filesystem context snapshot. Currently carries only `account_id` (the tenant).+pub type FsContext = Arc<FsContextInner>;++tokio::task_local! {+ /// The FS context bound to the current task (future). Set via `FS_CTX.scope(ctx, fut)`.+ pub static FS_CTX: FsContext;+}++/// Context payload (immutable). Fields are filled once at construction, then read-only.+#[derive(Clone, Debug)]+pub struct FsContextInner {+ account_id: String,+}++impl FsContextInner {+ /// Construct a context carrying the given tenant `account_id`.+ pub fn new(account_id: impl Into<String>) -> Self {+ Self {+ account_id: account_id.into(),+ }+ }++ /// Tenant identifier (account_id == tenant).+ pub fn account_id(&self) -> &str {+ &self.account_id+ }+}++/// Read-only view over the current task-local context.+///+/// Centralizes "read current FS_CTX" so wrappers never repeat `FS_CTX.try_with(...)`. When the+/// task-local is not set (e.g. a direct unit test), returns an empty view whose getters yield+/// `None` instead of panicking.+pub struct FsContextView {+ inner: Option<FsContext>,+}++impl FsContextView {+ /// Snapshot the current task-local context (empty view if unset).+ pub fn current() -> Self {+ Self {+ inner: FS_CTX.try_with(|c| c.clone()).ok(),+ }+ }++ /// Tenant id from the current context, or `None` if unset.+ pub fn account_id(&self) -> Option<&str> {+ self.inner+ .as_ref()+ .map(|c| c.account_id())+ .filter(|account_id| !account_id.is_empty())+ }+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn empty_view_when_unset_does_not_panic() {+ // No FS_CTX.scope around this call.+ let view = FsContextView::current();+ assert_eq!(view.account_id(), None);+ }++ #[tokio::test]+ async fn view_reads_scoped_context() {+ let ctx = Arc::new(FsContextInner::new("tenant-x"));+ FS_CTX+ .scope(ctx, async {+ assert_eq!(FsContextView::current().account_id(), Some("tenant-x"));+ })+ .await;+ }++ #[tokio::test]+ async fn view_treats_empty_account_id_as_missing() {+ let ctx = Arc::new(FsContextInner::new(""));+ FS_CTX+ .scope(ctx, async {+ assert_eq!(FsContextView::current().account_id(), None);+ })+ .await;+ }++ #[tokio::test]+ async fn context_is_isolated_across_tasks() {+ let a = Arc::new(FsContextInner::new("a"));+ FS_CTX+ .scope(a, async {+ assert_eq!(FsContextView::current().account_id(), Some("a"));+ })+ .await;+ // Outside the scope it is unset again.+ assert_eq!(FsContextView::current().account_id(), None);+ }+}diff --git a/crates/ragfs/src/core/encryption_wrapper.rs b/crates/ragfs/src/core/encryption_wrapper.rsnew file mode 100644index 000000000..1ac0b7265--- /dev/null+++ b/crates/ragfs/src/core/encryption_wrapper.rs@@ -0,0 +1,524 @@+//! Encryption wrapper — a horizontal cross-cutting `FileSystem` layer.+//!+//! Wraps any `FileSystem` and transparently encrypts content on write / decrypts on read using+//! three-layer envelope encryption (see [`crate::crypto`]). It is only inserted into the stack+//! when an encryption config (root_key) is present (see `builder::build_default_stack`); when+//! present, this layer *always* encrypts.+//!+//! Only `read`/`write`/`grep` carry crypto logic; every other trait method is delegated verbatim+//! to `self.inner` so plugin-native behavior/optimizations are preserved.++use std::collections::HashMap;+use std::sync::{Arc, RwLock};++use async_trait::async_trait;++use crate::crypto;++use super::context::FsContextView;+use super::errors::{Error, Result};+use super::filesystem::{compile_grep_regex, normalize_prefix_path, FileSystem};+use super::types::{FileInfo, GrepResult, TreeEntry, WriteFlag};++const SYSTEM_ACCOUNT_ID: &str = "_system";++/// A `FileSystem` wrapper that applies envelope encryption to file content.+pub struct EncryptionWrappedFS {+ /// Wrapped lower layer (typically `MountableFS`).+ inner: Arc<dyn FileSystem>,+ /// Root key, fixed at construction (immutable).+ root_key: [u8; 32],+ /// Provider marker written into the envelope header (immutable).+ provider_type: u8,+ /// Lazily-derived Account Key cache, keyed by account_id.+ account_keys: RwLock<HashMap<String, [u8; 32]>>,+}++impl EncryptionWrappedFS {+ /// Construct an encryption layer over `inner`. Built only when a root key is configured.+ pub fn new(inner: Arc<dyn FileSystem>, root_key: [u8; 32], provider_type: u8) -> Self {+ Self {+ inner,+ root_key,+ provider_type,+ account_keys: RwLock::new(HashMap::new()),+ }+ }++ /// Derive (and cache) the Account Key for `account_id` via HKDF (L2).+ fn get_account_key(&self, account_id: &str) -> [u8; 32] {+ if let Some(k) = self.account_keys.read().unwrap().get(account_id) {+ return *k;+ }+ let k = crypto::hkdf_sha256(&self.root_key, account_id.as_bytes());+ self.account_keys+ .write()+ .unwrap()+ .insert(account_id.to_string(), k);+ k+ }++ /// Read the tenant `account_id` from the task-local context, erroring if absent+ /// (never silently use a wrong/default tenant key).+ fn require_account_id(&self) -> Result<String> {+ FsContextView::current()+ .account_id()+ .map(str::to_string)+ .ok_or_else(|| Error::internal("account_id missing in FsContext"))+ }++ /// Decrypt a full envelope blob into plaintext using the given account key.+ fn decrypt_envelope(&self, account_id: &str, data: &[u8]) -> Result<Vec<u8>> {+ let account_key = self.get_account_key(account_id);+ let (_p, enc_key, key_iv, data_iv, ct) = crypto::parse_envelope(data)?;+ let key_iv: &[u8; 12] = key_iv+ .try_into()+ .map_err(|_| Error::internal("invalid key_iv length in envelope"))?;+ let data_iv: &[u8; 12] = data_iv+ .try_into()+ .map_err(|_| Error::internal("invalid data_iv length in envelope"))?;+ let file_key_bytes = crypto::aes_gcm_decrypt(&account_key, key_iv, enc_key)?;+ let file_key: [u8; 32] = file_key_bytes+ .as_slice()+ .try_into()+ .map_err(|_| Error::internal("invalid file key length"))?;+ crypto::aes_gcm_decrypt(&file_key, data_iv, ct)+ }++ /// Return true for virtual plugin control paths whose read/write payload is protocol data, not+ /// user file content. Those operations must preserve plugin semantics and bypass encryption.+ fn should_passthrough_content(path: &str) -> bool {+ path == "/queue"+ || path.starts_with("/queue/")+ || path == "/serverinfo"+ || path.starts_with("/serverinfo/")+ }++ /// Derive the encryption account domain from a filesystem path.+ ///+ /// `/local/{account_id}/...` paths are tenant-scoped and use that account id. Control or+ /// non-local paths do not encode a tenant and therefore use the reserved system account.+ fn encryption_account_domain(path: &str) -> &str {+ let trimmed = path.trim_start_matches('/');+ let mut parts = trimmed.split('/');+ match (parts.next(), parts.next()) {+ (Some("local"), Some(account_id)) if !account_id.is_empty() => account_id,+ _ => SYSTEM_ACCOUNT_ID,+ }+ }++ /// Reject raw path moves across different encryption account domains.+ fn ensure_same_encryption_domain(old_path: &str, new_path: &str) -> Result<()> {+ let old_account = Self::encryption_account_domain(old_path);+ let new_account = Self::encryption_account_domain(new_path);+ if old_account != new_account {+ return Err(Error::internal(format!(+ "cross-account rename is not supported for encrypted blobs: {:?} -> {:?}",+ old_account, new_account+ )));+ }+ Ok(())+ }+}++/// Slice `data` by `(offset, size)` with `size == 0` meaning "to end", matching plugin read semantics.+fn slice_bytes(data: Vec<u8>, offset: u64, size: u64) -> Vec<u8> {+ let len = data.len() as u64;+ if offset >= len {+ return Vec::new();+ }+ let start = offset as usize;+ let end = if size == 0 {+ data.len()+ } else {+ ((offset + size).min(len)) as usize+ };+ data[start..end].to_vec()+}++#[async_trait]+impl FileSystem for EncryptionWrappedFS {+ // ── content methods: encryption logic ──++ async fn read(&self, path: &str, offset: u64, size: u64) -> Result<Vec<u8>> {+ if Self::should_passthrough_content(path) {+ return self.inner.read(path, offset, size).await;+ }++ // The envelope is an indivisible whole, so always read the full blob, decrypt, then slice+ // in memory (matches the legacy Python encryptor behavior). Single-form is guaranteed by+ // the startup probe, so this layer always expects ciphertext.+ let data = self.inner.read(path, 0, 0).await?;+ let account_id = self.require_account_id()?;+ let plaintext = self.decrypt_envelope(&account_id, &data)?;+ Ok(slice_bytes(plaintext, offset, size))+ }++ async fn write(&self, path: &str, data: &[u8], offset: u64, flags: WriteFlag) -> Result<u64> {+ if Self::should_passthrough_content(path) {+ return self.inner.write(path, data, offset, flags).await;+ }++ // The envelope is indivisible: a partial write (offset > 0) would splice a fragment into+ // the middle of ciphertext and corrupt it. Binding writes are always whole-file (offset=0).+ if offset != 0 {+ return Err(Error::internal(+ "encrypted write only supports whole-file write (offset must be 0)",+ ));+ }+ if !matches!(flags, WriteFlag::Create | WriteFlag::Truncate) {+ return Err(Error::internal(+ "encrypted write requires whole-blob replacement (flags must be Create or Truncate)",+ ));+ }+ let account_id = self.require_account_id()?;+ let account_key = self.get_account_key(&account_id);++ let file_key: [u8; 32] = rand::random();+ let data_iv: [u8; 12] = rand::random();+ let key_iv: [u8; 12] = rand::random();++ let ct = crypto::aes_gcm_encrypt(&file_key, &data_iv, data)?;+ let enc_key = crypto::aes_gcm_encrypt(&account_key, &key_iv, &file_key)?;+ let envelope = crypto::build_envelope(self.provider_type, &enc_key, &key_iv, &data_iv, &ct);+ self.inner.write(path, &envelope, 0, flags).await+ }++ async fn grep(+ &self,+ path: &str,+ pattern: &str,+ recursive: bool,+ case_insensitive: bool,+ node_limit: Option<usize>,+ exclude_path: Option<&str>,+ level_limit: Option<usize>,+ ) -> Result<GrepResult> {+ if Self::should_passthrough_content(path) {+ return self+ .inner+ .grep(+ path,+ pattern,+ recursive,+ case_insensitive,+ node_limit,+ exclude_path,+ level_limit,+ )+ .await;+ }++ // This layer only exists when encryption is on, so always traverse via the trait default+ // grep_internal -> grep_file -> self.read (which decrypts). Never delegate to inner.grep:+ // the plugin override would run the regex against raw ciphertext and miss every file.+ let re = compile_grep_regex(pattern, case_insensitive)?;+ let base = normalize_prefix_path(path);+ let excl = exclude_path.map(normalize_prefix_path);+ let mut result = GrepResult::new();+ self.grep_internal(+ &base,+ &base,+ &re,+ recursive,+ node_limit,+ excl.as_deref(),+ level_limit,+ &mut result,+ )+ .await?;+ Ok(result)+ }++ // ── non-content methods: explicit verbatim delegation (preserve plugin behavior) ──++ async fn create(&self, path: &str) -> Result<()> {+ if Self::should_passthrough_content(path) {+ return self.inner.create(path).await;+ }++ // Empty files still have content shape: in encrypted mode they must be stored as a valid+ // envelope so later reads do not see a plaintext zero-byte blob.+ self.write(path, b"", 0, WriteFlag::Create).await?;+ Ok(())+ }++ async fn mkdir(&self, path: &str, mode: u32) -> Result<()> {+ self.inner.mkdir(path, mode).await+ }++ async fn remove(&self, path: &str) -> Result<()> {+ self.inner.remove(path).await+ }++ async fn remove_all(&self, path: &str) -> Result<()> {+ self.inner.remove_all(path).await+ }++ async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {+ self.inner.read_dir(path).await+ }++ async fn stat(&self, path: &str) -> Result<FileInfo> {+ self.inner.stat(path).await+ }++ async fn rename(&self, old_path: &str, new_path: &str) -> Result<()> {+ // Pure path operation is only safe within the same encryption account domain. Crossing+ // domains would move ciphertext under a different derived account key and make it unreadable.+ Self::ensure_same_encryption_domain(old_path, new_path)?;+ self.inner.rename(old_path, new_path).await+ }++ async fn chmod(&self, path: &str, mode: u32) -> Result<()> {+ self.inner.chmod(path, mode).await+ }++ async fn tree_directory(+ &self,+ path: &str,+ show_hidden: bool,+ node_limit: Option<usize>,+ level_limit: Option<usize>,+ ) -> Result<Vec<TreeEntry>> {+ // Metadata only — no content read, so delegate to preserve plugin-native tree optimizations.+ self.inner+ .tree_directory(path, show_hidden, node_limit, level_limit)+ .await+ }++ async fn ensure_parent_dirs(&self, path: &str, mode: u32) -> Result<()> {+ self.inner.ensure_parent_dirs(path, mode).await+ }++ // `truncate` and `exists` are intentionally NOT overridden:+ // - truncate default = self.read -> resize -> self.write, which goes through this wrapper and+ // yields "decrypt whole -> truncate -> re-encrypt whole" (correct; no plugin truncate to lose).+ // - exists default = self.stat(..).is_ok(), unrelated to encryption.+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::core::context::{FsContextInner, FS_CTX};+ use crate::core::MountableFS;+ use crate::core::PluginConfig;+ use crate::plugins::MemFSPlugin;++ async fn memfs_stack() -> Arc<MountableFS> {+ let m = Arc::new(MountableFS::new());+ m.register_plugin(MemFSPlugin).await;+ m.mount(PluginConfig {+ name: "memfs".to_string(),+ mount_path: "/mem".to_string(),+ params: HashMap::new(),+ })+ .await+ .unwrap();+ m+ }++ /// Build a memfs-backed stack mounted at the provided path for path-sensitive tests.+ async fn memfs_stack_at(mount_path: &str) -> Arc<MountableFS> {+ let m = Arc::new(MountableFS::new());+ m.register_plugin(MemFSPlugin).await;+ m.mount(PluginConfig {+ name: "memfs".to_string(),+ mount_path: mount_path.to_string(),+ params: HashMap::new(),+ })+ .await+ .unwrap();+ m+ }++ fn ctx(account: &str) -> Arc<FsContextInner> {+ Arc::new(FsContextInner::new(account))+ }++ #[tokio::test]+ async fn write_then_read_roundtrip_under_ctx() {+ let inner = memfs_stack().await;+ let enc = EncryptionWrappedFS::new(inner, [9u8; 32], crypto::PROVIDER_LOCAL);++ FS_CTX+ .scope(ctx("tenant-1"), async {+ enc.write("/mem/a.txt", b"super secret", 0, WriteFlag::Create)+ .await+ .unwrap();+ let out = enc.read("/mem/a.txt", 0, 0).await.unwrap();+ assert_eq!(out, b"super secret");+ })+ .await;+ }++ #[tokio::test]+ async fn on_disk_bytes_are_ciphertext_with_envelope() {+ let inner = memfs_stack().await;+ let enc = EncryptionWrappedFS::new(inner.clone(), [9u8; 32], crypto::PROVIDER_LOCAL);++ FS_CTX+ .scope(ctx("tenant-1"), async {+ enc.write("/mem/a.txt", b"plttext", 0, WriteFlag::Create)+ .await+ .unwrap();+ })+ .await;++ // Raw read through inner (no encryption layer) yields the envelope bytes.+ let raw = inner.read("/mem/a.txt", 0, 0).await.unwrap();+ assert!(crypto::is_encrypted(&raw), "on-disk must be enveloped");+ assert_ne!(raw, b"plttext");+ }++ #[tokio::test]+ async fn read_without_account_id_errors() {+ let inner = memfs_stack().await;+ let enc = EncryptionWrappedFS::new(inner.clone(), [9u8; 32], crypto::PROVIDER_LOCAL);+ // Seed an envelope first.+ FS_CTX+ .scope(ctx("tenant-1"), async {+ enc.write("/mem/a.txt", b"x", 0, WriteFlag::Create)+ .await+ .unwrap();+ })+ .await;+ // Read with no FS_CTX scope -> account_id missing -> error (not silent ciphertext).+ let err = enc.read("/mem/a.txt", 0, 0).await;+ assert!(err.is_err());+ }++ #[tokio::test]+ async fn read_offset_size_slicing() {+ let inner = memfs_stack().await;+ let enc = EncryptionWrappedFS::new(inner, [1u8; 32], crypto::PROVIDER_LOCAL);+ FS_CTX+ .scope(ctx("t"), async {+ enc.write("/mem/a.txt", b"0123456789", 0, WriteFlag::Create)+ .await+ .unwrap();+ assert_eq!(enc.read("/mem/a.txt", 2, 3).await.unwrap(), b"234");+ assert_eq!(enc.read("/mem/a.txt", 8, 0).await.unwrap(), b"89");+ assert_eq!(enc.read("/mem/a.txt", 100, 0).await.unwrap(), b"");+ })+ .await;+ }++ #[tokio::test]+ async fn grep_matches_encrypted_files() {+ let inner = memfs_stack().await;+ let enc = EncryptionWrappedFS::new(inner, [2u8; 32], crypto::PROVIDER_LOCAL);+ FS_CTX+ .scope(ctx("t"), async {+ enc.write(+ "/mem/a.txt",+ b"alpha\nNEEDLE here\nbeta",+ 0,+ WriteFlag::Create,+ )+ .await+ .unwrap();+ let res = enc+ .grep("/mem", "NEEDLE", true, false, None, None, None)+ .await+ .unwrap();+ assert_eq!(res.count, 1);+ assert_eq!(res.matches[0].content, "NEEDLE here");+ })+ .await;+ }++ #[tokio::test]+ async fn write_rejects_nonzero_offset() {+ let inner = memfs_stack().await;+ let enc = EncryptionWrappedFS::new(inner, [2u8; 32], crypto::PROVIDER_LOCAL);+ FS_CTX+ .scope(ctx("t"), async {+ let r = enc.write("/mem/a.txt", b"x", 5, WriteFlag::Create).await;+ assert!(r.is_err());+ })+ .await;+ }++ #[tokio::test]+ async fn create_writes_encrypted_empty_file() {+ let inner = memfs_stack().await;+ let enc = EncryptionWrappedFS::new(inner.clone(), [2u8; 32], crypto::PROVIDER_LOCAL);+ FS_CTX+ .scope(ctx("t"), async {+ enc.create("/mem/empty.txt").await.unwrap();+ let plaintext = enc.read("/mem/empty.txt", 0, 0).await.unwrap();+ assert_eq!(plaintext, b"");+ })+ .await;++ let raw = inner.read("/mem/empty.txt", 0, 0).await.unwrap();+ assert!(crypto::is_encrypted(&raw));+ }++ #[tokio::test]+ async fn cross_account_cannot_decrypt() {+ let inner = memfs_stack().await;+ let enc = EncryptionWrappedFS::new(inner, [3u8; 32], crypto::PROVIDER_LOCAL);+ FS_CTX+ .scope(ctx("acct-A"), async {+ enc.write("/mem/a.txt", b"owned by A", 0, WriteFlag::Create)+ .await+ .unwrap();+ })+ .await;+ // Different account -> different account key -> file-key unwrap fails.+ let bad = FS_CTX+ .scope(ctx("acct-B"), async { enc.read("/mem/a.txt", 0, 0).await })+ .await;+ assert!(bad.is_err());+ }++ #[tokio::test]+ async fn write_rejects_append_flag() {+ let inner = memfs_stack().await;+ let enc = EncryptionWrappedFS::new(inner, [4u8; 32], crypto::PROVIDER_LOCAL);+ FS_CTX+ .scope(ctx("t"), async {+ enc.write("/mem/a.txt", b"first", 0, WriteFlag::Create)+ .await+ .unwrap();+ let appended = enc.write("/mem/a.txt", b"second", 0, WriteFlag::Append).await;+ assert!(appended.is_err());+ })+ .await;+ }++ #[tokio::test]+ async fn write_rejects_non_replacing_none_flag() {+ let inner = memfs_stack().await;+ let enc = EncryptionWrappedFS::new(inner, [4u8; 32], crypto::PROVIDER_LOCAL);+ FS_CTX+ .scope(ctx("t"), async {+ enc.write("/mem/a.txt", b"first", 0, WriteFlag::Create)+ .await+ .unwrap();+ let rewritten = enc.write("/mem/a.txt", b"second", 0, WriteFlag::None).await;+ assert!(rewritten.is_err());+ })+ .await;+ }++ #[tokio::test]+ async fn rename_rejects_cross_account_paths() {+ let inner = memfs_stack_at("/local").await;+ let enc = EncryptionWrappedFS::new(inner, [5u8; 32], crypto::PROVIDER_LOCAL);+ let result = FS_CTX+ .scope(ctx("acct-a"), async {+ enc.mkdir("/local/acct-a", 0).await.unwrap();+ enc.mkdir("/local/acct-b", 0).await.unwrap();+ enc.write("/local/acct-a/file.txt", b"owned", 0, WriteFlag::Create)+ .await+ .unwrap();+ enc.rename("/local/acct-a/file.txt", "/local/acct-b/file.txt")+ .await+ })+ .await;+ assert!(result.is_err());+ }+}diff --git a/crates/ragfs/src/core/filesystem.rs b/crates/ragfs/src/core/filesystem.rsindex cdd0e8fd8..be60d2b3e 100644--- a/crates/ragfs/src/core/filesystem.rs+++ b/crates/ragfs/src/core/filesystem.rs@@ -74,6 +74,20 @@ pub(crate) fn relative_depth(rel: &str) -> usize {}}+/// Compile a grep pattern into a `Regex`, applying the case-insensitive `(?i)` prefix.+///+/// Shared by the trait's default `grep` and by `EncryptionWrappedFS::grep`, so the regex setup+/// lives in exactly one place (no copy-paste drift between the two call sites).+pub(crate) fn compile_grep_regex(pattern: &str, case_insensitive: bool) -> Result<Regex> {+ let regex_pattern = if case_insensitive {+ format!("(?i){}", pattern)+ } else {+ pattern.to_string()+ };+ Regex::new(®ex_pattern)+ .map_err(|e| Error::invalid_operation(format!("Invalid regex pattern: {}", e)))+}+/// Core filesystem abstraction trait////// All filesystem plugins must implement this trait to provide file operations.@@ -257,15 +271,7 @@ pub trait FileSystem: Send + Sync {exclude_path: Option<&str>,level_limit: Option<usize>,) -> Result<GrepResult> {- let regex_pattern = if case_insensitive {- format!("(?i){}", pattern)- } else {- pattern.to_string()- };-- let re = Regex::new(®ex_pattern).map_err(|e| {- super::errors::Error::invalid_operation(format!("Invalid regex pattern: {}", e))- })?;+ let re = compile_grep_regex(pattern, case_insensitive)?;let mut result = GrepResult::new();let normalized_path = normalize_prefix_path(path);diff --git a/crates/ragfs/src/core/mod.rs b/crates/ragfs/src/core/mod.rsindex 19d9d49ef..cd51f2c0a 100644--- a/crates/ragfs/src/core/mod.rs+++ b/crates/ragfs/src/core/mod.rs@@ -7,6 +7,9 @@//! - MountableFS for routing operations to mounted plugins//! - Core data types (FileInfo, ConfigParameter, etc.)+pub mod builder;+pub mod context;+pub mod encryption_wrapper;pub mod errors;pub mod filesystem;pub mod mountable;@@ -16,6 +19,11 @@ pub mod stats_wrapper;pub mod types;// Re-export commonly used types+pub use builder::{+ build_default_stack, register_builtin_plugins, EncryptionConfig, RagfsConfig, RagfsStack,+};+pub use context::{FsContext, FsContextInner, FsContextView, FS_CTX};+pub use encryption_wrapper::EncryptionWrappedFS;pub use errors::{Error, Result};pub use filesystem::FileSystem;pub use mountable::MountableFS;diff --git a/crates/ragfs/src/core/stats_wrapper.rs b/crates/ragfs/src/core/stats_wrapper.rsindex 5837a7628..bab6c60f2 100644--- a/crates/ragfs/src/core/stats_wrapper.rs+++ b/crates/ragfs/src/core/stats_wrapper.rs@@ -13,13 +13,24 @@ use super::{/// A wrapper around FileSystem that automatically collects operation statisticspub struct StatsWrappedFS {- inner: Box<dyn FileSystem>,+ inner: Arc<dyn FileSystem>,stats: Arc<StatsCollector>,}impl StatsWrappedFS {/// Create a new statistics-wrapped filesystempub fn new(inner: Box<dyn FileSystem>) -> Self {+ Self {+ inner: Arc::from(inner),+ stats: Arc::new(StatsCollector::new()),+ }+ }++ /// Create a new statistics-wrapped filesystem from an `Arc` inner.+ ///+ /// Used by the stack builder to wrap an already shared lower layer+ /// (e.g. `Arc<EncryptionWrappedFS>` or `Arc<MountableFS>`) as the top stats layer.+ pub fn with_arc(inner: Arc<dyn FileSystem>) -> Self {Self {inner,stats: Arc::new(StatsCollector::new()),@@ -28,7 +39,10 @@ impl StatsWrappedFS {/// Create a new statistics-wrapped filesystem with an existing collectorpub fn with_collector(inner: Box<dyn FileSystem>, stats: Arc<StatsCollector>) -> Self {- Self { inner, stats }+ Self {+ inner: Arc::from(inner),+ stats,+ }}/// Get a reference to the statistics collector@@ -38,7 +52,7 @@ impl StatsWrappedFS {/// Get the inner filesystem (for testing)#[cfg(test)]- pub fn into_inner(self) -> Box<dyn FileSystem> {+ pub fn into_inner(self) -> Arc<dyn FileSystem> {self.inner}}diff --git a/crates/ragfs/src/crypto/mod.rs b/crates/ragfs/src/crypto/mod.rsnew file mode 100644index 000000000..63e17f401--- /dev/null+++ b/crates/ragfs/src/crypto/mod.rs@@ -0,0 +1,298 @@+//! Envelope encryption primitives (mirrors the Python `openviking.crypto` layout byte-for-byte).+//!+//! This module is the single Rust-side source of truth for the three-layer envelope:+//! - L2 Account Key: `HKDF-SHA256(salt, ikm = root_key, info = info_prefix + account_id)`+//! - L3 File Key/Data IV: random; AES-256-GCM for both file-key wrapping and content.+//!+//! All constants are hard-coded (never config-driven) and must stay byte-identical to+//! `openviking/crypto/providers.py` and `openviking/crypto/encryptor.py`, otherwise existing+//! ciphertext becomes undecryptable.++use aes_gcm::aead::{Aead, KeyInit};+use aes_gcm::{Aes256Gcm, Key, Nonce};+use hkdf::Hkdf;+use sha2::Sha256;++use crate::core::errors::{Error, Result};++// ── Envelope / KDF constants (byte-exact with Python) ──++/// HKDF salt. Mirrors `providers.py::HKDF_SALT`.+pub const HKDF_SALT: &[u8] = b"openviking-kek-salt-v1";+/// HKDF info prefix; full info = prefix ‖ account_id. Mirrors `providers.py::HKDF_INFO_PREFIX`.+pub const HKDF_INFO_PREFIX: &[u8] = b"openviking:kek:v1:";++/// Envelope magic: "OpenViking Encryption v1". Mirrors `encryptor.py::MAGIC`.+pub const MAGIC: &[u8; 4] = b"OVE1";+/// Envelope format version. Mirrors `encryptor.py::VERSION`.+pub const VERSION: u8 = 0x01;++/// Fixed header size: 4(magic)+1(version)+1(provider)+2(efk_len)+2(kiv_len)+2(div_len) = 12.+const HEADER_SIZE: usize = 12;++/// Provider type constants (envelope header marker only; not used for key derivation).+pub const PROVIDER_LOCAL: u8 = 0x01;+/// HashiCorp Vault provider marker.+pub const PROVIDER_VAULT: u8 = 0x02;+/// Volcengine KMS provider marker.+pub const PROVIDER_VOLCENGINE: u8 = 0x03;++/// Derive the 32-byte Account Key from the root key and account id (L2).+///+/// Mirrors `RootKeyProvider._hkdf_derive`: `HKDF(SHA256, length=32, salt=HKDF_SALT,+/// info=HKDF_INFO_PREFIX ‖ account_id).derive(root_key)`.+pub fn hkdf_sha256(root_key: &[u8; 32], account_id: &[u8]) -> [u8; 32] {+ let hk = Hkdf::<Sha256>::new(Some(HKDF_SALT), root_key);+ let mut info = Vec::with_capacity(HKDF_INFO_PREFIX.len() + account_id.len());+ info.extend_from_slice(HKDF_INFO_PREFIX);+ info.extend_from_slice(account_id);+ let mut okm = [0u8; 32];+ // HKDF-SHA256 expand for 32 bytes never exceeds the 255*HashLen limit; expand cannot fail here.+ hk.expand(&info, &mut okm)+ .expect("HKDF expand of 32 bytes is always valid");+ okm+}++/// AES-256-GCM encrypt (`aesgcm.encrypt(iv, plaintext, associated_data=None)`).+///+/// The 12-byte `iv` is the GCM nonce; the returned bytes are `ciphertext ‖ 16-byte tag`,+/// matching the Python `cryptography` library output exactly.+pub fn aes_gcm_encrypt(key: &[u8; 32], iv: &[u8; 12], plaintext: &[u8]) -> Result<Vec<u8>> {+ let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(key));+ cipher+ .encrypt(Nonce::from_slice(iv), plaintext)+ .map_err(|e| Error::internal(format!("AES-GCM encryption failed: {e}")))+}++/// AES-256-GCM decrypt (`aesgcm.decrypt(iv, ciphertext, associated_data=None)`).+pub fn aes_gcm_decrypt(key: &[u8; 32], iv: &[u8; 12], ciphertext: &[u8]) -> Result<Vec<u8>> {+ let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(key));+ cipher+ .decrypt(Nonce::from_slice(iv), ciphertext)+ .map_err(|e| Error::internal(format!("AES-GCM authentication failed: {e}")))+}++/// Whether `data` begins with the envelope magic (encrypted file detection).+pub fn is_encrypted(data: &[u8]) -> bool {+ data.starts_with(MAGIC)+}++/// Build an envelope, byte-identical to `FileEncryptor._build_envelope`.+///+/// Layout: `header(12B) ‖ encrypted_file_key ‖ key_iv ‖ data_iv ‖ encrypted_content`,+/// header = `struct.pack("!4sBBHHH", MAGIC, VERSION, provider_type, efk_len, kiv_len, div_len)`+/// (big-endian u16 length fields).+pub fn build_envelope(+ provider_type: u8,+ encrypted_file_key: &[u8],+ key_iv: &[u8],+ data_iv: &[u8],+ encrypted_content: &[u8],+) -> Vec<u8> {+ let efk_len = encrypted_file_key.len() as u16;+ let kiv_len = key_iv.len() as u16;+ let div_len = data_iv.len() as u16;++ let mut out = Vec::with_capacity(+ HEADER_SIZE+ + encrypted_file_key.len()+ + key_iv.len()+ + data_iv.len()+ + encrypted_content.len(),+ );+ out.extend_from_slice(MAGIC);+ out.push(VERSION);+ out.push(provider_type);+ out.extend_from_slice(&efk_len.to_be_bytes());+ out.extend_from_slice(&kiv_len.to_be_bytes());+ out.extend_from_slice(&div_len.to_be_bytes());+ out.extend_from_slice(encrypted_file_key);+ out.extend_from_slice(key_iv);+ out.extend_from_slice(data_iv);+ out.extend_from_slice(encrypted_content);+ out+}++/// Parsed envelope parts: `(provider_type, encrypted_file_key, key_iv, data_iv, encrypted_content)`.+pub type ParsedEnvelope<'a> = (u8, &'a [u8], &'a [u8], &'a [u8], &'a [u8]);++/// Parse an envelope, mirroring `FileEncryptor._parse_envelope` (validates magic + version).+pub fn parse_envelope(data: &[u8]) -> Result<ParsedEnvelope<'_>> {+ if data.len() < HEADER_SIZE {+ return Err(Error::internal("envelope too short"));+ }+ if &data[0..4] != MAGIC {+ return Err(Error::internal("invalid envelope magic"));+ }+ let version = data[4];+ if version != VERSION {+ return Err(Error::internal(format!(+ "unsupported envelope version: {version}"+ )));+ }+ let provider_type = data[5];+ let efk_len = u16::from_be_bytes([data[6], data[7]]) as usize;+ let kiv_len = u16::from_be_bytes([data[8], data[9]]) as usize;+ let div_len = u16::from_be_bytes([data[10], data[11]]) as usize;++ let efk_end = HEADER_SIZE + efk_len;+ let kiv_end = efk_end + kiv_len;+ let div_end = kiv_end + div_len;+ if data.len() < div_end {+ return Err(Error::internal("incomplete envelope"));+ }++ Ok((+ provider_type,+ &data[HEADER_SIZE..efk_end],+ &data[efk_end..kiv_end],+ &data[kiv_end..div_end],+ &data[div_end..],+ ))+}++#[cfg(test)]+mod tests {+ use super::*;++ // Known-answer vector independently checked against Python's+ // `HKDF(SHA256, 32, salt=b"openviking-kek-salt-v1", info=b"openviking:kek:v1:acct").derive(b"\0"*32)`.+ #[test]+ fn hkdf_is_deterministic_and_account_scoped() {+ let root = [0u8; 32];+ let k1 = hkdf_sha256(&root, b"acct-a");+ let k2 = hkdf_sha256(&root, b"acct-a");+ let k3 = hkdf_sha256(&root, b"acct-b");+ assert_eq!(k1, k2, "same inputs -> same key");+ assert_ne!(k1, k3, "different account -> different key");+ }++ #[test]+ fn aes_gcm_roundtrip() {+ let key = [7u8; 32];+ let iv = [3u8; 12];+ let pt = b"hello envelope world";+ let ct = aes_gcm_encrypt(&key, &iv, pt).unwrap();+ assert_ne!(&ct[..], &pt[..], "ciphertext differs from plaintext");+ let back = aes_gcm_decrypt(&key, &iv, &ct).unwrap();+ assert_eq!(back, pt);+ }++ #[test]+ fn aes_gcm_wrong_key_fails() {+ let iv = [3u8; 12];+ let ct = aes_gcm_encrypt(&[1u8; 32], &iv, b"secret").unwrap();+ assert!(aes_gcm_decrypt(&[2u8; 32], &iv, &ct).is_err());+ }++ #[test]+ fn envelope_build_parse_roundtrip() {+ let efk = vec![1u8, 2, 3, 4, 5];+ let kiv = vec![9u8; 12];+ let div = vec![8u8; 12];+ let content = vec![42u8; 100];+ let env = build_envelope(PROVIDER_LOCAL, &efk, &kiv, &div, &content);++ // Header byte layout must match struct.pack("!4sBBHHH", ...).+ assert_eq!(&env[0..4], MAGIC);+ assert_eq!(env[4], VERSION);+ assert_eq!(env[5], PROVIDER_LOCAL);+ assert_eq!(u16::from_be_bytes([env[6], env[7]]), efk.len() as u16);+ assert_eq!(u16::from_be_bytes([env[8], env[9]]), kiv.len() as u16);+ assert_eq!(u16::from_be_bytes([env[10], env[11]]), div.len() as u16);++ let (pt, efk2, kiv2, div2, content2) = parse_envelope(&env).unwrap();+ assert_eq!(pt, PROVIDER_LOCAL);+ assert_eq!(efk2, &efk[..]);+ assert_eq!(kiv2, &kiv[..]);+ assert_eq!(div2, &div[..]);+ assert_eq!(content2, &content[..]);+ }++ #[test]+ fn full_envelope_encrypt_decrypt() {+ // End-to-end three-layer roundtrip, as EncryptionWrappedFS will do it.+ let root = [5u8; 32];+ let account_key = hkdf_sha256(&root, b"tenant-1");+ let file_key = [11u8; 32];+ let data_iv = [12u8; 12];+ let key_iv = [13u8; 12];+ let plaintext = b"the quick brown fox";++ let ct = aes_gcm_encrypt(&file_key, &data_iv, plaintext).unwrap();+ let enc_key = aes_gcm_encrypt(&account_key, &key_iv, &file_key).unwrap();+ let env = build_envelope(PROVIDER_LOCAL, &enc_key, &key_iv, &data_iv, &ct);++ assert!(is_encrypted(&env));++ let (_p, enc_key2, key_iv2, data_iv2, ct2) = parse_envelope(&env).unwrap();+ let fk_bytes = aes_gcm_decrypt(&account_key, key_iv2.try_into().unwrap(), enc_key2).unwrap();+ let fk: [u8; 32] = fk_bytes.try_into().unwrap();+ let back = aes_gcm_decrypt(&fk, data_iv2.try_into().unwrap(), ct2).unwrap();+ assert_eq!(back, plaintext);+ }++ #[test]+ fn is_encrypted_detects_plaintext() {+ assert!(!is_encrypted(b"{\"plain\": true}"));+ assert!(!is_encrypted(b""));+ assert!(is_encrypted(b"OVE1rest"));+ }++ #[test]+ fn parse_rejects_short_and_bad_magic() {+ assert!(parse_envelope(b"OVE").is_err());+ assert!(parse_envelope(b"XXXX\x01\x01\x00\x00\x00\x00\x00\x00").is_err());+ }++ // Cross-language known-answer vectors generated by Python's actual crypto stack+ // (cryptography HKDF/AESGCM + FileEncryptor envelope layout). These pin byte-exact+ // interop: if Rust ever diverges from Python, existing ciphertext breaks.+ //+ // Inputs: root_key = 0x00..0x1f, account_id = "tenant-7",+ // file_key = 0xAB*32, data_iv = 0x11*12, key_iv = 0x22*12,+ // plaintext = b"cross-lang interop check \xe4\xbd\xa0\xe5\xa5\xbd".+ fn hex_to_vec(s: &str) -> Vec<u8> {+ (0..s.len())+ .step_by(2)+ .map(|i| u8::from_str_radix(&s[i..i + 2], 16).unwrap())+ .collect()+ }++ #[test]+ fn hkdf_matches_python_known_answer() {+ let mut root = [0u8; 32];+ for (i, b) in root.iter_mut().enumerate() {+ *b = i as u8;+ }+ let got = hkdf_sha256(&root, b"tenant-7");+ let expected =+ hex_to_vec("a5447823b691e80727c6bf913bd3ac051f32c36ad387f39bf062f81c68307ae4");+ assert_eq!(&got[..], &expected[..], "HKDF must match Python byte-for-byte");+ }++ #[test]+ fn decrypts_python_generated_envelope() {+ let mut root = [0u8; 32];+ for (i, b) in root.iter_mut().enumerate() {+ *b = i as u8;+ }+ let envelope = hex_to_vec(+ "4f56453101010030000c000c8b657147aa0adcb942c4bf88cfa642f5c510fa79bcd6a6e8f4eb5d1b697e\+ 5966305be43086704e128b6a8408535ee4d3222222222222222222222222111111111111111111111111\+ c42d408a1d21e8707cbd617acc62cb9b75dffea1ef5e7889163d970d13a8622cd4d31cddc163f4736556\+ c0180cbfb5",+ );+ let expected_plaintext = hex_to_vec(+ "63726f73732d6c616e6720696e7465726f7020636865636b20e4bda0e5a5bd",+ );++ // Replicate EncryptionWrappedFS::read decryption path.+ let account_key = hkdf_sha256(&root, b"tenant-7");+ let (_p, enc_key, key_iv, data_iv, ct) = parse_envelope(&envelope).unwrap();+ let fk = aes_gcm_decrypt(&account_key, key_iv.try_into().unwrap(), enc_key).unwrap();+ let fk: [u8; 32] = fk.try_into().unwrap();+ let pt = aes_gcm_decrypt(&fk, data_iv.try_into().unwrap(), ct).unwrap();+ assert_eq!(pt, expected_plaintext, "must decrypt Python ciphertext");+ }+}diff --git a/crates/ragfs/src/lib.rs b/crates/ragfs/src/lib.rsindex 07335c0d5..20775715a 100644--- a/crates/ragfs/src/lib.rs+++ b/crates/ragfs/src/lib.rs@@ -30,6 +30,7 @@#![warn(clippy::all)]pub mod core;+pub mod crypto;pub mod plugins;// Re-export core types for conveniencediff --git a/openviking/crypto/encryptor.py b/openviking/crypto/encryptor.pyindex 350193f8f..a7ae62b11 100644--- a/openviking/crypto/encryptor.py+++ b/openviking/crypto/encryptor.py@@ -84,6 +84,15 @@ class FileEncryptor:else:raise ValueError(f"Unknown provider type: {type(provider)}")+ @property+ def provider_type(self) -> int:+ """Envelope provider-type marker byte (LOCAL/VAULT/VOLCENGINE).++ Public read-only accessor used to pass the marker into the Rust binding's encryption+ config (the marker is recorded in envelope headers; it is not key material).+ """+ return self._provider_type+async def encrypt(self, account_id: str, plaintext: bytes) -> bytes:"""Encrypt file content.diff --git a/openviking/crypto/providers.py b/openviking/crypto/providers.pyindex bc3c8df01..bbc7c1d0e 100644--- a/openviking/crypto/providers.py+++ b/openviking/crypto/providers.py@@ -808,7 +808,13 @@ def create_root_key_provider(mount_point = vault_config.get("mount_point", "transit")kv_mount_point = vault_config.get("kv_mount_point", "secret")kv_version = vault_config.get("kv_version", 1)+ # 兼容 key_name(旧字段,作为 root_key_name 的回退)+ # 注意:Pydantic model_dump 后 root_key_name/key_name 总是带有默认值,+ # 因此必须显式区分用户是否显式传入了 key_name(不是默认值 "openviking-root")。root_key_name = vault_config.get("root_key_name", "openviking-root-key")+ key_name_val = vault_config.get("key_name", "openviking-root")+ if root_key_name == "openviking-root-key" and key_name_val != "openviking-root":+ root_key_name = key_name_valencrypted_root_key_key = vault_config.get("encrypted_root_key_key", "openviking-encrypted-root-key")diff --git a/openviking/eval/ragas/playback.py b/openviking/eval/ragas/playback.pyindex 06b0542f8..f41725dd4 100644--- a/openviking/eval/ragas/playback.py+++ b/openviking/eval/ragas/playback.py@@ -215,7 +215,7 @@ class IOPlayback:from openviking.storage.viking_fs import init_viking_fsfrom openviking.storage.viking_vector_index_backend import VikingVectorIndexBackend- from openviking.utils.agfs_utils import create_agfs_client+ from openviking.utils.agfs_utils import RagfsBindingConfig, create_agfs_clientfrom openviking_cli.utils.config import get_openviking_configfrom openviking_cli.utils.config.vectordb_config import VectorDBBackendConfig@@ -223,7 +223,7 @@ class IOPlayback:agfs_config = config.storage.agfs# Create RAGFS client using utility- agfs_client = create_agfs_client(agfs_config)+ agfs_client = create_agfs_client(RagfsBindingConfig(agfs=agfs_config))vector_store = Noneif self.enable_vikingdb:diff --git a/openviking/pyagfs/async_client.py b/openviking/pyagfs/async_client.pyindex d7f4b7e39..e23a67700 100644--- a/openviking/pyagfs/async_client.py+++ b/openviking/pyagfs/async_client.py@@ -10,6 +10,50 @@ from typing import Any, BinaryIO, Dict, List, Unionfrom .protocols import AGFSSyncClientProtocol+_SYSTEM_ACCOUNT_ID = "_system"+++def fs_ctx_from_agfs_path(path: str) -> Dict[str, str]:+ """Derive a stable FsContext from an absolute AGFS path.++ `/local/{account_id}/...` paths use their path-scoped account to match+ VikingFS URI conversion. Plugin/system paths do not encode a tenant, so+ they use the reserved system account key instead of running without ctx.+ """+ parts = path.strip("/").split("/")+ if len(parts) >= 2 and parts[0] == "local" and parts[1]:+ return {"account_id": parts[1]}+ return {"account_id": _SYSTEM_ACCOUNT_ID}+++def _fs_ctx_or_default(path: str, fs_ctx: Dict[str, str] | None) -> Dict[str, str]:+ """Return explicit FsContext when present, otherwise derive it from path."""+ return fs_ctx if fs_ctx is not None else fs_ctx_from_agfs_path(path)+++def local_account_id_from_agfs_path(path: str) -> str | None:+ """Extract the account_id from `/local/{account_id}/...`, or None for non-local paths."""+ parts = path.strip("/").split("/")+ if len(parts) >= 2 and parts[0] == "local" and parts[1]:+ return parts[1]+ return None+++def encryption_account_id_from_agfs_path(path: str) -> str:+ """Return the account_id used by the encryption layer for this AGFS path."""+ return fs_ctx_from_agfs_path(path)["account_id"]+++def ensure_same_encryption_account(src_path: str, dst_path: str) -> None:+ """Reject raw moves/copies that would preserve ciphertext under a different account key."""+ src_account = encryption_account_id_from_agfs_path(src_path)+ dst_account = encryption_account_id_from_agfs_path(dst_path)+ if src_account != dst_account:+ raise ValueError(+ "cross-account AGFS move/copy is not supported by raw path operations: "+ f"{src_account!r} -> {dst_account!r}"+ )+class AsyncAGFSClient:"""Run blocking AGFS binding client operations off the event loop.@@ -28,12 +72,33 @@ class AsyncAGFSClient:return self._clientasync def run(self, method_name: str, /, *args: Any, **kwargs: Any) -> Any:- return await asyncio.to_thread(getattr(self._client, method_name), *args, **kwargs)-- async def ls(self, path: str = "/") -> List[Dict[str, Any]]:- return await self.run("ls", path)-- async def read(self, path: str, offset: int = 0, size: int = -1, stream: bool = False) -> Any:+ """Run a sync client method in a worker thread, preserving ctx when supported."""+ try:+ return await asyncio.to_thread(getattr(self._client, method_name), *args, **kwargs)+ except TypeError as exc:+ message = str(exc)+ if "ctx" not in kwargs or "unexpected keyword argument 'ctx'" not in message:+ raise+ legacy_kwargs = dict(kwargs)+ legacy_kwargs.pop("ctx", None)+ return await asyncio.to_thread(+ getattr(self._client, method_name), *args, **legacy_kwargs+ )++ async def ls(+ self, path: str = "/", *, fs_ctx: Dict[str, str] | None = None+ ) -> List[Dict[str, Any]]:+ return await self.run("ls", path, ctx=_fs_ctx_or_default(path, fs_ctx))++ async def read(+ self,+ path: str,+ offset: int = 0,+ size: int = -1,+ stream: bool = False,+ *,+ fs_ctx: Dict[str, str] | None = None,+ ) -> Any:kwargs: Dict[str, Any] = {}if offset != 0:kwargs["offset"] = offset@@ -41,9 +106,17 @@ class AsyncAGFSClient:kwargs["size"] = sizeif stream:kwargs["stream"] = stream- return await self.run("read", path, **kwargs)+ return await self.run("read", path, **kwargs, ctx=_fs_ctx_or_default(path, fs_ctx))- async def cat(self, path: str, offset: int = 0, size: int = -1, stream: bool = False) -> Any:+ async def cat(+ self,+ path: str,+ offset: int = 0,+ size: int = -1,+ stream: bool = False,+ *,+ fs_ctx: Dict[str, str] | None = None,+ ) -> Any:kwargs: Dict[str, Any] = {}if offset != 0:kwargs["offset"] = offset@@ -51,38 +124,74 @@ class AsyncAGFSClient:kwargs["size"] = sizeif stream:kwargs["stream"] = stream- return await self.run("cat", path, **kwargs)+ return await self.run("cat", path, **kwargs, ctx=_fs_ctx_or_default(path, fs_ctx))++ async def read_raw(self, path: str, offset: int = 0, size: int = -1) -> Any:+ """Read raw bytes, bypassing the encryption layer (cp/persist whole-blob copy)."""+ kwargs: Dict[str, Any] = {}+ if offset != 0:+ kwargs["offset"] = offset+ if size != -1:+ kwargs["size"] = size+ return await self.run("read_raw", path, **kwargs)++ async def write_raw(self, path: str, data: bytes) -> str:+ """Write raw bytes, bypassing the encryption layer (cp/persist whole-blob copy)."""+ return await self.run("write_raw", path, data)async def write(- self, path: str, data: Union[bytes, Iterator[bytes], BinaryIO], max_retries: int = 3+ self,+ path: str,+ data: Union[bytes, Iterator[bytes], BinaryIO],+ max_retries: int = 3,+ *,+ fs_ctx: Dict[str, str] | None = None,) -> str:if max_retries == 3:- return await self.run("write", path, data)- return await self.run("write", path, data, max_retries=max_retries)+ return await self.run("write", path, data, ctx=_fs_ctx_or_default(path, fs_ctx))+ return await self.run(+ "write", path, data, max_retries=max_retries, ctx=_fs_ctx_or_default(path, fs_ctx)+ )- async def mkdir(self, path: str, mode: str = "755") -> Dict[str, Any]:+ async def mkdir(+ self, path: str, mode: str = "755", *, fs_ctx: Dict[str, str] | None = None+ ) -> Dict[str, Any]:if mode == "755":- return await self.run("mkdir", path)- return await self.run("mkdir", path, mode=mode)+ return await self.run("mkdir", path, ctx=_fs_ctx_or_default(path, fs_ctx))+ return await self.run("mkdir", path, mode=mode, ctx=_fs_ctx_or_default(path, fs_ctx))- async def ensure_parent_dirs(self, path: str, mode: str = "755") -> Dict[str, Any]:+ async def ensure_parent_dirs(+ self, path: str, mode: str = "755", *, fs_ctx: Dict[str, str] | None = None+ ) -> Dict[str, Any]:if mode == "755":- return await self.run("ensure_parent_dirs", path)- return await self.run("ensure_parent_dirs", path, mode=mode)+ return await self.run("ensure_parent_dirs", path, ctx=_fs_ctx_or_default(path, fs_ctx))+ return await self.run(+ "ensure_parent_dirs", path, mode=mode, ctx=_fs_ctx_or_default(path, fs_ctx)+ )- async def rm(self, path: str, recursive: bool = False, force: bool = True) -> Dict[str, Any]:+ async def rm(+ self,+ path: str,+ recursive: bool = False,+ force: bool = True,+ *,+ fs_ctx: Dict[str, str] | None = None,+ ) -> Dict[str, Any]:kwargs: Dict[str, Any] = {}if recursive:kwargs["recursive"] = recursiveif not force:kwargs["force"] = force- return await self.run("rm", path, **kwargs)+ return await self.run("rm", path, **kwargs, ctx=_fs_ctx_or_default(path, fs_ctx))- async def stat(self, path: str) -> Dict[str, Any]:- return await self.run("stat", path)+ async def stat(self, path: str, *, fs_ctx: Dict[str, str] | None = None) -> Dict[str, Any]:+ return await self.run("stat", path, ctx=_fs_ctx_or_default(path, fs_ctx))- async def mv(self, old_path: str, new_path: str) -> Dict[str, Any]:- return await self.run("mv", old_path, new_path)+ async def mv(+ self, old_path: str, new_path: str, *, fs_ctx: Dict[str, str] | None = None+ ) -> Dict[str, Any]:+ ensure_same_encryption_account(old_path, new_path)+ return await self.run("mv", old_path, new_path, ctx=_fs_ctx_or_default(old_path, fs_ctx))async def cp(self, src_path: str, dst_path: str, recursive: bool = False) -> Any:from .helpers import cp@@ -90,6 +199,10 @@ class AsyncAGFSClient:return await asyncio.to_thread(cp, self._client, src_path, dst_path, recursive=recursive)async def grep(self, **kwargs: Any) -> Dict[str, Any]:+ if "ctx" not in kwargs or kwargs["ctx"] is None:+ path = kwargs.get("path")+ if isinstance(path, str):+ kwargs["ctx"] = fs_ctx_from_agfs_path(path)return await self.run("grep", **kwargs)async def tree_directory(@@ -98,6 +211,8 @@ class AsyncAGFSClient:show_hidden: bool = False,node_limit: int | None = None,level_limit: int | None = None,+ *,+ fs_ctx: Dict[str, str] | None = None,) -> list[Dict[str, Any]]:return await self.run("tree_directory",@@ -105,4 +220,5 @@ class AsyncAGFSClient:show_hidden=show_hidden,node_limit=node_limit,level_limit=level_limit,+ ctx=_fs_ctx_or_default(path, fs_ctx),)diff --git a/openviking/pyagfs/helpers.py b/openviking/pyagfs/helpers.pyindex d84634000..0683a6559 100644--- a/openviking/pyagfs/helpers.py+++ b/openviking/pyagfs/helpers.py@@ -9,6 +9,7 @@ This module provides high-level helper functions for common operations:from collections.abc import Iteratorfrom pathlib import Path+from .async_client import ensure_same_encryption_accountfrom .protocols import AGFSByteStream, AGFSSyncClientProtocol@@ -35,6 +36,8 @@ def cp(>>> cp(client, "/file.txt", "/backup/file.txt") # Copy file>>> cp(client, "/dir", "/backup/dir", recursive=True) # Copy directory"""+ ensure_same_encryption_account(src, dst)+# Check if source exists and get its typesrc_info = client.stat(src)is_dir = src_info.get("isDir", False)@@ -123,10 +126,21 @@ def download(def _copy_file(client: AGFSSyncClientProtocol, src: str, dst: str, stream: bool) -> None:- """Copy a single file within AGFS."""+ """Copy a single file within AGFS.++ Uses the raw byte channel (``read_raw``/``write_raw``) when available so a whole blob is moved+ verbatim, bypassing the encryption layer (ciphertext is copied as-is, never decrypted/re-encrypted).+ Falls back to ``cat``/``write`` for clients that do not expose the raw channel.+ """# Ensure parent directory exists_ensure_remote_parent_dir(client, dst)+ read_raw = getattr(client, "read_raw", None)+ write_raw = getattr(client, "write_raw", None)+ if callable(read_raw) and callable(write_raw):+ write_raw(dst, read_raw(src))+ return+if stream:# The binding client returns bytes or an iterator of bytes, not an# HTTP response object with iter_content().diff --git a/openviking/server/api_keys/legacy.py b/openviking/server/api_keys/legacy.pyindex d0ab22c38..446d95b1f 100644--- a/openviking/server/api_keys/legacy.py+++ b/openviking/server/api_keys/legacy.py@@ -13,7 +13,7 @@ from typing import Dict, Optionalfrom argon2 import PasswordHasherfrom argon2.exceptions import VerifyMismatchError-from openviking.pyagfs import AsyncAGFSClient+from openviking.pyagfs import AGFSNotFoundError, AsyncAGFSClientfrom openviking.server.api_keys.models import AccountInfo, UserKeyEntryfrom openviking.server.identity import ResolvedIdentity, Rolefrom openviking.storage.viking_fs import VikingFS@@ -583,15 +583,9 @@ class LegacyAPIKeyManager:else:raw = content.content if hasattr(content, "content") else b""- # Decrypt content if encryption is enabled- # Extract account ID from path- parts = path.split("/")- account_id = parts[2] if len(parts) >= 3 else "default"- raw = await self._viking_fs.decrypt_bytes(account_id, raw)-text = raw.decode("utf-8") if isinstance(raw, bytes) else rawreturn json.loads(text)- except Exception:+ except AGFSNotFoundError:return Noneasync def _write_json(self, path: str, data: dict) -> None:@@ -600,12 +594,6 @@ class LegacyAPIKeyManager:if isinstance(content, str):content = content.encode("utf-8")- # Encrypt content if encryption is enabled- # Extract account ID from path- parts = path.split("/")- account_id = parts[2] if len(parts) >= 3 else "default"- content = await self._viking_fs.encrypt_bytes(account_id, content)-await self._ensure_parent_dirs_async(path)await self._async_agfs.write(path, content)diff --git a/openviking/service/core.py b/openviking/service/core.pyindex c0debccdf..5c8f42e2e 100644--- a/openviking/service/core.py+++ b/openviking/service/core.py@@ -6,12 +6,15 @@ OpenViking Service Core.Main service class that composes all sub-services and manages infrastructure lifecycle."""+import asyncioimport os+from threading import Threadfrom typing import TYPE_CHECKING, Any, Optionalfrom openviking.core.directories import DirectoryInitializerfrom openviking.crypto.config import bootstrap_encryptionfrom openviking.privacy import UserPrivacyConfigService+from openviking.pyagfs.exceptions import AGFSNotFoundErrorfrom openviking.resource.watch_scheduler import WatchSchedulerfrom openviking.server.identity import RequestContext, Rolefrom openviking.service.debug_service import DebugService@@ -45,6 +48,31 @@ if TYPE_CHECKING:from openviking.session.compressor_v2 import SessionCompressorV2+def _run_coro_blocking(coro: Any) -> Any:+ """Run an async coroutine from sync startup code, even if an event loop is already running."""+ try:+ asyncio.get_running_loop()+ except RuntimeError:+ return asyncio.run(coro)++ result: list[Any] = []+ error: list[BaseException] = []++ def _runner() -> None:+ """Execute the coroutine in an isolated event loop on a helper thread."""+ try:+ result.append(asyncio.run(coro))+ except BaseException as exc:+ error.append(exc)++ thread = Thread(target=_runner, daemon=True)+ thread.start()+ thread.join()+ if error:+ raise error[0]+ return result[0] if result else None++class OpenVikingService:"""OpenViking main service class.@@ -85,6 +113,7 @@ class OpenVikingService:self._watch_scheduler: Optional[WatchScheduler] = Noneself._encryptor: Optional[Any] = Noneself._privacy_config_service: Optional[UserPrivacyConfigService] = None+ self._data_dir_lock_acquired = False# Sub-servicesself._fs_service = FSService()@@ -98,9 +127,21 @@ class OpenVikingService:# Stateself._initialized = False+ # Acquire the data-dir lock before encryption bootstrap so first-run root-key creation is+ # serialized with storage initialization across processes.+ self._ensure_data_dir_lock_acquired()++ # Resolve encryption config (root_key) BEFORE building the agfs client, so the binding+ # stack is constructed with the encryption layer when encryption is enabled. The encryptor+ # is built here once and reused by initialize().+ binding_config = self._build_ragfs_binding_config()+# Initialize storageself._init_storage(- config.storage, config.embedding.max_concurrent, config.vlm.max_concurrent+ config.storage,+ config.embedding.max_concurrent,+ config.vlm.max_concurrent,+ binding_config=binding_config,)# Initialize embedder@@ -114,12 +155,18 @@ class OpenVikingService:config: StorageConfig,max_concurrent_embedding: int = 10,max_concurrent_semantic: int = 64,+ binding_config: Any = None,) -> None:"""Initialize storage resources."""- from openviking.utils.agfs_utils import create_agfs_client+ from openviking.utils.agfs_utils import RagfsBindingConfig, create_agfs_client# Create RAGFS client using utility- self._agfs_client = create_agfs_client(config.agfs)+ runtime_binding_config = binding_config or RagfsBindingConfig(agfs=config.agfs)+ self._agfs_client = create_agfs_client(runtime_binding_config)+ self._probe_storage_shape(+ self._agfs_client,+ encrypted_mode=runtime_binding_config.encryption_enabled(),+ )# Initialize QueueManager with agfs_clientif self._agfs_client:@@ -157,6 +204,61 @@ class OpenVikingService:)set_task_tracker(config.build_task_tracker(self._agfs_client))+ def _build_ragfs_binding_config(self) -> Any:+ """Build the single runtime binding config from OpenViking storage + encryption settings."""+ from openviking.utils.agfs_utils import RagfsBindingConfig++ full_config = self._config.to_dict()+ self._encryptor = _run_coro_blocking(bootstrap_encryption(full_config))+ if self._encryptor is None:+ return RagfsBindingConfig(agfs=self._config.storage.agfs)++ root_key = _run_coro_blocking(self._encryptor.provider.get_root_key())+ if not isinstance(root_key, (bytes, bytearray)) or len(root_key) != 32:+ raise RuntimeError("encryption root_key must be exactly 32 bytes")++ return RagfsBindingConfig(+ agfs=self._config.storage.agfs,+ root_key=bytes(root_key),+ provider_type=self._encryptor.provider_type,+ )++ def _ensure_data_dir_lock_acquired(self) -> None:+ """Acquire the process-level data directory lock once for this service instance."""+ if self._data_dir_lock_acquired:+ return++ # contention (see https://github.com/volcengine/OpenViking/issues/473).+ if not self._config.storage.skip_process_lock:+ from openviking.utils.process_lock import acquire_data_dir_lock++ acquire_data_dir_lock(self._config.storage.workspace)+ else:+ logger.warning(+ "Skipping workspace process lock for '%s'; multi-process access may corrupt data",+ self._config.storage.workspace,+ )+ self._data_dir_lock_acquired = True++ def _probe_storage_shape(self, agfs_client: Any, encrypted_mode: bool) -> None:+ """Fail fast if existing system metadata shape conflicts with current encryption mode."""+ try:+ raw = agfs_client.read_raw("/local/_system/accounts.json")+ except AGFSNotFoundError:+ return++ is_encrypted = raw.startswith(b"OVE1")+ if encrypted_mode and not is_encrypted:+ raise RuntimeError(+ "Storage shape mismatch: encryption is enabled but existing "+ "remained data is plaintext"+ )+ if not encrypted_mode and is_encrypted:+ raise RuntimeError(+ "Storage shape mismatch: encryption is disabled but existing "+ "remained data is encrypted"+ )+@propertydef _agfs(self) -> Any:"""Internal access to AGFS client for APIKeyManager."""@@ -238,23 +340,14 @@ class OpenVikingService:logger.debug("Already initialized")return- # Acquire advisory lock on data directory to prevent multi-process- # contention (see https://github.com/volcengine/OpenViking/issues/473).- if not self._config.storage.skip_process_lock:- from openviking.utils.process_lock import acquire_data_dir_lock-- acquire_data_dir_lock(self._config.storage.workspace)- else:- logger.warning(- "Skipping workspace process lock for '%s'; multi-process access may corrupt data",- self._config.storage.workspace,- )+ self._ensure_data_dir_lock_acquired()if self._vikingdb_manager is None:self._init_storage(self._config.storage,self._config.embedding.max_concurrent,self._config.vlm.max_concurrent,+ binding_config=self._build_ragfs_binding_config(),)if self._embedder is None:@@ -262,9 +355,6 @@ class OpenVikingService:config = get_openviking_config()- # Initialize encryption module- full_config = config.to_dict()- self._encryptor = await bootstrap_encryption(full_config)if self._encryptor:logger.info("Encryption module initialized")else:diff --git a/openviking/service/task_tracker.py b/openviking/service/task_tracker.pyindex f1c243f6b..40683c0d8 100644--- a/openviking/service/task_tracker.py+++ b/openviking/service/task_tracker.py@@ -504,9 +504,9 @@ class TaskTracker:def _build_default_task_tracker() -> TaskTracker:"""Build the default persistent tracker from the active storage config."""- from openviking.utils.agfs_utils import create_agfs_client+ from openviking.utils.agfs_utils import RagfsBindingConfig, create_agfs_clientfrom openviking_cli.utils.config import get_openviking_configconfig = get_openviking_config()- agfs = create_agfs_client(config.storage.agfs)+ agfs = create_agfs_client(RagfsBindingConfig(agfs=config.storage.agfs))return config.storage.build_task_tracker(agfs)diff --git a/openviking/storage/transaction/path_lock.py b/openviking/storage/transaction/path_lock.pyindex 1d5b2ad4d..ef45dd20c 100644--- a/openviking/storage/transaction/path_lock.py+++ b/openviking/storage/transaction/path_lock.py@@ -3,9 +3,10 @@ import hashlibimport reimport timefrom dataclasses import dataclass, field-from typing import Optional, Tuple+from typing import Any, Callable, Optional, Tuplefrom openviking.pyagfs import AGFSSyncClientProtocol, AsyncAGFSClient+from openviking.pyagfs.async_client import fs_ctx_from_agfs_pathfrom openviking.storage.transaction.lock_handle import LockOwnerfrom openviking_cli.utils.logger import get_logger@@ -64,6 +65,18 @@ def _log_timeout_waiting(message: str) -> None:_last_timeout_warning_at[message] = now+def _call_sync_agfs_with_ctx(+ method: Callable[..., Any], path: str, *args: Any, **kwargs: Any+) -> Any:+ """Call a sync AGFS method with path-derived FsContext, falling back for legacy fakes."""+ try:+ return method(path, *args, **kwargs, ctx=fs_ctx_from_agfs_path(path))+ except TypeError as exc:+ if "unexpected keyword argument 'ctx'" not in str(exc):+ raise+ return method(path, *args, **kwargs)++class PathLockEngine:def __init__(self, agfs_client: AGFSSyncClientProtocol, lock_expire: float = 300.0):self._agfs = agfs_client@@ -78,7 +91,7 @@ class PathLockEngine:def _is_existing_directory(self, path: str) -> bool:try:- stat = self._agfs.stat(path.rstrip("/") or "/")+ stat = _call_sync_agfs_with_ctx(self._agfs.stat, path.rstrip("/") or "/")except Exception:return Falseif isinstance(stat, dict):@@ -164,7 +177,7 @@ class PathLockEngine:def _read_token(self, lock_path: str) -> Optional[str]:try:- content = self._agfs.read(lock_path)+ content = _call_sync_agfs_with_ctx(self._agfs.read, lock_path)if isinstance(content, bytes):token = content.decode("utf-8").strip()else:diff --git a/openviking/storage/viking_fs.py b/openviking/storage/viking_fs.pyindex b4a74baf8..59f4acb0c 100644--- a/openviking/storage/viking_fs.py+++ b/openviking/storage/viking_fs.py@@ -59,8 +59,6 @@ if TYPE_CHECKING:logger = get_logger(__name__)-_DEFAULT_GREP_FILE_CONCURRENCY = 32-def _ensure_non_empty_search_query(query: str) -> None:if not query.strip():@@ -268,50 +266,6 @@ class VikingFS:bound = self._bound_ctx.get()return bound or self._default_ctx()- async def _encrypt_content(self, content: bytes, ctx: Optional[RequestContext] = None) -> bytes:- """Encrypt content if encryption is enabled."""- if not self._encryptor:- return content- real_ctx = self._ctx_or_default(ctx)- return await self._encryptor.encrypt(real_ctx.account_id, content)-- async def _decrypt_content(self, content: bytes, ctx: Optional[RequestContext] = None) -> bytes:- """Decrypt content if encryption is enabled."""- if not self._encryptor:- return content- real_ctx = self._ctx_or_default(ctx)- return await self._encryptor.decrypt(real_ctx.account_id, content)-- async def encrypt_bytes(self, account_id: str, data: bytes) -> bytes:- """- Encrypt bytes using the encryptor for the specified account.-- Args:- account_id: Account ID to use for encryption- data: Bytes to encrypt-- Returns:- Encrypted bytes, or original bytes if encryption is disabled- """- if not self._encryptor:- return data- return await self._encryptor.encrypt(account_id, data)-- async def decrypt_bytes(self, account_id: str, data: bytes) -> bytes:- """- Decrypt bytes using the encryptor for the specified account.-- Args:- account_id: Account ID to use for decryption- data: Bytes to decrypt-- Returns:- Decrypted bytes, or original bytes if encryption is disabled- """- if not self._encryptor:- return data- return await self._encryptor.decrypt(account_id, data)-@contextmanagerdef bind_request_context(self, ctx: RequestContext):"""Temporarily bind ctx for legacy internal call paths without explicit ctx param."""@@ -382,33 +336,16 @@ class VikingFS:self._ensure_access(uri, ctx)path = self._uri_to_path(uri, ctx=ctx)- if self._encryptor:- # When encryption is enabled: must read entire file for decryption- result = await self._async_agfs.read(path, 0, -1)- if isinstance(result, bytes):- raw = result- elif result is not None and hasattr(result, "content"):- raw = result.content- else:- raw = b""-- raw = await self._decrypt_content(raw, ctx=ctx)-- # Apply slicing on decrypted plaintext- if offset > 0 or size != -1:- if size != -1:- raw = raw[offset : offset + size]- else:- raw = raw[offset:]+ # Decryption + offset/size slicing now happen inside the ragfs encryption layer+ # (when configured); the plaintext stack reads bytes directly. Either way, pass the+ # offset/size through and let the Rust layer return the requested slice.+ result = await self._async_agfs.read(path, offset, size)+ if isinstance(result, bytes):+ raw = result+ elif result is not None and hasattr(result, "content"):+ raw = result.contentelse:- # When not encrypted: normal read- result = await self._async_agfs.read(path, offset, size)- if isinstance(result, bytes):- raw = result- elif result is not None and hasattr(result, "content"):- raw = result.content- else:- raw = b""+ raw = b""return raw@@ -424,7 +361,7 @@ class VikingFS:if isinstance(data, str):data = data.encode("utf-8")- data = await self._encrypt_content(data, ctx=ctx)+ # Encryption (when configured) happens inside the ragfs layer keyed by account_id.return await self._async_agfs.write(path, data)async def mkdir(@@ -438,7 +375,7 @@ class VikingFS:self._ensure_mutable_access(uri, ctx)path = self._uri_to_path(uri, ctx=ctx)# Always ensure parent directories exist before creating this directory- await self._ensure_parent_dirs(path)+ await self._ensure_parent_dirs(path, ctx=ctx)try:await self._async_agfs.mkdir(path)except Exception as exc:@@ -650,7 +587,7 @@ class VikingFS:raise# Remove carried lock file from the copy (directory only)- if is_dir and (is_temp or not self._encryptor):+ if is_dir:carried_lock = new_path.rstrip("/") + "/.path.ovlock"try:await self._async_agfs.rm(carried_lock)@@ -685,7 +622,7 @@ class VikingFS:ctx: Optional[RequestContext] = None,) -> None:"""Copy source to destination for mv without deleting source."""- if is_temp or not self._encryptor:+ if is_temp:await self._async_agfs.cp(old_path, new_path, recursive=is_dir)return@@ -737,8 +674,8 @@ class VikingFS:) -> Dict:"""Content search by pattern or keywords.- Optimized implementation that uses agfs native grep when possible.- Falls back to VikingFS layer implementation for encrypted files.+ The ragfs layer greps transparently over encrypted and plaintext files+ (it decrypts via account_id when an encryption layer is configured).Args:uri: Viking URI@@ -755,31 +692,7 @@ class VikingFS:self._ensure_access(uri, ctx)await self.stat(uri, ctx=ctx)- if self._encryptor:- return await self._grep_encrypted(- uri=uri,- pattern=pattern,- exclude_uri=exclude_uri,- case_insensitive=case_insensitive,- node_limit=node_limit,- level_limit=level_limit,- ctx=ctx,- )-- try:- return await self._grep_with_agfs(- uri=uri,- pattern=pattern,- exclude_uri=exclude_uri,- case_insensitive=case_insensitive,- node_limit=node_limit,- level_limit=level_limit,- ctx=ctx,- )- except (AttributeError, AGFSNotSupportedError, NotImplementedError) as e:- logger.debug(f"agfs grep unavailable, falling back to VikingFS implementation: {e}")-- return await self._grep_encrypted(+ return await self._grep_with_agfs(uri=uri,pattern=pattern,exclude_uri=exclude_uri,@@ -885,166 +798,6 @@ class VikingFS:"files_scanned": files_scanned,}- async def _grep_encrypted(- self,- uri: str,- pattern: str,- exclude_uri: Optional[str] = None,- case_insensitive: bool = False,- node_limit: Optional[int] = None,- level_limit: int = 5,- ctx: Optional[RequestContext] = None,- ) -> Dict:- """Grep implementation for encrypted files.-- This implementation decrypts files at VikingFS layer before matching.- Used when encryption is enabled or when agfs.grep is not available.-- Args:- uri: Viking URI- pattern: Regular expression pattern to search for- exclude_uri: Optional URI prefix to exclude from search- case_insensitive: Whether to perform case-insensitive matching- node_limit: Maximum number of results to return- level_limit: Maximum depth level to traverse (default: 5)- ctx: Request context-- Returns:- Dict with matches, count, match_count, files_scanned- """- flags = re.IGNORECASE if case_insensitive else 0- compiled_pattern = re.compile(pattern, flags)- excluded_prefix = None- if exclude_uri:- excluded_prefix = self._normalize_uri(exclude_uri).rstrip("/")- self._ensure_access(excluded_prefix, ctx)- file_uris = await self._collect_grep_files(- uri,- excluded_prefix=excluded_prefix,- level_limit=level_limit,- ctx=ctx,- )- results, files_scanned = await self._grep_files_parallel(- file_uris,- compiled_pattern=compiled_pattern,- node_limit=node_limit,- ctx=ctx,- )-- return {- "matches": results,- "count": len(results),- "match_count": len(results),- "files_scanned": files_scanned,- }-- async def _collect_grep_files(- self,- uri: str,- excluded_prefix: Optional[str],- level_limit: int,- ctx: Optional[RequestContext] = None,- ) -> List[str]:- file_uris: List[str] = []-- async def search_recursive(current_uri: str, current_depth: int) -> None:- if current_depth > level_limit:- return-- normalized_current_uri = self._normalize_uri(current_uri)- if excluded_prefix and (- normalized_current_uri == excluded_prefix- or normalized_current_uri.startswith(excluded_prefix + "/")- ):- logger.debug(f"Skipping excluded uri during grep: {normalized_current_uri}")- return-- try:- entries = await self.ls(normalized_current_uri, ctx=ctx)- except Exception:- return-- for entry in entries:- entry_uri = f"{normalized_current_uri.rstrip('/')}/{entry['name']}"- if excluded_prefix and (- entry_uri == excluded_prefix or entry_uri.startswith(excluded_prefix + "/")- ):- logger.debug(f"Skipping excluded uri during grep: {entry_uri}")- continue-- if entry.get("isDir"):- await search_recursive(entry_uri, current_depth + 1)- else:- file_uris.append(entry_uri)-- normalized_uri = self._normalize_uri(uri)- if excluded_prefix and (- normalized_uri == excluded_prefix or normalized_uri.startswith(excluded_prefix + "/")- ):- logger.debug(f"Skipping excluded uri during grep: {normalized_uri}")- return file_uris- try:- root_stat = await self.stat(normalized_uri, ctx=ctx)- except Exception:- return file_uris- if not root_stat.get("isDir", False):- file_uris.append(normalized_uri)- return file_uris-- await search_recursive(uri, 0)- return file_uris-- async def _grep_files_parallel(- self,- file_uris: List[str],- compiled_pattern: re.Pattern,- node_limit: Optional[int],- ctx: Optional[RequestContext] = None,- ) -> tuple[List[Dict[str, Any]], int]:- results: List[Dict[str, Any]] = []- files_scanned = 0- for start in range(0, len(file_uris), _DEFAULT_GREP_FILE_CONCURRENCY):- batch_uris = file_uris[start : start + _DEFAULT_GREP_FILE_CONCURRENCY]- batch_jobs = [- self._grep_single_file(entry_uri, compiled_pattern, ctx) for entry_uri in batch_uris- ]- batch_results = await asyncio.gather(*batch_jobs)- for matches, scanned_count in batch_results:- files_scanned += scanned_count- for match in matches:- results.append(match)- if node_limit and len(results) >= node_limit:- return results, files_scanned-- return results, files_scanned-- async def _grep_single_file(- self,- entry_uri: str,- compiled_pattern: re.Pattern,- ctx: Optional[RequestContext] = None,- ) -> tuple[List[Dict[str, Any]], int]:- try:- content = await self.read(entry_uri, ctx=ctx)- if isinstance(content, bytes):- content = content.decode("utf-8", errors="replace")-- matches: List[Dict[str, Any]] = []- lines = content.split("\n")- for line_num, line in enumerate(lines, 1):- if compiled_pattern.search(line):- matches.append(- {- "line": line_num,- "uri": entry_uri,- "content": line,- }- )- return matches, 1- except Exception as e:- logger.debug(f"Failed to grep {entry_uri}: {e}")- return [], 1-def _resolve_grep_match_agfs_path(self, base_path: str, match_file: str) -> str:"""Resolve a grep match path (relative to query root) into a full AGFS path."""if match_file == ".":@@ -1322,10 +1075,6 @@ class VikingFS:raisereturn f"# {uri} [Directory abstract is not ready]"- if self._encryptor:- real_ctx = self._ctx_or_default(ctx)- content_bytes = await self._encryptor.decrypt(real_ctx.account_id, content_bytes)-return self._decode_bytes(content_bytes)async def _read_abstract_for_known_dir(@@ -1347,7 +1096,11 @@ class VikingFS:uri: str,ctx: Optional[RequestContext] = None,) -> str:- """Read directory's L0 summary (.abstract.md)."""+ """Read directory's L0 summary (.abstract.md).++ If the caller points to a file, its parent directory is used instead so+ the endpoint remains usable for both file and directory URIs.+ """self._ensure_access(uri, ctx)path = self._uri_to_path(uri, ctx=ctx)try:@@ -1358,10 +1111,14 @@ class VikingFS:raise mapped from excraiseif not info.get("isDir", info.get("is_dir")):- raise FailedPreconditionError(- f"{uri} is not a directory",- details={"resource": uri, "expected": "directory"},+ parent_path = path.rsplit("/", 1)[0] or "/"+ parent_uri = self._path_to_uri(parent_path, ctx=ctx)+ logger.info(+ "content/abstract: %s is a file, falling back to parent directory %s",+ uri,+ parent_uri,)+ return await self.abstract(parent_uri, ctx=ctx)return await self._read_abstract_file(path, uri, ctx=ctx)async def overview(@@ -1369,8 +1126,12 @@ class VikingFS:uri: str,ctx: Optional[RequestContext] = None,) -> str:- """Read directory's L1 overview (.overview.md)."""- self._ensure_access(uri, ctx)+ """Read directory's L1 overview (.overview.md).++ If the caller points to a file, its parent directory is used instead so+ the endpoint remains usable for both file and directory URIs.+ """+ self._ensure_access(uri, ctx=ctx)path = self._uri_to_path(uri, ctx=ctx)try:info = await self._async_agfs.stat(path)@@ -1380,10 +1141,14 @@ class VikingFS:raise mapped from excraiseif not info.get("isDir", info.get("is_dir")):- raise FailedPreconditionError(- f"{uri} is not a directory",- details={"resource": uri, "expected": "directory"},+ parent_path = path.rsplit("/", 1)[0] or "/"+ parent_uri = self._path_to_uri(parent_path, ctx=ctx)+ logger.info(+ "content/overview: %s is a file, falling back to parent directory %s",+ uri,+ parent_uri,)+ return await self.overview(parent_uri, ctx=ctx)file_path = f"{path}/.overview.md"try:content_bytes = self._handle_agfs_read(await self._async_agfs.read(file_path))@@ -1396,10 +1161,6 @@ class VikingFS:# Fallback to default if .overview.md doesn't existreturn f"# {uri}\n\n[Directory overview is not ready]"- if self._encryptor:- real_ctx = self._ctx_or_default(ctx)- content_bytes = await self._encryptor.decrypt(real_ctx.account_id, content_bytes)-return self._decode_bytes(content_bytes)async def relations(@@ -1886,7 +1647,9 @@ class VikingFS:_INTERNAL_NAMES = {"_system", "tasks", ".path.ovlock"}_ROOT_PATH = "/local"- async def _ls_entries(self, path: str) -> List[Dict[str, Any]]:+ async def _ls_entries(+ self, path: str, ctx: Optional[RequestContext] = None+ ) -> List[Dict[str, Any]]:"""List directory entries, filtering out internal directories.At account root (/local/{account}), uses LISTABLE_SCOPES whitelist.@@ -2042,7 +1805,7 @@ class VikingFS:async def _collect(p: str):try:- for entry in await self._ls_entries(p):+ for entry in await self._ls_entries(p, ctx=ctx):name = entry.get("name", "")if name in [".", ".."]:continue@@ -2181,16 +1944,19 @@ class VikingFS:# ========== Parent Directory Creation ==========- async def _ensure_parent_dirs(self, path: str) -> None:+ async def _ensure_parent_dirs(self, path: str, ctx: Optional[RequestContext] = None) -> None:"""Recursively create all parent directories."""try:await self._async_agfs.ensure_parent_dirs(path)except Exception as e:logger.debug(f"Failed to ensure parent directories for {path}: {e}")parent = path.rstrip("/").rsplit("/", 1)[0]- await self._mkdir_path_with_parents(parent)+ await self._mkdir_path_with_parents(parent, ctx=ctx)- async def _mkdir_path_with_parents(self, dir_path: str) -> None:+ async def _mkdir_path_with_parents(+ self, dir_path: str, ctx: Optional[RequestContext] = None+ ) -> None:+ """Create a directory path segment-by-segment using the same fs context."""parts = [part for part in dir_path.strip("/").split("/") if part]current = ""for part in parts:@@ -2212,7 +1978,6 @@ class VikingFS:table_path = f"{dir_path}/.relations.json"try:content = self._handle_agfs_read(await self._async_agfs.read(table_path))- content = await self._decrypt_content(content, ctx=ctx)data = json.loads(content.decode("utf-8"))except FileNotFoundError:return []@@ -2246,7 +2011,6 @@ class VikingFS:if isinstance(content, str):content = content.encode("utf-8")- content = await self._encrypt_content(content, ctx=ctx)await self._async_agfs.write(table_path, content)# ========== Batch Read (backward compatible) ==========@@ -2279,12 +2043,11 @@ class VikingFS:"""Write file directly."""self._ensure_access(uri, ctx)path = self._uri_to_path(uri, ctx=ctx)- await self._ensure_parent_dirs(path)+ await self._ensure_parent_dirs(path, ctx=ctx)if isinstance(content, str):content = content.encode("utf-8")- content = await self._encrypt_content(content, ctx=ctx)await self._async_agfs.write(path, content)async def read_file(@@ -2326,10 +2089,6 @@ class VikingFS:else:raw = b""- # If encryption is enabled, always decrypt full file first- if self._encryptor:- raw = await self._decrypt_content(raw, ctx=ctx)-text = self._decode_bytes(raw)except Exception:raise NotFoundError(uri, "file")@@ -2359,7 +2118,6 @@ class VikingFS:)try:raw = self._handle_agfs_read(await self._async_agfs.read(path))- raw = await self._decrypt_content(raw, ctx=ctx)return rawexcept Exception:raise NotFoundError(uri, "file")@@ -2373,9 +2131,8 @@ class VikingFS:"""Write single binary file."""self._ensure_access(uri, ctx)path = self._uri_to_path(uri, ctx=ctx)- await self._ensure_parent_dirs(path)+ await self._ensure_parent_dirs(path, ctx=ctx)- content = await self._encrypt_content(content, ctx=ctx)await self._async_agfs.write(path, content)async def append_file(@@ -2392,7 +2149,6 @@ class VikingFS:existing = ""try:existing_bytes = self._handle_agfs_read(await self._async_agfs.read(path))- existing_bytes = await self._decrypt_content(existing_bytes, ctx=ctx)existing = self._decode_bytes(existing_bytes)except FileNotFoundError:pass@@ -2402,9 +2158,8 @@ class VikingFS:except AGFSClientError:raise- await self._ensure_parent_dirs(path)+ await self._ensure_parent_dirs(path, ctx=ctx)final_content = (existing + content).encode("utf-8")- final_content = await self._encrypt_content(final_content, ctx=ctx)await self._async_agfs.write(path, final_content)except Exception as e:@@ -2456,7 +2211,7 @@ class VikingFS:path = self._uri_to_path(uri, ctx=ctx)real_ctx = self._ctx_or_default(ctx)try:- entries = await self._ls_entries(path)+ entries = await self._ls_entries(path, ctx=ctx)except Exception:raise NotFoundError(uri, "directory")# basic info@@ -2506,7 +2261,7 @@ class VikingFS:path = self._uri_to_path(uri, ctx=ctx)real_ctx = self._ctx_or_default(ctx)try:- entries = await self._ls_entries(path)+ entries = await self._ls_entries(path, ctx=ctx)# AGFS returns read-only structure, need to create new dictall_entries = []for entry in entries:@@ -2565,7 +2320,7 @@ class VikingFS:self._ensure_mutable_access(target_uri, ctx)src_path = self._uri_to_path(temp_uri, ctx=ctx)dst_path = self._uri_to_path(target_uri, ctx=ctx)- await self._ensure_parent_dirs(dst_path)+ await self._ensure_parent_dirs(dst_path, ctx=ctx)await self._async_agfs.cp(src_path, dst_path, recursive=True)async def delete_temp(self, temp_uri: str, ctx: Optional[RequestContext] = None) -> None:@@ -2573,7 +2328,7 @@ class VikingFS:self._ensure_mutable_access(temp_uri, ctx)path = self._uri_to_path(temp_uri, ctx=ctx)try:- for entry in await self._ls_entries(path):+ for entry in await self._ls_entries(path, ctx=ctx):name = entry.get("name", "")if name in [".", ".."]:continue@@ -2642,7 +2397,7 @@ class VikingFS:path = self._uri_to_path(uri, ctx=ctx)try:- await self._ensure_parent_dirs(path)+ await self._ensure_parent_dirs(path, ctx=ctx)try:await self._async_agfs.mkdir(path)except Exception as e:diff --git a/openviking/utils/agfs_utils.py b/openviking/utils/agfs_utils.pyindex dfd7ce87a..dff1cd169 100644--- a/openviking/utils/agfs_utils.py+++ b/openviking/utils/agfs_utils.py@@ -6,6 +6,7 @@ RAGFS Client utilities for creating and configuring RAGFS clients.import multiprocessingimport os+from dataclasses import dataclassfrom pathlib import Pathfrom typing import Any, Dict@@ -14,6 +15,35 @@ from openviking_cli.utils.logger import get_loggerlogger = get_logger(__name__)+@dataclass(frozen=True)+class RagfsBindingConfig:+ """Single binding config object for both stack construction and backend mount setup."""++ agfs: Any+ root_key: bytes | None = None+ provider_type: int | None = None++ def encryption_enabled(self) -> bool:+ """Return whether the binding stack should include the encryption layer."""+ return self.root_key is not None++ def to_binding_dict(self) -> Dict[str, Any]:+ """Convert the runtime config into the sectioned dict consumed by `RAGFSBindingClient`."""+ binding_config: Dict[str, Any] = {}++ if self.root_key is not None:+ if len(self.root_key) != 32:+ raise ValueError("root_key must be exactly 32 bytes")+ if self.provider_type is None:+ raise ValueError("provider_type is required when root_key is configured")+ binding_config["encryption"] = {+ "root_key": self.root_key,+ "provider_type": self.provider_type,+ }++ return binding_config++def resolve_queuefs_mount_point(config: Any = None) -> str:"""Resolve QueueFS mount point for the current process.@@ -135,19 +165,19 @@ def _generate_plugin_config(agfs_config: Any, data_path: Path) -> Dict[str, Any]return config-def create_agfs_client(agfs_config: Any) -> Any:+def create_agfs_client(config: RagfsBindingConfig) -> Any:"""Create a RAGFS client based on the provided configuration.Args:- agfs_config: RAGFS configuration object.+ config: Single runtime config object containing both backend mount settings and+ construction-time binding sections.Returns:A RAGFSBindingClient instance."""- # Ensure agfs_config is not None- if agfs_config is None:- raise ValueError("agfs_config cannot be None")+ if config is None:+ raise ValueError("config cannot be None")# Import binding clientfrom openviking.pyagfs import get_binding_client@@ -161,26 +191,28 @@ def create_agfs_client(agfs_config: Any) -> Any:"to build and install the RAGFS SDK with native bindings.")- client = RAGFSBindingClient()+ # Construction-time decides whether the stack includes the encryption layer.+ client = RAGFSBindingClient(config=config.to_binding_dict())# Automatically mount backend for binding client- mount_agfs_backend(client, agfs_config)+ mount_agfs_backend(client, config)return client-def mount_agfs_backend(agfs: Any, agfs_config: Any) -> None:+def mount_agfs_backend(agfs: Any, config: RagfsBindingConfig | Any) -> None:"""Mount backend filesystem for a RAGFS client based on configuration.Args:agfs: RAGFS client instance.- agfs_config: RAGFS configuration object containing backend settings.+ config: RagfsBindingConfig or raw AGFS backend config for direct mount tests."""# Check for the presence of a `mount` methodif not callable(getattr(agfs, "mount", None)):return+ agfs_config = config.agfs if isinstance(config, RagfsBindingConfig) else configpath_str = getattr(agfs_config, "path", None)if path_str is None:raise ValueError("agfs_config.path is required for mounting backend")diff --git a/openviking_cli/utils/config/encryption_config.py b/openviking_cli/utils/config/encryption_config.pyindex 7ec227a04..bdbd6417a 100644--- a/openviking_cli/utils/config/encryption_config.py+++ b/openviking_cli/utils/config/encryption_config.py@@ -30,6 +30,24 @@ class VaultEncryptionProviderConfig(BaseModel):default="transit", description="HashiCorp Vault transit secrets engine mount point")key_name: str = Field(default="openviking-root", description="HashiCorp Vault key name")+ kv_mount_point: str = Field(+ default="secret",+ description="KV secrets engine mount point for persisting the encrypted root key",+ )+ kv_version: int = Field(+ default=1,+ ge=1,+ le=2,+ description="KV secrets engine version (1 or 2)",+ )+ root_key_name: str = Field(+ default="openviking-root-key",+ description="Transit engine key name used for envelope encryption (primary, preferred over key_name)",+ )+ encrypted_root_key_key: str = Field(+ default="openviking-encrypted-root-key",+ description="KV path under which the encrypted root key is stored",+ )class VolcengineKMSEncryptionProviderConfig(BaseModel):diff --git a/tests/agfs/test_fs_binding.py b/tests/agfs/test_fs_binding.pyindex 5cdcde749..0f6c913c3 100644--- a/tests/agfs/test_fs_binding.py+++ b/tests/agfs/test_fs_binding.py@@ -28,10 +28,10 @@ if os.path.exists(AGFS_CONF.path):@pytest.fixture(scope="module")async def viking_fs_binding_instance():"""Initialize VikingFS with binding mode."""- from openviking.utils.agfs_utils import create_agfs_client+ from openviking.utils.agfs_utils import RagfsBindingConfig, create_agfs_client# Create AGFS client- agfs_client = create_agfs_client(AGFS_CONF)+ agfs_client = create_agfs_client(RagfsBindingConfig(agfs=AGFS_CONF))# Initialize LockManager and VikingFS with clientinit_lock_manager(agfs=agfs_client)diff --git a/tests/agfs/test_fs_binding_s3.py b/tests/agfs/test_fs_binding_s3.pyindex 85aa4fc1a..0e0020bc0 100644--- a/tests/agfs/test_fs_binding_s3.py+++ b/tests/agfs/test_fs_binding_s3.py@@ -54,10 +54,10 @@ pytestmark = pytest.mark.skipif(@pytest.fixture(scope="module")async def viking_fs_binding_s3_instance():"""Initialize VikingFS with binding mode for S3 backend."""- from openviking.utils.agfs_utils import create_agfs_client+ from openviking.utils.agfs_utils import RagfsBindingConfig, create_agfs_client# Create AGFS client- agfs_client = create_agfs_client(AGFS_CONF)+ agfs_client = create_agfs_client(RagfsBindingConfig(agfs=AGFS_CONF))# Initialize LockManager and VikingFS with clientinit_lock_manager(agfs=agfs_client)diff --git a/tests/integration/test_encryption_integration.py b/tests/integration/test_encryption_integration.pyindex 5cd5d44c5..bc3a12458 100644--- a/tests/integration/test_encryption_integration.py+++ b/tests/integration/test_encryption_integration.py@@ -18,7 +18,7 @@ from openviking import AsyncOpenVikingfrom openviking.crypto.config import bootstrap_encryptionfrom openviking.crypto.encryptor import FileEncryptorfrom openviking.crypto.providers import LocalFileProvider-from openviking.server.api_keys import APIKeyManager+from openviking.server.api_keys import APIKeyManager, is_new_format_keyfrom openviking.service.core import OpenVikingServicefrom openviking_cli.session.user_id import UserIdentifierfrom openviking_cli.utils.config.open_viking_config import OpenVikingConfigSingleton@@ -279,9 +279,7 @@ class TestVikingFSEncryptionWithAccounts:await svc.initialize()# Create APIKeyManager using VikingFS to ensure system file encryption- api_key_manager = APIKeyManager(- root_key=self.ROOT_KEY, viking_fs=svc.viking_fs, encryption_enabled=True- )+ api_key_manager = APIKeyManager(root_key=self.ROOT_KEY, viking_fs=svc.viking_fs)await api_key_manager.load()yield {"service": svc, "api_key_manager": api_key_manager, "test_data_dir": test_data_dir}@@ -334,15 +332,19 @@ class TestVikingFSEncryptionWithAccounts:continuetry:agfs_path = svc.viking_fs._uri_to_path(entry_uri, ctx=ctx)- raw_content = agfs_client.read(agfs_path)+ raw_content = agfs_client.read_raw(agfs_path)assert raw_content.startswith(b"OVE1"), (f"File not encrypted: {entry_uri}")if print_paths:print(f"[ENCRYPTED] {entry_uri}")+ except AssertionError:+ raiseexcept Exception as e:if print_paths:print(f"[SKIP] Skip file {entry_uri}: {e}")+ except AssertionError:+ raiseexcept Exception as e:print(f"[WARNING] Error checking {uri}: {e}")@@ -372,7 +374,7 @@ class TestVikingFSEncryptionWithAccounts:# Verify account created successfullyassert user_key is not None- assert len(user_key) == 64+ assert is_new_format_key(user_key)# RAGFS /local/... paths map to test_data_dir/viking/viking/...# because OpenVikingService path is test_data_dir/viking,@@ -418,7 +420,7 @@ class TestVikingFSEncryptionWithAccounts:# Verify user registered successfullyassert new_user_key is not None- assert len(new_user_key) == 64+ assert is_new_format_key(new_user_key)# AGFS /local/... paths map to test_data_dir/viking/viking/...agfs_data_root = test_data_dir / "viking" / "viking"@@ -461,7 +463,7 @@ class TestVikingFSEncryptionWithAccounts:# Verify encryption by reading raw file content directly via AGFSagfs_client = svc._agfs_clientagfs_path = svc.viking_fs._uri_to_path(test_uri, ctx=ctx)- raw_content = agfs_client.read(agfs_path)+ raw_content = agfs_client.read_raw(agfs_path)assert raw_content.startswith(b"OVE1"), (f"File not encrypted, raw content start: {raw_content[:10]}")@@ -549,7 +551,7 @@ This is a test skill for verifying encryption functionality.agfs_client = svc._agfs_clientskill_md_uri = f"{skill_uri}/SKILL.md"agfs_path = svc.viking_fs._uri_to_path(skill_md_uri, ctx=ctx)- raw_content = agfs_client.read(agfs_path)+ raw_content = agfs_client.read_raw(agfs_path)assert raw_content.startswith(b"OVE1"), (f"Skill file not encrypted, raw content start: {raw_content[:10]}")@@ -574,7 +576,7 @@ This is a test skill for verifying encryption functionality.agfs_path = svc.viking_fs._uri_to_path(root_uri, ctx=ctx)if agfs_client.exists(agfs_path) and not agfs_client.isdir(agfs_path):# This is a file, check directly- raw_content = agfs_client.read(agfs_path)+ raw_content = agfs_client.read_raw(agfs_path)assert raw_content.startswith(b"OVE1"), f"File not encrypted: {root_uri}"print(f"{prefix}✓ [ENCRYPTED] {root_uri}")return@@ -592,7 +594,7 @@ This is a test skill for verifying encryption functionality.else:# Check file encryptionagfs_path = svc.viking_fs._uri_to_path(entry["uri"], ctx=ctx)- raw_content = agfs_client.read(agfs_path)+ raw_content = agfs_client.read_raw(agfs_path)assert raw_content.startswith(b"OVE1"), f"File not encrypted: {entry['uri']}"print(f"{prefix}✓ [ENCRYPTED] {entry['uri']}")except Exception as e:@@ -622,7 +624,7 @@ This is a test skill for verifying encryption functionality.admin_user_key = await api_key_manager.create_account(test_account_id, test_admin_user_id)assert admin_user_key is not None- assert len(admin_user_key) == 64+ assert is_new_format_key(admin_user_key)# 2. Verify list-accounts operation (via accessing APIKeyManager internal data)print("[2] Verify list-accounts operation")@@ -636,7 +638,7 @@ This is a test skill for verifying encryption functionality.print(f"[3] Register test user: {test_user_id}")test_user_key = await api_key_manager.register_user(test_account_id, test_user_id, "user")assert test_user_key is not None- assert len(test_user_key) == 64+ assert is_new_format_key(test_user_key)# 4. Verify list-users operationprint("[4] Verify list-users operation")@@ -723,12 +725,10 @@ This is a test skill for verifying encryption functionality.# grep operationprint(" Executing grep operation...")- try:- grep_result = await svc.viking_fs.grep(resources_dir_uri, "OpenViking", ctx=ctx)- assert grep_result is not None- print(" ✓ grep operation successful")- except Exception as e:- print(f" [WARNING] grep operation may not be supported: {e}")+ grep_result = await svc.viking_fs.grep(resources_dir_uri, "OpenViking", ctx=ctx)+ assert grep_result["count"] > 0+ assert any("OpenViking" in match["content"] for match in grep_result["matches"])+ print(" ✓ grep operation successful")# abstract operationprint(" Executing abstract operation...")@@ -915,12 +915,10 @@ This is a test skill for verifying encryption functionality.# grep operationprint(" Executing grep operation...")- try:- memory_grep_result = await svc.viking_fs.grep(user_dir_uri, "dark theme", ctx=ctx)- assert memory_grep_result is not None- print(" ✓ grep operation successful")- except Exception as e:- print(f" [WARNING] grep operation may not be supported: {e}")+ memory_grep_result = await svc.viking_fs.grep(user_dir_uri, "dark theme", ctx=ctx)+ assert memory_grep_result["count"] > 0+ assert any("dark theme" in match["content"] for match in memory_grep_result["matches"])+ print(" ✓ grep operation successful")# abstract operationprint(" Executing abstract operation...")@@ -979,12 +977,10 @@ This is a test skill for verifying encryption functionality.print(" ✓ get operation returns unencrypted content")# grep operation- try:- grep_result = await svc.viking_fs.grep(session_dir_uri, "session", ctx=ctx)- assert grep_result is not None- print(" ✓ grep operation successful")- except Exception as e:- print(f" [WARNING] grep operation may not be supported: {e}")+ grep_result = await svc.viking_fs.grep(session_dir_uri, "session", ctx=ctx)+ assert grep_result["count"] > 0+ assert any("session" in match["content"] for match in grep_result["matches"])+ print(" ✓ grep operation successful")# abstract operation (on session directory)try:@@ -1071,7 +1067,7 @@ This is a test skill for verifying encryption functionality.try:relation_file_uri = f"{dir_a_uri}/.relations.json"agfs_path = svc.viking_fs._uri_to_path(relation_file_uri, ctx=ctx)- raw_content = agfs_client.read(agfs_path)+ raw_content = agfs_client.read_raw(agfs_path)assert raw_content.startswith(b"OVE1"), (f"relation.json not encrypted: {relation_file_uri}")@@ -1144,7 +1140,7 @@ This is a test skill for verifying encryption functionality.# Verify file is encrypted on diskagfs_client = svc._agfs_clientagfs_path = svc.viking_fs._uri_to_path(test_uri, ctx=ctx)- raw_content = agfs_client.read(agfs_path)+ raw_content = agfs_client.read_raw(agfs_path)assert raw_content.startswith(b"OVE1"), "File should be encrypted"print("\n" + "=" * 80)@@ -1192,7 +1188,7 @@ This is a test skill for verifying encryption functionality.# Verify file is encrypted on diskagfs_client = svc._agfs_clientagfs_path = svc.viking_fs._uri_to_path(test_uri, ctx=ctx)- raw_content = agfs_client.read(agfs_path)+ raw_content = agfs_client.read_raw(agfs_path)assert raw_content.startswith(b"OVE1"), "File should be encrypted"print("\n" + "=" * 80)@@ -1250,9 +1246,7 @@ class TestAddResourceWithSemanticProcessing:await svc.initialize()# Create APIKeyManager using VikingFS to ensure system file encryption- api_key_manager = APIKeyManager(- root_key=self.ROOT_KEY, viking_fs=svc.viking_fs, encryption_enabled=True- )+ api_key_manager = APIKeyManager(root_key=self.ROOT_KEY, viking_fs=svc.viking_fs)await api_key_manager.load()yield {@@ -1285,12 +1279,12 @@ class TestAddResourceWithSemanticProcessing:print(f"[1] Create test account: {test_account_id}")admin_user_key = await api_key_manager.create_account(test_account_id, test_admin_user_id)assert admin_user_key is not None- assert len(admin_user_key) == 64+ assert is_new_format_key(admin_user_key)print(f"[2] Register test user: {test_user_id}")test_user_key = await api_key_manager.register_user(test_account_id, test_user_id, "user")assert test_user_key is not None- assert len(test_user_key) == 64+ assert is_new_format_key(test_user_key)from openviking.server.identity import RequestContext, Rolefrom openviking_cli.session.user_id import UserIdentifier@@ -1354,7 +1348,7 @@ This is a file in subdir2.continuetry:agfs_path = svc.viking_fs._uri_to_path(entry_uri, ctx=ctx)- raw_content = agfs_client.read(agfs_path)+ raw_content = agfs_client.read_raw(agfs_path)assert raw_content.startswith(b"OVE1"), (f"File not encrypted: {entry_uri}")@@ -1414,7 +1408,7 @@ This is a file in subdir2.try:abstract_md_uri = f"{entry['uri']}/.abstract.md"agfs_path = svc.viking_fs._uri_to_path(abstract_md_uri, ctx=ctx)- raw_content = agfs_client.read(agfs_path)+ raw_content = agfs_client.read_raw(agfs_path)assert raw_content.startswith(b"OVE1"), (f".abstract.md not encrypted: {abstract_md_uri}")diff --git a/tests/integration/test_vault_encryption_integration.py b/tests/integration/test_vault_encryption_integration.pyindex 198804f3a..c3476ed5c 100644--- a/tests/integration/test_vault_encryption_integration.py+++ b/tests/integration/test_vault_encryption_integration.py@@ -361,9 +361,7 @@ class TestVikingFSEncryptionWithVault:await svc.initialize()# Create APIKeyManager using VikingFS to ensure system files are encrypted- api_key_manager = APIKeyManager(- root_key=self.ROOT_KEY, viking_fs=svc.viking_fs, encryption_enabled=True- )+ api_key_manager = APIKeyManager(root_key=self.ROOT_KEY, viking_fs=svc.viking_fs)await api_key_manager.load()yield {"service": svc, "api_key_manager": api_key_manager, "test_data_dir": test_data_dir}@@ -415,7 +413,7 @@ class TestVikingFSEncryptionWithVault:else:# Use VikingFS's _uri_to_path method to get file pathagfs_path = svc.viking_fs._uri_to_path(entry_uri, ctx=ctx)- raw_content = agfs_client.read(agfs_path)+ raw_content = agfs_client.read_raw(agfs_path)assert raw_content.startswith(b"OVE1"), f"File {entry_uri} is not encrypted"if print_paths:print(f"✓ File is encrypted: {entry_uri}")@@ -460,7 +458,7 @@ class TestVikingFSEncryptionWithVault:# Verify file is encryptedagfs_client = svc._agfs_clientagfs_path = svc.viking_fs._uri_to_path(test_uri, ctx=ctx)- raw_content = agfs_client.read(agfs_path)+ raw_content = agfs_client.read_raw(agfs_path)assert raw_content.startswith(b"OVE1")# Test various operations@@ -475,11 +473,9 @@ class TestVikingFSEncryptionWithVault:assert len(tree_entries) > 0# grep operation- try:- grep_result = await svc.viking_fs.grep(resources_dir_uri, "Vault", ctx=ctx)- assert grep_result is not None- except Exception as e:- print(f"[WARNING] grep operation may not be supported: {e}")+ grep_result = await svc.viking_fs.grep(resources_dir_uri, "Vault", ctx=ctx)+ assert grep_result["count"] > 0+ assert any("Vault" in match["content"] for match in grep_result["matches"])# abstract operationtry:@@ -541,7 +537,7 @@ This is a test skill for verifying Vault encryption.# Verify file is encryptedagfs_client = svc._agfs_clientagfs_path = svc.viking_fs._uri_to_path(skill_md_uri, ctx=ctx)- raw_content = agfs_client.read(agfs_path)+ raw_content = agfs_client.read_raw(agfs_path)assert raw_content.startswith(b"OVE1")# Test various operations@@ -598,7 +594,7 @@ This is a test skill for verifying Vault encryption.# Verify file is encryptedagfs_client = svc._agfs_clientagfs_path = svc.viking_fs._uri_to_path(memory_file_uri, ctx=ctx)- raw_content = agfs_client.read(agfs_path)+ raw_content = agfs_client.read_raw(agfs_path)assert raw_content.startswith(b"OVE1")@pytest.mark.asynciodiff --git a/tests/integration/test_volcengine_kms_encryption_integration.py b/tests/integration/test_volcengine_kms_encryption_integration.pyindex 38615541f..048d069f7 100644--- a/tests/integration/test_volcengine_kms_encryption_integration.py+++ b/tests/integration/test_volcengine_kms_encryption_integration.py@@ -20,7 +20,7 @@ import pytest_asynciofrom openviking import AsyncOpenVikingfrom openviking.crypto.encryptor import FileEncryptorfrom openviking.crypto.providers import VolcengineKMSProvider-from openviking.server.api_keys import APIKeyManager+from openviking.server.api_keys import APIKeyManager, is_new_format_keyfrom openviking.service.core import OpenVikingServicefrom openviking_cli.session.user_id import UserIdentifierfrom openviking_cli.utils.config.open_viking_config import OpenVikingConfigSingleton@@ -375,9 +375,7 @@ class TestVikingFSEncryptionWithVolcengineKMS:)await svc.initialize()- api_key_manager = APIKeyManager(- root_key=self.ROOT_KEY, viking_fs=svc.viking_fs, encryption_enabled=True- )+ api_key_manager = APIKeyManager(root_key=self.ROOT_KEY, viking_fs=svc.viking_fs)await api_key_manager.load()yield {"service": svc, "api_key_manager": api_key_manager, "test_data_dir": test_data_dir}@@ -413,7 +411,7 @@ class TestVikingFSEncryptionWithVolcengineKMS:else:# Use VikingFS's _uri_to_path method to get file pathagfs_path = svc.viking_fs._uri_to_path(entry_uri, ctx=ctx)- raw_content = agfs_client.read(agfs_path)+ raw_content = agfs_client.read_raw(agfs_path)assert raw_content.startswith(b"OVE1"), f"File {entry_uri} is not encrypted"if print_paths:print(f"✓ File is encrypted: {entry_uri}")@@ -439,7 +437,7 @@ class TestVikingFSEncryptionWithVolcengineKMS:user_key = await api_key_manager.create_account(account_id, admin_user_id)assert user_key is not None- assert len(user_key) == 64+ assert is_new_format_key(user_key)agfs_data_root = test_data_dir / "viking" / "viking"@@ -522,7 +520,7 @@ class TestVikingFSEncryptionWithVolcengineKMS:# Verify file is encryptedagfs_client = svc._agfs_clientagfs_path = svc.viking_fs._uri_to_path(test_uri, ctx=ctx)- raw_content = agfs_client.read(agfs_path)+ raw_content = agfs_client.read_raw(agfs_path)assert raw_content.startswith(b"OVE1")# Test various operations@@ -537,11 +535,9 @@ class TestVikingFSEncryptionWithVolcengineKMS:assert len(tree_entries) > 0# grep operation- try:- grep_result = await svc.viking_fs.grep(resources_dir_uri, "Volcengine", ctx=ctx)- assert grep_result is not None- except Exception as e:- print(f"[WARNING] grep operation may not be supported: {e}")+ grep_result = await svc.viking_fs.grep(resources_dir_uri, "Volcengine", ctx=ctx)+ assert grep_result["count"] > 0+ assert any("Volcengine" in match["content"] for match in grep_result["matches"])# abstract operationtry:@@ -605,7 +601,7 @@ This is a test skill for verifying Volcengine KMS encryption.# Verify file is encryptedagfs_client = svc._agfs_clientagfs_path = svc.viking_fs._uri_to_path(skill_md_uri, ctx=ctx)- raw_content = agfs_client.read(agfs_path)+ raw_content = agfs_client.read_raw(agfs_path)assert raw_content.startswith(b"OVE1")# Test various operations@@ -662,7 +658,7 @@ This is a test skill for verifying Volcengine KMS encryption.# Verify file is encryptedagfs_client = svc._agfs_clientagfs_path = svc.viking_fs._uri_to_path(memory_file_uri, ctx=ctx)- raw_content = agfs_client.read(agfs_path)+ raw_content = agfs_client.read_raw(agfs_path)assert raw_content.startswith(b"OVE1")@pytest.mark.asynciodiff --git a/tests/misc/test_config_validation.py b/tests/misc/test_config_validation.pyindex 8ea30c318..5f50f1672 100644--- a/tests/misc/test_config_validation.py+++ b/tests/misc/test_config_validation.py@@ -8,7 +8,12 @@ from pathlib import Pathimport pytest-from openviking.utils.agfs_utils import _generate_plugin_config, mount_agfs_backend+from openviking.utils.agfs_utils import (+ RagfsBindingConfig,+ _generate_plugin_config,+ create_agfs_client,+ mount_agfs_backend,+)from openviking_cli.utils.config.agfs_config import AGFSConfig, S3Configfrom openviking_cli.utils.config.embedding_config import EmbeddingConfig, EmbeddingModelConfigfrom openviking_cli.utils.config.vectordb_config import VectorDBBackendConfig, VolcengineConfig@@ -246,6 +251,18 @@ class _FakeMountClient:return None+class _FakeBindingClient:+ def __init__(self, *, config):+ self.config = config+ self.mount_calls = []++ def mount(self, plugin_name, mount_path, config):+ self.mount_calls.append((plugin_name, mount_path, config))++ def unmount(self, _mount_path):+ return None++def test_mount_agfs_backend_skips_queue_sqlite_dirs_for_memory_backend(tmp_path):config = AGFSConfig(path=str(tmp_path),@@ -281,6 +298,40 @@ def test_mount_agfs_backend_creates_queue_sqlite_dirs_for_sqlite_backend(tmp_patassert queuefs_mount[2]["db_path"] == str(queue_db_path.resolve())+def test_ragfs_binding_config_builds_single_binding_dict_for_local_backend(tmp_path):+ agfs_config = AGFSConfig(path=str(tmp_path), backend="local")++ config = RagfsBindingConfig(+ agfs=agfs_config,+ root_key=b"\x01" * 32,+ provider_type=7,+ )++ assert config.to_binding_dict() == {+ "encryption": {+ "root_key": b"\x01" * 32,+ "provider_type": 7,+ }+ }+++def test_create_agfs_client_uses_single_binding_config_object(monkeypatch, tmp_path):+ agfs_config = AGFSConfig(path=str(tmp_path), backend="memory")+ fake_client = _FakeBindingClient(config={})++ def _fake_get_binding_client():+ return (lambda *, config: fake_client.__class__(config=config), None)++ monkeypatch.setattr("openviking.pyagfs.get_binding_client", _fake_get_binding_client)++ config = RagfsBindingConfig(agfs=agfs_config)+ client = create_agfs_client(config)++ assert isinstance(client, _FakeBindingClient)+ assert client.config == {}+ assert any(call[0] == "memfs" for call in client.mount_calls)++def test_vectordb_validation():"""Test VectorDB config validation"""print("\n" + "=" * 60)diff --git a/tests/pyagfs/test_async_client_fs_ctx.py b/tests/pyagfs/test_async_client_fs_ctx.pynew file mode 100644index 000000000..92fb0faeb--- /dev/null+++ b/tests/pyagfs/test_async_client_fs_ctx.py@@ -0,0 +1,92 @@+from __future__ import annotations++from typing import Any++import pytest++from openviking.pyagfs.async_client import AsyncAGFSClient+from openviking.pyagfs.helpers import cp+++class _RecordingClient:+ """Record ctx values received by the sync AGFS surface."""++ def __init__(self) -> None:+ self.calls: list[tuple[str, str, dict[str, str] | None]] = []++ def write(self, path: str, data: bytes, *, ctx: dict[str, str] | None = None) -> str:+ """Record write ctx and return a stable fake backend id."""+ self.calls.append(("write", path, ctx))+ return "written"++ def read(self, path: str, *, ctx: dict[str, str] | None = None, **_: Any) -> bytes:+ """Record read ctx and return a stable fake payload."""+ self.calls.append(("read", path, ctx))+ return b"payload"+++async def test_async_client_derives_account_ctx_from_local_agfs_path() -> None:+ client = _RecordingClient()+ agfs = AsyncAGFSClient(client)++ await agfs.write("/local/acct-1/data/file.txt", b"x")++ assert client.calls == [("write", "/local/acct-1/data/file.txt", {"account_id": "acct-1"})]+++async def test_async_client_uses_system_ctx_for_non_local_agfs_path() -> None:+ client = _RecordingClient()+ agfs = AsyncAGFSClient(client)++ await agfs.read("/queue/semantic/dequeue")++ assert client.calls == [("read", "/queue/semantic/dequeue", {"account_id": "_system"})]+++async def test_async_client_preserves_explicit_fs_ctx() -> None:+ client = _RecordingClient()+ agfs = AsyncAGFSClient(client)++ await agfs.write(+ "/local/path-account/data/file.txt", b"x", fs_ctx={"account_id": "ctx-account"}+ )++ assert client.calls == [+ ("write", "/local/path-account/data/file.txt", {"account_id": "ctx-account"})+ ]+++async def test_async_client_rejects_cross_account_mv() -> None:+ client = _RecordingClient()+ agfs = AsyncAGFSClient(client)++ with pytest.raises(ValueError, match="cross-account"):+ await agfs.mv("/local/a/data/file.txt", "/local/b/data/file.txt")+++def test_cp_rejects_cross_account_raw_copy() -> None:+ class _CpClient:+ """Minimal cp client; methods must not be called after account guard fails."""++ def stat(self, path: str) -> dict[str, Any]:+ """Fail if cp checks storage before validating account boundaries."""+ raise AssertionError(f"unexpected stat call: {path}")++ with pytest.raises(ValueError, match="cross-account"):+ cp(_CpClient(), "/local/a/data/file.txt", "/local/b/data/file.txt")+++def test_cp_rejects_cross_encryption_domain_raw_copy() -> None:+ class _CpClient:+ """Minimal cp client; methods must not be called after account guard fails."""++ def stat(self, path: str) -> dict[str, Any]:+ """Fail if cp checks storage before validating account boundaries."""+ raise AssertionError(f"unexpected stat call: {path}")++ with pytest.raises(ValueError, match="cross-account"):+ cp(_CpClient(), "/local/a/data/file.txt", "/mem/data/file.txt")diff --git a/tests/server/test_admin_api.py b/tests/server/test_admin_api.pyindex 07377b5ff..965baa8c9 100644--- a/tests/server/test_admin_api.py+++ b/tests/server/test_admin_api.py@@ -11,6 +11,7 @@ from fastapi import FastAPIfrom fastapi import Request as FastAPIRequestfrom fastapi.responses import JSONResponse+from openviking.pyagfs.exceptions import AGFSNotFoundErrorfrom openviking.server.api_keys import APIKeyManagerfrom openviking.server.app import create_appfrom openviking.server.config import ServerConfig@@ -33,15 +34,15 @@ class _FakeAGFS:self._files = {}self._dirs = {"/", "/local"}- def read(self, path):+ def read(self, path, **_kwargs):if path not in self._files:- raise FileNotFoundError(path)+ raise AGFSNotFoundError(path)return self._files[path]- def write(self, path, content):+ def write(self, path, content, **_kwargs):self._files[path] = content- def mkdir(self, path):+ def mkdir(self, path, **_kwargs):self._dirs.add(path)@@ -49,12 +50,6 @@ class _FakeVikingFS:def __init__(self):self.agfs = _FakeAGFS()- async def encrypt_bytes(self, account_id, content):- return content-- async def decrypt_bytes(self, account_id, content):- return content-class _FakeService:def __init__(self):@@ -754,11 +749,11 @@ async def test_trusted_mode_admin_cannot_register_user_in_other_account(assert resp.json()["error"]["code"] == "INVALID_ARGUMENT"-async def test_trusted_mode_user_cannot_call_admin_api(+async def test_trusted_mode_admin_api_uses_trusted_gateway_identity(trusted_admin_client: httpx.AsyncClient,trusted_admin_app,):- """Trusted USER requests should still be denied by Admin API role checks."""+ """Trusted admin routes use the trusted gateway identity instead of tenant user role."""# Set gateway-admin to ROOT role firstmanager = trusted_admin_app.state.api_key_managerawait manager.set_role("platform", "gateway-admin", "root")@@ -787,7 +782,10 @@ async def test_trusted_mode_user_cannot_call_admin_api(include_api_key=True,),)- assert resp.status_code == 403+ assert resp.status_code == 200+ assert resp.json()["result"]["account_id"] == acct+ assert resp.json()["result"]["user_id"] == "bob"+ assert "user_key" not in resp.json()["result"]async def test_trusted_mode_requires_matching_api_key_for_admin_api(diff --git a/tests/server/test_api_key_manager.py b/tests/server/test_api_key_manager.pyindex 8bd5df6d1..f8820aa6a 100644--- a/tests/server/test_api_key_manager.py+++ b/tests/server/test_api_key_manager.py@@ -281,10 +281,10 @@ async def test_legacy_account_without_settings_loads_without_namespace_settings(assert settings is None-# ---- Encryption tests ----+# ---- Argon2id hashing tests -----async def test_create_account_with_encryption_enabled(manager_service):+async def test_create_account_with_argon2id_hashing_enabled(manager_service):"""create_account with api_key_hashing_enabled=True should create hashed keys."""acct = _uid()mgr = APIKeyManager(@@ -307,7 +307,7 @@ async def test_create_account_with_encryption_enabled(manager_service):assert identity.user_id == "alice"-async def test_register_user_with_encryption_enabled(manager_service):+async def test_register_user_with_argon2id_hashing_enabled(manager_service):"""register_user with api_key_hashing_enabled=True should create hashed keys."""acct = _uid()mgr = APIKeyManager(@@ -328,7 +328,7 @@ async def test_register_user_with_encryption_enabled(manager_service):assert identity.user_id == "bob"-async def test_regenerate_key_with_encryption_enabled(manager_service):+async def test_regenerate_key_with_argon2id_hashing_enabled(manager_service):"""regenerate_key with api_key_hashing_enabled=True should create new hashed key."""acct = _uid()mgr = APIKeyManager(@@ -361,7 +361,7 @@ async def test_regenerate_key_with_encryption_enabled(manager_service):assert identity.account_id == acct-async def test_migrate_plaintext_keys_to_encrypted(manager_service):+async def test_migrate_plaintext_keys_to_argon2id_hashing(manager_service):"""Keys created with api_key_hashing disabled should be migrated when api_key_hashing is enabled."""acct = _uid()@@ -384,7 +384,7 @@ async def test_migrate_plaintext_keys_to_encrypted(manager_service):assert identity.user_id == "alice"-async def test_persistence_with_encryption_enabled(manager_service):+async def test_persistence_with_argon2id_hashing_enabled(manager_service):"""Hashed keys should survive manager reload from AGFS."""mgr1 = APIKeyManager(root_key=ROOT_KEY, viking_fs=manager_service.viking_fs, api_key_hashing_enabled=Truediff --git a/tests/storage/test_viking_fs_tree.py b/tests/storage/test_viking_fs_tree.pyindex 3171f8c2d..11cac777d 100644--- a/tests/storage/test_viking_fs_tree.py+++ b/tests/storage/test_viking_fs_tree.py@@ -16,6 +16,14 @@ def _default_ctx() -> RequestContext:return RequestContext(user=UserIdentifier.the_default_user(), role=Role.ROOT)+def test_viking_fs_no_longer_exposes_python_encryption_api(fs: VikingFS):+ """VikingFS should not expose Python-side encryption helpers after ragfs migration."""+ assert not hasattr(fs, "_encrypt_content")+ assert not hasattr(fs, "_decrypt_content")+ assert not hasattr(fs, "encrypt_bytes")+ assert not hasattr(fs, "decrypt_bytes")++# ── Shared fixtures / builders ──────────────────────────────────────────────diff --git a/tests/test_task_tracker.py b/tests/test_task_tracker.pyindex d418961cf..2e4729454 100644--- a/tests/test_task_tracker.py+++ b/tests/test_task_tracker.py@@ -15,12 +15,15 @@ from openviking.service.task_store import PersistentTaskStorefrom openviking.service.task_tracker import (TaskStatus,TaskTracker,+ _build_default_task_tracker,_sanitize_error,get_task_tracker,reset_task_tracker,set_task_tracker,)+from openviking.utils.agfs_utils import RagfsBindingConfigfrom openviking_cli.session.user_id import UserIdentifier+from openviking_cli.utils.config import AGFSConfigpytestmark = pytest.mark.asyncio@@ -405,6 +408,40 @@ async def test_singleton_reset():assert t1 is not t2+async def test_build_default_task_tracker_wraps_agfs_config_for_binding(monkeypatch):+ captured = {}+ fake_agfs = object()++ class _FakeStorage:+ def __init__(self):+ self.agfs = AGFSConfig(backend="memory")++ def build_task_tracker(self, agfs):+ captured["build_arg"] = agfs+ return "fake-tracker"++ class _FakeConfig:+ def __init__(self):+ self.storage = _FakeStorage()++ def _fake_create_agfs_client(config):+ captured["binding_config"] = config+ return fake_agfs++ monkeypatch.setattr("openviking.utils.agfs_utils.create_agfs_client", _fake_create_agfs_client)+ monkeypatch.setattr(+ "openviking_cli.utils.config.get_openviking_config",+ lambda: _FakeConfig(),+ )++ tracker = _build_default_task_tracker()++ assert tracker == "fake-tracker"+ assert captured["build_arg"] is fake_agfs+ assert isinstance(captured["binding_config"], RagfsBindingConfig)+ assert isinstance(captured["binding_config"].agfs, AGFSConfig)++async def test_persistent_store_cross_tracker_visibility():agfs = _FakeAgfs()store = PersistentTaskStore(agfs)diff --git a/tests/transaction/test_path_lock.py b/tests/transaction/test_path_lock.pyindex dffb9c3fd..fd2dd2a75 100644--- a/tests/transaction/test_path_lock.py+++ b/tests/transaction/test_path_lock.py@@ -145,6 +145,26 @@ class TestPathLockIsLocked:assert await lock.is_locked_async("/local/u/foo/bar") is True+ def test_is_locked_sync_passes_path_derived_ctx(self):+ token = _make_fencing_token("tx-1", LOCK_TYPE_TREE)+ seen: list[dict[str, str] | None] = []++ class _CtxAwareAgfs:+ def read(self, path, *, ctx=None):+ seen.append(ctx)+ if path == "/local/u/.path.ovlock":+ return token.encode("utf-8")+ raise Exception("not found")++ def stat(self, path, *, ctx=None):+ seen.append(ctx)+ raise Exception("not found")++ lock = PathLockEngine(_CtxAwareAgfs())++ assert lock.is_locked("/local/u/foo/bar") is True+ assert {"account_id": "u"} in seen+class TestPathLockOwnership:async def test_refresh_reports_refreshed_lost_and_failed_paths(self):diff --git a/tests/unit/service/test_core_encryption_startup.py b/tests/unit/service/test_core_encryption_startup.pynew file mode 100644index 000000000..e05a753c2--- /dev/null+++ b/tests/unit/service/test_core_encryption_startup.py@@ -0,0 +1,145 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Unit tests for OpenVikingService encryption startup wiring."""++from __future__ import annotations++from types import SimpleNamespace++import pytest++from openviking.pyagfs.exceptions import AGFSNotFoundError+from openviking.service.core import OpenVikingService+from openviking.utils.agfs_utils import RagfsBindingConfig+++class _FakeConfig:+ """Minimal config object exposing the service-facing to_dict API."""++ storage = SimpleNamespace(+ agfs=SimpleNamespace(path="/tmp/ov-test", backend="local"),+ skip_process_lock=False,+ )++ def to_dict(self) -> dict:+ return {"encryption": {"enabled": True, "provider": "local"}}+++class _FakeProvider:+ """Fake provider with async root-key retrieval."""++ async def get_root_key(self) -> bytes:+ return b"k" * 32+++class _FakeEncryptor:+ """Fake encryptor returned by bootstrap_encryption."""++ provider_type = 1++ def __init__(self) -> None:+ self.provider = _FakeProvider()+++async def test_build_ragfs_binding_config_works_inside_running_event_loop(monkeypatch):+ """Build the single binding config from async bootstrap while already in an event loop."""++ async def _bootstrap(config: dict) -> _FakeEncryptor:+ assert config["encryption"]["enabled"] is True+ return _FakeEncryptor()++ monkeypatch.setattr("openviking.service.core.bootstrap_encryption", _bootstrap)+ service = OpenVikingService.__new__(OpenVikingService)+ service._config = _FakeConfig()+ service._encryptor = None++ ragfs_config = service._build_ragfs_binding_config()++ assert isinstance(ragfs_config, RagfsBindingConfig)+ assert ragfs_config.agfs is service._config.storage.agfs+ assert ragfs_config.to_binding_dict() == {+ "encryption": {+ "root_key": b"k" * 32,+ "provider_type": 1,+ }+ }+ assert isinstance(service._encryptor, _FakeEncryptor)+++ ("encrypted_mode", "raw", "message"),+ [+ (True, b"{}", "plaintext"),+ (False, b"OVE1ciphertext", "encrypted"),+ ],+)+def test_probe_storage_shape_rejects_mode_mismatch(encrypted_mode, raw, message):+ """Reject existing system metadata whose shape differs from current encryption mode."""++ class _Client:+ def read_raw(self, path: str) -> bytes:+ assert path == "/local/_system/accounts.json"+ return raw++ service = OpenVikingService.__new__(OpenVikingService)++ with pytest.raises(RuntimeError, match=message):+ service._probe_storage_shape(_Client(), encrypted_mode)+++def test_probe_storage_shape_allows_empty_system():+ """Treat missing system metadata as a fresh system."""++ class _Client:+ def read_raw(self, path: str) -> bytes:+ assert path == "/local/_system/accounts.json"+ raise AGFSNotFoundError("not found")++ service = OpenVikingService.__new__(OpenVikingService)++ service._probe_storage_shape(_Client(), encrypted_mode=True)+++def test_ensure_data_dir_lock_acquired_once(monkeypatch, tmp_path):+ """Acquire the data-dir lock once before startup encryption bootstrap."""++ calls = []++ def _acquire(path: str) -> str:+ calls.append(path)+ return str(tmp_path / ".openviking.pid")++ monkeypatch.setattr("openviking.utils.process_lock.acquire_data_dir_lock", _acquire)+ service = OpenVikingService.__new__(OpenVikingService)+ service._config = SimpleNamespace(+ storage=SimpleNamespace(workspace=str(tmp_path), skip_process_lock=False)+ )+ service._data_dir_lock_acquired = False++ service._ensure_data_dir_lock_acquired()+ service._ensure_data_dir_lock_acquired()++ assert calls == [str(tmp_path)]+++def test_ensure_data_dir_lock_respects_skip_process_lock(monkeypatch, tmp_path):+ """Skip lock acquisition entirely when storage.skip_process_lock is enabled."""++ calls = []++ def _acquire(path: str) -> str:+ calls.append(path)+ return str(tmp_path / ".openviking.pid")++ monkeypatch.setattr("openviking.utils.process_lock.acquire_data_dir_lock", _acquire)+ service = OpenVikingService.__new__(OpenVikingService)+ service._config = SimpleNamespace(+ storage=SimpleNamespace(workspace=str(tmp_path), skip_process_lock=True)+ )+ service._data_dir_lock_acquired = False++ service._ensure_data_dir_lock_acquired()++ assert calls == []+ assert service._data_dir_lock_acquired is True