@umutcansu/react-native-pinvault 2.3.2 → 2.4.1

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## 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
+
+- **Release builds need the native security file** when the config has Config
+  APIs or static pins (Android manifest meta-data
+  `io.github.umutcansu.pinvault.ALLOW_NO_NATIVE_SECURITY_FILE` / iOS Info.plist
+  `PinVaultAllowNoNativeSecurityFile` = YES opts out).
+- **`requirePinnedReactNativeNetworking` is on by default in release builds.**
+- **`expiredConfigGrace` is at most 7 days in release builds.**
+- **Vault file keys** must match `[A-Za-z0-9._-]{1,64}` (not only dots).
+
+### Security
+
+- The native security file may also fix a block's `url`, `tokenHosts`,
+  `clientCertHosts` and `attestation`, carry a `require` section (protections
+  JS cannot switch off) and `vaultFiles` (signature key, encryption, lock).
+- `start` answers `nativeSecurityApplied`.
+- `proofOfPossession` on a Config API (JS or the native security file, where
+  it cannot be switched off): the native clients add a `PinVault-Proof` signed
+  by the device key to every request that carries the token (ATTESTATION.md §5.1).
+- Android: React Native's long-lived clients (WebSocket, images) run the
+  current start's network interceptors (the per-request pin check) and their
+  pooled connections are closed on every start and reset; a hook installed only
+  by `start()` is reported as not pinned; a hook replaced after start refuses
+  https while `requirePinnedReactNativeNetworking` is on.
+- The JS guard of a start the native side refuses is put back.
+- `LOAD_FILE` is a guarded operation (`loadFile`).
+
 ## 2.3.2 — 2026-10-08 — first release
 
 First published version (2.3.1 was never published). Needs PinVault 2.3.2 on both platforms.

package/README.md

@@ -1,5 +1,7 @@
 # PinVault for React Native
 
+[![npm](https://img.shields.io/npm/v/@umutcansu/react-native-pinvault)](https://www.npmjs.com/package/@umutcansu/react-native-pinvault)
+
 `@umutcansu/react-native-pinvault` — dynamic certificate pinning with a signed,
 remotely updated pin config, mTLS enrollment with a hardware identity key,
 signed and encrypted vault files, and device attestation, for React Native
@@ -11,23 +13,34 @@ It is a thin bridge over the two native libraries — Android
 Secure Enclave), signature checks and vault decryption all stay native: no
 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/README.md) applies as it is.
