@umutcansu/react-native-pinvault 2.3.2 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 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,7 +13,7 @@ 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.
 - Android minSdk 24; iOS 16+.
@@ -19,11 +21,18 @@ ones (`InitResult`, `ClientCertEnrollmentResult`, `VaultFileResult`, …), so th
 
 ## 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.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).
+
 **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
@@ -93,7 +102,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 +176,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 }
+  ]
 }
 ```
 
@@ -183,11 +208,32 @@ parsed as strictly; a broken file rejects `start` with `E_INVALID_CONFIG`
   applies) or repeat it (lists in any order); a different value rejects `start`
   with `E_INVALID_CONFIG` naming the field;
 - `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;
+- `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`).
 
@@ -214,9 +260,11 @@ 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.
+  - `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** (two hooks of RN 0.87, read from its sources), installed by the
   plugin's content provider before `Application.onCreate`, so every client RN
   builds is covered:
@@ -277,7 +325,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 +358,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

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.0);
 #   - 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.0",
   ]
   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

@@ -55,11 +55,16 @@ internal object ConfigParser {
     const val MAX_PINS = 256
     const val MAX_PINS_PER_HOST = 16
     const val KEY_LENGTH = 4096
+    private val VAULT_KEY = Regex("^[A-Za-z0-9._-]{1,64}$")
 
     /**
      * @param native the app's native security file ([NativeSecurity]); null = none.
-     * @param release a release build of the app: without a native file, the
-     *   relaxations (`allowUnsigned`, …) are refused from JS.
+     * @param release a release build of the app: without a native file, a
+     *   config with Config APIs or static pins is refused (unless
+     *   [noFileAllowed]) and the relaxations (`allowUnsigned`, …) are refused
+     *   from JS; `expiredConfigGrace` is capped.
+     * @param noFileAllowed the app's manifest accepts a release start without
+     *   a native security file ([NativeSecurity.NO_FILE_META_DATA]).
      */
     fun parse(
         json: String,
@@ -68,27 +73,64 @@ internal object ConfigParser {
         listener: PinVaultConnectionListener?,
         native: NativeSecurity? = null,
         release: Boolean = false,
+        noFileAllowed: Boolean = false,
     ): ParsedConfig {
         val root = StrictJson.parseObject(json, "config")
         val builder = PinVaultConfig.Builder()
+        val nativeRequire = native?.require ?: NativeSecurity.Require()
 
-        root.objList("configApis", MAX_CONFIG_APIS)?.forEach { addConfigApi(builder, it, native, release) }
-        root.objList("vaultFiles", MAX_VAULT_FILES)?.forEach { addVaultFile(builder, it, tokens) }
+        val configApis = root.objList("configApis", MAX_CONFIG_APIS)
+        val vaultFiles = root.objList("vaultFiles", MAX_VAULT_FILES)
         val staticPins = root.obj("staticPins")?.let(::staticPins)
+        if (release && native == null && !noFileAllowed && (!configApis.isNullOrEmpty() || staticPins != null)) {
+            throw BridgeInputException(
+                "config: a release build takes its trust anchors only from the app's native security file " +
+                    "(assets/${NativeSecurity.ASSET_NAME}, README \"Native security file\"); none is shipped. " +
+                    "An app that accepts JS-only anchors says so in its manifest: meta-data ${NativeSecurity.NO_FILE_META_DATA}=true"
+            )
+        }
+        configApis?.forEach { addConfigApi(builder, it, native, release) }
+        vaultFiles?.forEach { addVaultFile(builder, it, tokens, native) }
         SecurityPolicy.staticPins("config.staticPins", staticPins, native)?.let { builder.staticPins(it) }
 
         root.int("maxRetryCount", 0, 10)?.let { builder.maxRetryCount(it) }
         root.long("updateIntervalHours", 1, 24L * 30)?.let { builder.updateIntervalHours(it) }
         root.long("updateIntervalMinutes", 15, 60L * 24 * 30)?.let { builder.updateIntervalMinutes(it) }
         root.string("deviceAlias", 128)?.let { builder.deviceAlias(it) }
-        root.obj("expiredConfigGrace")?.let { d -> duration(d).let { builder.expiredConfigGrace(it.first, it.second) } }
-        root.stringList("requireCaTrust", 64, 255)?.let { builder.requireCaTrust(*it.toTypedArray()) }
-        if (root.bool("wipeVaultFilesOnRevocation") == true) builder.wipeVaultFilesOnRevocation()
-        root.obj("vaultFileMaxOfflineAge")?.let { d -> duration(d).let { builder.vaultFileMaxOfflineAge(it.first, it.second) } }
-        val requireUnlocked = root.bool("requireUnlockedDevice") == true
-        if (root.bool("requireHardwareBackedKeys") == true) builder.requireHardwareBackedKeys()
-        if (root.bool("managedTrustRoots") == true) builder.managedTrustRoots()
-        root.stringList("expectedSignerSha256", 16, 128)?.let { builder.expectedSignerSha256(it) }
+        root.obj("expiredConfigGrace")?.let { d ->
+            val (amount, unit) = duration(d)
+            val ms = unit.toMillis(amount)
+            if (release && ms > NativeSecurity.MAX_RELEASE_GRACE_MS) {
+                throw BridgeInputException("${d.path}: a release build takes at most 7 days")
+            }
+            nativeRequire.expiredConfigGraceMs?.let { max ->
+                if (ms > max) throw BridgeInputException("${d.path}: longer than the app's native security file allows (${max / 1000} s)")
+            }
+            builder.expiredConfigGrace(amount, unit)
+        } ?: nativeRequire.expiredConfigGraceMs?.let { builder.expiredConfigGrace(it, TimeUnit.MILLISECONDS) }
+        // `require` hosts are added to JS's: JS can name more, never fewer.
+        val caTrust = (root.stringList("requireCaTrust", 64, 255) ?: emptyList()) + (nativeRequire.requireCaTrust ?: emptyList())
+        if (caTrust.isNotEmpty()) builder.requireCaTrust(*caTrust.distinct().toTypedArray())
+        if (root.bool("wipeVaultFilesOnRevocation") == true || nativeRequire.wipeVaultFilesOnRevocation) builder.wipeVaultFilesOnRevocation()
+        root.obj("vaultFileMaxOfflineAge")?.let { d ->
+            val (amount, unit) = duration(d)
+            nativeRequire.vaultFileMaxOfflineAgeMs?.let { max ->
+                val ms = unit.toMillis(amount)
+                // 0 = no limit: longer than any.
+                if (ms == 0L || ms > max) throw BridgeInputException("${d.path}: longer than the app's native security file allows (${max / 1000} s)")
+            }
+            builder.vaultFileMaxOfflineAge(amount, unit)
+        } ?: nativeRequire.vaultFileMaxOfflineAgeMs?.let { builder.vaultFileMaxOfflineAge(it, TimeUnit.MILLISECONDS) }
+        val requireUnlocked = root.bool("requireUnlockedDevice") == true || nativeRequire.requireUnlockedDevice
+        if (root.bool("requireHardwareBackedKeys") == true || nativeRequire.requireHardwareBackedKeys) builder.requireHardwareBackedKeys()
+        if (root.bool("managedTrustRoots") == true || nativeRequire.managedTrustRoots) builder.managedTrustRoots()
+        val signers = root.stringList("expectedSignerSha256", 16, 128)
+        nativeRequire.expectedSignerSha256?.let { fixed ->
+            if (signers != null && !NativeSecurity.sameKeys(signers.map(String::lowercase), fixed.map(String::lowercase))) {
+                throw BridgeInputException("config.expectedSignerSha256: differs from the app's native security file (${native?.source}); the native value is fixed")
+            }
+        }
+        (nativeRequire.expectedSignerSha256 ?: signers)?.let { builder.expectedSignerSha256(it) }
 
         var guardTimeout: Long? = null
         root.obj("environmentGuard")?.let { g ->
@@ -109,7 +151,8 @@ internal object ConfigParser {
             keepCookies = a.bool("keepReactNativeCookies") == true
             a.finish()
         }
-        val requirePinned = root.bool("requirePinnedReactNativeNetworking") == true
+        // On by default in a release build: RN's https must go through PinVault there.
+        val requirePinned = root.bool("requirePinnedReactNativeNetworking") ?: (release && pinGlobal)
         if (requirePinned && !pinGlobal) {
             throw BridgeInputException("config.requirePinnedReactNativeNetworking: contradicts android.pinGlobalNetworking: false")
         }
@@ -206,11 +249,34 @@ internal object ConfigParser {
         val enrollmentUrl = httpsUrl(b, "enrollmentUrl")
         val threshold = b.double("clientCertRenewalThreshold", 0.0, 1.0)
         val disableRenewal = b.bool("disableClientCertRenewal") == true
-        val attestation = b.bool("attestation") == true
+        val jsAttestation = b.bool("attestation")
         val attestationInterval = b.obj("attestationInterval")?.let(::duration)
-        val tokenHosts = b.stringList("tokenHosts", 64, 255)
+        val jsTokenHosts = b.stringList("tokenHosts", 64, 255)
+        val jsProof = b.bool("proofOfPossession")
         b.finish()
 
+        // Where the block talks to and who gets its token and identity: fixed where the file says.
+        val nativeBlock = native?.blocks?.get(id)
+        fun fixed(key: String): Nothing =
+            throw BridgeInputException("${b.path}.$key: differs from the app's native security file (${native?.source}); the native value is fixed")
+        val blockUrl = nativeBlock?.url?.also { if (it != url) fixed("url") } ?: url
+        val fixedEnrollmentUrl = nativeBlock?.enrollmentUrl?.also { if (enrollmentUrl != null && it != enrollmentUrl) fixed("enrollmentUrl") } ?: enrollmentUrl
+        val fixedRenewalUrl = nativeBlock?.renewalUrl?.also { if (renewalUrl != null && it != renewalUrl) fixed("renewalUrl") } ?: renewalUrl
+        if (nativeBlock?.attestation == true && jsAttestation == false) {
+            throw BridgeInputException("${b.path}.attestation: the app's native security file turns it on; JS cannot turn it off")
+        }
+        val attestation = jsAttestation == true || nativeBlock?.attestation == true
+        if (nativeBlock?.proofOfPossession == true && jsProof == false) {
+            throw BridgeInputException("${b.path}.proofOfPossession: the app's native security file turns it on; JS cannot turn it off")
+        }
+        val proof = jsProof == true || nativeBlock?.proofOfPossession == true
+        val tokenHosts = nativeBlock?.tokenHosts?.also { n ->
+            if (jsTokenHosts != null && !NativeSecurity.sameKeys(jsTokenHosts.map(String::lowercase), n.map(String::lowercase))) fixed("tokenHosts")
+        } ?: jsTokenHosts
+        val certHosts = nativeBlock?.clientCertHosts?.also { n ->
+            if (clientCertHosts != null && !NativeSecurity.sameKeys(clientCertHosts.map(String::lowercase), n.map(String::lowercase))) fixed("clientCertHosts")
+        } ?: clientCertHosts
+
         // The trust anchors and relaxations: the native security file decides, JS only repeats.
         val sec = SecurityPolicy.apply(
             b.path, id,
@@ -221,7 +287,7 @@ internal object ConfigParser {
             native, release,
         )
 
-        builder.configApi(id, url) {
+        builder.configApi(id, blockUrl) {
             sec.bootstrapPins?.let { this.bootstrapPins(it) }
             configEndpoint?.let { this.configEndpoint(it) }
             healthEndpoint?.let { this.healthEndpoint(it) }
@@ -236,36 +302,66 @@ internal object ConfigParser {
             if (sec.allowServerKey) this.allowServerGeneratedKey()
             sec.clientCaPins?.let { this.clientCaPins(it) }
             maxLifetime?.let { this.maxClientCertLifetimeDays(it) }
-            clientCertHosts?.let { this.clientCertHosts(it) }
+            certHosts?.let { this.clientCertHosts(it) }
             enrollmentEndpoint?.let { this.enrollmentEndpoint(it) }
             clientCertEndpoint?.let { this.clientCertEndpoint(it) }
             vaultReportEndpoint?.let { this.vaultReportEndpoint(it) }
             clientCertLabel?.let { this.clientCertLabel(it) }
             wantPinsFor?.let { this.wantPinsFor(*it.toTypedArray()) }
-            renewalUrl?.let { this.renewalUrl(it) }
-            enrollmentUrl?.let { this.enrollmentUrl(it) }
+            fixedRenewalUrl?.let { this.renewalUrl(it) }
+            fixedEnrollmentUrl?.let { this.enrollmentUrl(it) }
             threshold?.let { this.clientCertRenewalThreshold(it) }
             if (disableRenewal) this.disableClientCertRenewal()
             if (attestation) this.attestation()
             attestationInterval?.let { this.attestationInterval(it.first, it.second) }
             tokenHosts?.let { this.tokenHosts(it) }
+            if (proof) this.proofOfPossession()
         }
     }
 
-    private fun addVaultFile(builder: PinVaultConfig.Builder, f: Fields, tokens: VaultTokenStore) {
+    private fun addVaultFile(builder: PinVaultConfig.Builder, f: Fields, tokens: VaultTokenStore, native: NativeSecurity?) {
         val key = f.requireString("key", 128)
+        // The same rule as the library's (the key names the stored copy's file).
+        if (!VAULT_KEY.matches(key) || key.all { it == '.' }) {
+            throw BridgeInputException("${f.path}.key: must match [A-Za-z0-9._-]{1,64} and not be only dots")
+        }
         val endpoint = f.requireString("endpoint", 512)
-        val signatureKey = f.string("signaturePublicKey", KEY_LENGTH, multiline = true)
+        val jsSignatureKey = f.string("signaturePublicKey", KEY_LENGTH, multiline = true)
         val updateWithPins = f.bool("updateWithPins")
         val storage = f.enum("storage", StorageStrategy.values())
         val configApi = f.string("configApi", 128)
         val policy = f.enum("accessPolicy", VaultFileAccessPolicy.values())
-        val encryption = f.enum("encryption", VaultFileEncryption.values())
-        val userAuth = f.enum("userAuth", UserAuth.values())
+        val jsEncryption = f.enum("encryption", VaultFileEncryption.values())
+        val jsUserAuth = f.enum("userAuth", UserAuth.values())
         val maxOfflineAge = f.obj("maxOfflineAge")?.let(::duration)
         val wipeWhenStale = f.bool("wipeWhenStale") == true
         f.finish()
 
+        // A file the native security file names keeps its signature key, encryption and lock.
+        val declared = native?.vaultFiles?.let { files ->
+            files[key] ?: throw BridgeInputException("${f.path}: vault file '$key' is not declared in the app's native security file (${native.source})")
+        }
+        fun fixed(field: String): Nothing =
+            throw BridgeInputException("${f.path}.$field: differs from the app's native security file (${native?.source}); the native value is fixed")
+        val signatureKey = declared?.signaturePublicKey?.also { n ->
+            if (jsSignatureKey != null && jsSignatureKey.trim() != n.trim()) fixed("signaturePublicKey")
+        } ?: jsSignatureKey
+        val encryption = declared?.encryption?.also { if (jsEncryption != null && jsEncryption != it) fixed("encryption") } ?: jsEncryption
+        val userAuth = declared?.userAuth?.also { if (jsUserAuth != null && jsUserAuth != it) fixed("userAuth") } ?: jsUserAuth
+        // The tighter of the file's own cap and the config-wide one: a per-file value
+        // overrides the config's, so it must not escape the config-wide cap either.
+        val cap = listOfNotNull(declared?.maxOfflineAgeMs, native?.require?.vaultFileMaxOfflineAgeMs).minOrNull()
+        cap?.let { max ->
+            maxOfflineAge?.let { (amount, unit) ->
+                val ms = unit.toMillis(amount)
+                // 0 = no limit: longer than any.
+                if (ms == 0L || ms > max) {
+                    throw BridgeInputException("${f.path}.maxOfflineAge: longer than the app's native security file allows (${max / 1000} s)")
+                }
+            }
+        }
+        val offlineAge = maxOfflineAge ?: declared?.maxOfflineAgeMs?.let { it to TimeUnit.MILLISECONDS }
+
         builder.vaultFile(key) {
             this.endpoint(endpoint)
             signatureKey?.let { this.signaturePublicKey(it) }
@@ -279,7 +375,7 @@ internal object ConfigParser {
             }
             encryption?.let { this.encryption(it) }
             userAuth?.let { this.userAuth(it) }
-            maxOfflineAge?.let { this.maxOfflineAge(it.first, it.second) }
+            offlineAge?.let { this.maxOfflineAge(it.first, it.second) }
             if (wipeWhenStale) this.wipeWhenStale()
         }
     }

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

@@ -4,6 +4,8 @@ import android.content.Context
 import android.content.pm.ApplicationInfo
 import io.github.umutcansu.pinvault.model.CertificateConfig
 import io.github.umutcansu.pinvault.model.HostPin
+import io.github.umutcansu.pinvault.model.UserAuth
+import io.github.umutcansu.pinvault.model.VaultFileEncryption
 import java.io.FileNotFoundException
 import java.io.IOException
 
@@ -22,9 +24,18 @@ import java.io.IOException
  *     "signaturePublicKeys": ["…", "…"], "requiredSignatures": 2,
  *     "recoveryPublicKeys": ["…"], "requiredRecoverySignatures": 1,
  *     "serverScope": "default-tls", "clientCaPins": ["…"],
+ *     "url": "https://config.example.com/", "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": ["…"], "expiredConfigGraceSeconds": 0, "vaultFileMaxOfflineAgeSeconds": 604800
+ *   },
+ *   "vaultFiles": [{ "key": "statement", "signaturePublicKey": "…", "encryption": "USER_AUTH", "userAuth": "REQUIRED", "maxOfflineAgeSeconds": 86400 }]
  * }
  * ```
  *
