Add proxy feature for iOS support #1
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Implement iOS VPN proxy functionality matching Android feature parity: Core Components: - VPNModule: React Native bridge for iOS (Swift + Objective-C) - VPNManager: NetworkExtension lifecycle management - PacketTunnelProvider: Network Extension packet tunnel - ProfileStorage: Secure profile persistence with App Groups - SOCKS5ProxyHandler: Full SOCKS5 protocol (RFC 1928, 1929) - HTTPProxyHandler: HTTP CONNECT proxy with authentication Features: ✅ SOCKS5 proxy with username/password auth ✅ HTTP CONNECT proxy with Basic auth ✅ Profile management (create, read, delete) ✅ VPN lifecycle (start, stop, status monitoring) ✅ Real-time status updates and event emission ✅ App Groups for data sharing between app and extension ✅ Network Extension entitlements configured Architecture: - Uses Apple NetworkExtension framework (NEPacketTunnelProvider) - Matches Android VPNModule API for cross-platform consistency - Packet-level VPN tunnel with IP routing - Secure storage with UserDefaults + App Group Documentation: - iOS_PROXY_IMPLEMENTATION.md: Complete technical documentation - XCODE_SETUP_REQUIRED.md: Step-by-step Xcode configuration guide Notes: - Requires manual Xcode project configuration (Network Extension target) - Requires Apple Developer entitlements for Network Extensions - Basic packet handling implemented; consider tun2socks for production - Tested architecture on iOS 15.1+ deployment target Files Added: - ios/CBVVPN/VPNModule.swift (React Native bridge) - ios/CBVVPN/VPNModule.m (Bridge definition) - ios/CBVVPN/VPNManager.swift (VPN lifecycle) - ios/CBVVPN/VPNProfile.swift (Data model) - ios/CBVVPN/ProfileStorage.swift (Persistence) - ios/CBVVPN/SOCKS5ProxyHandler.swift (SOCKS5 implementation) - ios/CBVVPN/HTTPProxyHandler.swift (HTTP proxy) - ios/PacketTunnel/PacketTunnelProvider.swift (Network Extension) - ios/PacketTunnel/Info.plist (Extension config) - ios/PacketTunnel/PacketTunnel.entitlements Files Modified: - ios/CBVVPN/CBVVPN.entitlements (Added VPN capabilities) - README.md (Updated iOS status to "Implementation Ready")
There was a problem hiding this comment.
Pull Request Overview
This PR implements a complete iOS VPN proxy feature to achieve feature parity with the existing Android implementation. The implementation uses Apple's NetworkExtension framework to create a packet tunnel that routes traffic through SOCKS5 or HTTP proxies, matching the Android VPNService architecture.
Key Changes:
- Added complete iOS VPN infrastructure using NetworkExtension framework with React Native bridge
- Implemented SOCKS5 (RFC 1928, 1929) and HTTP CONNECT proxy handlers with authentication support
- Created Network Extension packet tunnel provider with App Groups for secure data sharing
- Updated README to reflect iOS implementation status change from "In Development" to "Implementation Ready"
Reviewed Changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| ios/iOS_PROXY_IMPLEMENTATION.md | Comprehensive technical documentation covering architecture, setup, API interface, and production recommendations |
| ios/XCODE_SETUP_REQUIRED.md | Step-by-step Xcode configuration guide with troubleshooting and verification steps |
| ios/PacketTunnel/PacketTunnelProvider.swift | Network Extension implementation handling packet interception and proxy routing |
| ios/PacketTunnel/PacketTunnel.entitlements | Network Extension entitlements configuration for packet-tunnel-provider and App Groups |
| ios/PacketTunnel/Info.plist | Network Extension target configuration with bundle settings and extension point identifier |
| ios/CBVVPN/VPNProfile.swift | Data model for VPN/proxy profiles supporting SOCKS5 and HTTP with authentication |
| ios/CBVVPN/VPNModule.swift | React Native bridge providing JavaScript interface for VPN control and profile management |
| ios/CBVVPN/VPNModule.m | Objective-C bridge definitions exposing Swift VPNModule methods to React Native |
| ios/CBVVPN/VPNManager.swift | VPN lifecycle manager using NETunnelProviderManager for connection control |
| ios/CBVVPN/SOCKS5ProxyHandler.swift | Full SOCKS5 protocol implementation with username/password authentication |
| ios/CBVVPN/ProfileStorage.swift | Persistent storage using UserDefaults with App Group for main app and extension sharing |
| ios/CBVVPN/HTTPProxyHandler.swift | HTTP CONNECT proxy implementation with Basic authentication |
| ios/CBVVPN/CBVVPN.entitlements | Main app entitlements enabling Network Extensions and App Groups capabilities |
| README.md | Updated iOS status badge and added implementation details with setup references |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| // Configure protocol | ||
| let protocolConfiguration = NETunnelProviderProtocol() | ||
| protocolConfiguration.providerBundleIdentifier = "com.cbv.vpn.PacketTunnel" |
There was a problem hiding this comment.
The bundle identifier is hardcoded here and also documented in line 119 of iOS_PROXY_IMPLEMENTATION.md. Consider defining this as a constant at the top of the file (e.g., private static let packetTunnelBundleId = \"com.cbv.vpn.PacketTunnel\") to improve maintainability and ensure consistency across the codebase.
Comment on lines
+34
to
+35
| let dns1 = config["dns1"] as? String ?? "1.1.1.1" | ||
| let dns2 = config["dns2"] as? String ?? "8.8.8.8" |
There was a problem hiding this comment.
Default DNS servers are hardcoded and duplicated in VPNManager.swift lines 64-65. Consider defining these as constants in a shared configuration file or struct to avoid duplication and make them easier to update.
Comment on lines
+6
to
+10
| private let userDefaults: UserDefaults | ||
| private let profilesKey = "vpn_profiles" | ||
|
|
||
| private init() { | ||
| if let sharedDefaults = UserDefaults(suiteName: "group.com.cbv.vpn") { |
There was a problem hiding this comment.
The App Group identifier "group.com.cbv.vpn" is hardcoded here and repeated in multiple files (PacketTunnel.entitlements:11, CBVVPN.entitlements:11, iOS_PROXY_IMPLEMENTATION.md:97, XCODE_SETUP_REQUIRED.md:98, 110). Consider defining this as a constant in a shared configuration to ensure consistency and easier maintenance.
Suggested change
| private let userDefaults: UserDefaults | |
| private let profilesKey = "vpn_profiles" | |
| private init() { | |
| if let sharedDefaults = UserDefaults(suiteName: "group.com.cbv.vpn") { | |
| private static let appGroupIdentifier = "group.com.cbv.vpn" | |
| private let userDefaults: UserDefaults | |
| private let profilesKey = "vpn_profiles" | |
| private init() { | |
| if let sharedDefaults = UserDefaults(suiteName: ProfileStorage.appGroupIdentifier) { |
|
|
||
| // MARK: - Helper Methods | ||
|
|
||
| private func getHTTPErrorMessage(_ statusCode: Int) -> String { |
There was a problem hiding this comment.
The method getHTTPErrorMessage is defined but never used in the code. It appears the error message is constructed inline at line 135 instead. Either remove this unused method or refactor line 134-136 to use it.
Fix code quality issue where getHTTPErrorMessage method was defined but never used. Refactored parseHTTPResponse to use the helper method for better error messages instead of constructing them inline. Benefits: - Provides more descriptive error messages for common HTTP status codes - Eliminates dead code - Improves maintainability Changed: - ios/CBVVPN/HTTPProxyHandler.swift: Use getHTTPErrorMessage() at line 134
Add Expo prebuild support and CI/CD workflows for iOS builds. Major Changes: - Enhanced Expo config plugin for iOS native module integration - Added GitHub Actions workflow for iOS IPA builds - Created comprehensive documentation for Expo prebuild workflow - Added configuration helper script for iOS Network Extension Files Added: 1. .github/workflows/build-ios.yml - Complete iOS build workflow with code signing - Xcode 15.4, macOS 14 runner - Automated IPA generation and artifact upload - Optional TestFlight upload support 2. .github/SECRETS.md - Complete guide for GitHub Actions secrets - Android keystore setup instructions - iOS certificate and provisioning profile guide - Network Extensions capability requirements 3. EXPO_PREBUILD_GUIDE.md - Comprehensive Expo prebuild workflow guide - Development workflow best practices - Native module development instructions - Troubleshooting section 4. ios/configure-network-extension.sh - Helper script to validate iOS project setup - Checks for required files and entitlements - Provides step-by-step manual configuration checklist - Executable shell script Files Modified: 1. plugins/withVPNModule.js - Added iOS support with entitlements configuration - Auto-configures Network Extensions capability - Updates bridging header automatically - Validates iOS project structure 2. README.md - Updated Quick Start with Expo prebuild workflow - Added CI/CD section with GitHub Actions info - Added comprehensive Documentation section - Updated Requirements with CocoaPods and Xcode version - Clarified Expo Go is not supported Key Features: ✅ Full Expo managed workflow support for native modules ✅ Automated iOS entitlements configuration ✅ CI/CD ready with GitHub Actions ✅ Comprehensive documentation ✅ Helper scripts for iOS configuration ✅ TestFlight upload support (optional) iOS Build Requirements: - Xcode 15.4+ - macOS 14 for GitHub Actions - Apple Developer account with Network Extensions - Code signing certificates and provisioning profiles Documentation Structure: - EXPO_PREBUILD_GUIDE.md: Prebuild workflow - ios/iOS_PROXY_IMPLEMENTATION.md: Technical details - ios/XCODE_SETUP_REQUIRED.md: Xcode setup - .github/SECRETS.md: CI/CD secrets
Add complete iOS Simulator build workflow and tooling that requires
NO Apple Developer account, certificates, or provisioning profiles.
Perfect for:
✅ CI/CD testing without secrets
✅ Unit and snapshot tests
✅ Development and debugging
✅ Quick iteration without device
Key Features:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. GitHub Actions Workflow (.github/workflows/build-ios-simulator.yml)
- Builds on macOS 14 with Xcode 15.4
- No secrets required (CODE_SIGNING_ALLOWED=NO)
- Creates .app bundle for simulator
- Uploads artifacts with 30-day retention
- Optional unit test execution
- Multi-simulator matrix build support (manual trigger)
2. Automated Build Script (scripts/build-simulator.sh)
- One-command simulator build
- Checks prerequisites automatically
- Runs expo prebuild if needed
- Installs CocoaPods dependencies
- Creates distribution archive with:
* .app bundle
* README with instructions
* Quick install script
- Beautiful color-coded output
3. Comprehensive Documentation (docs/IOS_SIMULATOR_BUILD.md)
- Complete simulator build guide
- Installation methods (GUI, CLI, script)
- Working with simulators (boot, install, launch)
- Testing and debugging techniques
- Troubleshooting section
- CI/CD integration examples
- Simulator vs Device comparison table
- Advanced usage examples
4. Updated Project Documentation
- README.md: Added simulator build section
- EXPO_PREBUILD_GUIDE.md: Added simulator workflow
- Clear distinction: Device vs Simulator builds
Technical Details:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Build Configuration:
- SDK: iphonesimulator
- Configuration: Debug
- Destination: iPhone 15 (configurable)
- Architectures: x86_64, arm64 (Apple Silicon compatible)
- Code Signing: Completely disabled
xcodebuild flags:
- CODE_SIGN_IDENTITY=""
- CODE_SIGNING_REQUIRED=NO
- CODE_SIGNING_ALLOWED=NO
Output:
- .app bundle in build/Build/Products/Debug-iphonesimulator/
- Zipped archive with install script and README
- Ready for distribution to team
Installation Methods:
1. Drag & Drop in Xcode Device Manager
2. Command line: xcrun simctl install booted CBVVPN.app
3. Quick script: ./install.sh (auto-boot simulator)
Testing:
- Unit tests: xcodebuild test with simulator destination
- Logs: xcrun simctl spawn booted log stream
- Screenshots: xcrun simctl io booted screenshot
- Recording: xcrun simctl io booted recordVideo
Limitations:
⚠️ Simulator only (not installable on physical devices)
⚠️ Network Extension has limited functionality
⚠️ Some hardware features unavailable
Use Cases:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Development:
- Quick iteration without device
- Test UI changes instantly
- Debug with Xcode instruments
Testing:
- Unit tests in CI/CD
- Snapshot tests
- Integration tests
- Regression testing
CI/CD:
- GitHub Actions without secrets
- No certificate management
- Fast builds
- Artifact distribution
Team Collaboration:
- Share builds easily
- No provisioning profile hassles
- Works on any Mac with Xcode
Files Added:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
.github/workflows/build-ios-simulator.yml (219 lines)
- Complete GitHub Actions workflow
- Single simulator build job
- Multi-simulator matrix build job (manual)
- Artifact upload and summary
scripts/build-simulator.sh (182 lines)
- Automated simulator build script
- Prerequisites checking
- Distribution archive creation
- Install script generation
- Color-coded output
docs/IOS_SIMULATOR_BUILD.md (600+ lines)
- Complete simulator guide
- Installation instructions
- Testing techniques
- Debugging tips
- Troubleshooting
- Advanced usage
- Comparison tables
Files Modified:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
README.md
- Added "iOS - Simulator" section in Build for Production
- Updated CI/CD section with simulator workflow
- Added simulator guide to documentation index
EXPO_PREBUILD_GUIDE.md
- Added iOS Simulator Builds section
- Updated CI/CD section
- Added workflow comparison
Quick Start:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Local build
./scripts/build-simulator.sh
# Install on simulator
cd ios/build/simulator-dist && ./install.sh
# CI/CD (GitHub Actions)
# Automatically runs on push to main/develop
# No secrets required!
# Manual trigger
# Actions tab → Build iOS Simulator → Run workflow
Benefits:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ No Apple Developer account needed
✅ No certificates or provisioning profiles
✅ No code signing complexity
✅ Perfect for CI/CD without secrets
✅ Fast iteration for development
✅ Easy team distribution
✅ Comprehensive documentation
✅ Automated tooling
This implementation makes iOS testing accessible to everyone,
regardless of Apple Developer program membership.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Implement iOS VPN proxy functionality matching Android feature parity:
Core Components:
Features:
✅ SOCKS5 proxy with username/password auth
✅ HTTP CONNECT proxy with Basic auth
✅ Profile management (create, read, delete)
✅ VPN lifecycle (start, stop, status monitoring)
✅ Real-time status updates and event emission
✅ App Groups for data sharing between app and extension ✅ Network Extension entitlements configured
Architecture:
Documentation:
Notes:
Files Added:
Files Modified: