react-native-ovpn 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Rasel
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Openvpn.podspec

@@ -0,0 +1,34 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "Openvpn"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => "13.0" }
+  s.source       = { :git => "https://github.com/Raselj71/react-native-ovpn.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
+  s.private_header_files = "ios/*.h"
+
+  # The PacketTunnelProvider sources are templates copied into the consumer's
+  # own Network Extension target. They must NOT be compiled into our pod (host
+  # app code), so exclude them here.
+  s.exclude_files = "ios/PacketTunnelProvider/**/*"
+
+  # OpenVPNAdapter — AGPLv3, the canonical iOS OpenVPN binding.
+  s.dependency 'OpenVPNAdapter', '~> 0.8.0'
+
+  s.pod_target_xcconfig = {
+    "SWIFT_OBJC_BRIDGING_HEADER" => "$(PODS_TARGET_SRCROOT)/ios/Openvpn-Bridging-Header.h",
+    "DEFINES_MODULE" => "YES",
+    "SWIFT_VERSION" => "5.0"
+  }
+
+  install_modules_dependencies(s)
+end

package/README.md

@@ -0,0 +1,80 @@
+# react-native-ovpn
+
+[![npm](https://img.shields.io/npm/v/react-native-ovpn.svg)](https://www.npmjs.com/package/react-native-ovpn)
+[![license](https://img.shields.io/npm/l/react-native-ovpn.svg)](LICENSE)
+
+OpenVPN client for React Native — Android, iOS, and Expo. New Architecture (TurboModule), bounded auto-reconnect, kill-switch, custom DNS.
+
+```ts
+import { OpenVPNClient } from 'react-native-ovpn';
+
+const client = new OpenVPNClient();
+client.on('state', (s) => console.log(s));    // 'connecting' | 'connected' | ...
+client.on('stats', ({ bytesIn, bytesOut }) => {});
+
+await client.requestPermission();
+await client.connect({ config: ovpnString, username: 'alice', password: 's3cret' });
+await client.disconnect();
+```
+
+## Documentation
+
+- **[Getting started](docs/getting-started.md)** — install, Android setup, iOS setup, Expo setup
+- **[API reference](docs/api.md)** — full method/event/type reference
+- **[OpenVPN config support](docs/ovpn-support.md)** — which `.ovpn` directives work
+- **[Recipes](docs/examples.md)** — kill-switch, custom DNS, reconnect, 2FA
+- **[Troubleshooting](docs/troubleshooting.md)** — common errors and fixes
+
+## Install
+
+```bash
+npm install react-native-ovpn
+# or
+yarn add react-native-ovpn
+# or
+pnpm add react-native-ovpn
+```
+
+**Expo:** add to `app.config.js`:
+
+```js
+plugins: [
+  ['react-native-ovpn', {
+    iosAppGroup: 'group.com.example.myapp.openvpn',
+    iosExtensionBundleIdentifier: 'com.example.myapp.OpenVPNTunnel',
+  }],
+];
+```
+
+Then `npx expo prebuild --clean`.
+
+**Bare React Native:** see [Getting started](docs/getting-started.md).
+
+## Feature matrix
+
+| Feature | Android | iOS |
+| --- | --- | --- |
+| Connect / disconnect | ✅ | ✅ |
+| State + stats + log events | ✅ | ✅ |
+| Auto-reconnect (bounded backoff) | ✅ | ✅ |
+| Username + password auth | ✅ | ✅ |
+| Certificate-only auth | ✅ | ✅ |
+| TLS-auth / tls-crypt / tls-crypt-v2 | ✅ | ✅ |
+| Legacy cipher fallback (AES-128-CBC) | ✅ (auto-injected) | ✅ |
+| Custom DNS override | ✅ | ✅ |
+| Kill-switch | ✅ | ❌ |
+| Foreground notification | ✅ | n/a |
+| Per-app routing | ❌ | ❌ |
+| Expo config plugin | ✅ | ✅ |
+
+See [OpenVPN config support](docs/ovpn-support.md) for the full directive-level matrix.
+
+## License
+
+Wrapper code: MIT.
+
+**Important** — Android embeds [ics-openvpn](https://github.com/schwabe/ics-openvpn) (**GPLv2**), iOS embeds [OpenVPNAdapter](https://github.com/ss-abramchuk/OpenVPNAdapter) (**AGPLv3**). Apps that ship `react-native-ovpn` inherit those copyleft obligations. Fine for personal, internal, or open-source apps; **not compatible** with closed-source commercial distribution without separate commercial agreements with the upstream projects.
+
+## Contributing
+
+[Development workflow](CONTRIBUTING.md) · [Code of conduct](CODE_OF_CONDUCT.md)

package/android/build.gradle

@@ -0,0 +1,98 @@
+buildscript {
+  ext.Openvpn = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return Openvpn[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.openvpn"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  testOptions {
+    unitTests {
+      includeAndroidResources = true
+      returnDefaultValues = true
+    }
+  }
+
+  packagingOptions {
+    resources {
+      excludes += [
+        "META-INF/AL2.0",
+        "META-INF/LGPL2.1",
+        "**/*.po",
+      ]
+    }
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  // ics-openvpn engine, committed to the repo at android/libs/ — see
+  // android/libs/README.md for how it was produced.
+  implementation files("$projectDir/libs/ics-openvpn.aar")
+  implementation "androidx.core:core-ktx:1.13.1"
+
+  testImplementation "junit:junit:4.13.2"
+  testImplementation "org.robolectric:robolectric:4.13"
+  testImplementation "androidx.test:core:1.5.0"
+  testImplementation "androidx.test.ext:junit:1.1.5"
+}

package/android/libs/README.md

@@ -0,0 +1,46 @@
+# `android/libs/` — vendored AAR location
+
+`ics-openvpn.aar` lives here and **is committed to the repository**. Consumers and CI never need to rebuild it. Rebuild only when bumping the ics-openvpn submodule pointer.
+
+```
+android/libs/ics-openvpn.aar    (~5–10 MB binary, tracked in git)
+```
+
+## How it was produced (rebuilding when needed)
+
+ics-openvpn's upstream `main` Gradle module is an **application**, not a library, so we cannot consume it via a normal `implementation project(...)` dependency or a Maven coordinate. Instead, we build it locally once into an AAR and commit the binary.
+
+Run the build script from the repo root:
+
+```powershell
+pwsh ./scripts/build-ics-openvpn-aar.ps1
+```
+
+That script:
+
+1. Patches `third_party/ics-openvpn/main/build.gradle.kts` in-place to use the `com.android.library` plugin (so the build emits an AAR).
+2. Runs `./gradlew :main:assembleSkeletonOvpn23Release` inside the submodule (skeleton = no UI; ovpn23 = both OpenVPN 2.x and 3.x).
+3. Copies the resulting AAR to `android/libs/ics-openvpn.aar`.
+4. Reverts the gradle patch so the submodule stays clean.
+
+After running the script, **commit the AAR** so other clones and CI don't need NDK:
+
+```bash
+git add android/libs/ics-openvpn.aar
+git commit -m "build(android): vendor ics-openvpn AAR (v0.7.59 skeleton-ovpn23)"
+```
+
+## Prerequisites for running the script
+
+- Java 17+ (Temurin or Android Studio JBR)
+- Android SDK with build-tools and platform-35
+- Android NDK 27.x or 28.x
+- CMake 3.22+ (Android SDK CMake component)
+- SWIG (`choco install swig` on Windows; `brew install swig` on macOS)
+- **Nested submodules initialized:** `git -C third_party/ics-openvpn submodule update --init --recursive` (pulls in asio, lz4, mbedtls, openssl, openvpn, openvpn3)
+
+## When to rebuild
+
+- After bumping the submodule pointer (security fixes, new ics-openvpn release)
+- After changing the chosen flavor (e.g., `ovpn2` instead of `ovpn23`)
+- Otherwise: never — the AAR is a stable artifact

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+
+  <uses-permission android:name="android.permission.INTERNET" />
+  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
+  <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+  <!-- ics-openvpn schedules a PERSISTED keepalive JobService that survives
+       reboots; the OS requires this permission on apps that do that. -->
+  <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
+
+  <!--
+    The bundled ics-openvpn.aar declares <application android:name=... label=... theme=...>
+    inherited from its original "application" build. Tell the manifest merger to drop
+    those attributes at this layer so they don't conflict with the consumer's app manifest.
+  -->
+  <application
+      tools:remove="android:name,android:label,android:theme,android:icon,android:allowBackup">
+    <service
+        android:name="com.openvpn.OpenvpnService"
+        android:permission="android.permission.BIND_VPN_SERVICE"
+        android:foregroundServiceType="specialUse"
+        android:exported="false">
+      <property
+          android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE"
+          android:value="vpn" />
+      <intent-filter>
+        <action android:name="android.net.VpnService" />
+      </intent-filter>
+    </service>
+
+    <!--
+      ics-openvpn's OpenVPNService.startOpenVPN schedules this JobService
+      directly via JobScheduler. The original AAR manifest declared it but
+      we stripped the AAR manifest to avoid <application>-attribute conflicts.
+      Re-declare it here so Android can find the component.
+    -->
+    <service
+        android:name="de.blinkt.openvpn.core.keepVPNAlive"
+        android:exported="false"
+        android:permission="android.permission.BIND_JOB_SERVICE" />
+
+    <!--
+      Status-broadcast service used by ics-openvpn internally for IPC between
+      the foreground OpenVPN service and its API consumers. Declared here for
+      the same reason as keepVPNAlive.
+    -->
+    <service
+        android:name="de.blinkt.openvpn.core.OpenVPNStatusService"
+        android:exported="false" />
+  </application>
+</manifest>

package/android/src/main/java/com/openvpn/NotificationHelper.kt

@@ -0,0 +1,59 @@
+package com.openvpn
+
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.content.Context
+import android.os.Build
+import androidx.core.app.NotificationCompat
+
+data class NotificationOverrides(
+  val title: String? = null,
+  val text: String? = null,
+  val smallIcon: String? = null,
+  val channelId: String? = null,
+)
+
+object NotificationHelper {
+
+  private const val DEFAULT_CHANNEL_ID = "openvpn"
+
+  fun build(context: Context, overrides: NotificationOverrides): Notification {
+    val channelId = overrides.channelId ?: DEFAULT_CHANNEL_ID
+    ensureChannel(
+      context,
+      channelId,
+      context.getString(R.string.openvpn_notification_channel_name),
+    )
+
+    val title = overrides.title ?: context.getString(R.string.openvpn_notification_title)
+    val text = overrides.text ?: context.getString(R.string.openvpn_notification_text)
+    val iconResId = resolveIcon(context, overrides.smallIcon)
+
+    return NotificationCompat.Builder(context, channelId)
+      .setContentTitle(title)
+      .setContentText(text)
+      .setSmallIcon(iconResId)
+      .setOngoing(true)
+      .setPriority(NotificationCompat.PRIORITY_LOW)
+      .build()
+  }
+
+  fun ensureChannel(context: Context, channelId: String, channelName: String) {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
+    val mgr = context.getSystemService(NotificationManager::class.java) ?: return
+    if (mgr.getNotificationChannel(channelId) != null) return
+    val channel = NotificationChannel(
+      channelId,
+      channelName,
+      NotificationManager.IMPORTANCE_LOW,
+    )
+    mgr.createNotificationChannel(channel)
+  }
+
+  private fun resolveIcon(context: Context, name: String?): Int {
+    if (name.isNullOrBlank()) return R.drawable.ic_vpn_default
+    val res = context.resources.getIdentifier(name, "drawable", context.packageName)
+    return if (res != 0) res else R.drawable.ic_vpn_default
+  }
+}

package/android/src/main/java/com/openvpn/OpenvpnEventBus.kt

@@ -0,0 +1,52 @@
+package com.openvpn
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.modules.core.DeviceEventManagerModule
+
+object OpenvpnEventBus {
+
+  @Volatile
+  private var reactContext: ReactApplicationContext? = null
+
+  fun attach(context: ReactApplicationContext) {
+    reactContext = context
+  }
+
+  fun detach() {
+    reactContext = null
+  }
+
+  fun emitState(state: String) {
+    emit("OpenVpn:state", state)
+  }
+
+  fun emitStats(bytesIn: Long, bytesOut: Long, durationMs: Long) {
+    val payload = Arguments.createMap().apply {
+      putDouble("bytesIn", bytesIn.toDouble())
+      putDouble("bytesOut", bytesOut.toDouble())
+      putDouble("durationMs", durationMs.toDouble())
+    }
+    emit("OpenVpn:stats", payload)
+  }
+
+  fun emitLog(line: String) {
+    emit("OpenVpn:log", line)
+  }
+
+  fun emitError(code: String, nativeMessage: String?) {
+    val payload = Arguments.createMap().apply {
+      putString("code", code)
+      putString("nativeMessage", nativeMessage)
+    }
+    emit("OpenVpn:error", payload)
+  }
+
+  private fun emit(eventName: String, payload: Any?) {
+    val ctx = reactContext ?: return
+    if (!ctx.hasActiveReactInstance()) return
+    ctx
+      .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+      .emit(eventName, payload)
+  }
+}

package/android/src/main/java/com/openvpn/OpenvpnException.kt

@@ -0,0 +1,6 @@
+package com.openvpn
+
+class OpenvpnException(
+  val code: String,
+  val nativeMessage: String,
+) : RuntimeException("$code: $nativeMessage")

package/android/src/main/java/com/openvpn/OpenvpnModule.kt

@@ -0,0 +1,140 @@
+package com.openvpn
+
+import android.content.Intent
+import android.os.Build
+import com.facebook.react.bridge.ActivityEventListener
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.LifecycleEventListener
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.WritableMap
+
+class OpenvpnModule(reactContext: ReactApplicationContext) :
+  NativeOpenvpnSpec(reactContext), LifecycleEventListener, ActivityEventListener {
+
+  private val context: ReactApplicationContext = reactContext
+
+  init {
+    OpenvpnEventBus.attach(reactContext)
+    reactContext.addLifecycleEventListener(this)
+    reactContext.addActivityEventListener(this)
+  }
+
+  override fun getName(): String = NAME
+
+  override fun requestPermission(promise: Promise) {
+    PermissionLauncher.request(context, promise)
+  }
+
+  override fun connect(params: ReadableMap, promise: Promise) {
+    try {
+      // Reject per-app routing (deferred from Plan 2)
+      val allowed = if (params.hasKey("allowedApps")) params.getArray("allowedApps") else null
+      val disallowed = if (params.hasKey("disallowedApps")) params.getArray("disallowedApps") else null
+      if ((allowed?.size() ?: 0) > 0 || (disallowed?.size() ?: 0) > 0) {
+        promise.reject(
+          "INVALID_CONFIG",
+          "per-app routing (allowedApps/disallowedApps) not yet implemented on Android",
+        )
+        return
+      }
+
+      val ovpn = params.getString("config")
+        ?: throw OpenvpnException("INVALID_CONFIG", "config missing")
+      val username = params.getString("username") ?: ""
+      val password = params.getString("password") ?: ""
+      val killSwitch = if (params.hasKey("killSwitch")) params.getBoolean("killSwitch") else false
+      val dns = if (params.hasKey("dns")) {
+        params.getArray("dns")?.let { array ->
+          (0 until array.size()).mapNotNull { array.getString(it) }
+        } ?: emptyList()
+      } else emptyList()
+      val notificationMap = if (params.hasKey("notification")) params.getMap("notification") else null
+
+      val profile = ProfileBuilder.build(ovpn, username, password, dns, killSwitch)
+
+      val intent = Intent(context, OpenvpnService::class.java).apply {
+        action = OpenvpnService.ACTION_START
+        putExtra(OpenvpnService.EXTRA_PROFILE, profile)
+        notificationMap?.let {
+          if (it.hasKey("title")) putExtra(OpenvpnService.EXTRA_NOTIF_TITLE, it.getString("title"))
+          if (it.hasKey("text")) putExtra(OpenvpnService.EXTRA_NOTIF_TEXT, it.getString("text"))
+          if (it.hasKey("smallIcon")) putExtra(OpenvpnService.EXTRA_NOTIF_ICON, it.getString("smallIcon"))
+          if (it.hasKey("channelId")) putExtra(OpenvpnService.EXTRA_NOTIF_CHANNEL, it.getString("channelId"))
+        }
+      }
+
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+        context.startForegroundService(intent)
+      } else {
+        context.startService(intent)
+      }
+      // The JS-side connect() Promise resolves on the 'connected' state event,
+      // so we resolve this native promise as soon as the start request is
+      // accepted by the system.
+      promise.resolve(null)
+    } catch (e: OpenvpnException) {
+      promise.reject(e.code, e.nativeMessage)
+    } catch (e: Exception) {
+      promise.reject("NATIVE_ERROR", e.message ?: "unknown error")
+    }
+  }
+
+  override fun disconnect(promise: Promise) {
+    try {
+      val intent = Intent(context, OpenvpnService::class.java).apply {
+        action = OpenvpnService.ACTION_STOP
+      }
+      context.startService(intent)
+      promise.resolve(null)
+    } catch (e: Exception) {
+      promise.reject("NATIVE_ERROR", e.message ?: "unknown error")
+    }
+  }
+
+  override fun getStatus(promise: Promise) {
+    val map: WritableMap = Arguments.createMap()
+    // State is delivered via the 'OpenVpn:state' event channel.
+    // This method returns a minimal snapshot; consumers should prefer events.
+    map.putString("state", "idle")
+    promise.resolve(map)
+  }
+
+  override fun getStats(promise: Promise) {
+    val map: WritableMap = Arguments.createMap()
+    map.putDouble("bytesIn", 0.0)
+    map.putDouble("bytesOut", 0.0)
+    map.putDouble("durationMs", 0.0)
+    promise.resolve(map)
+  }
+
+  override fun addListener(eventName: String?) {
+    // required by RN's NativeEventEmitter contract; no-op
+  }
+
+  override fun removeListeners(count: Double) {
+    // required by RN's NativeEventEmitter contract; no-op
+  }
+
+  override fun onHostResume() = Unit
+  override fun onHostPause() = Unit
+  override fun onHostDestroy() {
+    OpenvpnEventBus.detach()
+  }
+
+  override fun onActivityResult(
+    activity: android.app.Activity,
+    requestCode: Int,
+    resultCode: Int,
+    data: Intent?,
+  ) {
+    PermissionLauncher.onActivityResult(requestCode, resultCode, data)
+  }
+
+  override fun onNewIntent(intent: Intent) = Unit
+
+  companion object {
+    const val NAME = NativeOpenvpnSpec.NAME
+  }
+}

package/android/src/main/java/com/openvpn/OpenvpnPackage.kt

@@ -0,0 +1,31 @@
+package com.openvpn
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+import java.util.HashMap
+
+class OpenvpnPackage : BaseReactPackage() {
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+    return if (name == OpenvpnModule.NAME) {
+      OpenvpnModule(reactContext)
+    } else {
+      null
+    }
+  }
+
+  override fun getReactModuleInfoProvider() = ReactModuleInfoProvider {
+    mapOf(
+      OpenvpnModule.NAME to ReactModuleInfo(
+        name = OpenvpnModule.NAME,
+        className = OpenvpnModule.NAME,
+        canOverrideExistingModule = false,
+        needsEagerInit = false,
+        isCxxModule = false,
+        isTurboModule = true
+      )
+    )
+  }
+}