Contributing Guide

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• README_en.md
• SECURITY.md
• apps/desktop/src/ui/rule-library.js
• apps/desktop/src-tauri/src/prism_tests.rs

Zephyr is a modern, secure GUI for the Mihomo proxy core built with Tauri and Rust. This guide outlines the standard procedures for contributing code, adhering to technical standards, and maintaining the project's security posture.

The contribution process follows a standard GitHub fork-and-pull-request workflow. Contributors must ensure that all new functionality includes automated tests and passes the project's rigorous linting and security checks.

Contribution Workflow

Zephyr utilizes a structured workflow to manage changes and ensure code quality. You must follow these steps for any code submission:

1. Fork the Zephyr repository to your GitHub account.
2. Clone your fork to your local development environment.
3. Create a branch using a descriptive name (e.g., feature/your-feature-name).
4. Implement changes while following the project's coding and security standards.
5. Run local tests to verify that your changes do not introduce regressions.
6. Commit your changes using the Conventional Commits format.
7. Push the branch to your fork and Open a Pull Request (PR) against the main branch.

Sources: CONTRIBUTING.md:5-15

Pull Request Guidelines

Maintainers review every PR for correctness, test coverage, and security implications. Each PR should focus on a single feature or fix. You must provide a clear description of the changes and the rationale behind them.

Sources: CONTRIBUTING.md:17-27

The diagram shows the lifecycle of a contribution from forking to merging. Sources: CONTRIBUTING.md:5-20

Technical Standards

Zephyr enforces strict coding standards across its Rust backend and JavaScript frontend to maintain performance and safety.

Rust Backend

The backend uses rustfmt for formatting and Clippy for static analysis. The project enforces 170 deny rules across four tiers in Cargo.toml.

Tier	Focus Area	Example Denied Lints
1	Correctness & Security	unwrap_used, expect_used, undocumented_unsafe_blocks
2	Concurrency	await_holding_lock, future_not_send, rc_mutex
3	Memory Performance	redundant_clone, vec_init_then_push
4	CPU Performance	suboptimal_flops, float_cmp

Sources: CONTRIBUTING.md:31-43

JavaScript Frontend

The frontend uses ESLint with a flat configuration and Prettier for formatting. A critical custom lint rule, no-unsanitized, prevents unsafe assignments to innerHTML or outerHTML. Developers must use html, escapeHtml, or sanitizeHtml tagged templates for DOM manipulations.

Sources: CONTRIBUTING.md:47-51, apps/desktop/src/ui/rule-library.js:132-135

Testing Policy

All major new functionality must include automated tests. The project utilizes various testing frameworks across the stack.

Test Execution Commands

Environment	Tool	Command
Backend	Cargo	cargo test --workspace --exclude zephyr-core-ffi --release
Frontend	Vitest	pnpm --filter @zephyr/desktop test
Snapshots	Insta	INSTA_UPDATE=always cargo test --workspace --exclude zephyr-core-ffi --release

Sources: CONTRIBUTING.md:55-75

Testing Structures

• Rust Unit Tests: Located inline within source files using #[cfg(test)].
• Rust Integration Tests: Found in specific test files like apps/desktop/src-tauri/src/prism_tests.rs.
• Frontend Tests: Managed via Vitest with the happy-dom environment, stored in *.test.js files alongside source code.
• Security Tests: CI pipelines run cargo-deny for dependency audits and secret detection via Trufflehog.

Sources: CONTRIBUTING.md:68-78, SECURITY.md:144-150

Security and Vulnerability Reporting

Zephyr treats security as a core design principle rather than a feature. It implements 13 layers of defense-in-depth, including SSRF protection and encrypted subscription metadata.

Reporting Process

You must not open public issues for security vulnerabilities. Instead, use the GitHub Private Vulnerability Reporting (PVR) feature or email juwan.hwang@proton.me.

Sources: SECURITY.md:28-44

Vulnerability Severity Scale

Severity	Impact	Examples
Critical	RCE / Full Compromise	Prism sandbox escape, update signature bypass
High	Proxy/DNS Bypass	IP leakage, SSRF filter bypass, credential extraction
Medium	Tampering	DoS via remote input, insecure temp file handling
Low	Hardening	Minor UI anomalies with no direct exploitability

Sources: SECURITY.md:64-74

The sequence diagram illustrates the coordinated vulnerability disclosure (CVD) process. Sources: SECURITY.md:78-90

Project Architecture for Contributors

Zephyr is organized as a pnpm workspace containing native JavaScript and Rust modules.

• apps/desktop: The main Tauri application.
  • src/: Native JS frontend and styles.
  • src-tauri/: Rust backend and IPC integration.
• crates/core: Pure business logic in Rust.
• packages/shared: Code shared between different frontend modules.
• packages/tokens: Design token system using Style Dictionary.

Sources: README_en.md:284-297

Build System Requirements

To build Zephyr from source, you must install the following prerequisites:

• Rust: Version 1.96.0 or higher.
• Node.js: Version 20.18.1 or higher.
• pnpm: Version 9 or higher.

Sources: CONTRIBUTING.md:84-88

Build and Development Commands

• pnpm install: Install workspace dependencies.
• pnpm --filter @zephyr/desktop tauri dev: Run the application in development mode.
• pnpm --filter @zephyr/desktop tauri build: Generate a production build.

Sources: CONTRIBUTING.md:92-102

Zephyr prioritizes security, performance, and aesthetic quality. By adhering to these standards, you help maintain a secure and lightweight proxy client for the community.