+[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.
 
 ## Install
 
+From npm ([`@umutcansu/react-native-pinvault`](https://www.npmjs.com/package/@umutcansu/react-native-pinvault)):
+
 ```bash
 npm install @umutcansu/react-native-pinvault
 cd ios && pod install
 ```
 
+The native libraries come with it, at the package's own version: npm 2.4.0
+uses `io.github.umutcansu:pinvault:2.4.0` from Maven Central and the Swift
+package at tag `v2.4.0`. 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 |
 |---|---|
@@ -93,7 +106,7 @@ names), enum values are the Kotlin constant names (`'TOKEN_MTLS'`,
 ```ts
 {
   configApis: [{ id, url, bootstrapPins, signaturePublicKeys, requiredSignatures, recoveryPublicKeys,
-                 serverScope, clientCaPins, clientCertHosts, renewalUrl, attestation, tokenHosts, … }],
+                 serverScope, clientCaPins, clientCertHosts, renewalUrl, attestation, tokenHosts, proofOfPossession, … }],
   vaultFiles: [{ key, endpoint, configApi, accessPolicy, encryption, userAuth, storage,
                  maxOfflineAge: { amount: 7, unit: 'DAYS' }, … }],
   requireCaTrust, requireUnlockedDevice, requireHardwareBackedKeys, expectedSignerSha256,
@@ -167,9 +180,25 @@ signature. Ship them natively as well, in `pinvault_security.json`:
     "signaturePublicKeys": ["…", "…", "…"], "requiredSignatures": 2,
     "recoveryPublicKeys": ["…"], "requiredRecoverySignatures": 1,
     "serverScope": "default-tls", "clientCaPins": ["…"],
+    "url": "https://config.example.com:8081/", "attestation": true,
+    "tokenHosts": ["api.example.com"], "proofOfPossession": true, "clientCertHosts": ["api.example.com:443"],
+    "enrollmentUrl": "https://enroll.example.com/", "renewalUrl": "https://renew.example.com/",
     "allowUnsigned": false, "allowUnpinnedConfigApi": false, "allowServerGeneratedKey": false
   }],
-  "staticPins": { "pins": [ … ], "version": 1 }
+  "staticPins": { "pins": [ … ], "version": 1 },
+  "require": {
+    "requireUnlockedDevice": true, "requireHardwareBackedKeys": true,
+    "managedTrustRoots": true, "wipeVaultFilesOnRevocation": true,
+    "requireCaTrust": ["api.example.com"],
+    "expectedSignerSha256": ["…"],
+    "expectedBundleIds": ["com.example.app"], "expectedTeamIds": ["ABCDE12345"],
+    "expiredConfigGraceSeconds": 0, "vaultFileMaxOfflineAgeSeconds": 604800,
+    "userAuthStrength": "BIOMETRIC_CURRENT_SET"
+  },
+  "vaultFiles": [
+    { "key": "statement", "signaturePublicKey": "…", "encryption": "USER_AUTH", "userAuth": "REQUIRED",
+      "maxOfflineAgeSeconds": 86400 }
+  ]
 }
 ```
 
@@ -182,12 +211,40 @@ 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 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`
+  / `vaultFileMaxOfflineAgeSeconds` are the most JS may ask for (the value when
+  JS asks for none)
+  (Android reads `expectedSignerSha256`, iOS the bundle and team ids; one file
+  can serve both);
+- `vaultFiles` fixes those files' signature key, encryption and screen lock, and
+  `maxOfflineAgeSeconds` is the longest offline lifetime JS may give them;
+  with the section present, a JS vault file it does not name is refused.
+
+`start` answers `nativeSecurityApplied: true` when the file was applied.
 
 Without the file, **release builds** (Android: the app is not
-`android:debuggable`; iOS: compiled without `DEBUG`) refuse those three
-relaxations from JS; debug builds take them as before. The sample app writes
+`android:debuggable`; iOS: compiled without `DEBUG`) refuse to start a config
+with Config APIs or static pins: its trust anchors would come from JS alone.
+An app that accepts that says so natively — Android:
+`<meta-data android:name="io.github.umutcansu.pinvault.ALLOW_NO_NATIVE_SECURITY_FILE" android:value="true"/>`
+in the manifest's `<application>`; iOS: `PinVaultAllowNoNativeSecurityFile` =
+YES in Info.plist — and the three relaxations stay refused from JS then. Debug
+builds take everything as before. Whatever the file says, a release build
+takes an `expiredConfigGrace` of at most 7 days. The sample app writes
 the file for its release builds from `sample-host.properties`
 (`scripts/gen-host-config.js --native-out`).
 
@@ -204,8 +261,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
@@ -214,10 +271,12 @@ signer check of attestation (`expectedSignerSha256`, `expectedTeamIds`) reports.
   - Hosts without a pin entry are refused like everywhere else in PinVault.
   - No `https` → `http` redirects; no disk HTTP cache and no cookie jar (Android:
     `android.keepReactNativeHttpCache` / `keepReactNativeCookies` keep RN's own).
-  - `requirePinnedReactNativeNetworking: true` makes `start` fail with
-    `E_NETWORKING_NOT_PINNED` when RN's networking does not go through PinVault
-    (below); without it a warning is logged.
-- **Android** (two hooks of RN 0.87, read from its sources), installed by the
+  - `requirePinnedReactNativeNetworking` (on by default in release builds)
+    makes `start` fail with `E_NETWORKING_NOT_PINNED` when RN's networking does
+    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** (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
@@ -227,9 +286,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
@@ -254,13 +318,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
@@ -277,7 +349,10 @@ value until the garbage collector drops it, and if it went through React
 state, a form field or a store, it lives there too. Pass it straight from where
 it came from, clear the field, and never persist or log it. For an attestation
 `PinVault-Token`, prefer `tokenHosts` + `PinVault.fetch` (the native client adds
-it) over `fetchAttestationToken`, which hands the token to JS. Forget vault
+it) over `fetchAttestationToken`, which hands the token to JS. With
+`proofOfPossession` the native client also adds a `PinVault-Proof` signed by the
+device key on every such request, and a backend that requires it refuses the
+token alone — a token in JS is then of no use without the native client. Forget vault
 tokens on a revocation:
 
 ```ts
@@ -307,10 +382,10 @@ environmentGuard: async (operation) => !(await myRaspSaysCompromised()),
 environmentGuardTimeoutMs: 5000,
 ```
 
-Asked before `INIT`, `ENROLL`, `FETCH_FILE` and `UNLOCK_FILE`. On iOS the bridge
-asks before it calls the library (`start`: `INIT` and `ENROLL`; enrollment
-calls: `ENROLL`; `fetchFile` / `syncAllFiles`: `FETCH_FILE`; `unlockFile`:
-`UNLOCK_FILE`), so the wait for JS holds no thread; an operation the library
+Asked before `INIT`, `ENROLL`, `FETCH_FILE`, `UNLOCK_FILE` and `LOAD_FILE`. On iOS
+the bridge asks before it calls the library (`start`: `INIT` and `ENROLL`;
+enrollment calls: `ENROLL`; `fetchFile` / `syncAllFiles`: `FETCH_FILE`;
+`unlockFile`: `UNLOCK_FILE`; `loadFile`: `LOAD_FILE`), so the wait for JS holds no thread; an operation the library
 starts on its own (a background refresh) still waits on its own thread,
 bounded by the timeout. **Fail closed:**
 a timeout (native deadline 100–30 000 ms, default 5000), a thrown error, a
@@ -322,8 +397,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.
@@ -369,7 +444,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
 
@@ -378,10 +455,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.3.2);
+#   - consumers: the git URL at the tag of this package's version (v2.4.1);
 #   - 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.3.2",
+    pinvaultVersion: "2.4.1",
   ]
   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.