@@ -35,18 +46,57 @@ import java.io.IOException
  * - a field the file declares is the value: JS may leave it out or repeat it,
  *   a different value is refused (`E_INVALID_CONFIG`);
  * - `allowUnsigned`, `allowUnpinnedConfigApi`, `allowServerGeneratedKey` from
- *   JS are refused unless the file allows them for that block.
+ *   JS are refused unless the file allows them for that block;
+ * - `url`, `tokenHosts` and `clientCertHosts` of a block are fixed where the
+ *   file gives them, and `attestation: true` / `proofOfPossession: true` there
+ *   cannot be switched off;
+ * - `require` only tightens: a protection it turns on stays on whatever JS
+ *   says, `requireCaTrust` hosts are added to JS's, `expectedSignerSha256` is
+ *   fixed, and `expiredConfigGraceSeconds` is the most JS may ask for;
+ * - `vaultFiles` fixes those files' signature key, encryption and screen lock;
+ *   with the section present, a JS vault file it does not name is refused.
  *
- * Without the file, release builds (the app is not debuggable) refuse those
- * three relaxations from JS; debug builds take them as before.
+ * Without the file, release builds (the app is not debuggable) refuse to start
+ * a config with Config APIs or static pins: the trust anchors would come from
+ * JS alone. An app that accepts that says so natively, in its manifest
+ * (`<meta-data android:name="io.github.umutcansu.pinvault.ALLOW_NO_NATIVE_SECURITY_FILE" android:value="true"/>`);
+ * the three relaxations stay refused from JS then. Debug builds take
+ * everything as before. Whatever the file says, a release build caps
+ * `expiredConfigGrace` at [MAX_RELEASE_GRACE_MS].
  */
 internal class NativeSecurity(
     /** Where the file came from, for messages. */
     val source: String,
     val blocks: Map<String, Block>,
     val staticPins: CertificateConfig?,
+    val require: Require = Require(),
+    /** Null when the file has no `vaultFiles` section. */
+    val vaultFiles: Map<String, VaultFilePolicy>? = null,
 ) {
 
+    /** The `require` section: protections JS cannot switch off. */
+    class Require(
+        val requireUnlockedDevice: Boolean = false,
+        val requireHardwareBackedKeys: Boolean = false,
+        val managedTrustRoots: Boolean = false,
+        val wipeVaultFilesOnRevocation: Boolean = false,
+        val requireCaTrust: List<String>? = null,
+        val expectedSignerSha256: List<String>? = null,
+        /** The most `expiredConfigGrace` JS may set; null = only the release cap. */
+        val expiredConfigGraceMs: Long? = null,
+        /** The most `vaultFileMaxOfflineAge` JS may set (and the value when JS sets none); null = no rule. */
+        val vaultFileMaxOfflineAgeMs: Long? = null,
+    )
+
+    /** One `vaultFiles` entry: what JS cannot change about that file. */
+    class VaultFilePolicy(
+        val signaturePublicKey: String?,
+        val encryption: VaultFileEncryption?,
+        val userAuth: UserAuth?,
+        /** The most `maxOfflineAge` JS may give this file (and the value when JS gives none). */
+        val maxOfflineAgeMs: Long? = null,
+    )
+
     class Block(
         val bootstrapPins: List<HostPin>?,
         val signaturePublicKeys: List<String>?,
@@ -58,10 +108,25 @@ internal class NativeSecurity(
         val allowUnsigned: Boolean,
         val allowUnpinnedConfigApi: Boolean,
         val allowServerGeneratedKey: Boolean,
+        val url: String? = null,
+        val attestation: Boolean = false,
+        val tokenHosts: List<String>? = null,
+        val proofOfPossession: Boolean = false,
+        val clientCertHosts: List<String>? = null,
+        val enrollmentUrl: String? = null,
+        val renewalUrl: String? = null,
     )
 
     companion object {
         const val ASSET_NAME = "pinvault_security.json"
+        const val NO_FILE_META_DATA = "io.github.umutcansu.pinvault.ALLOW_NO_NATIVE_SECURITY_FILE"
+        /** The longest `expiredConfigGrace` a release build takes: an expired pin set must not live on for months. */
+        const val MAX_RELEASE_GRACE_MS = 7L * 24 * 3600 * 1000
+        private const val MAX_OFFLINE_AGE_S = 10L * 365 * 24 * 3600
+
+        private fun httpsOnly(b: Fields, key: String): String? = b.string(key, 2048)?.also {
+            if (!it.startsWith("https://")) throw BridgeInputException("${b.path}.$key: must be an https:// URL")
+        }
         private const val MAX_FILE_CHARS = 256 * 1024
 
         /** The file from the app's assets; null when the app ships none. A broken file throws [BridgeInputException]. */
@@ -77,6 +142,15 @@ internal class NativeSecurity(
             return parse(text, "assets/$ASSET_NAME")
         }
 
+        /** True when the app's manifest says it starts without a native security file in release. */
+        fun noFileAllowed(context: Context): Boolean = try {
+            @Suppress("DEPRECATION")
+            context.packageManager.getApplicationInfo(context.packageName, android.content.pm.PackageManager.GET_META_DATA)
+                .metaData?.getBoolean(NO_FILE_META_DATA, false) == true
+        } catch (_: Exception) {
+            false
+        }
+
         /** True for a release build of the app (not `android:debuggable`). */
         fun isReleaseBuild(context: Context): Boolean =
             (context.applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE) == 0
@@ -103,15 +177,56 @@ internal class NativeSecurity(
                         allowUnsigned = b.bool("allowUnsigned") == true,
                         allowUnpinnedConfigApi = b.bool("allowUnpinnedConfigApi") == true,
                         allowServerGeneratedKey = b.bool("allowServerGeneratedKey") == true,
+                        url = httpsOnly(b, "url"),
+                        attestation = b.bool("attestation") == true,
+                        tokenHosts = b.stringList("tokenHosts", 64, 255),
+                        proofOfPossession = b.bool("proofOfPossession") == true,
+                        clientCertHosts = b.stringList("clientCertHosts", 64, 2048),
+                        enrollmentUrl = httpsOnly(b, "enrollmentUrl"),
+                        renewalUrl = httpsOnly(b, "renewalUrl"),
                     )
                     b.finish()
                 }
                 val staticPins = root.obj("staticPins")?.let(ConfigParser::staticPins)
+                val require = root.obj("require")?.let { r ->
+                    Require(
+                        requireUnlockedDevice = r.bool("requireUnlockedDevice") == true,
+                        requireHardwareBackedKeys = r.bool("requireHardwareBackedKeys") == true,
+                        managedTrustRoots = r.bool("managedTrustRoots") == true,
+                        wipeVaultFilesOnRevocation = r.bool("wipeVaultFilesOnRevocation") == true,
+                        requireCaTrust = r.stringList("requireCaTrust", 64, 255),
+                        expectedSignerSha256 = r.stringList("expectedSignerSha256", 16, 128),
+                        expiredConfigGraceMs = r.long("expiredConfigGraceSeconds", 0, MAX_RELEASE_GRACE_MS / 1000)?.let { it * 1000 },
+                        vaultFileMaxOfflineAgeMs = r.long("vaultFileMaxOfflineAgeSeconds", 1, MAX_OFFLINE_AGE_S)?.let { it * 1000 },
+                    ).also {
+                        // iOS-only (screen-lock strength): read for the shape, used by the iOS side.
+                        r.string("userAuthStrength", 32)
+                        // iOS-only (bundle and team ids): read for the shape, used by the iOS side.
+                        r.stringList("expectedBundleIds", 16, 255)
+                        r.stringList("expectedTeamIds", 16, 32)
+                        r.finish()
+                    }
+                } ?: Require()
+                val vaultFiles = root.objList("vaultFiles", ConfigParser.MAX_VAULT_FILES)?.let { list ->
+                    val map = LinkedHashMap<String, VaultFilePolicy>()
+                    list.forEach { f ->
+                        val key = f.requireString("key", 128)
+                        if (key in map) throw BridgeInputException("${f.path}.key: '$key' is declared twice")
+                        map[key] = VaultFilePolicy(
+                            signaturePublicKey = f.string("signaturePublicKey", ConfigParser.KEY_LENGTH, multiline = true),
+                            encryption = f.enum("encryption", VaultFileEncryption.values()),
+                            userAuth = f.enum("userAuth", UserAuth.values()),
+                            maxOfflineAgeMs = f.long("maxOfflineAgeSeconds", 1, MAX_OFFLINE_AGE_S)?.let { it * 1000 },
+                        )
+                        f.finish()
+                    }
+                    map
+                }
                 root.finish()
                 if (blocks.isEmpty() && staticPins == null) {
                     throw BridgeInputException("$source: declares neither configApis nor staticPins")
                 }
-                return NativeSecurity(source, blocks, staticPins)
+                return NativeSecurity(source, blocks, staticPins, require, vaultFiles)
             } catch (e: BridgeInputException) {
                 val message = e.message ?: ""
                 throw BridgeInputException(if (message.startsWith("native security file")) message else "native security file $message")