Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(encryption): support inline local root key (#6678)
Jiahui Zhou3901724ac4e4
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex 08eeafb3d..e1d0f6847 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -2284,7 +2284,7 @@ At-rest encryption protects newly written files with account-specific keys throu| `provider` | str | Key provider: `"local"`, `"vault"`, or `"volcengine_kms"` | - || `api_key_hashing.enabled` | bool | File-provider only: whether to apply Argon2id one-way hashing to API key values (independent of file-level `enabled`); see [Encryption Guide](./08-encryption.md) | `false` |-### Local (File)+### LocalSuitable for development environments and single-node deployments:@@ -2303,6 +2303,11 @@ Suitable for development environments and single-node deployments:| Parameter | Type | Description | Default ||-----------|------|-------------|---------|| `local.key_file` | str | Root key file path | `~/.openviking/master.key` |+| `local.root_key` | str | Inline 32-byte root key encoded as exactly 64 hexadecimal characters | - |++Do not configure `local.key_file` and `local.root_key` together. If both are omitted,+`local.key_file` defaults to `~/.openviking/master.key`. See the [Encryption Guide](./08-encryption.md)+for inline-key handling and security requirements.### Vault (HashiCorp Vault)diff --git a/docs/en/guides/08-encryption.md b/docs/en/guides/08-encryption.mdindex 9f3a28ba1..c1ef340b0 100644--- a/docs/en/guides/08-encryption.md+++ b/docs/en/guides/08-encryption.md@@ -146,7 +146,7 @@ Enable Argon2id one-way hashing to stop storing recoverable API key values:| Provider | Use Case | Pros | Cons ||----------|----------|------|------|-| **Local** | Dev environments, single-node | Simple, no external services | Requires local file permissions and separate key backups |+| **Local** | Dev environments, single-node | Simple, no external services | Requires local secret permissions and separate key backups || **Vault** | Production, multi-cloud | Enterprise-grade KMS, version control | Requires deploying and maintaining Vault || **Volcengine KMS** | Volcengine cloud | Cloud-native KMS service | Volcengine-only |@@ -191,6 +191,35 @@ ov system crypto init-key -f ~/.openviking/master.key}```+### Inline Root Key++For simple, controlled deployments, the Local provider can read the same 32-byte root key+directly from `ov.conf` instead of a separate file:++```json+{+ "encryption": {+ "enabled": true,+ "provider": "local",+ "local": {+ "root_key": "<64-character hexadecimal root key>"+ }+ }+}+```++The value is 32 bytes encoded as exactly 64 hexadecimal characters. You can generate one with+`openssl rand -hex 32`, or reuse the contents of an existing `master.key` when moving between the+two Local configurations.++- Do not configure `root_key` and `key_file` together. If both are omitted, the Local provider+ continues to use `~/.openviking/master.key`.+- An inline key is never generated automatically. Losing or changing it makes existing encrypted+ data unreadable.+- Treat `ov.conf` as a key file: restrict it to the service user, back it up securely, and never+ commit it to version control.+- Prefer Vault or KMS when production deployments need centralized secret management.+---## Vault Mode Detailed Guidediff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex 082b15657..926720ad5 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -2199,7 +2199,7 @@ Redis 连接和命令超时通过 `cache.params.connect_timeout_ms` 和| `provider` | str | 密钥提供程序:`"local"`、`"vault"` 或 `"volcengine_kms"` | - || `api_key_hashing.enabled` | bool | 仅 File Provider:是否对 API key 字段启用 Argon2id 单向哈希(与文件级 `enabled` 独立控制),详见 [加密指南](./08-encryption.md) | `false` |-### Local(本地文件)+### Local适合开发环境和单节点部署:@@ -2218,6 +2218,10 @@ Redis 连接和命令超时通过 `cache.params.connect_timeout_ms` 和| 参数 | 类型 | 说明 | 默认值 ||------|------|------|--------|| `local.key_file` | str | 根密钥文件路径 | `~/.openviking/master.key` |+| `local.root_key` | str | 直接配置的 32 字节根密钥,必须编码为恰好 64 个十六进制字符 | - |++不要同时配置 `local.key_file` 和 `local.root_key`。如果两者都省略,`local.key_file` 默认使用+`~/.openviking/master.key`。内联密钥的管理和安全要求详见[加密指南](./08-encryption.md)。### Vault(HashiCorp Vault)diff --git a/docs/zh/guides/08-encryption.md b/docs/zh/guides/08-encryption.mdindex 6c47a83df..0ceadef03 100644--- a/docs/zh/guides/08-encryption.md+++ b/docs/zh/guides/08-encryption.md@@ -146,7 +146,7 @@ test()| 提供程序 | 适用场景 | 优点 | 缺点 ||---------|---------|------|------|-| **Local** | 开发环境、单节点部署 | 简单,无需外部服务 | 需要管理本地文件权限和独立密钥备份 |+| **Local** | 开发环境、单节点部署 | 简单,无需外部服务 | 需要管理本地密钥权限和独立密钥备份 || **Vault** | 生产环境、多云部署 | 企业级密钥管理,支持版本控制 | 需要部署和维护 Vault || **Volcengine KMS** | 火山引擎云部署 | 云原生密钥管理服务 | 仅限火山引擎环境 |@@ -191,6 +191,33 @@ ov system crypto init-key -f ~/.openviking/master.key}```+### 在配置中直接提供根密钥++对于简单、受控的部署,Local provider 可以直接从 `ov.conf` 读取同一个 32 字节根密钥,+不再使用单独的密钥文件:++```json+{+ "encryption": {+ "enabled": true,+ "provider": "local",+ "local": {+ "root_key": "<64 个十六进制字符的根密钥>"+ }+ }+}+```++配置值是 32 字节密钥的十六进制表示,因此必须恰好包含 64 个十六进制字符。可以使用+`openssl rand -hex 32` 生成,也可以在两种 Local 配置之间迁移时直接复用已有+`master.key` 的内容。++- 不要同时配置 `root_key` 和 `key_file`;如果两者都省略,Local provider 仍使用+ `~/.openviking/master.key`。+- 内联密钥不会自动生成;密钥丢失或改变后,已有加密数据将无法读取。+- 此时必须把 `ov.conf` 当作密钥文件管理:只允许服务用户读取、安全备份,并且禁止提交到版本控制。+- 生产环境需要集中式密钥管理时,仍建议使用 Vault 或 KMS。+---## Vault 模式详细指南diff --git a/openviking/crypto/config.py b/openviking/crypto/config.pyindex 1824c8345..04f3580ed 100644--- a/openviking/crypto/config.py+++ b/openviking/crypto/config.py@@ -12,7 +12,7 @@ from typing import Any, Dict, List, Optional, Tuplefrom openviking.crypto.encryptor import FileEncryptorfrom openviking.crypto.exceptions import ConfigError-from openviking.crypto.providers import create_root_key_provider+from openviking.crypto.providers import create_root_key_provider, decode_inline_root_keyfrom openviking_cli.utils.logger import get_loggerlogger = get_logger(__name__)@@ -60,8 +60,22 @@ def _validate_local_provider_config(config: Dict[str, Any]) -> List[str]:"""Validate Local Provider configuration."""errors = []local_config = config.get("local", {})- key_file_path = local_config.get("key_file", "~/.openviking/master.key")+ key_file_path = local_config.get("key_file")+ root_key = local_config.get("root_key")+ if key_file_path is not None and root_key is not None:+ errors.append(+ "encryption.local.root_key and encryption.local.key_file are mutually exclusive"+ )+ return errors+ if root_key is not None:+ try:+ decode_inline_root_key(root_key)+ except ConfigError as exc:+ errors.append(str(exc))+ return errors+ if key_file_path is None:+ key_file_path = "~/.openviking/master.key"if not key_file_path:errors.append("encryption.local.key_file is required")return errorsdiff --git a/openviking/crypto/providers.py b/openviking/crypto/providers.pyindex cbeb50c10..59e612876 100644--- a/openviking/crypto/providers.py+++ b/openviking/crypto/providers.py@@ -53,6 +53,20 @@ PROVIDER_VAULT = 0x02PROVIDER_VOLCENGINE = 0x03+def decode_inline_root_key(root_key: object) -> bytes:+ """Decode a 32-byte root key without exposing it in validation errors."""+ error = "encryption.local.root_key must be a 64-character hexadecimal string"+ if not isinstance(root_key, str) or len(root_key) != 64:+ raise ConfigError(error)+ try:+ decoded = bytes.fromhex(root_key)+ except ValueError as exc:+ raise ConfigError(error) from exc+ if len(decoded) != 32:+ raise ConfigError(error)+ return decoded++class RootKeyProvider(ABC):"""Root Key Provider abstract base class."""@@ -179,17 +193,20 @@ class BaseProvider(RootKeyProvider):class LocalFileProvider(BaseProvider):- """Local file Root Key Provider."""+ """Local Root Key Provider backed by a file or inline configuration."""- def __init__(self, key_file: str):+ def __init__(self, key_file: Optional[str] = None, root_key: Optional[str] = None):"""Initialize LocalFileProvider.Args:- key_file: Root Key file path+ key_file: Root Key file path.+ root_key: 32-byte Root Key encoded as 64 hexadecimal characters."""- self.key_file = Path(key_file).expanduser()- self._root_key: Optional[bytes] = None+ if (key_file is None) == (root_key is None):+ raise ConfigError("exactly one of key_file or root_key must be configured")+ self.key_file = Path(key_file).expanduser() if key_file is not None else None+ self._root_key = decode_inline_root_key(root_key) if root_key is not None else Noneasync def get_root_key(self) -> bytes:"""Get Root Key."""@@ -224,6 +241,7 @@ class LocalFileProvider(BaseProvider):async def _load_or_create_root_key(self) -> bytes:"""Load or create Root Key."""+ assert self.key_file is not Noneif self.key_file.exists():# Read existing keywith open(self.key_file, "r") as f:@@ -820,8 +838,17 @@ def create_root_key_provider("""if provider_type == "local":local_config = config.get("local", {})- key_file_path = local_config.get("key_file", "~/.openviking/master.key")+ key_file_path = local_config.get("key_file")+ root_key = local_config.get("root_key")+ if key_file_path is not None and root_key is not None:+ raise ConfigError(+ "encryption.local.root_key and encryption.local.key_file are mutually exclusive"+ )+ if root_key is not None:+ return LocalFileProvider(root_key=root_key)+ if key_file_path is None:+ key_file_path = "~/.openviking/master.key"if not key_file_path:raise ConfigError("encryption.local.key_file is required")return LocalFileProvider(key_file_path)diff --git a/openviking_cli/utils/config/encryption_config.py b/openviking_cli/utils/config/encryption_config.pyindex 377468df5..d7fb244fc 100644--- a/openviking_cli/utils/config/encryption_config.py+++ b/openviking_cli/utils/config/encryption_config.py@@ -2,19 +2,31 @@# SPDX-License-Identifier: AGPL-3.0from typing import Any, Dict, Optional-from pydantic import BaseModel, Field+from pydantic import BaseModel, Field, model_validatorclass LocalEncryptionProviderConfig(BaseModel):- """Local file encryption provider configuration.+ """Local encryption provider configuration.- Uses a local file to store the Root Key.+ Reads the Root Key from a local file or directly from configuration.Suitable for single-user or development environments."""- key_file: str = Field(- default="~/.openviking/master.key", description="Path to local root key file"+ key_file: Optional[str] = Field(+ default="~/.openviking/master.key",+ description="Path to local root key file",)+ root_key: Optional[str] = Field(+ default=None,+ repr=False,+ description="32-byte root key encoded as 64 hexadecimal characters",+ )++ @model_validator(mode="after")+ def use_inline_key_without_implicit_file(self) -> "LocalEncryptionProviderConfig":+ if self.root_key is not None and "key_file" not in self.model_fields_set:+ self.key_file = None+ return selfclass VaultEncryptionProviderConfig(BaseModel):diff --git a/tests/unit/crypto/test_config.py b/tests/unit/crypto/test_config.pyindex b77660219..36a9dc006 100644--- a/tests/unit/crypto/test_config.py+++ b/tests/unit/crypto/test_config.py@@ -6,7 +6,11 @@ Unit tests for crypto configuration.import pytest-from openviking.crypto.config import bootstrap_encryption+from openviking.crypto.config import bootstrap_encryption, validate_encryption_config+from openviking_cli.utils.config.encryption_config import (+ EncryptionConfig,+ LocalEncryptionProviderConfig,+)@pytest.mark.asyncio@@ -43,6 +47,78 @@ async def test_bootstrap_encryption_local_file(tmp_path):assert encryptor is not None+async def test_bootstrap_encryption_inline_local_root_key(tmp_path, monkeypatch):+ """The local provider can use the existing 32-byte key directly from config."""+ monkeypatch.setenv("HOME", str(tmp_path))+ root_key = bytes(range(32))+ encryption = EncryptionConfig(+ enabled=True,+ provider="local",+ local={"root_key": root_key.hex()},+ )++ encryptor = await bootstrap_encryption({"encryption": encryption.model_dump()})++ assert encryptor is not None+ assert await encryptor.provider.get_root_key() == root_key+++def test_local_root_key_and_key_file_are_mutually_exclusive(tmp_path):+ config = {+ "encryption": {+ "enabled": True,+ "provider": "local",+ "local": {+ "key_file": str(tmp_path / "master.key"),+ "root_key": "00" * 32,+ },+ }+ }++ is_valid, errors = validate_encryption_config(config)++ assert not is_valid+ assert errors == [+ "encryption.local.root_key and encryption.local.key_file are mutually exclusive"+ ]++[email protected]("root_key", ["00" * 31, "zz" * 32, 123])+def test_local_root_key_must_be_32_byte_hex(root_key):+ config = {+ "encryption": {+ "enabled": True,+ "provider": "local",+ "local": {"root_key": root_key},+ }+ }++ is_valid, errors = validate_encryption_config(config)++ assert not is_valid+ assert errors == [+ "encryption.local.root_key must be a 64-character hexadecimal string"+ ]+ assert str(root_key) not in errors[0]+++def test_local_encryption_config_hides_inline_root_key_from_repr():+ root_key = "ab" * 32++ config = LocalEncryptionProviderConfig(root_key=root_key)++ assert config.root_key == root_key+ assert config.key_file is None+ assert root_key not in repr(config)+++def test_local_encryption_config_preserves_default_key_file():+ config = LocalEncryptionProviderConfig()++ assert config.key_file == "~/.openviking/master.key"++@pytest.mark.asyncioasync def test_bootstrap_encryption_invalid_provider():"""Test bootstrap_encryption with invalid provider."""diff --git a/tests/unit/crypto/test_local_provider.py b/tests/unit/crypto/test_local_provider.pyindex d599e538c..fcbca091c 100644--- a/tests/unit/crypto/test_local_provider.py+++ b/tests/unit/crypto/test_local_provider.py@@ -9,6 +9,7 @@ import tempfileimport pytest+from openviking.crypto.encryptor import PROVIDER_LOCAL, FileEncryptorfrom openviking.crypto.providers import LocalFileProvider@@ -68,3 +69,30 @@ async def test_local_file_provider_different_accounts(local_file_provider):decrypted2 = await local_file_provider.decrypt_file_key(encrypted_key2, iv2, account2)assert decrypted2 == plaintext_key+++async def test_local_provider_accepts_inline_root_key_with_local_envelope_type():+ root_key = bytes(range(32))++ provider = LocalFileProvider(root_key=root_key.hex())++ assert await provider.get_root_key() == root_key+ assert FileEncryptor(provider).provider_type == PROVIDER_LOCAL+++async def test_inline_and_file_local_providers_are_ciphertext_compatible(tmp_path):+ root_key = bytes(range(32))+ key_file = tmp_path / "master.key"+ key_file.write_text(root_key.hex())+ file_encryptor = FileEncryptor(LocalFileProvider(key_file=str(key_file)))+ inline_encryptor = FileEncryptor(LocalFileProvider(root_key=root_key.hex()))+ account_id = "test_account"+ plaintext = b"compatible local provider ciphertext"++ file_ciphertext = await file_encryptor.encrypt(account_id, plaintext)+ inline_ciphertext = await inline_encryptor.encrypt(account_id, plaintext)++ assert await inline_encryptor.decrypt(account_id, file_ciphertext) == plaintext+ assert await file_encryptor.decrypt(account_id, inline_ciphertext) == plaintext