@umutcansu/react-native-pinvault 2.4.1 → 2.4.2

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # 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

package/README.md

@@ -29,9 +29,9 @@ 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
+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
@@ -65,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
@@ -216,7 +253,10 @@ parsed as strictly; a broken file rejects `start` with `E_INVALID_CONFIG`
   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;

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.1);
+#   - 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.1",
+    pinvaultVersion: "2.4.2",
   ]
   ext.pinvaultRnExt = { prop ->
     rootProject.ext.has(prop) ? rootProject.ext.get(prop) : PinVaultRN[prop]

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

@@ -321,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) }

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

@@ -346,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) }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umutcansu/react-native-pinvault",
-  "version": "2.4.1",
+  "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",
@@ -65,6 +69,7 @@
     "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 };