diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml index f91adb8..4dd2bf5 100644 --- a/.github/FUNDING.yml +++ b/.github/FUNDING.yml @@ -1,3 +1,5 @@ -github: Anof-Cyber -custom: +github: + - InterceptSuite + - Anof-Cyber +custom: - https://www.buymeacoffee.com/AnoF \ No newline at end of file diff --git a/.github/workflows/build-mac.yml b/.github/workflows/build-mac.yml index fa13ee7..1b854af 100644 --- a/.github/workflows/build-mac.yml +++ b/.github/workflows/build-mac.yml @@ -22,19 +22,32 @@ jobs: with: xcode-version: latest-stable - - name: Build ProxyBridge + - name: Create xcconfig files run: | cd MacOS/ProxyBridge - chmod +x build.sh - ./build.sh - env: - SIGN_APP: "" - SIGN_PKG: "" - NOTARIZE: "" + cp proxybridge-app.xcconfig Signing-Config-app.xcconfig + cp proxybridge-ext.xcconfig Signing-Config-ext.xcconfig + sed -i '' 's/DEVELOPMENT_TEAM = L.*/DEVELOPMENT_TEAM = /' Signing-Config-app.xcconfig + sed -i '' 's/DEVELOPMENT_TEAM = L.*/DEVELOPMENT_TEAM = /' Signing-Config-ext.xcconfig - - name: Upload PKG artifact - uses: actions/upload-artifact@v4 - with: - name: ProxyBridge-macOS - path: MacOS/ProxyBridge/output/ProxyBridge-Installer.pkg - retention-days: 30 + - name: Build Universal Binary + run: | + cd MacOS/ProxyBridge + xcodebuild \ + -project ProxyBridge.xcodeproj \ + -scheme ProxyBridge \ + -configuration Release \ + -derivedDataPath build/DerivedData \ + ARCHS="arm64 x86_64" \ + ONLY_ACTIVE_ARCH=NO \ + CODE_SIGN_IDENTITY="-" \ + CODE_SIGNING_REQUIRED=NO \ + CODE_SIGNING_ALLOWED=NO \ + clean build + + - name: Verify Build + run: | + cd MacOS/ProxyBridge + ls -la build/DerivedData/Build/Products/Release/ + file build/DerivedData/Build/Products/Release/ProxyBridge.app/Contents/MacOS/ProxyBridge + lipo -archs build/DerivedData/Build/Products/Release/ProxyBridge.app/Contents/MacOS/ProxyBridge \ No newline at end of file diff --git a/.github/workflows/build.yml b/.github/workflows/build-windows.yml similarity index 72% rename from .github/workflows/build.yml rename to .github/workflows/build-windows.yml index ba85fb6..06b9872 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build-windows.yml @@ -1,10 +1,10 @@ -name: Build ProxyBridge +name: Build Windows on: push: - branches: [ main ] + branches: [ main, dev ] pull_request: - branches: [ main ] + branches: [ main, dev ] workflow_dispatch: jobs: @@ -18,7 +18,7 @@ jobs: - name: Setup .NET uses: actions/setup-dotnet@v4 with: - dotnet-version: '9.0.x' + dotnet-version: '10.0.x' - name: Setup MSYS2 (for GCC) uses: msys2/setup-msys2@v2 @@ -38,6 +38,16 @@ jobs: choco install nsis -y shell: pwsh + - name: Install NSIS EnVar plugin + run: | + $nsisPluginDir = "C:\Program Files (x86)\NSIS\Plugins\x86-unicode" + $url = "https://nsis.sourceforge.io/mediawiki/images/7/7f/EnVar_plugin.zip" + Invoke-WebRequest -Uri $url -OutFile "EnVar.zip" + Expand-Archive -Path "EnVar.zip" -DestinationPath "EnVar" + Copy-Item "EnVar\Plugins\x86-unicode\EnVar.dll" -Destination $nsisPluginDir -Force + Write-Host "EnVar plugin installed successfully" + shell: pwsh + - name: Download WinDivert run: | $url = "https://github.com/basil00/Divert/releases/download/v2.2.2/WinDivert-2.2.2-A.zip" @@ -57,7 +67,9 @@ jobs: shell: pwsh - name: Build project - run: .\Windows\compile.ps1 -NoSign -Compiler gcc + run: | + cd Windows + .\compile.ps1 -NoSign -Compiler gcc shell: pwsh - name: Upload artifacts diff --git a/.github/workflows/release-windows.yml b/.github/workflows/release-windows.yml new file mode 100644 index 0000000..f3b1dfc --- /dev/null +++ b/.github/workflows/release-windows.yml @@ -0,0 +1,53 @@ +name: Release ProxyBridge Windows + +on: + release: + types: [created] + +jobs: + build-and-release: + runs-on: self-hosted + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup .NET + uses: actions/setup-dotnet@v4 + with: + dotnet-version: '9.0.x' + + - name: Verify WinDivert installation + run: | + if (Test-Path "C:\WinDivert-2.2.2-A") { + Write-Host "WinDivert found at C:\WinDivert-2.2.2-A" + } else { + Write-Error "WinDivert not found. Please install WinDivert 2.2.2-A at C:\WinDivert-2.2.2-A" + exit 1 + } + shell: pwsh + + - name: Build and sign project + run: .\Windows\compile.ps1 + shell: pwsh + + - name: List built files + run: | + Write-Host "`nBuild artifacts:" + Get-ChildItem Windows/output -Recurse | ForEach-Object { + $size = [math]::Round($_.Length/1MB, 2) + Write-Host " $($_.Name) - $size MB" + } + shell: pwsh + + - name: Upload installer to release + uses: softprops/action-gh-release@v1 + with: + files: Windows/output/ProxyBridge-Setup-*.exe + + - name: Upload build artifacts + uses: actions/upload-artifact@v4 + with: + name: ProxyBridge-Release-${{ github.event.release.tag_name }} + path: Windows/output/ + retention-days: 90 diff --git a/.gitignore b/.gitignore index f5bc961..bbf80e0 100644 --- a/.gitignore +++ b/.gitignore @@ -20,6 +20,12 @@ Windows/output/ProxyBridge_CLI.pdb MacOS/ProxyBridge/.env MacOS/ProxyBridge/output/ MacOS/ProxyBridge/build/ +MacOS/ProxyBridge/provision/** + +# Signing configuration files (sensitive) +MacOS/ProxyBridge/Signing-App.xcconfig +MacOS/ProxyBridge/Signing-Extension.xcconfig +MacOS/ProxyBridge/Signing-Config.xcconfig # Xcode xcuserdata/ @@ -81,4 +87,11 @@ Temporary Items MacOS/ProxyBridge/build/ MacOS/ProxyBridge/output/ -Linux/** +# Linux/** +MacOS/ProxyBridge/Signing-Config.xcconfig +MacOS/ProxyBridge/Signing-Config-app.xcconfig +MacOS/ProxyBridge/Signing-Config-ext.xcconfig +Linux/output/** +Linux/build/** +MacOS/ProxyBridge/config/Signing-Config-ext.xcconfig +MacOS/ProxyBridge/config/Signing-Config-app.xcconfig diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..8d8008e --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,131 @@ +# Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our community include: + +* **Being respectful and inclusive** of differing opinions, viewpoints, and experiences +* **Giving and gracefully accepting constructive feedback** +* **Accepting responsibility** and apologizing to those affected by our mistakes, and learning from the experience +* **Focusing on what is best** not just for us as individuals, but for the overall community +* **Showing empathy** towards other community members +* **Using welcoming and inclusive language** +* **Being patient** with new contributors and questions + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, without their explicit permission +* Spam, promotional content, or excessive self-promotion +* Disruptive behavior that interferes with constructive discussion +* Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement Responsibilities + +Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, including: + +- GitHub repository (issues, pull requests, discussions) +- Project communication channels +- Official project social media accounts +- Project events and meetups + +This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + +## Reporting Violations + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project team at: + +- **GitHub Issues** (for public, non-sensitive violations) +- **Email:** conduct@interceptsuite.com (for private reports) +- **GitHub Security Advisories** (for security-related concerns) + +All complaints will be reviewed and investigated promptly and fairly. + +All project maintainers are obligated to respect the privacy and security of the reporter of any incident. + +## Enforcement Guidelines + +Project maintainers will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact:** Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. + +**Consequence:** A private, written warning from project maintainers, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact:** A violation through a single incident or series of actions. + +**Consequence:** A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. + +### 3. Temporary Ban + +**Community Impact:** A serious violation of community standards, including sustained inappropriate behavior. + +**Consequence:** A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact:** Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. + +**Consequence:** A permanent ban from any sort of public interaction within the community. + +## Technical Conduct + +In addition to general community standards, we expect technical contributions to adhere to: + +### Code Quality +- Follow the coding standards outlined in [CONTRIBUTING.md](CONTRIBUTING.md) +- Write clear, maintainable code with appropriate comments +- Test your changes thoroughly before submitting + +### Security +- Report security vulnerabilities privately (see [SECURITY.md](SECURITY.md)) +- Do not publicly disclose security issues before they are addressed +- Do not include malicious code or backdoors + +### Intellectual Property +- Respect software licenses and copyright +- Do not submit copyrighted code without proper attribution +- Ensure you have the right to contribute the code you submit + +### Pull Requests and Issues +- Create GitHub issues before submitting PRs for new features or bug fixes +- Provide clear descriptions and context +- Be responsive to feedback and questions +- Respect maintainers' decisions on feature inclusion + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html). + +Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). + +For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). + +## Contact + +For questions about this Code of Conduct, please: +- Open a discussion in [GitHub Discussions](https://github.com/InterceptSuite/ProxyBridge/discussions) +- Contact the project maintainers via [GitHub Issues](https://github.com/InterceptSuite/ProxyBridge/issues) + +--- + +**Last Updated:** January 2026 + +Thank you for helping make ProxyBridge a welcoming and inclusive community! šŸ¤ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b6d0f16 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,588 @@ +# Contributing to ProxyBridge + +Thank you for your interest in contributing to ProxyBridge! We welcome contributions from the community to help make this project better. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [How Can I Contribute?](#how-can-i-contribute) +- [Development Setup](#development-setup) +- [Pull Request Process](#pull-request-process) +- [Coding Standards](#coding-standards) +- [Reporting Bugs](#reporting-bugs) +- [Suggesting Features](#suggesting-features) + +## Code of Conduct + +This project and everyone participating in it is governed by our commitment to fostering an open and welcoming environment. We pledge to make participation in our project a harassment-free experience for everyone. + +### Our Standards + +- Be respectful and inclusive +- Accept constructive criticism gracefully +- Focus on what is best for the community +- Show empathy towards other community members + +## How Can I Contribute? + +### Reporting Bugs + +Before creating bug reports, please check existing issues to avoid duplicates. When creating a bug report, include: + +- **Clear title and description** +- **Steps to reproduce** the issue +- **Expected behavior** vs **actual behavior** +- **Screenshots** if applicable +- **Environment details**: + - OS version (Windows 10/11, macOS version) + - ProxyBridge version + - Proxy server type (SOCKS5/HTTP) + +### Suggesting Features + +Feature suggestions are welcome! Please provide: + +- **Clear use case** - explain the problem you're trying to solve +- **Proposed solution** - describe how the feature would work +- **Alternatives considered** - what other solutions did you think about? +- **Additional context** - mockups, examples, etc. + +### Pull Requests + +**IMPORTANT: Before Creating a Pull Request** + +1. **Create a GitHub Issue First** + - If you want to fix a bug or add a new feature, **create a GitHub issue first** + - This allows us to track and confirm whether: + - The feature is already implemented in our development branch + - We plan to include that feature (some features may not align with project goals) + - Your pull request will be accepted before you invest time coding + - If a GitHub issue already exists for the bug/feature you want to work on: + - Comment on the existing issue mentioning you plan to fix it + - **Do NOT create a duplicate issue** + +2. **Fork the `dev` Branch** + - **Always fork and create pull requests against the `dev` branch** + - **NEVER create pull requests against the `master` branch** + - The `master` branch is only updated with new releases + - All development work happens in the `dev` branch + - Pull requests to `master` will be **automatically rejected** + +3. **macOS Code Changes - Apple Developer Account Required** + - If you are making changes to macOS code, you **MUST**: + - Have a valid Apple Developer account ($99/year) + - Have tested your code changes and verified they work as expected + - Have proper code signing configured (see Apple Signing section below) + - **Pull requests with untested macOS code will NOT be merged** + - If you don't have an Apple Developer account and cannot test your changes, your PR will be rejected + +**Standard Pull Request Process:** + +1. Fork the repository (`dev` branch) +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Make your changes +4. Test thoroughly +5. Commit with clear messages (`git commit -m 'Add amazing feature'`) +6. Push to your fork (`git push origin feature/amazing-feature`) +7. Open a Pull Request to the `dev` branch + +## Development Setup + +### Windows + +**Prerequisites:** +- Visual Studio 2022 or later (with C++ tools) +- .NET 10.0 SDK +- PowerShell 5.1 or later +- Git +- **WinDivert 2.2.2-A** - Download from: https://www.reqrypt.org/windivert.html +- **NSIS** (optional, for building installer) - Download from: https://nsis.sourceforge.io/ + - **EnVar Plugin** (required for NSIS) - Download from: https://nsis.sourceforge.io/EnVar_plug-in + - Install EnVar plugin to: `C:\Program Files (x86)\NSIS\Plugins\` + - The installer uses EnVar to add ProxyBridge to system PATH + +**WinDivert Setup:** +1. Download WinDivert 2.2.2-A from the official website +2. Extract to `C:\WinDivert-2.2.2-A\` (default path used by compile script) +3. Or extract to a different location and update the path in `compile.ps1`: + ```powershell + $WinDivertPath = "C:\Your\Custom\Path\WinDivert-2.2.2-A" + ``` + +**Required WinDivert Files:** +- `WinDivert-2.2.2-A\include\windivert.h` (header file) +- `WinDivert-2.2.2-A\x64\WinDivert.lib` (import library) +- `WinDivert-2.2.2-A\x64\WinDivert.dll` (runtime library) +- `WinDivert-2.2.2-A\x64\WinDivert64.sys` (kernel driver) +- `WinDivert-2.2.2-A\x64\WinDivert32.sys` (32-bit driver) + +**Setup:** +```powershell +# Clone the repository (dev branch) +git clone -b dev https://github.com/InterceptSuite/ProxyBridge.git +cd ProxyBridge/Windows + +# Verify WinDivert is installed +Test-Path C:\WinDivert-2.2.2-A\include\windivert.h + +# Build the project (auto-detects MSVC or GCC) +.\compile.ps1 + +# Or specify compiler explicitly +.\compile.ps1 -Compiler msvc # Recommended +.\compile.ps1 -Compiler gcc # Use MinGW-w64 + +# Build without code signing +.\compile.ps1 -NoSign +``` + +**What compile.ps1 Does:** +1. Compiles `ProxyBridgeCore.dll` from C source code (using MSVC or GCC) +2. Copies WinDivert runtime files (`WinDivert.dll`, `WinDivert64.sys`, `WinDivert32.sys`) +3. Publishes GUI app (`ProxyBridge.exe`) with .NET single-file deployment +4. Publishes CLI app (`ProxyBridge_CLI.exe`) as single executable +5. Optionally signs all binaries (requires code signing certificate) +6. Builds NSIS installer (`ProxyBridge-Setup-3.1.0.exe`) if NSIS is installed + +**Output:** +All compiled files are placed in `Windows/output/` directory: +- `ProxyBridgeCore.dll` - Native C library +- `ProxyBridge.exe` - GUI application +- `ProxyBridge_CLI.exe` - CLI application +- `WinDivert.dll`, `WinDivert64.sys` - WinDivert files +- `ProxyBridge-Setup-3.1.0.exe` - Installer (if NSIS installed) +- Additional .NET runtime DLLs + +**Project Structure:** +- `Windows/src/` - C library core (ProxyBridge.c, ProxyBridge.h) + - `ProxyBridge.c` - Main packet interception logic + - Uses WinDivert for kernel-level packet capture +- `Windows/gui/` - Avalonia GUI (.NET 10.0) + - GUI application using Avalonia UI framework +- `Windows/cli/` - Command-line interface (.NET 10.0) + - CLI application for headless operation +- `Windows/installer/` - NSIS installer script + - `ProxyBridge.nsi` - Installer configuration +- `Windows/compile.ps1` - Build script +- `Windows/output/` - Compiled binaries (created by compile.ps1) + +### macOS + +**Prerequisites:** +- Xcode 15.0 or later +- macOS 13.0 (Ventura) or later +- Swift 5.9+ +- Git +- **Valid Apple Developer Account** (required for code signing) +- **Provisioning Profiles** installed on your system + +**Apple Developer Account & Code Signing:** + +macOS development requires a valid Apple Developer account with proper signing configuration: + +1. **Apple Developer Account:** + - Sign up at: https://developer.apple.com/programs/ + - Cost: $99/year (required for System Extension development) + - You need this to create Provisioning Profiles and sign the app + +2. **Create Provisioning Profiles:** + - Log in to Apple Developer Portal: https://developer.apple.com/account + - Create two Provisioning Profiles: + - **ProxyBridge Prod** - for the main GUI app + - **ProxyBridge Extension Prod** - for the Network Extension + - Download and install both profiles on your system (double-click to install) + +3. **Configure Code Signing:** + + The project uses configuration files to manage signing credentials securely. + + **Step 1: Create config folder** + ```bash + cd MacOS/ProxyBridge + mkdir config + ``` + + **Step 2: Copy template config files** + ```bash + # Copy template files from project root to config folder + cp proxybridge-app.xcconfig config/Signing-Config-app.xcconfig + cp proxybridge-ext.xcconfig config/Signing-Config-ext.xcconfig + ``` + + **Step 3: Edit config files with YOUR credentials** + + Edit `config/Signing-Config-app.xcconfig`: + ```plaintext + // MARK: - Team Configuration + DEVELOPMENT_TEAM = YOUR_TEAM_ID // Replace with your Team ID (e.g., L4HJT32Z59) + + // MARK: - Main App Signing (ProxyBridge) + CODE_SIGN_STYLE = Manual + CODE_SIGN_IDENTITY = Developer ID Application + CODE_SIGN_ENTITLEMENTS = ProxyBridge/ProxyBridgeRelease.entitlements + PRODUCT_BUNDLE_IDENTIFIER = com.interceptsuite.ProxyBridge + PRODUCT_MODULE_NAME = ProxyBridge + PRODUCT_NAME = ProxyBridge + PROVISIONING_PROFILE_SPECIFIER = ProxyBridge Prod // Your provisioning profile name + + // MARK: - Additional Signing Settings + CODE_SIGN_INJECT_BASE_ENTITLEMENTS = NO + ENABLE_HARDENED_RUNTIME = YES + ``` + + Edit `config/Signing-Config-ext.xcconfig`: + ```plaintext + // MARK: - Team Configuration + DEVELOPMENT_TEAM = YOUR_TEAM_ID // Replace with your Team ID + + // MARK: - Extension Signing + CODE_SIGN_STYLE = Manual + CODE_SIGN_IDENTITY = Developer ID Application + CODE_SIGN_ENTITLEMENTS = extension/extensionRelease.entitlements + PRODUCT_BUNDLE_IDENTIFIER = com.interceptsuite.ProxyBridge.extension + PRODUCT_MODULE_NAME = com_interceptsuite_ProxyBridge_extension + PROVISIONING_PROFILE_SPECIFIER = ProxyBridge Extension Prod // Your extension profile name + + // MARK: - Additional Signing Settings + CODE_SIGN_INJECT_BASE_ENTITLEMENTS = NO + ENABLE_HARDENED_RUNTIME = YES + ``` + + **How to find your DEVELOPMENT_TEAM ID:** + - Open Xcode ā†’ Settings ā†’ Accounts + - Select your Apple ID ā†’ Click "Manage Certificates" + - Your Team ID is shown next to your team name + + **Note:** The `config/` folder is in `.gitignore` to keep your credentials private. + +**Setup:** +```bash +# Clone the repository (dev branch) +git clone -b dev https://github.com/InterceptSuite/ProxyBridge.git +cd ProxyBridge/MacOS/ProxyBridge + +# Edit signing configuration files with your Apple Developer details +# proxybridge-app.xcconfig - for main app +# proxybridge-ext.xcconfig - for network extension + +# Open in Xcode and configure signing (see steps above) +open ProxyBridge.xcodeproj +``` + +**Building the Application:** + +**āš ļø IMPORTANT: Network Extension will NOT work with Debug builds!** + +You **MUST** create a **Release build** for the Network Extension to function properly. + +**Step-by-Step Build Process:** + +1. **Configure Signing** (see "Apply Configuration Files in Xcode" above) + +2. **Create Archive (Release Build):** + ``` + In Xcode: + - Select "ProxyBridge" scheme + - Go to: Product ā†’ Archive + - Wait for archive to complete + ``` + +3. **Export the App:** + ``` + After archive completes: + - Xcode Organizer window will open automatically + - Select your archive + - Click "Distribute App" + - Choose "Developer ID" (for distribution outside App Store) + - Select "Export" + - Choose export location: MacOS/ProxyBridge/output/ + - Click "Export" + ``` + + This will create a **signed and notarized** `ProxyBridge.app` in the output folder. + +4. **Create PKG Installer (Optional):** + ```bash + # The build.sh script creates a PKG installer from the .app + # It does NOT build the .app - you must export it from Xcode first + + cd MacOS/ProxyBridge + + # Verify ProxyBridge.app exists in output/ + ls -la output/ProxyBridge.app + + # Create PKG installer + ./build.sh + ``` + + **What build.sh does:** + - Checks for `output/ProxyBridge.app` (exits if not found) + - Creates PKG installer: `output/ProxyBridge-v3.1-Universal-Installer.pkg` + - Optionally signs and notarizes the PKG (requires .env file with credentials) + +**Output:** +- `MacOS/ProxyBridge/output/ProxyBridge.app` - Release build (from Xcode Archive) +- `MacOS/ProxyBridge/output/ProxyBridge-v3.1-Universal-Installer.pkg` - PKG installer (from build.sh) + +**Project Structure:** +- `MacOS/ProxyBridge/ProxyBridge/` - SwiftUI main app +- `MacOS/ProxyBridge/extension/` - Network Extension provider +- `MacOS/ProxyBridge/config/` - Your signing configuration (NOT in git) +- `MacOS/ProxyBridge/build.sh` - PKG installer creation script +- `MacOS/ProxyBridge/output/` - Exported .app and PKG installer +- `proxybridge-app.xcconfig` - Template config (in project root) +- `proxybridge-ext.xcconfig` - Template config (in project root) + +## Pull Request Process + +1. **Update documentation** - if your changes affect user-facing features +2. **Add tests** - for new functionality when applicable +3. **Follow coding standards** - see below +4. **Update CHANGELOG** - add a note about your changes +5. **One feature per PR** - keep pull requests focused +6. **Sign your commits** - use `git commit -s` + +### PR Checklist + +- [ ] Code builds without errors +- [ ] All tests pass +- [ ] Documentation updated +- [ ] No merge conflicts +- [ ] Commit messages are clear +- [ ] Code follows project style + +## Coding Standards + +All code submissions must follow these standards and optimization principles. + +### AI-Generated Code + +We **accept and welcome** code written with AI assistance (such as Claude, GitHub Copilot, or other AI coding tools), provided it meets our quality and optimization standards. + +**Requirements for AI-Generated Code:** + +1. **Code Quality Standards** + - Code must be well-written, optimized, and follow project coding standards + - Follow the same review process as manually written code + - Must be thoroughly tested and verified before submission + +2. **Optimization is Critical** + - We take code optimization **very seriously** + - All code must be optimized for performance and clarity + - Contributors are responsible for understanding and optimizing AI-generated code + +3. **Contributor Responsibility** + - **Understand what the code does** - Don't blindly submit AI-generated code + - **Review and optimize** - If code seems verbose or inefficient, refactor it + - **Question verbosity** - If you feel the code is too large or can be written better, optimize it + - **Benchmark when needed** - For performance-critical code, verify optimization claims + +**Our Two Optimization Priorities:** + +1. **Performance First** + - Code must be optimized for best performance + - Choose algorithms and data structures wisely + - Minimize memory allocations, CPU cycles, and I/O operations + - Profile performance-critical sections + +2. **Simplicity and Brevity** + - Prefer clear, concise code over verbose implementations + - **If 10 lines can do what 20-30 lines do, use 10 lines** + - Even without performance difference, we prefer shorter, clearer code + - Avoid unnecessary abstractions, boilerplate, or redundant code + - Write code that is easy to read, understand, and maintain + +**Examples:** + +āœ… **Good - Optimized and concise:** +```c +// Fast hash lookup, minimal code +if (connection_table[hash] && connection_table[hash]->port == port) { + return connection_table[hash]; +} +``` + +āŒ **Bad - Verbose, unnecessary:** +```c +// Same functionality but unnecessarily verbose +ConnectionInfo* info = connection_table[hash]; +if (info != NULL) { + if (info->port == port) { + return info; + } +} +return NULL; +``` + +**Before Submitting AI-Generated Code:** + +- [ ] I understand what this code does and how it works +- [ ] I have reviewed it for optimization opportunities +- [ ] I have removed unnecessary code, variables, or abstractions +- [ ] I have verified it follows project coding standards +- [ ] I have tested it thoroughly +- [ ] Performance-critical code has been profiled/benchmarked +- [ ] Code is as simple and concise as possible while remaining clear + +**Remember:** Using AI tools is encouraged, but you are responsible for the quality and optimization of the code you submit. AI-generated code that is verbose, inefficient, or poorly optimized will be rejected. + +### C/C++ (Windows Core) + +```c +// Use clear, descriptive names +static bool check_proxy_rules(const char *process, uint32_t dest_ip, + uint16_t dest_port, uint8_t proto) +{ + // Comments for complex logic + if (!process || !dest_ip) return false; + + // Use consistent formatting + for (int i = 0; i < rule_count; i++) { + if (match_rule(&rules[i], process, dest_ip, dest_port, proto)) { + return rules[i].action; + } + } + + return ACTION_DIRECT; +} +``` + +**Standards:** +- Use 4 spaces for indentation (no tabs) +- Maximum line length: 100 characters +- Always use braces for if/while/for blocks +- Declare variables close to usage +- Check for NULL/error conditions +- Free allocated memory +- Use meaningful variable names + +### C# (Windows GUI/CLI) + +```csharp +// Follow .NET naming conventions +public class ProxySettingsViewModel : ViewModelBase +{ + private string _proxyHost = "127.0.0.1"; + + // Properties use PascalCase + public string ProxyHost + { + get => _proxyHost; + set => this.RaiseAndSetIfChanged(ref _proxyHost, value); + } + + // Methods use PascalCase + public async Task SaveSettingsAsync() + { + // Use meaningful names + var settings = new ProxySettings + { + ProxyHost = ProxyHost, + ProxyPort = ProxyPort + }; + + await _configManager.SaveAsync(settings); + } +} +``` + +**Standards:** +- Use 4 spaces for indentation +- Follow C# naming conventions (PascalCase for public, camelCase for private) +- Use `async/await` for asynchronous operations +- Handle exceptions appropriately +- Use `using` statements for IDisposable +- Add XML documentation comments for public APIs + +### Swift (macOS) + +```swift +// Use Swift naming conventions +class ProxyBridgeViewModel: ObservableObject { + @Published var proxyHost: String = "127.0.0.1" + @Published var proxyPort: String = "1080" + + // Use descriptive parameter names + func saveProxySettings(host: String, port: UInt16) async throws { + // Guard for early returns + guard !host.isEmpty else { + throw ProxyError.invalidHost + } + + // Use clear, self-documenting code + let settings = ProxySettings(host: host, port: port) + try await configManager.save(settings) + } +} +``` + +**Standards:** +- Use 4 spaces for indentation +- Follow Swift naming conventions (camelCase) +- Use `guard` for early returns +- Prefer `let` over `var` when possible +- Use optionals appropriately +- Add documentation comments for public APIs + + +### Manual Testing Checklist + +- [ ] Proxy connection works (SOCKS5) +- [ ] Proxy connection works (HTTP) +- [ ] Rules are applied correctly +- [ ] Direct connections bypass proxy +- [ ] Blocked connections are denied +- [ ] TCP traffic routes correctly +- [ ] UDP traffic routes correctly +- [ ] GUI updates reflect changes +- [ ] Settings persist after restart +- [ ] No memory leaks +- [ ] Clean shutdown/cleanup + +## Commit Messages + +Use clear, descriptive commit messages: + +``` +Good: +āœ… Fix memory leak in connection table cleanup +āœ… Add support for wildcard IP matching +āœ… Update GUI to show connection count + +Bad: +āŒ fix bug +āŒ update +āŒ wip +``` + +### Format: +``` +: + + + +