Subscription Management
Relevant source files
The following files were used as context for generating this wiki page:
Subscription Management in Zephyr handles the downloading, parsing, sanitizing, and periodic updating of proxy configuration profiles from remote URLs or local files. The system implements a three-tier download strategy with integrated SSRF protection and metadata encryption to ensure secure configuration management for the underlying Mihomo engine.
Sources: apps/desktop/src-tauri/src/core/subscription.rs:1052-1057, FEATURES.md:6-10
Multi-Tier Download Strategy
The download system utilizes a prioritized three-tier strategy to retrieve subscription content while maintaining security boundaries. Each tier is subject to cumulative deadlines to ensure the application remains responsive.
- Tier 1: Direct Connection: Attempts to connect directly to the provider URL using DNS pinning to prevent DNS rebinding attacks.
- Tier 2: Mihomo Proxy: Retries the download through the Mihomo core's mixed-port proxy if the direct connection fails or is blocked.
- Tier 3: Global Mode Fallback: Temporarily switches the Mihomo core to "Global" mode and selects an active proxy node to bypass routing rules that might block the subscription provider.
Sources: apps/desktop/src-tauri/src/core/subscription.rs:1052-1057, FEATURES.md:6
Global Mode Fallback Flow
When Tier 3 is engaged, the system preserves the original state of the core using a ModeRestoreGuard. If the download is interrupted or the process crashes, a restore marker on disk ensures the core is returned to its previous mode and node selection upon restart.
The diagram represents the prioritized fallback logic and state preservation mechanism during subscription retrieval.
Sources: apps/desktop/src-tauri/src/core/subscription.rs:807-880, apps/desktop/src-tauri/src/core/subscription.rs:1052-1065
Security and Sanitization
Zephyr treats all incoming subscription data as untrusted. Before a configuration is saved to the profiles directory, it undergoes rigorous validation and sanitization.
- SSRF Protection: DNS resolution is validated against private IP ranges. Redirects to private addresses are blocked unless the initial host was explicitly private.
- YAML Sanitization: The system recursively removes dangerous YAML keys such as
scriptandscript-pathto prevent arbitrary code execution within the proxy core. - Metadata Encryption: Subscription URLs and usage info are encrypted using AES-256-GCM, with keys derived from hardware fingerprints (Machine-bound encryption).
- Short-ID Protection: Hex values in REALITY options are automatically quoted during parsing to prevent misinterpretation as scientific notation.
Sources: apps/desktop/src-tauri/src/core/subscription.rs:1145-1153, FEATURES.md:59-68
Configuration Metadata
Subscription metadata is managed in a metadata.json file, tracking provider information, update intervals, and traffic usage statistics.
| Field | Type | Description |
|---|---|---|
url | String | The remote URL used to retrieve the subscription. |
sub_info | String | Traffic info (upload, download, total, expire) parsed from headers. |
last_updated | u64 | Unix timestamp of the last successful download. |
auto_update_interval | u64 | Time in seconds between automated updates (0 to disable). |
user_agent | String | Custom User-Agent string for provider requests. |
Sources: apps/desktop/src-tauri/src/core/subscription.rs:567-580, apps/desktop/src/ui/settings/subscriptions.js:103-125
Automated Scheduling
The background scheduler manages periodic updates based on user-defined intervals. It resolves per-subscription User-Agent overrides and performs batch updates to minimize IPC overhead.
This sequence shows the interaction between the background scheduler, the secure backend, and the proxy core during automated updates.
Sources: apps/desktop/src/ui/settings/subscriptions.js:296-335, apps/desktop/src-tauri/src/core/subscription.rs:1255-1290
User Interface Integration
The frontend provides a management interface for CRUD operations on subscriptions and real-time monitoring of traffic quotas.
Subscription Actions
Users can perform the following actions through the UI:
- Import: Add via URL, file selection, or drag-and-drop.
- Update: Manually trigger a refresh for a single item or all subscriptions.
- Edit: Modify the display name, URL, or auto-update interval.
- Extract: Pull rule sets from a subscription into the local Rule Library.
- Reorder: Use drag-and-drop to change the priority/order of profiles.
Sources: apps/desktop/src/ui/settings/subscriptions.js:433-470, apps/desktop/src/ui/settings/subscriptions.js:630-675, FEATURES.md:9-12
Traffic Monitoring
The system parses the subscription-userinfo header to display usage bars.
// Example traffic info parsing logic
function parseSubInfo(subInfo) {
let upload = 0, download = 0, total = 0, expire = 0;
for (const p of subInfo.split(';')) {
const s = p.trim();
if (s.startsWith('upload=')) upload = parseInt(s.slice(7));
else if (s.startsWith('total=')) total = parseInt(s.slice(6));
}
return { used: upload + download, total };
}
Sources: apps/desktop/src/ui/console-home.js:630-645, apps/desktop/src/ui/settings/subscriptions.js:775-800
API Endpoints (IPC Commands)
| Command | Arguments | Description |
|---|---|---|
download_sub | name, url, userAgent, overwrite | Downloads a single subscription. |
download_sub_batch | items: Vec<BatchUpdateItem>, userAgent | Performs batch updates without per-item rate limits. |
update_config_url | name, newUrl | Updates the URL associated with a profile name. |
update_subscription_interval | name, interval | Sets the auto-update frequency in seconds. |
Sources: packages/shared/src/index.js:145-151, apps/desktop/src-tauri/src/core/subscription.rs:1225-1240
Subscription Management provides a secure bridge between untrusted remote providers and the local proxy core. By combining machine-bound encryption, strict YAML sanitization, and a robust three-tier download fallback system, it ensures that proxy configurations remain fresh, private, and safe from common network-based attack vectors.