Skip to content

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

refactor(encryption): using rust refactor encryption (#2444)

baojun-zhange492cbd16fb9
diff --git a/Cargo.lock b/Cargo.lock
index 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.rs
index 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, Confi
Ok(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.toml
index 790e0d5e4..5f2f828f8 100644
--- a/crates/ragfs/Cargo.toml
+++ b/crates/ragfs/Cargo.toml
@@ -64,6 +64,12 @@ lru = "0.12"
# Regular expressions for grep
regex = "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/O
futures = "0.3"
diff --git a/crates/ragfs/src/core/builder.rs b/crates/ragfs/src/core/builder.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
index 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(&regex_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(&regex_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.rs
index 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.rs
index 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 statistics
pub struct StatsWrappedFS {
- inner: Box<dyn FileSystem>,
+ inner: Arc<dyn FileSystem>,
stats: Arc<StatsCollector>,
}
impl StatsWrappedFS {
/// Create a new statistics-wrapped filesystem
pub 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 collector
pub 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.rs
new file mode 100644
index 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.rs
index 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 convenience
diff --git a/openviking/crypto/encryptor.py b/openviking/crypto/encryptor.py
index 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.py
index 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_val
encrypted_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.py
index 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_fs
from 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_client
from openviking_cli.utils.config import get_openviking_config
from 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 = None
if self.enable_vikingdb:
diff --git a/openviking/pyagfs/async_client.py b/openviking/pyagfs/async_client.py
index 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, Union
from .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._client
async 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"] = size
if 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"] = size
if 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"] = recursive
if 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.py
index 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 Iterator
from pathlib import Path
+from .async_client import ensure_same_encryption_account
from .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 type
src_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.py
index 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, Optional
from argon2 import PasswordHasher
from argon2.exceptions import VerifyMismatchError
-from openviking.pyagfs import AsyncAGFSClient
+from openviking.pyagfs import AGFSNotFoundError, AsyncAGFSClient
from openviking.server.api_keys.models import AccountInfo, UserKeyEntry
from openviking.server.identity import ResolvedIdentity, Role
from 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 raw
return json.loads(text)
- except Exception:
+ except AGFSNotFoundError:
return None
async 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.py
index 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 asyncio
import os
+from threading import Thread
from typing import TYPE_CHECKING, Any, Optional
from openviking.core.directories import DirectoryInitializer
from openviking.crypto.config import bootstrap_encryption
from openviking.privacy import UserPrivacyConfigService
+from openviking.pyagfs.exceptions import AGFSNotFoundError
from openviking.resource.watch_scheduler import WatchScheduler
from openviking.server.identity import RequestContext, Role
from 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] = None
self._encryptor: Optional[Any] = None
self._privacy_config_service: Optional[UserPrivacyConfigService] = None
+ self._data_dir_lock_acquired = False
# Sub-services
self._fs_service = FSService()
@@ -98,9 +127,21 @@ class OpenVikingService:
# State
self._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 storage
self._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_client
if 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"
+ )
+
@property
def _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.py
index 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_client
from openviking_cli.utils.config import get_openviking_config
config = 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.py
index 1d5b2ad4d..ef45dd20c 100644
--- a/openviking/storage/transaction/path_lock.py
+++ b/openviking/storage/transaction/path_lock.py
@@ -3,9 +3,10 @@ import hashlib
import re
import time
from dataclasses import dataclass, field
-from typing import Optional, Tuple
+from typing import Any, Callable, Optional, Tuple
from openviking.pyagfs import AGFSSyncClientProtocol, AsyncAGFSClient
+from openviking.pyagfs.async_client import fs_ctx_from_agfs_path
from openviking.storage.transaction.lock_handle import LockOwner
from 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 False
if 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.py
index 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)
-
@contextmanager
def 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.content
else:
- # 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:
raise
return 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 exc
raise
if 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 exc
raise
if 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 exist
return 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 raw
except 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 dict
all_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.py
index 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 multiprocessing
import os
+from dataclasses import dataclass
from pathlib import Path
from typing import Any, Dict
@@ -14,6 +15,35 @@ from openviking_cli.utils.logger import get_logger
logger = 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 client
from 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` method
if not callable(getattr(agfs, "mount", None)):
return
+ agfs_config = config.agfs if isinstance(config, RagfsBindingConfig) else config
path_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.py
index 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.py
index 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 client
init_lock_manager(agfs=agfs_client)
diff --git a/tests/agfs/test_fs_binding_s3.py b/tests/agfs/test_fs_binding_s3.py
index 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 client
init_lock_manager(agfs=agfs_client)
diff --git a/tests/integration/test_encryption_integration.py b/tests/integration/test_encryption_integration.py
index 5cd5d44c5..bc3a12458 100644
--- a/tests/integration/test_encryption_integration.py
+++ b/tests/integration/test_encryption_integration.py
@@ -18,7 +18,7 @@ from openviking import AsyncOpenViking
from openviking.crypto.config import bootstrap_encryption
from openviking.crypto.encryptor import FileEncryptor
from openviking.crypto.providers import LocalFileProvider
-from openviking.server.api_keys import APIKeyManager
+from openviking.server.api_keys import APIKeyManager, is_new_format_key
from openviking.service.core import OpenVikingService
from openviking_cli.session.user_id import UserIdentifier
from 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:
continue
try:
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:
+ raise
except Exception as e:
if print_paths:
print(f"[SKIP] Skip file {entry_uri}: {e}")
+ except AssertionError:
+ raise
except Exception as e:
print(f"[WARNING] Error checking {uri}: {e}")
@@ -372,7 +374,7 @@ class TestVikingFSEncryptionWithAccounts:
# Verify account created successfully
assert 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 successfully
assert 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 AGFS
agfs_client = svc._agfs_client
agfs_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_client
skill_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 encryption
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']}"
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 operation
print("[4] Verify list-users operation")
@@ -723,12 +725,10 @@ This is a test skill for verifying encryption functionality.
# grep operation
print(" 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 operation
print(" Executing abstract operation...")
@@ -915,12 +915,10 @@ This is a test skill for verifying encryption functionality.
# grep operation
print(" 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 operation
print(" 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 disk
agfs_client = svc._agfs_client
agfs_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 disk
agfs_client = svc._agfs_client
agfs_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, Role
from openviking_cli.session.user_id import UserIdentifier
@@ -1354,7 +1348,7 @@ This is a file in subdir2.
continue
try:
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.py
index 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 path
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 {entry_uri} is not encrypted"
if print_paths:
print(f"✓ File is encrypted: {entry_uri}")
@@ -460,7 +458,7 @@ class TestVikingFSEncryptionWithVault:
# Verify file is encrypted
agfs_client = svc._agfs_client
agfs_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 operation
try:
@@ -541,7 +537,7 @@ This is a test skill for verifying Vault encryption.
# Verify file is encrypted
agfs_client = svc._agfs_client
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")
# Test various operations
@@ -598,7 +594,7 @@ This is a test skill for verifying Vault encryption.
# Verify file is encrypted
agfs_client = svc._agfs_client
agfs_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.asyncio
diff --git a/tests/integration/test_volcengine_kms_encryption_integration.py b/tests/integration/test_volcengine_kms_encryption_integration.py
index 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_asyncio
from openviking import AsyncOpenViking
from openviking.crypto.encryptor import FileEncryptor
from openviking.crypto.providers import VolcengineKMSProvider
-from openviking.server.api_keys import APIKeyManager
+from openviking.server.api_keys import APIKeyManager, is_new_format_key
from openviking.service.core import OpenVikingService
from openviking_cli.session.user_id import UserIdentifier
from 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 path
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 {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 encrypted
agfs_client = svc._agfs_client
agfs_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 operation
try:
@@ -605,7 +601,7 @@ This is a test skill for verifying Volcengine KMS encryption.
# Verify file is encrypted
agfs_client = svc._agfs_client
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")
# Test various operations
@@ -662,7 +658,7 @@ This is a test skill for verifying Volcengine KMS encryption.
# Verify file is encrypted
agfs_client = svc._agfs_client
agfs_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.asyncio
diff --git a/tests/misc/test_config_validation.py b/tests/misc/test_config_validation.py
index 8ea30c318..5f50f1672 100644
--- a/tests/misc/test_config_validation.py
+++ b/tests/misc/test_config_validation.py
@@ -8,7 +8,12 @@ from pathlib import Path
import 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, S3Config
from openviking_cli.utils.config.embedding_config import EmbeddingConfig, EmbeddingModelConfig
from 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_pat
assert 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.py
new file mode 100644
index 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.py
index 07377b5ff..965baa8c9 100644
--- a/tests/server/test_admin_api.py
+++ b/tests/server/test_admin_api.py
@@ -11,6 +11,7 @@ from fastapi import FastAPI
from fastapi import Request as FastAPIRequest
from fastapi.responses import JSONResponse
+from openviking.pyagfs.exceptions import AGFSNotFoundError
from openviking.server.api_keys import APIKeyManager
from openviking.server.app import create_app
from 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 first
manager = trusted_admin_app.state.api_key_manager
await 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.py
index 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=True
diff --git a/tests/storage/test_viking_fs_tree.py b/tests/storage/test_viking_fs_tree.py
index 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.py
index 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 PersistentTaskStore
from 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 RagfsBindingConfig
from openviking_cli.session.user_id import UserIdentifier
+from openviking_cli.utils.config import AGFSConfig
pytestmark = 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.py
index 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.py
new file mode 100644
index 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