🛡️ ShieldShare VPN

A powerful, cross-platform VPN library for React Native applications built with Expo. ShieldShare VPN provides secure, reliable VPN connectivity using OpenVPN protocol with platform-specific optimizations for both Android and iOS.

✨ Features

• 🔒 Secure VPN Connection - Built on OpenVPN protocol for maximum security
• 📱 Cross-Platform - Works seamlessly on both Android and iOS
• ⚡ High Performance - Optimized native implementations
• 🎯 Easy Integration - Simple React Native API
• 🛠️ Expo Compatible - Works with Expo Development Build and EAS Build
• 🔧 Customizable - Extensive configuration options
• 📊 Real-time Monitoring - VPN state monitoring and event handling
• 🌐 Multi-Protocol Support - OpenVPN 2.x and 3.x compatibility

🚀 Quick Start

Installation

# Using npm
npm install shieldshare-vpn

# Using yarn
yarn add shieldshare-vpn

# Using pnpm
pnpm add shieldshare-vpn

Basic Usage

import ShieldShareVpn, { addVpnStateListener, removeVpnStateListener } from 'shieldshare-vpn';

// Listen to VPN state changes
useEffect(() => {
  addVpnStateListener((event) => {
    console.log('VPN State:', event.state);
    console.log('Message:', event.message);
  });

  return () => {
    removeVpnStateListener();
  };
}, []);

// Connect to VPN
const connectVPN = async () => {
  try {
    await ShieldShareVpn.connect({
      remoteAddress: 'your-vpn-server.com 1194',
      ovpnFileName: 'client',
      assetsPath: 'ovpn/',
      providerBundleIdentifier: 'com.yourapp.ShieldShareVPN',
      localizedDescription: 'ShieldShare VPN',
      username: 'your-username',
      password: 'your-password'
    });
  } catch (error) {
    console.error('VPN Connection Error:', error);
  }
};

// Disconnect VPN
const disconnectVPN = async () => {
  try {
    await ShieldShareVpn.disconnect();
  } catch (error) {
    console.error('VPN Disconnection Error:', error);
  }
};

📋 Requirements

Android

• Android API 21+ (Android 5.0+)
• React Native 0.60+
• Java 11 or 17

iOS

• iOS 9.0+
• React Native 0.60+
• Xcode 12+

Expo

• Expo SDK 47+
• Expo Development Build or EAS Build (not compatible with Expo Go)

🔧 Installation Guide

React Native CLI

1. Install the package:

   npm install shieldshare-vpn

2. iOS Setup:

   cd ios && pod install

3. Android Setup:

   • Add VPN permissions to android/app/src/main/AndroidManifest.xml
   • The library will be auto-linked

Expo Development Build

1. Install the package:

   npx expo install shieldshare-vpn

2. Create development build:

   npx expo run:ios
   npx expo run:android

3. Or use EAS Build:

   eas build --platform ios
   eas build --platform android

📖 API Reference

Methods

connect(options: VpnOptions): Promise<void>

Establishes a VPN connection with the specified configuration.

disconnect(): Promise<void>

Disconnects the current VPN connection.

getCurrentState(): Promise<VpnState>

Returns the current VPN connection state.

observeState(): Promise<void>

Starts observing VPN state changes (iOS only).

stopObserveState(): Promise<void>

Stops observing VPN state changes (iOS only).

Types

VpnOptions

interface VpnOptions {
  remoteAddress?: string;           // VPN server address and port
  ovpnString?: string;             // OpenVPN configuration string
  ovpnFileName?: string;           // OpenVPN configuration file name
  username?: string;               // VPN username
  password?: string;               // VPN password
  assetsPath?: string;             // Path to assets folder
  notificationTitle?: string;      // Notification title
  compatMode?: CompatMode;         // OpenVPN compatibility mode
  useLegacyProvider?: boolean;     // Use legacy provider
  useCustomConfig?: boolean;       // Use custom configuration
  customConfigOptions?: string;    // Custom configuration options
  allowedAppsVpn?: Array<string>;  // Allowed apps for VPN
  allowedAppsVpnAreDisallowed?: boolean; // Disallow specific apps
  providerBundleIdentifier: string; // iOS bundle identifier
  localizedDescription?: string;   // VPN description
}

VpnState

enum VpnState {
  VPN_STATE_DISCONNECTED,
  VPN_STATE_CONNECTING,
  VPN_STATE_CONNECTED,
  VPN_STATE_DISCONNECTING,
  VPN_OTHER_STATE,
}

CompatMode

enum CompatMode {
  MODERN_DEFAULTS,
  OVPN_TWO_FIVE_PEER,
  OVPN_TWO_FOUR_PEER,
  OVPN_TWO_THREE_PEER,
}

🔐 Security Features

• End-to-End Encryption - All traffic is encrypted using OpenVPN protocol
• Certificate Validation - Automatic certificate validation and verification
• Perfect Forward Secrecy - Dynamic key exchange for enhanced security
• DNS Leak Protection - Prevents DNS leaks during VPN connection
• Kill Switch - Automatic connection termination on VPN failure

🛠️ Configuration

Android Permissions

Add the following permissions to your AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.BIND_VPN_SERVICE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

iOS Capabilities

Add the following capabilities to your iOS project:

• Network Extensions
• VPN Configuration

📱 Platform-Specific Features

Android

• VPNService Integration - Uses Android's native VPNService
• Background Processing - Reliable background VPN connections
• Notification Support - Persistent VPN status notifications
• App-Specific Routing - Control which apps use VPN

iOS

• Network Extension - Uses iOS Network Extension framework
• Packet Tunnel Provider - Custom packet processing
• System Integration - Native iOS VPN settings integration
• Background App Refresh - Maintains connections in background

🧪 Examples

Check out the examples/ directory for complete working examples:

• React Native Example - Basic React Native implementation
• Expo Example - Expo Development Build implementation

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• OpenVPN - The underlying VPN protocol
• react-native-simple-openvpn - Original inspiration
• Expo - Development platform
• React Native - Mobile development framework

📞 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Full Documentation
• 💬 Discord: ShieldShare Community

🔄 Changelog

See CHANGELOG.md for a list of changes and version history.