Profile & Configuration Management
Relevant source files
The following files were used as context for generating this wiki page:
Zephyr manages proxy profiles and configurations through a multi-layered architecture that combines the Mihomo core, the Prism Engine, and a secure backend. The system handles YAML-based profile CRUD operations, subscription management, and declarative rule patches to provide a robust networking environment.
The system ensures security through machine-bound encryption for sensitive metadata and sanitizes configurations to prevent path traversal and recursive YAML attacks. Users interact with these configurations through a native JavaScript frontend that communicates with the Rust backend via a Tauri IPC bridge.
Architecture and Data Flow
Configuration management follows a structured flow where user inputs or subscription updates are processed by the backend, validated, and then applied to the running proxy core.
The diagram shows the lifecycle of a configuration from user input or remote subscription to its final application in the Mihomo Core.
Sources: README_en.md, FEATURES.md, apps/desktop/src/main.js
Profile Management
Zephyr provides a comprehensive suite for managing multi-profile YAML configurations. This includes creating, reading, editing, and deleting profiles.
Core Capabilities
- Multi-profile Support: Users create and switch between different YAML configurations.
- Persistence: The application persists window state, position, and the last used configuration across sessions.
- Validation: Before starting the core, the system runs
mihomo -t -fto validate the configuration and prevent crash-loops.
Sources: FEATURES.md:4-7, apps/desktop/src/main.js:203-210
Profile Security
The system implements several layers of security to protect configuration integrity:
- Encryption: Subscription metadata (URLs and traffic info) uses AES-256-GCM encryption bound to the hardware fingerprint.
- Sanitization: Zephyr recursively removes dangerous YAML keys, such as
scriptandscript-path, and prevents path traversal in providers. - Resource Limits: Profiles are limited by a
MAX_RESPONSE_SIZEto prevent memory exhaustion.
Sources: FEATURES.md:92-105, apps/desktop/src-tauri/src/prism/host.rs:188-193
Subscription Management
Subscriptions allow for automated retrieval of proxy node information from remote URLs or local files.
| Feature | Description |
|---|---|
| Import Formats | Supports URL, file, QR code, and drag-and-drop. |
| Decoding | Automatically handles Base64 decoding for subscription payloads. |
| Auto-Update | Background tokio scheduler updates subscriptions at configurable intervals (30 min – 24 h). |
| Download Tiers | Uses a 3-tier fallback: Direct → Mihomo Proxy → System Proxy. |
Sources: FEATURES.md:8-16, README_en.md:Quick Start
Subscription Workflow
The sequence diagram illustrates the secure subscription import process including SSRF protection.
Sources: FEATURES.md:94-96, apps/desktop/src-tauri/src/prism/host.rs:180-205
Prism Engine Integration
The Prism Engine enhances standard Mihomo configurations using declarative rule patches and smart selector logic.
Rule Library and DSL
The system manages a library of .prism.yaml files that support specific DSL operations:
$prepend/$append: Adds rules to the beginning or end of the list.$filter: Removes rules matching specific criteria.$override: Replaces existing configuration values.__when__: Conditional application based on environment (e.g., WiFi SSID).
Sources: FEATURES.md:58-62, apps/desktop/src-tauri/src/prism_tests.rs:360-375
Config Application Flow
When a configuration is applied, the ZephyrPrismHost bridges the engine to the app state.
The flow represents the synchronous HTTP PUT mechanism used to hot-reload configurations into the proxy core.
Sources: apps/desktop/src-tauri/src/prism/host.rs:136-160
Implementation Details
Filename Sanitization
To prevent path traversal and shell injection, the system strictly sanitizes filenames for profiles and rules.
// Example from apps/desktop/src-tauri/src/prism_tests.rs
#[test]
fn rejects_path_traversal_dotdot() {
let result = sanitize_filename("../../etc/passwd");
assert!(result.is_ok());
assert_eq!(result.unwrap(), "....etcpasswd");
}
Sources: apps/desktop/src-tauri/src/prism_tests.rs:107-113
Running Config Storage
The final merged configuration used by the core is stored in run_config.yaml within the application's core directory. The backend uses secure I/O (Unix 0600 / Windows DACL) to ensure only the application can access this file.
Sources: apps/desktop/src-tauri/src/prism/host.rs:132-140, FEATURES.md:108-112
Summary
Profile and Configuration Management in Zephyr prioritizes security and flexibility. By combining encrypted metadata storage, rigorous YAML sanitization, and the Prism Engine's declarative patching, the system provides a powerful yet safe method for managing complex networking rules. The integration of background schedulers for subscriptions and a synchronous hot-reload API ensures that the networking environment remains up-to-date with minimal user intervention.