@umutcansu/react-native-pinvault 2.4.0 → 2.4.2

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## 2.4.2 — 2026-10-10
+
+### Added
+
+- **Expo config plugin** (`app.plugin.js`): at `expo prebuild` it sets the
+  iOS deployment target to 16.0, writes the Info.plist keys
+  (`faceIDPermission`, `backgroundUpdates`), adds
+  `PinVaultBridge.registerBackgroundTask()` to a Swift `AppDelegate`, copies
+  the native security file into Android's assets and the iOS app bundle
+  (`nativeSecurityFile`), and writes the two native opt-outs only when asked
+  (`allowNoNativeSecurityFile`, `pinReactNativeNetworking: false`). Built and
+  run with Expo SDK 54 (React Native 0.81), Android and iOS release builds.
+
+### Changed
+
+- **Native libraries 2.4.2:** release builds refuse `allowUnsigned()` /
+  `allowUnpinnedConfigApi()` unless the block also calls
+  `allowRelaxationsInRelease()`. The bridge calls it only where the native
+  security file itself allows the relaxation (`allowUnsigned` /
+  `allowUnpinned`), so the native file stays the only place that decides;
+  JS cannot turn it on.
+
+## 2.4.1 — 2026-10-10
+
+### Security
+
+- **React Native's WebSocket is pinned on iOS.** `wss://` went through
+  SocketRocket on CFStream with the platform's CA check only, so a socket.io /
+  graphql-ws connection could be intercepted by anyone holding a certificate
+  the device trusts (a corporate proxy, a user-installed root), and `start`
+  still reported RN's networking as pinned. Every SocketRocket socket to a
+  `wss` / `https` URL now gets a security policy that asks PinVault (the
+  library's new `evaluateServerTrust(_:host:port:)`) before the upgrade
+  request is written; subprotocols are kept. `requirePinnedReactNativeNetworking`
+  covers it (`E_NETWORKING_NOT_PINNED` when the hook is not in place), and
+  Info.plist `PinVaultPinReactNativeNetworking` = NO turns it off with the
+  https handler. A WebSocket to a host that requires a client certificate is
+  not supported on iOS yet (the handshake fails).
+- **Android: every WebSocket goes through PinVault's hook of its own.** RN's
+  `WebSocketModule` has a separate `setCustomClientBuilder`; up to 0.81 it
+  builds each socket's client from a bare `OkHttpClient.Builder()`, outside
+  `OkHttpClientProvider`, so there the socket kept the system's trust while
+  `start` reported RN's networking as pinned. The plugin now installs that hook
+  too and checks it with the other two (`HookStatus.webSocketBuilderIsPinVault`),
+  so a library replacing it is also caught on 0.87.
+
+- **A release build needs the anchors in the native security file:** a declared
+  block must carry `bootstrapPins` (or `allowUnpinnedConfigApi`) and
+  `signaturePublicKeys` (or `allowUnsigned`). A file with a bare
+  `{"id": …}` satisfied the release rule while the bundle supplied the pins
+  and keys; it now rejects `start` with `E_INVALID_CONFIG` naming the field.
+- **`clientCertHosts` from JS only where the file names them** (release
+  builds): an OTA bundle could otherwise present the device's mTLS identity
+  to another pinned host. `tokenHosts` from JS is still taken: it only
+  narrows the library's default.
+
+### Changed
+
+- **React Native 0.81+** (was 0.87+): built and run on 0.81.6 and 0.87.1,
+  Android and iOS (start with `requirePinnedReactNativeNetworking`, RN `fetch`
+  and `WebSocket` to a pinned and an unpinned host).
+
 ## 2.4.0 — 2026-10-09
 
 ### Breaking

package/README.md

@@ -15,7 +15,8 @@ crypto runs in JavaScript, and JavaScript never sees TLS. Names are the native
 ones (`InitResult`, `ClientCertEnrollmentResult`, `VaultFileResult`, …), so the
 [library documentation](https://github.com/umutcansu/PinVault/blob/main/GUIDE.md) applies as it is.
 
-- React Native **0.87+**, New Architecture only (TurboModule, codegen), Hermes.
+- React Native **0.81+** (built and tested on 0.81.6 and 0.87.1), New
+  Architecture only (TurboModule, codegen), Hermes.
 - Android minSdk 24; iOS 16+.
 - No runtime dependencies: `react` and `react-native` are peers.
 
@@ -28,15 +29,18 @@ npm install @umutcansu/react-native-pinvault
 cd ios && pod install
 ```
 
-The native libraries come with it, at the package's own version: npm 2.3.2
-uses `io.github.umutcansu:pinvault:2.3.2` from Maven Central and the Swift
-package at tag `v2.3.2`. The New Architecture must stay on (React Native
-0.87's default).
+The native libraries come with it, at the package's own version: npm 2.4.2
+uses `io.github.umutcansu:pinvault:2.4.2` from Maven Central and the Swift
+package at tag `v2.4.2`. The New Architecture must stay on (React Native's
+default since 0.76).
 
 **iOS.** The pod depends on the PinVault Swift package through React Native's
 `spm_dependency` (git URL `https://github.com/umutcansu/PinVault.git`, exact
-version = this package's version, product `PinVault`). Info.plist, as for the
-native library:
+version = this package's version, product `PinVault`). On React Native 0.81
+with Xcode 26 or later, React Native's own `fmt` pod does not compile from
+source; install the prebuilt dependencies instead
+(`RCT_USE_RN_DEP=1 RCT_USE_PREBUILT_RNCORE=1 pod install`, 0.87's default).
+Info.plist, as for the native library:
 
 | Key | Why |
 |---|---|
@@ -61,6 +65,43 @@ hooks before `Application.onCreate` runs (see [Networking](#networking)).
 **Release builds.** Put the trust anchors into the app itself, not only into
 the JS bundle: [Native security file](#native-security-file).
 
+### Expo
+
+A native module: it runs in a development build or `expo prebuild`, not in
+Expo Go. The package's config plugin does the steps above at prebuild — iOS
+deployment target 16.0 (`Podfile.properties.json` and the Xcode project),
+the Info.plist keys, the background task in `AppDelegate.swift`, and the
+native security file copied into Android's assets and the iOS app bundle:
+
+```bash
+npx expo install @umutcansu/react-native-pinvault
+```
+
+```json
+{
+  "expo": {
+    "plugins": [
+      ["@umutcansu/react-native-pinvault", {
+        "nativeSecurityFile": "./pinvault_security.json",
+        "faceIDPermission": "Unlock your protected files",
+        "backgroundUpdates": true
+      }]
+    ]
+  }
+}
+```
+
+| Option | Does |
+|---|---|
+| `nativeSecurityFile` | path (from the project root) of your `pinvault_security.json`; checked to be a JSON object at prebuild |
+| `faceIDPermission` | `NSFaceIDUsageDescription`, for vault files behind the screen lock (`userAuth`) |
+| `backgroundUpdates` | `BGTaskSchedulerPermittedIdentifiers`, `UIBackgroundModes` = `fetch` and `PinVaultBridge.registerBackgroundTask()` in a Swift `AppDelegate` (Expo SDK 53+), for `schedulePeriodicUpdates` |
+| `allowNoNativeSecurityFile` | `true` writes the opt-out of the file (Android meta-data, Info.plist): release builds then take anchors from JS — not recommended |
+| `pinReactNativeNetworking` | `false` removes the networking provider and writes `PinVaultPinReactNativeNetworking` = NO: RN's own fetch / WebSocket stay unpinned |
+
+Unknown options and wrong types stop prebuild. Tested with Expo SDK 54
+(React Native 0.81) on Android and iOS, release builds.
+
 ## Quick start
 
 ```ts
@@ -207,11 +248,21 @@ parsed as strictly; a broken file rejects `start` with `E_INVALID_CONFIG`
 - a field the file declares is the value: JS may leave it out (the native value
   applies) or repeat it (lists in any order); a different value rejects `start`
   with `E_INVALID_CONFIG` naming the field;
+- in a release build a declared block must carry its anchors: `bootstrapPins`
+  (or `allowUnpinnedConfigApi`) and `signaturePublicKeys` (or `allowUnsigned`);
+  a block that only names itself rejects `start` — otherwise the bundle would
+  supply the pins and keys;
 - `allowUnsigned`, `allowUnpinnedConfigApi` and `allowServerGeneratedKey` from
-  JS are refused unless the file allows them for that block;
+  JS are refused unless the file allows them for that block; a release build
+  of the native libraries (2.4.2+) refuses the first two unless the block also
+  says `allowRelaxationsInRelease()`, which the bridge adds only where the file
+  allows the relaxation;
 - a block's `url`, `enrollmentUrl`, `renewalUrl`, `tokenHosts` and
   `clientCertHosts` are fixed where the file gives them (where the block talks to, and who gets its token and identity),
   and `attestation: true` / `proofOfPossession: true` there cannot be turned off from JS;
+  in a release build JS may give `clientCertHosts` only where the file names
+  them (the bundle cannot hand the device's identity to another host;
+  `tokenHosts` from JS only narrows the library's default);
 - `require` only tightens: a protection it turns on stays on whatever JS says,
   its `requireCaTrust` hosts are added to JS's, the expected signer / bundle /
   team ids and iOS `userAuthStrength` are fixed, and `expiredConfigGraceSeconds`
@@ -250,8 +301,8 @@ signer check of attestation (`expectedSignerSha256`, `expectedTeamIds`) reports.
   back) on either platform. Request bodies ≤ 10 MiB, responses ≤ 10 MiB by
   default (`maxResponseBytes`, at most 50 MiB) — enforced while the body is
   read on both platforms (a declared `Content-Length` over it is refused first).
-- **React Native's own `fetch`, `XMLHttpRequest` and `<Image>` are pinned on
-  both platforms** (WebSocket on Android only). The rules are the same on both:
+- **React Native's own `fetch`, `XMLHttpRequest`, `<Image>` and `WebSocket`
+  are pinned on both platforms.** The rules are the same on both:
   - **Before `start()`** — and after a start that failed — every `https`
     request through RN's networking fails (`PinVault has not started`): fail
     closed, as the native `getClient()` / `session()` before `init`. Plain
@@ -265,7 +316,7 @@ signer check of attestation (`expectedSignerSha256`, `expectedTeamIds`) reports.
     not go through PinVault (below); on Android a hook replaced after start
     then refuses RN's https too (checked every few seconds). With it off a
     warning is logged.
-- **Android** (two hooks of RN 0.87, read from its sources), installed by the
+- **Android** (three hooks, read from RN 0.81 and 0.87's sources), installed by the
   plugin's content provider before `Application.onCreate`, so every client RN
   builds is covered:
   `NetworkingModule.setCustomClientBuilder` is called for every fetch / XHR
@@ -275,9 +326,14 @@ signer check of attestation (`expectedSignerSha256`, `expectedTeamIds`) reports.
   covers the clients RN builds once — the networking base client, the
   WebSocket / dev-support singleton and Fresco's image client: their TLS goes
   through a forwarding socket factory to the current pinned one.
-  Another library that calls either setter after PinVault (a network inspector,
+  `WebSocketModule.setCustomClientBuilder` is called for every `WebSocket`: up
+  to 0.81 RN builds each socket's client from a bare `OkHttpClient.Builder()`,
+  outside `OkHttpClientProvider`, so without this hook a socket would get the
+  system's trust; from 0.87 it derives from the provider's client. Either way
+  the socket gets the same forwarding factory.
+  Another library that calls any of these setters after PinVault (a network inspector,
   a crash reporter, another pinning package) replaces the hook: `start()` and
-  every `PinVault.fetch` check both (`PinVaultNetworking.status()`) and log a
+  every `PinVault.fetch` check all three (`PinVaultNetworking.status()`) and log a
   warning; `requirePinnedReactNativeNetworking` turns it into a failed start.
   Opt out natively by removing the provider in the app's manifest —
   `android.pinGlobalNetworking: false` alone is refused while the hooks are in
@@ -302,13 +358,21 @@ signer check of attestation (`expectedSignerSha256`, `expectedTeamIds`) reports.
   body in chunks and the completion after the body has been read (progress
   events arrive at the end); cancelling a request cancels it. `start` checks
   which handler RCTNetworking picks for an `https` request.
+  **WebSocket:** RN's `RCTWebSocketModule` uses SocketRocket on CFStream, not
+  URLSession. Every SocketRocket initializer ends in
+  `-initWithURLRequest:protocols:securityPolicy:`; the plugin replaces that
+  method at load (`RNPinVaultWebSocketPinning.mm`), so a socket to a `wss` /
+  `https` URL always gets a security policy that asks
+  `PinVault.shared.evaluateServerTrust(_:host:port:)` — the same pins, host
+  check and fail-closed rule as the https handler — whatever policy its creator
+  passed. SocketRocket judges the trust before it writes the upgrade request,
+  so a refused chain sends no header or cookie. Subprotocols are kept
+  (`RCTSetCustomSRWebSocketProvider` is not used: its block never sees them).
+  `start` checks the hook is still the initializer's implementation. A
+  WebSocket to a host that requires a client certificate fails on iOS (no
+  identity is presented); use it over TLS, or Android.
   Opt out natively with the Info.plist key `PinVaultPinReactNativeNetworking`
-  = NO. **WebSocket is not pinned on iOS:** RN 0.87's `RCTWebSocketModule`
-  uses SocketRocket on CFStream, not URLSession, so it cannot take PinVault's
-  session or delegate; its hook (`RCTSetCustomSRWebSocketProvider` with an
-  `SRSecurityPolicy` whose `evaluateServerTrust:forDomain:` decides) would need
-  a public trust-evaluation API from the PinVault library, which it does not
-  have. Keep secrets off `wss://` on iOS, or send them with `PinVault.fetch`.
+  = NO (both the https handler and the WebSocket hook).
   Keep App Transport Security on (no `NSAllowsArbitraryLoads`).
 
 ## Enrollment and vault tokens
@@ -373,8 +437,8 @@ as one more signal. The decisive check is server-side attestation
 ## Security notes (OWASP MASVS)
 
 - **NETWORK** — pinned native path only; no unpinned fallback; `https` → `http`
-  redirects are not followed; RN's own fetch / XHR / images are pinned on both
-  platforms (WebSocket on Android), fail closed before `start`, and a replaced
+  redirects are not followed; RN's own fetch / XHR / images / WebSocket are pinned on
+  both platforms, fail closed before `start`, and a replaced
   hook is detected.
 - **Trust anchors** — release builds take the relaxations only from the native
   security file; with the file, JS cannot change pins, keys or scopes.
@@ -420,7 +484,9 @@ repository's `:pinvault` (unsigned) into `android/build/pinvault-maven` at every
 build and resolves `io.github.umutcansu:pinvault` only from there — a composite
 build is not possible because PinVault builds with AGP 8.7 and React Native 0.87
 with AGP 9. iOS: the Podfile sets `PINVAULT_IOS_PACKAGE_PATH` to the repository,
-and the podspec hands `spm_dependency` that local path instead of the git tag.
+and the podspec hands `spm_dependency` that local path instead of the git tag. A
+local path needs a React Native whose `spm_dependency` takes one (0.87 does,
+0.81 takes git URLs only); apps on 0.81 use the git tag, as every app outside the repository does.
 
 ## Known limits
 
@@ -429,10 +495,13 @@ and the podspec hands `spm_dependency` that local path instead of the git tag.
   `build_auth_list`); the keystore daemon then keeps a dead connection and every
   Keystore operation fails until it is restarted. Turn `requireUnlockedDevice`
   on for release builds / real devices only (the sample does).
-- iOS: RN's WebSocket is not pinned, and RN's https answers are delivered after
-  the whole (bounded) body is read (above).
-- Android: the networking hooks are detected by reading two private fields of
-  React Native 0.87 (`OkHttpClientProvider.factory`,
-  `NetworkingModule.customClientBuilder`; the consumer R8 rules keep them). A
+- iOS: RN's https answers are delivered after the whole (bounded) body is read,
+  and a WebSocket presents no client certificate (above). The WebSocket hook
+  expects SocketRocket 0.7's designated initializer; another shape reads as
+  not pinned.
+- Android: the networking hooks are detected by reading three private fields
+  of React Native (`OkHttpClientProvider.factory`,
+  `NetworkingModule.customClientBuilder`, `WebSocketModule.customClientBuilder`;
+  the same in 0.81 and 0.87, the consumer R8 rules keep them). A
   React Native version that renames them reads as "could not be read", which
   counts as not pinned.

package/RNPinVault.podspec

@@ -4,7 +4,7 @@ package = JSON.parse(File.read(File.join(__dir__, "package.json")))
 
 # PinVault for iOS is a Swift package (Package.swift at the repository root,
 # product "PinVault"). React Native's spm_dependency adds it to the Pods project:
-#   - consumers: the git URL at the tag of this package's version (v2.4.0);
+#   - consumers: the git URL at the tag of this package's version (v2.4.2);
 #   - development: PINVAULT_IOS_PACKAGE_PATH = a PinVault checkout (the sample's
 #     Podfile sets it to this repository), the counterpart of pinvault.localPath.
 pinvault_url = "https://github.com/umutcansu/PinVault.git"

package/android/build.gradle

@@ -9,7 +9,7 @@ buildscript {
     kotlinVersion: "2.2.0",
     minSdkVersion: 24,
     compileSdkVersion: 36,
-    pinvaultVersion: "2.4.0",
+    pinvaultVersion: "2.4.2",
   ]
   ext.pinvaultRnExt = { prop ->
     rootProject.ext.has(prop) ? rootProject.ext.get(prop) : PinVaultRN[prop]

package/android/consumer-rules.pro

@@ -14,6 +14,9 @@
 -keepclassmembers class com.facebook.react.modules.network.NetworkingModule {
     private static com.facebook.react.modules.network.CustomClientBuilder customClientBuilder;
 }
+-keepclassmembers class com.facebook.react.modules.websocket.WebSocketModule {
+    private static com.facebook.react.modules.network.CustomClientBuilder customClientBuilder;
+}
 # Tink (under the PinVault library's encrypted storage) references Error Prone's
 # compile-time annotations, which no React Native app has on its classpath; R8
 # stops a release build on the missing classes otherwise.

package/android/src/main/java/io/github/umutcansu/pinvault/reactnative/ConfigParser.kt

@@ -152,7 +152,9 @@ internal object ConfigParser {
             a.finish()
         }
         // On by default in a release build: RN's https must go through PinVault there.
-        val requirePinned = root.bool("requirePinnedReactNativeNetworking") ?: (release && pinGlobal)
+        // The native security file can pin this on (RN-3): JS may turn it on, never off.
+        val requirePinned = (root.bool("requirePinnedReactNativeNetworking") ?: (release && pinGlobal)) ||
+            nativeRequire.requirePinnedReactNativeNetworking
         if (requirePinned && !pinGlobal) {
             throw BridgeInputException("config.requirePinnedReactNativeNetworking: contradicts android.pinGlobalNetworking: false")
         }
@@ -192,6 +194,20 @@ internal object ConfigParser {
         return url
     }
 
+    /**
+     * An endpoint path, resolved relative to the block's base URL. An absolute
+     * value — a scheme (`://`) or a root (`/`, `\`) — would silently retarget the
+     * request past the pinned host (`@Url`/`URL(string:relativeTo:)` honour it),
+     * so it is refused (RN-2). Returns null when the optional field is absent.
+     */
+    private fun relEndpoint(f: Fields, key: String, max: Int): String? {
+        val v = f.string(key, max) ?: return null
+        if (v.contains("://") || v.startsWith("/") || v.startsWith("\\")) {
+            throw BridgeInputException("${f.path}.$key: must be a relative path, not an absolute URL")
+        }
+        return v
+    }
+
     fun hostPin(p: Fields): HostPin {
         val hostname = p.requireString("hostname", 255)
         val pins = p.stringList("sha256", MAX_PINS_PER_HOST, 128) ?: throw BridgeInputException("${p.path}.sha256: required")
@@ -223,8 +239,8 @@ internal object ConfigParser {
         val url = httpsUrl(b, "url") ?: throw BridgeInputException("${b.path}.url: required")
         // Read everything before the builder runs, so a refusal names the JSON path.
         val bootstrapPins = b.objList("bootstrapPins", MAX_PINS)?.map(::hostPin)
-        val configEndpoint = b.string("configEndpoint", 512)
-        val healthEndpoint = b.string("healthEndpoint", 512)
+        val configEndpoint = relEndpoint(b, "configEndpoint", 512)
+        val healthEndpoint = relEndpoint(b, "healthEndpoint", 512)
         val oneKey = b.string("signaturePublicKey", KEY_LENGTH, multiline = true)
         val keys = b.stringList("signaturePublicKeys", 16, KEY_LENGTH, multiline = true)
         if (oneKey != null && keys != null) {
@@ -240,9 +256,9 @@ internal object ConfigParser {
         val clientCaPins = b.stringList("clientCaPins", 16, 128)
         val maxLifetime = b.int("maxClientCertLifetimeDays", 1, 3650)
         val clientCertHosts = b.stringList("clientCertHosts", 64, 2048)
-        val enrollmentEndpoint = b.string("enrollmentEndpoint", 512)
-        val clientCertEndpoint = b.string("clientCertEndpoint", 512)
-        val vaultReportEndpoint = b.string("vaultReportEndpoint", 512)
+        val enrollmentEndpoint = relEndpoint(b, "enrollmentEndpoint", 512)
+        val clientCertEndpoint = relEndpoint(b, "clientCertEndpoint", 512)
+        val vaultReportEndpoint = relEndpoint(b, "vaultReportEndpoint", 512)
         val clientCertLabel = b.string("clientCertLabel", 128)
         val wantPinsFor = b.stringList("wantPinsFor", 256, 255)
         val renewalUrl = httpsUrl(b, "renewalUrl")
@@ -273,6 +289,12 @@ internal object ConfigParser {
         val tokenHosts = nativeBlock?.tokenHosts?.also { n ->
             if (jsTokenHosts != null && !NativeSecurity.sameKeys(jsTokenHosts.map(String::lowercase), n.map(String::lowercase))) fixed("tokenHosts")
         } ?: jsTokenHosts
+        // Who gets the device's identity is the file's call in a release build: JS cannot
+        // add a host the file does not name (tokenHosts only narrows the library's default).
+        if (release && nativeBlock != null && nativeBlock.clientCertHosts == null && clientCertHosts != null) {
+            throw BridgeInputException("${b.path}.clientCertHosts: a release build takes it only from the app's native security file " +
+                "(${native?.source}); declare clientCertHosts for Config API '$id' there")
+        }
         val certHosts = nativeBlock?.clientCertHosts?.also { n ->
             if (clientCertHosts != null && !NativeSecurity.sameKeys(clientCertHosts.map(String::lowercase), n.map(String::lowercase))) fixed("clientCertHosts")
         } ?: clientCertHosts
@@ -299,6 +321,8 @@ internal object ConfigParser {
             if (sec.allowUnsigned) this.allowUnsigned()
             sec.serverScope?.let { this.serverScope(it) }
             if (sec.allowUnpinned) this.allowUnpinnedConfigApi()
+            // The native security file allowed them for this block: the library keeps them in a release build too.
+            if (native != null && (sec.allowUnsigned || sec.allowUnpinned)) this.allowRelaxationsInRelease()
             if (sec.allowServerKey) this.allowServerGeneratedKey()
             sec.clientCaPins?.let { this.clientCaPins(it) }
             maxLifetime?.let { this.maxClientCertLifetimeDays(it) }
@@ -326,6 +350,9 @@ internal object ConfigParser {
             throw BridgeInputException("${f.path}.key: must match [A-Za-z0-9._-]{1,64} and not be only dots")
         }
         val endpoint = f.requireString("endpoint", 512)
+        if (endpoint.contains("://") || endpoint.startsWith("/") || endpoint.startsWith("\\")) {
+            throw BridgeInputException("${f.path}.endpoint: must be a relative path, not an absolute URL")
+        }
         val jsSignatureKey = f.string("signaturePublicKey", KEY_LENGTH, multiline = true)
         val updateWithPins = f.bool("updateWithPins")
         val storage = f.enum("storage", StorageStrategy.values())

package/android/src/main/java/io/github/umutcansu/pinvault/reactnative/NativeSecurity.kt

@@ -31,7 +31,8 @@ import java.io.IOException
  *   }],
  *   "staticPins": { "pins": [ … ], "version": 1 },
  *   "require": {
- *     "requireUnlockedDevice": true, "requireHardwareBackedKeys": true, "managedTrustRoots": true,
+ *     "requireUnlockedDevice": true, "requireHardwareBackedKeys": true,
+ *     "requirePinnedReactNativeNetworking": true, "managedTrustRoots": true,
  *     "wipeVaultFilesOnRevocation": true, "requireCaTrust": ["api.example.com"],
  *     "expectedSignerSha256": ["…"], "expiredConfigGraceSeconds": 0, "vaultFileMaxOfflineAgeSeconds": 604800
  *   },
@@ -78,6 +79,8 @@ internal class NativeSecurity(
     class Require(
         val requireUnlockedDevice: Boolean = false,
         val requireHardwareBackedKeys: Boolean = false,
+        /** Pins `requirePinnedReactNativeNetworking`: JS cannot set it false (RN-3). */
+        val requirePinnedReactNativeNetworking: Boolean = false,
         val managedTrustRoots: Boolean = false,
         val wipeVaultFilesOnRevocation: Boolean = false,
         val requireCaTrust: List<String>? = null,
@@ -192,6 +195,7 @@ internal class NativeSecurity(
                     Require(
                         requireUnlockedDevice = r.bool("requireUnlockedDevice") == true,
                         requireHardwareBackedKeys = r.bool("requireHardwareBackedKeys") == true,
+                        requirePinnedReactNativeNetworking = r.bool("requirePinnedReactNativeNetworking") == true,
                         managedTrustRoots = r.bool("managedTrustRoots") == true,
                         wipeVaultFilesOnRevocation = r.bool("wipeVaultFilesOnRevocation") == true,
                         requireCaTrust = r.stringList("requireCaTrust", 64, 255),
@@ -295,6 +299,16 @@ internal object SecurityPolicy {
         relaxation("allowUnpinnedConfigApi", js.allowUnpinned, block.allowUnpinnedConfigApi)
         relaxation("allowServerGeneratedKey", js.allowServerKey, block.allowServerGeneratedKey)
 
+        // A release build's trust anchors come from the file, so a declared block
+        // must carry them: a bare `{"id": …}` would hand pins and keys to the bundle.
+        if (release) {
+            fun anchor(key: String, relaxation: String): Nothing = throw BridgeInputException(
+                "$path.$key: a release build takes it only from the app's native security file (${native.source}); " +
+                    "declare $key for Config API '$id' there (or $relaxation)")
+            if (block.bootstrapPins == null && !block.allowUnpinnedConfigApi) anchor("bootstrapPins", "allowUnpinnedConfigApi")
+            if (block.signaturePublicKeys == null && !block.allowUnsigned) anchor("signaturePublicKeys", "allowUnsigned")
+        }
+
         val pins = block.bootstrapPins?.also { n ->
             if (js.bootstrapPins != null && !NativeSecurity.samePins(js.bootstrapPins, n)) fixed("bootstrapPins")
         } ?: js.bootstrapPins

package/android/src/main/java/io/github/umutcansu/pinvault/reactnative/PinVaultNetworking.kt

@@ -10,6 +10,7 @@ import com.facebook.react.modules.network.CustomClientBuilder
 import com.facebook.react.modules.network.NetworkingModule
 import com.facebook.react.modules.network.OkHttpClientFactory
 import com.facebook.react.modules.network.OkHttpClientProvider
+import com.facebook.react.modules.websocket.WebSocketModule
 import io.github.umutcansu.pinvault.PinVault
 import okhttp3.Cache
 import okhttp3.CookieJar
@@ -35,7 +36,7 @@ import javax.net.ssl.X509TrustManager
  * Startup pattern, without the dependency). [install] stays as an explicit
  * alternative for apps that remove the provider.
  *
- * Two hooks, both verified against React Native 0.87's sources:
+ * Three hooks, verified against React Native 0.81 and 0.87's sources:
  *
  * - `NetworkingModule.setCustomClientBuilder`: RN calls it for **every**
  *   fetch / XHR request on `client.newBuilder()`. Each request gets the
@@ -50,6 +51,11 @@ import javax.net.ssl.X509TrustManager
  *   singleton, Fresco's image client) get a forwarding socket factory: every
  *   TLS handshake uses the pinned factory of the current start. No disk
  *   cache, no `https` → `http` redirects.
+ * - `WebSocketModule.setCustomClientBuilder`: RN calls it for every
+ *   `WebSocket`. Up to 0.81 the module builds each socket's client from a
+ *   bare `OkHttpClient.Builder()`, outside `OkHttpClientProvider`; from 0.87
+ *   it derives it from the provider's client. Either way the socket gets the
+ *   same forwarding factory, gate and network interceptors.
  *
  * Before `start()` — and after a start that failed — every `https` request
  * through RN's networking fails (`IOException: PinVault has not started`),
@@ -59,7 +65,7 @@ import javax.net.ssl.X509TrustManager
  * without a pin entry are refused by PinVault's trust manager like
  * everywhere else.
  *
- * Another library that calls `setOkHttpClientFactory` or
+ * Another library that calls `setOkHttpClientFactory` or either
  * `setCustomClientBuilder` after PinVault replaces these hooks: [status]
  * tells, `start()` and every plugin `fetch` check it and log a warning, and
  * `requirePinnedReactNativeNetworking: true` makes `start()` fail.
@@ -71,11 +77,12 @@ object PinVaultNetworking {
     @Volatile private var installed = false
     @Volatile private var app: Context? = null
 
-    /** The two hooks this object installed; compared by identity in [status]. */
+    /** The hooks this object installed; compared by identity in [status]. */
     private val factory = OkHttpClientFactory {
         pinning.track(pinning.configureLongLived(OkHttpClientProvider.createClientBuilder()).build())
     }
     private val clientBuilder = CustomClientBuilder { builder -> pinning.configurePerRequest(builder) }
+    private val webSocketBuilder = CustomClientBuilder { builder -> pinning.configureLongLived(builder) }
 
     internal val pinning = NetworkPinning(
         applier = { builder -> PinVault.applyTo(builder) },
@@ -87,7 +94,7 @@ object PinVaultNetworking {
     @Volatile private var installedLate = false
 
     /**
-     * Installs both hooks (once per process). The plugin's content provider
+     * Installs the hooks (once per process). The plugin's content provider
      * calls it before `Application.onCreate`; call it yourself in
      * `MainApplication.onCreate`, before `loadReactNative`, only when the app
      * removed that provider.
@@ -103,6 +110,7 @@ object PinVaultNetworking {
         app = context.applicationContext
         OkHttpClientProvider.setOkHttpClientFactory(factory)
         NetworkingModule.setCustomClientBuilder(clientBuilder)
+        WebSocketModule.setCustomClientBuilder(webSocketBuilder)
         installed = true
         installedLate = late
     }
@@ -110,9 +118,9 @@ object PinVaultNetworking {
     @JvmStatic
     val isInstalled: Boolean get() = installed
 
-    /** Whether React Native's two networking hooks are still the ones [install] set. */
+    /** Whether React Native's networking hooks are still the ones [install] set. */
     @JvmStatic
-    fun status(): HookStatus = HookStatus.read(installed, factory, clientBuilder, installedLate)
+    fun status(): HookStatus = HookStatus.read(installed, factory, clientBuilder, webSocketBuilder, installedLate)
 
     private val warned = java.util.concurrent.atomic.AtomicReference<HookStatus?>(null)
 
@@ -135,10 +143,13 @@ data class HookStatus(
     val factoryIsPinVault: Boolean?,
     /** `NetworkingModule`'s custom client builder is PinVault's. */
     val clientBuilderIsPinVault: Boolean?,
+    /** `WebSocketModule`'s custom client builder is PinVault's. */
+    val webSocketBuilderIsPinVault: Boolean?,
     /** Installed only by `start()`: clients React Native built before (Fresco's, among them) keep the system's trust. */
     val installedLate: Boolean = false,
 ) {
-    val pinned: Boolean get() = installed && !installedLate && factoryIsPinVault == true && clientBuilderIsPinVault == true
+    val pinned: Boolean get() = installed && !installedLate && factoryIsPinVault == true &&
+        clientBuilderIsPinVault == true && webSocketBuilderIsPinVault == true
 
     fun describe(): String = when {
         pinned -> "React Native's networking is pinned by PinVault"
@@ -151,20 +162,22 @@ data class HookStatus(
         else -> buildList {
             if (factoryIsPinVault != true) add("OkHttpClientProvider's client factory " + if (factoryIsPinVault == null) "could not be read" else "was replaced by another library")
             if (clientBuilderIsPinVault != true) add("NetworkingModule's custom client builder " + if (clientBuilderIsPinVault == null) "could not be read" else "was replaced by another library")
+            if (webSocketBuilderIsPinVault != true) add("WebSocketModule's custom client builder " + if (webSocketBuilderIsPinVault == null) "could not be read" else "was replaced by another library")
         }.joinToString("; ") + ": React Native's own networking may NOT be pinned"
     }
 
     internal companion object {
-        fun read(installed: Boolean, ourFactory: Any, ourBuilder: Any, installedLate: Boolean = false): HookStatus = HookStatus(
+        fun read(installed: Boolean, ourFactory: Any, ourBuilder: Any, ourWebSocketBuilder: Any, installedLate: Boolean = false): HookStatus = HookStatus(
             installed,
             isOurs(OkHttpClientProvider::class.java, "factory", ourFactory),
             isOurs(NetworkingModule::class.java, "customClientBuilder", ourBuilder),
+            isOurs(WebSocketModule::class.java, "customClientBuilder", ourWebSocketBuilder),
             installedLate,
         )
 
         /**
          * Whether RN's private static field [name] holds [ours]; null when it
-         * cannot be read. The plugin's consumer R8 rules keep both fields' names.
+         * cannot be read. The plugin's consumer R8 rules keep the fields' names.
          */
         private fun isOurs(owner: Class<*>, name: String, ours: Any): Boolean? = try {
             owner.getDeclaredField(name).apply { isAccessible = true }.get(null) === ours
@@ -281,14 +294,18 @@ internal class NetworkPinning(
         pinned.networkInterceptors.forEach { if (it !in builder.networkInterceptors()) builder.addNetworkInterceptor(it) }
     }
 
-    /** Clients RN builds once and keeps: TLS goes through the pinned factory of the current start. */
+    /**
+     * Clients RN builds once and keeps, and each WebSocket's client: TLS goes
+     * through the pinned factory of the current start. Idempotent: from RN
+     * 0.87 a WebSocket's builder derives from a client already configured here.
+     */
     fun configureLongLived(builder: OkHttpClient.Builder): OkHttpClient.Builder {
         val forwarding = ForwardingSocketFactory { template?.sslSocketFactory }
         builder.sslSocketFactory(forwarding, ForwardingTrustManager { template?.x509TrustManager })
-        builder.addInterceptor(httpsGate)
+        if (httpsGate !in builder.interceptors()) builder.addInterceptor(httpsGate)
         // The current start's network interceptors (the per-request pin check of a pooled
         // or coalesced connection, among them) run for these clients too.
-        builder.addNetworkInterceptor(forwardingNetwork)
+        if (forwardingNetwork !in builder.networkInterceptors()) builder.addNetworkInterceptor(forwardingNetwork)
         builder.cache(null)
         builder.followSslRedirects(false)
         return builder

package/app.plugin.js

@@ -0,0 +1,2 @@
+// Expo config plugin: see plugin/withPinVault.js and the README's "Expo" section.
+module.exports = require('./plugin/withPinVault');

package/ios/Core/ConfigParser.swift

@@ -115,7 +115,9 @@ public enum ConfigParser {
 
         // On by default in a release build — unless the app opted out of pinning RN's
         // networking natively (Info.plist PinVaultPinReactNativeNetworking = NO).
-        let requirePinned = try root.bool("requirePinnedReactNativeNetworking") ?? (release && reactNetworkingEnabled)
+        // The native security file can pin this on (RN-3): JS may turn it on, never off.
+        let requirePinned = (try root.bool("requirePinnedReactNativeNetworking") ?? (release && reactNetworkingEnabled))
+            || require.requirePinnedReactNativeNetworking
         // Android-only settings: the Android side reads them; here only their shape is checked.
         _ = try root.object("android")
         var maxRN = ReactNetworking.defaultMaxResponseBytes
@@ -194,6 +196,18 @@ public enum ConfigParser {
         return url
     }
 
+    /// An endpoint path resolved relative to the block's base URL. An absolute
+    /// value — a scheme (`://`) or a root (`/`, `\`) — would silently retarget the
+    /// request past the pinned host (`URL(string:relativeTo:)` honours it), so it
+    /// is refused (RN-2). Returns nil when the optional field is absent.
+    static func relEndpoint(_ f: Fields, _ key: String, maxLength: Int) throws -> String? {
+        guard let v = try f.string(key, maxLength: maxLength) else { return nil }
+        if v.contains("://") || v.hasPrefix("/") || v.hasPrefix("\\") {
+            throw BridgeInputError("\(f.path).\(key): must be a relative path, not an absolute URL")
+        }
+        return v
+    }
+
     public static func hostPin(_ p: Fields) throws -> HostPin {
         let hostname = try p.requireString("hostname", maxLength: 255)
         guard let pins = try p.stringList("sha256", maxItems: maxPinsPerHost, maxLength: 128) else {
@@ -230,8 +244,8 @@ public enum ConfigParser {
         let id = try b.requireString("id", maxLength: 128)
         guard let url = try httpsUrl(b, "url") else { throw BridgeInputError("\(b.path).url: required") }
         let bootstrapPins = try b.objectList("bootstrapPins", maxItems: maxPins)?.map(hostPin)
-        let configEndpoint = try b.string("configEndpoint", maxLength: 512)
-        let healthEndpoint = try b.string("healthEndpoint", maxLength: 512)
+        let configEndpoint = try relEndpoint(b, "configEndpoint", maxLength: 512)
+        let healthEndpoint = try relEndpoint(b, "healthEndpoint", maxLength: 512)
         let oneKey = try b.string("signaturePublicKey", maxLength: keyLength, multiline: true)
         let keys = try b.stringList("signaturePublicKeys", maxItems: 16, maxLength: keyLength, multiline: true)
         if oneKey != nil && keys != nil {
@@ -247,9 +261,9 @@ public enum ConfigParser {
         let clientCaPins = try b.stringList("clientCaPins", maxItems: 16, maxLength: 128)
         let maxLifetime = try b.int("maxClientCertLifetimeDays", min: 1, max: 3650)
         let clientCertHosts = try b.stringList("clientCertHosts", maxItems: 64, maxLength: 2048)
-        let enrollmentEndpoint = try b.string("enrollmentEndpoint", maxLength: 512)
-        let clientCertEndpoint = try b.string("clientCertEndpoint", maxLength: 512)
-        let vaultReportEndpoint = try b.string("vaultReportEndpoint", maxLength: 512)
+        let enrollmentEndpoint = try relEndpoint(b, "enrollmentEndpoint", maxLength: 512)
+        let clientCertEndpoint = try relEndpoint(b, "clientCertEndpoint", maxLength: 512)
+        let vaultReportEndpoint = try relEndpoint(b, "vaultReportEndpoint", maxLength: 512)
         let clientCertLabel = try b.string("clientCertLabel", maxLength: 128)
         let wantPinsFor = try b.stringList("wantPinsFor", maxItems: 256, maxLength: 255)
         let renewalUrl = try httpsUrl(b, "renewalUrl")
@@ -296,6 +310,12 @@ public enum ConfigParser {
             if let j = renewalUrl, j != n { throw fixed("renewalUrl") }
             fixedRenewalUrl = n
         }
+        // Who gets the device's identity is the file's call in a release build: JS cannot
+        // add a host the file does not name (tokenHosts only narrows the library's default).
+        if release, let nativeBlock, nativeBlock.clientCertHosts == nil, clientCertHosts != nil {
+            throw BridgeInputError("\(b.path).clientCertHosts: a release build takes it only from the app's native security file "
+                + "(\(native?.source ?? "")); declare clientCertHosts for Config API '\(id)' there")
+        }
         var certHosts = clientCertHosts
         if let n = nativeBlock?.clientCertHosts {
             if let j = clientCertHosts, !NativeSecurity.sameKeys(lower(j), lower(n)) { throw fixed("clientCertHosts") }
@@ -326,6 +346,8 @@ public enum ConfigParser {
             if sec.allowUnsigned { api.allowUnsigned() }
             if let v = sec.serverScope { api.serverScope(v) }
             if sec.allowUnpinned { api.allowUnpinnedConfigApi() }
+            // The native security file allowed them for this block: the library keeps them in a release build too.
+            if native != nil, sec.allowUnsigned || sec.allowUnpinned { api.allowRelaxationsInRelease() }
             if sec.allowServerKey { api.allowServerGeneratedKey() }
             if let v = sec.clientCaPins { api.clientCaPins(v) }
             if let maxLifetime { api.maxClientCertLifetimeDays(maxLifetime) }
@@ -349,6 +371,9 @@ public enum ConfigParser {
     static func addVaultFile(_ builder: PinVaultConfig.Builder, _ f: Fields, _ tokens: VaultTokenStore, native: NativeSecurity?) throws {
         let key = try f.requireString("key", maxLength: 128)
         let endpoint = try f.requireString("endpoint", maxLength: 512)
+        if endpoint.contains("://") || endpoint.hasPrefix("/") || endpoint.hasPrefix("\\") {
+            throw BridgeInputError("\(f.path).endpoint: must be a relative path, not an absolute URL")
+        }
         let jsSignatureKey = try f.string("signaturePublicKey", maxLength: keyLength, multiline: true)
         let updateWithPins = try f.bool("updateWithPins")
         let storage = try f.enumValue("storage", StorageStrategy.self)

package/ios/Core/NativeSecurity.swift

@@ -11,7 +11,8 @@
 //                      "clientCertHosts",
 //                      "enrollmentUrl", "renewalUrl" }],
 //     "staticPins": { "pins": [...], "version": 1 },
-//     "require": { "requireUnlockedDevice", "requireHardwareBackedKeys", "managedTrustRoots",
+//     "require": { "requireUnlockedDevice", "requireHardwareBackedKeys",
+//                  "requirePinnedReactNativeNetworking", "managedTrustRoots",
 //                  "wipeVaultFilesOnRevocation", "requireCaTrust", "expectedBundleIds",
 //                  "expectedTeamIds", "userAuthStrength", "expiredConfigGraceSeconds",
 //                  "vaultFileMaxOfflineAgeSeconds", "expectedSignerSha256" (Android's, read for the shape) },
@@ -62,6 +63,8 @@ public struct NativeSecurity {
     public struct Require {
         var requireUnlockedDevice = false
         var requireHardwareBackedKeys = false
+        /// Pins `requirePinnedReactNativeNetworking`: JS cannot set it false (RN-3).
+        var requirePinnedReactNativeNetworking = false
         var managedTrustRoots = false
         var wipeVaultFilesOnRevocation = false
         var requireCaTrust: [String]? = nil
@@ -149,6 +152,7 @@ public struct NativeSecurity {
             if let r = try root.object("require") {
                 require.requireUnlockedDevice = try r.bool("requireUnlockedDevice") == true
                 require.requireHardwareBackedKeys = try r.bool("requireHardwareBackedKeys") == true
+                require.requirePinnedReactNativeNetworking = try r.bool("requirePinnedReactNativeNetworking") == true
                 require.managedTrustRoots = try r.bool("managedTrustRoots") == true
                 require.wipeVaultFilesOnRevocation = try r.bool("wipeVaultFilesOnRevocation") == true
                 require.requireCaTrust = try r.stringList("requireCaTrust", maxItems: 64, maxLength: 255)
@@ -255,6 +259,17 @@ enum SecurityPolicy {
         try relaxation("allowUnpinnedConfigApi", js.allowUnpinned, block.allowUnpinnedConfigApi)
         try relaxation("allowServerGeneratedKey", js.allowServerKey, block.allowServerGeneratedKey)
 
+        // A release build's trust anchors come from the file, so a declared block
+        // must carry them: a bare `{"id": …}` would hand pins and keys to the bundle.
+        if release {
+            func anchor(_ key: String, _ relaxation: String) -> BridgeInputError {
+                BridgeInputError("\(path).\(key): a release build takes it only from the app's native security file (\(native.source)); "
+                    + "declare \(key) for Config API '\(id)' there (or \(relaxation))")
+            }
+            if block.bootstrapPins == nil && !block.allowUnpinnedConfigApi { throw anchor("bootstrapPins", "allowUnpinnedConfigApi") }
+            if block.signaturePublicKeys == nil && !block.allowUnsigned { throw anchor("signaturePublicKeys", "allowUnsigned") }
+        }
+
         var out = js
         if let n = block.bootstrapPins {
             if let j = js.bootstrapPins, !NativeSecurity.samePins(j, n) { throw fixed("bootstrapPins") }

package/ios/PinVaultBridge.swift

@@ -29,6 +29,9 @@ public final class PinVaultBridge: NSObject {
     /// RNPinVault.mm: whether RCTNetworking hands an https request to
     /// RNPinVaultURLRequestHandler (true), to another handler (false), or nil = unknown.
     @objc public var reactNetworkingIsPinned: (() -> NSNumber?)?
+    /// RNPinVault.mm: whether SocketRocket hands every wss socket to PinVault
+    /// (RNPinVaultWebSocketPinning); nil = treated as not pinned.
+    @objc public var reactWebSocketIsPinned: (() -> Bool)?
 
     /// `PinVault.shared.registerBackgroundTask()` for the app's AppDelegate (before launch ends):
     /// the app target does not link the PinVault package itself.
@@ -150,12 +153,14 @@ public final class PinVaultBridge: NSObject {
                     return
                 }
                 let pinned = self.reactNetworkingIsPinned?()?.boolValue
-                if pinned != true {
+                let socketPinned = self.reactWebSocketIsPinned?() ?? false
+                if pinned != true || !socketPinned {
                     let why = !PinVaultReactNetworking.enabled
                         ? "Info.plist PinVaultPinReactNativeNetworking is NO"
                         : pinned == nil ? "RCTNetworking's handler could not be checked"
-                        : "RCTNetworking hands https to another RCTURLRequestHandler"
-                    NSLog("PinVault: React Native's own fetch / XMLHttpRequest / images may NOT be pinned (\(why)); README, \"Networking\"")
+                        : pinned == false ? "RCTNetworking hands https to another RCTURLRequestHandler"
+                        : "SocketRocket's WebSocket initializer is not PinVault's (wss is not pinned)"
+                    NSLog("PinVault: React Native's own fetch / XMLHttpRequest / images / WebSocket may NOT be pinned (\(why)); README, \"Networking\"")
                     if parsed.requirePinnedReactNativeNetworking {
                         reject("E_NETWORKING_NOT_PINNED", "requirePinnedReactNativeNetworking: \(why)", nil)
                         return

package/ios/PinVaultReactNetworking.swift

@@ -2,6 +2,7 @@
 // requests (fetch, XMLHttpRequest, <Image>) through PinVault's pinned session.
 // The rules live in Core/ReactNetworking.swift.
 import Foundation
+import Security
 import PinVault
 
 @objc(RNPinVaultReactNetworking)
@@ -17,6 +18,21 @@ public final class PinVaultReactNetworking: NSObject {
         enabled && ReactNetworking.handles(request)
     }
 
+    /// The server-trust check of a `wss` WebSocket (RNPinVaultWebSocketPinning.mm):
+    /// the decision of every PinVault session for the host and port the socket
+    /// was opened for. Fail-closed: before `start`, after a failed one, or
+    /// while a restart resets the library, every handshake is refused.
+    @objc public static func acceptsWebSocketTrust(_ trust: SecTrust, host: String, port: Int) -> Bool {
+        do {
+            try PinVault.shared.evaluateServerTrust(trust, host: host, port: port)
+            return true
+        } catch {
+            let (name, message) = PinVaultBridge.describe(error)
+            NSLog("PinVault: WebSocket to %@:%ld refused (%@: %@)", host, port, name, message)
+            return false
+        }
+    }
+
     /// The request token for RN; nothing reaches the blocks before `resume()`.
     @objc public static func prepare(
         _ request: URLRequest,

package/ios/RNPinVault.mm

@@ -3,6 +3,8 @@
 #import <objc/message.h>
 #import <React/RCTBridgeModule.h>
 
+#import "RNPinVaultWebSocketPinning.h"
+
 #if __has_include(<RNPinVault/RNPinVault-Swift.h>)
 #import <RNPinVault/RNPinVault-Swift.h>
 #else
@@ -51,6 +53,10 @@
       id handler = ((id(*)(id, SEL, NSURLRequest *))objc_msgSend)(networking, selector, probe);
       return @([handler isKindOfClass:ours]);
     };
+    // Whether SocketRocket's initializer still hands every wss socket to PinVault.
+    _bridge.reactWebSocketIsPinned = ^BOOL {
+      return [RNPinVaultWebSocketPinning isPinned];
+    };
   }
   return self;
 }

package/ios/RNPinVaultWebSocketPinning.h

@@ -0,0 +1,21 @@
+// RNPinVaultWebSocketPinning — React Native's WebSocket (SocketRocket) through
+// PinVault's pins on iOS. See RNPinVaultWebSocketPinning.mm.
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface RNPinVaultWebSocketPinning : NSObject
+
+/// Installs the hook when it is not in place yet (it is installed at load;
+/// this covers a SocketRocket image loaded later). NO when it cannot be:
+/// Info.plist opt-out, no SocketRocket initializer of the known shape.
++ (BOOL)install;
+
+/// Whether every SocketRocket socket to a `wss` / `https` URL is judged by
+/// PinVault right now: the hook is installed and still the initializer's
+/// implementation (nothing replaced it since). YES without SocketRocket in the app.
++ (BOOL)isPinned;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/RNPinVaultWebSocketPinning.mm

@@ -0,0 +1,170 @@
+// RNPinVaultWebSocketPinning — React Native's WebSocket through PinVault's
+// pins on iOS.
+//
+// RCTWebSocketModule opens every socket with SocketRocket (SRWebSocket on
+// CFStream), outside URLSession, so the URLRequestHandler never sees it. Every
+// SRWebSocket initializer ends in -initWithURLRequest:protocols:securityPolicy:
+// (SocketRocket 0.7.x, SRWebSocket.m). This file replaces that method at load:
+// a socket to a wss / https URL (SocketRocket's SRURLRequiresSSL) always gets a
+// policy that asks PinVault, whatever policy its creator passed.
+//
+// RCTSetCustomSRWebSocketProvider is not used: its block gets only the
+// request, so the subprotocols RN hands the initializer (graphql-ws, MQTT,
+// STOMP) would be lost, and a provider set later by another library would
+// replace ours without a trace.
+//
+// SocketRocket checks the server trust in -stream:handleEvent: before it
+// writes the upgrade request: a refused chain sends no header and no cookie.
+//
+// The policy is a runtime subclass of SRSecurityPolicy, so the plugin needs
+// neither SocketRocket's headers nor a link to it: no chain validation in the
+// stream (pins replace CA trust, as in every PinVault session), the TLS 1.2
+// floor of SocketRocket's default, and -evaluateServerTrust:forDomain: →
+// PinVault for the host and port of the socket's own URL.
+#import "RNPinVaultWebSocketPinning.h"
+
+#import <Security/Security.h>
+#import <objc/runtime.h>
+#import <os/lock.h>
+
+#if __has_include(<RNPinVault/RNPinVault-Swift.h>)
+#import <RNPinVault/RNPinVault-Swift.h>
+#else
+#import "RNPinVault-Swift.h"
+#endif
+
+typedef id (*RNPVSocketInit)(id, SEL, NSURLRequest *, NSArray *, id);
+
+static os_unfair_lock gLock = OS_UNFAIR_LOCK_INIT;
+static RNPVSocketInit gOriginalInit = NULL;
+static Class gPolicyClass = Nil;
+static char kHostKey;
+static char kPortKey;
+
+static NSString *const kSocketClass = @"SRWebSocket";
+static NSString *const kPolicyClass = @"SRSecurityPolicy";
+static NSString *const kInitSelector = @"initWithURLRequest:protocols:securityPolicy:";
+static NSString *const kUpdateSelector = @"updateSecurityOptionsInStream:";
+static NSString *const kEvaluateSelector = @"evaluateServerTrust:forDomain:";
+
+// SocketRocket's SRURLRequiresSSL.
+static BOOL RequiresTLS(NSURL *url)
+{
+  NSString *scheme = url.scheme.lowercaseString;
+  return [scheme isEqualToString:@"wss"] || [scheme isEqualToString:@"https"];
+}
+
+static void PinnedUpdateSecurityOptions(id self, SEL _cmd, NSStream *stream)
+{
+  [stream setProperty:(__bridge id)CFSTR("kCFStreamSocketSecurityLevelTLSv1_2")
+               forKey:(__bridge NSString *)kCFStreamPropertySocketSecurityLevel];
+  [stream setProperty:@{(__bridge NSString *)kCFStreamSSLValidatesCertificateChain : @NO}
+               forKey:(__bridge NSString *)kCFStreamPropertySSLSettings];
+}
+
+static BOOL PinnedEvaluateServerTrust(id self, SEL _cmd, SecTrustRef trust, NSString *domain)
+{
+  NSString *host = objc_getAssociatedObject(self, &kHostKey);
+  NSNumber *port = objc_getAssociatedObject(self, &kPortKey);
+  if (trust == NULL || host.length == 0 || port == nil) {
+    return NO;
+  }
+  return [RNPinVaultReactNetworking acceptsWebSocketTrust:trust host:host port:port.integerValue];
+}
+
+// The policy class, made once; Nil when SocketRocket's is missing or has another shape.
+static Class PolicyClass(void)
+{
+  static dispatch_once_t once;
+  dispatch_once(&once, ^{
+    Class base = NSClassFromString(kPolicyClass);
+    SEL update = NSSelectorFromString(kUpdateSelector);
+    SEL evaluate = NSSelectorFromString(kEvaluateSelector);
+    Method baseUpdate = base ? class_getInstanceMethod(base, update) : NULL;
+    Method baseEvaluate = base ? class_getInstanceMethod(base, evaluate) : NULL;
+    if (baseUpdate == NULL || baseEvaluate == NULL) {
+      return;
+    }
+    Class sub = objc_allocateClassPair(base, "RNPinVaultSRSecurityPolicy", 0);
+    if (sub == Nil) {
+      return;
+    }
+    class_addMethod(sub, update, (IMP)PinnedUpdateSecurityOptions, method_getTypeEncoding(baseUpdate));
+    class_addMethod(sub, evaluate, (IMP)PinnedEvaluateServerTrust, method_getTypeEncoding(baseEvaluate));
+    objc_registerClassPair(sub);
+    gPolicyClass = sub;
+  });
+  return gPolicyClass;
+}
+
+// A policy for one socket: the host and port SocketRocket connects to (port 0 → 443, as SRProxyConnect).
+static id PolicyFor(NSURL *url)
+{
+  Class cls = PolicyClass();
+  if (cls == Nil) {
+    return nil; // SocketRocket asks nil, which answers NO: refused.
+  }
+  id policy = [[cls alloc] init];
+  NSUInteger port = url.port.unsignedIntValue;
+  objc_setAssociatedObject(policy, &kHostKey, url.host, OBJC_ASSOCIATION_COPY_NONATOMIC);
+  objc_setAssociatedObject(policy, &kPortKey, @(port == 0 ? 443 : port), OBJC_ASSOCIATION_RETAIN_NONATOMIC);
+  return policy;
+}
+
+static id PinnedInit(id self, SEL _cmd, NSURLRequest *request, NSArray *protocols, id securityPolicy)
+{
+  if (RequiresTLS(request.URL)) {
+    securityPolicy = PolicyFor(request.URL);
+  }
+  return gOriginalInit(self, _cmd, request, protocols, securityPolicy);
+}
+
+static Method SocketInit(void)
+{
+  Class socket = NSClassFromString(kSocketClass);
+  return socket ? class_getInstanceMethod(socket, NSSelectorFromString(kInitSelector)) : NULL;
+}
+
+// Info.plist PinVaultPinReactNativeNetworking = NO: the native opt-out of the https handler covers this too.
+static BOOL Enabled(void)
+{
+  id value = [NSBundle.mainBundle objectForInfoDictionaryKey:@"PinVaultPinReactNativeNetworking"];
+  return ![value respondsToSelector:@selector(boolValue)] || [value boolValue];
+}
+
+@implementation RNPinVaultWebSocketPinning
+
++ (void)load
+{
+  [self install];
+}
+
++ (BOOL)install
+{
+  if (!Enabled()) {
+    return NO;
+  }
+  os_unfair_lock_lock(&gLock);
+  BOOL installed = NO;
+  Method method = SocketInit();
+  if (method != NULL && gOriginalInit != NULL) {
+    installed = method_getImplementation(method) == (IMP)PinnedInit;
+  } else if (method != NULL && PolicyClass() != Nil &&
+             strcmp(method_getTypeEncoding(method) ?: "", "@40@0:8@16@24@32") == 0) {
+    gOriginalInit = (RNPVSocketInit)method_getImplementation(method);
+    method_setImplementation(method, (IMP)PinnedInit);
+    installed = YES;
+  }
+  os_unfair_lock_unlock(&gLock);
+  return installed;
+}
+
++ (BOOL)isPinned
+{
+  if (NSClassFromString(kSocketClass) == Nil) {
+    return YES; // No SocketRocket: React Native has no WebSocket to pin.
+  }
+  return [self install];
+}
+
+@end

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umutcansu/react-native-pinvault",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "PinVault for React Native: dynamic certificate pinning with signed remote configs, mTLS enrollment and signed vault files, as a thin bridge over the native PinVault libraries",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -10,7 +10,8 @@
       "types": "./lib/typescript/src/index.d.ts",
       "default": "./lib/module/index.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./app.plugin.js": "./app.plugin.js"
   },
   "files": [
     "src",
@@ -23,6 +24,8 @@
     "ios/*.swift",
     "ios/Core",
     "*.podspec",
+    "app.plugin.js",
+    "plugin",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
@@ -43,7 +46,8 @@
     "mtls",
     "security",
     "ios",
-    "android"
+    "android",
+    "expo"
   ],
   "repository": {
     "type": "git",
@@ -62,9 +66,10 @@
   },
   "peerDependencies": {
     "react": "*",
-    "react-native": ">=0.87.0"
+    "react-native": ">=0.81.0"
   },
   "devDependencies": {
+    "@expo/config-plugins": "^54.0.5",
     "@jest/globals": "^29.7.0",
     "@react-native/babel-preset": "0.87.1",
     "@react-native/jest-preset": "0.87.1",

package/plugin/withPinVault.js

@@ -0,0 +1,232 @@
+// Expo config plugin for @umutcansu/react-native-pinvault: does at
+// `expo prebuild` what the README's Install and "Native security file"
+// sections ask of a bare React Native app.
+//
+//   plugins: [["@umutcansu/react-native-pinvault", {
+//     nativeSecurityFile: "./pinvault_security.json", // → Android assets + iOS app bundle
+//     faceIDPermission: "Unlock your protected files", // NSFaceIDUsageDescription (userAuth vault files)
+//     backgroundUpdates: true,                          // schedulePeriodicUpdates on iOS
+//     allowNoNativeSecurityFile: false,                 // release builds without the file (not recommended)
+//     pinReactNativeNetworking: true                    // false = RN's own networking stays unpinned
+//   }]]
+//
+// Every option is optional. Without `nativeSecurityFile` a release build
+// refuses a config with Config APIs or static pins (README, "Native security
+// file") unless `allowNoNativeSecurityFile` is true.
+const fs = require('fs');
+const path = require('path');
+
+let configPlugins;
+try {
+  configPlugins = require('expo/config-plugins');
+} catch (e) {
+  configPlugins = require('@expo/config-plugins');
+}
+const {
+  AndroidConfig,
+  IOSConfig,
+  withAndroidManifest,
+  withAppDelegate,
+  withDangerousMod,
+  withInfoPlist,
+  withPodfileProperties,
+  withXcodeProject,
+  createRunOncePlugin,
+} = configPlugins;
+
+const pkg = require('../package.json');
+
+const SECURITY_FILE = 'pinvault_security.json';
+const BG_TASK_ID = 'io.github.umutcansu.pinvault.refresh';
+const MIN_IOS = '16.0';
+const ALLOW_NO_FILE_META = 'io.github.umutcansu.pinvault.ALLOW_NO_NATIVE_SECURITY_FILE';
+const NETWORKING_PROVIDER = 'io.github.umutcansu.pinvault.reactnative.PinVaultNetworkingInitializer';
+const KNOWN_OPTIONS = [
+  'nativeSecurityFile',
+  'faceIDPermission',
+  'backgroundUpdates',
+  'allowNoNativeSecurityFile',
+  'pinReactNativeNetworking',
+];
+
+function checkOptions(options) {
+  const props = options || {};
+  const unknown = Object.keys(props).filter((k) => !KNOWN_OPTIONS.includes(k));
+  if (unknown.length > 0) {
+    throw new Error(`[${pkg.name}] unknown plugin option(s): ${unknown.join(', ')} (known: ${KNOWN_OPTIONS.join(', ')})`);
+  }
+  for (const k of ['backgroundUpdates', 'allowNoNativeSecurityFile', 'pinReactNativeNetworking']) {
+    if (props[k] !== undefined && typeof props[k] !== 'boolean') throw new Error(`[${pkg.name}] ${k} must be true or false`);
+  }
+  for (const k of ['nativeSecurityFile', 'faceIDPermission']) {
+    if (props[k] !== undefined && (typeof props[k] !== 'string' || props[k].trim() === '')) {
+      throw new Error(`[${pkg.name}] ${k} must be a non-empty string`);
+    }
+  }
+  return props;
+}
+
+/** "15.1" < "16.0": dotted numeric versions. */
+function versionLess(a, b) {
+  const x = String(a).split('.').map(Number);
+  const y = String(b).split('.').map(Number);
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    const d = (x[i] || 0) - (y[i] || 0);
+    if (d !== 0) return d < 0;
+  }
+  return false;
+}
+
+/** The project's security file, read and parsed (a JSON error stops prebuild, not the app at launch). */
+function readSecurityFile(projectRoot, relative) {
+  const source = path.resolve(projectRoot, relative);
+  if (!fs.existsSync(source)) throw new Error(`[${pkg.name}] nativeSecurityFile not found: ${source}`);
+  const text = fs.readFileSync(source, 'utf8');
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('not a JSON object');
+  } catch (e) {
+    throw new Error(`[${pkg.name}] nativeSecurityFile ${source} is not a JSON object: ${e.message}`);
+  }
+  return text;
+}
+
+/**
+ * AppDelegate.swift: `import RNPinVault` and the background task registration
+ * as the first line of didFinishLaunchingWithOptions. Idempotent.
+ */
+function addBackgroundTaskToAppDelegate(contents, language) {
+  if (language !== 'swift') {
+    throw new Error(`[${pkg.name}] backgroundUpdates needs a Swift AppDelegate (Expo SDK 53+); add the call by hand: README, "Install"`);
+  }
+  if (contents.includes('PinVaultBridge.registerBackgroundTask()')) return contents;
+  let out = contents;
+  if (!/^import RNPinVault$/m.test(out)) {
+    const imports = out.match(/^import .+$/gm);
+    if (!imports) throw new Error(`[${pkg.name}] AppDelegate.swift has no import lines`);
+    const last = imports[imports.length - 1];
+    out = out.replace(last, `${last}\nimport RNPinVault`);
+  }
+  const launch = /(didFinishLaunchingWithOptions launchOptions:[^{]*\{\n)/;
+  if (!launch.test(out)) {
+    throw new Error(`[${pkg.name}] application(_:didFinishLaunchingWithOptions:) not found in AppDelegate.swift`);
+  }
+  return out.replace(
+    launch,
+    '$1    // @umutcansu/react-native-pinvault: schedulePeriodicUpdates (before launch ends)\n' +
+      '    _ = PinVaultBridge.registerBackgroundTask()\n'
+  );
+}
+
+/** Info.plist entries the options ask for. */
+function applyInfoPlist(plist, props) {
+  const out = { ...plist };
+  if (props.faceIDPermission) out.NSFaceIDUsageDescription = props.faceIDPermission;
+  if (props.backgroundUpdates) {
+    const ids = Array.isArray(out.BGTaskSchedulerPermittedIdentifiers) ? [...out.BGTaskSchedulerPermittedIdentifiers] : [];
+    if (!ids.includes(BG_TASK_ID)) ids.push(BG_TASK_ID);
+    out.BGTaskSchedulerPermittedIdentifiers = ids;
+    const modes = Array.isArray(out.UIBackgroundModes) ? [...out.UIBackgroundModes] : [];
+    if (!modes.includes('fetch')) modes.push('fetch');
+    out.UIBackgroundModes = modes;
+  }
+  if (props.allowNoNativeSecurityFile === true) out.PinVaultAllowNoNativeSecurityFile = true;
+  else delete out.PinVaultAllowNoNativeSecurityFile;
+  if (props.pinReactNativeNetworking === false) out.PinVaultPinReactNativeNetworking = false;
+  else delete out.PinVaultPinReactNativeNetworking;
+  return out;
+}
+
+/** AndroidManifest: the allow-no-file meta-data and the networking provider opt-out. */
+function applyAndroidManifest(manifest, props) {
+  const app = AndroidConfig.Manifest.getMainApplicationOrThrow(manifest);
+  if (props.allowNoNativeSecurityFile === true) {
+    AndroidConfig.Manifest.addMetaDataItemToMainApplication(app, ALLOW_NO_FILE_META, 'true');
+  } else {
+    AndroidConfig.Manifest.removeMetaDataItemFromMainApplication(app, ALLOW_NO_FILE_META);
+  }
+  app.provider = (app.provider || []).filter((p) => p.$['android:name'] !== NETWORKING_PROVIDER);
+  if (props.pinReactNativeNetworking === false) {
+    manifest.manifest.$['xmlns:tools'] = manifest.manifest.$['xmlns:tools'] || 'http://schemas.android.com/tools';
+    app.provider.push({
+      $: {
+        'android:name': NETWORKING_PROVIDER,
+        'android:authorities': '${applicationId}.pinvault-networking',
+        'tools:node': 'remove',
+      },
+    });
+  }
+  return manifest;
+}
+
+function withPinVault(config, options) {
+  const props = checkOptions(options);
+
+  // iOS 16: the PinVault Swift package's minimum.
+  config = withPodfileProperties(config, (c) => {
+    const current = c.modResults['ios.deploymentTarget'];
+    if (!current || versionLess(current, MIN_IOS)) c.modResults['ios.deploymentTarget'] = MIN_IOS;
+    return c;
+  });
+  config = withXcodeProject(config, (c) => {
+    const configurations = c.modResults.pbxXCBuildConfigurationSection();
+    for (const key of Object.keys(configurations)) {
+      const settings = configurations[key].buildSettings;
+      if (!settings || settings.IPHONEOS_DEPLOYMENT_TARGET === undefined) continue;
+      if (versionLess(String(settings.IPHONEOS_DEPLOYMENT_TARGET).replace(/"/g, ''), MIN_IOS)) {
+        settings.IPHONEOS_DEPLOYMENT_TARGET = MIN_IOS;
+      }
+    }
+    return c;
+  });
+
+  config = withInfoPlist(config, (c) => {
+    c.modResults = applyInfoPlist(c.modResults, props);
+    return c;
+  });
+  config = withAndroidManifest(config, (c) => {
+    c.modResults = applyAndroidManifest(c.modResults, props);
+    return c;
+  });
+
+  if (props.backgroundUpdates) {
+    config = withAppDelegate(config, (c) => {
+      c.modResults.contents = addBackgroundTaskToAppDelegate(c.modResults.contents, c.modResults.language);
+      return c;
+    });
+  }
+
+  if (props.nativeSecurityFile) {
+    // Android: assets (sealed by the APK signature; README, "Native security file").
+    config = withDangerousMod(config, [
+      'android',
+      async (c) => {
+        const text = readSecurityFile(c.modRequest.projectRoot, props.nativeSecurityFile);
+        const assets = path.join(c.modRequest.platformProjectRoot, 'app', 'src', 'main', 'assets');
+        fs.mkdirSync(assets, { recursive: true });
+        fs.writeFileSync(path.join(assets, SECURITY_FILE), text);
+        return c;
+      },
+    ]);
+    // iOS: a resource of the app target (sealed by the code signature).
+    config = withXcodeProject(config, (c) => {
+      const text = readSecurityFile(c.modRequest.projectRoot, props.nativeSecurityFile);
+      const projectName = c.modRequest.projectName;
+      fs.writeFileSync(path.join(c.modRequest.platformProjectRoot, projectName, SECURITY_FILE), text);
+      const file = `${projectName}/${SECURITY_FILE}`;
+      if (!c.modResults.hasFile(file)) {
+        c.modResults = IOSConfig.XcodeUtils.addResourceFileToGroup({
+          filepath: file,
+          groupName: projectName,
+          project: c.modResults,
+          isBuildFile: true,
+        });
+      }
+      return c;
+    });
+  }
+  return config;
+}
+
+module.exports = createRunOncePlugin(withPinVault, pkg.name, pkg.version);
+module.exports.internal = { addBackgroundTaskToAppDelegate, applyInfoPlist, applyAndroidManifest, checkOptions, versionLess };