@umutcansu/react-native-pinvault 0.0.0-stage → 2.3.2

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

@@ -0,0 +1,300 @@
+package io.github.umutcansu.pinvault.reactnative
+
+import io.github.umutcansu.pinvault.api.PinVaultConnectionListener
+import io.github.umutcansu.pinvault.model.CertificateConfig
+import io.github.umutcansu.pinvault.model.EnvironmentGuard
+import io.github.umutcansu.pinvault.model.HostPin
+import io.github.umutcansu.pinvault.model.PinVaultConfig
+import io.github.umutcansu.pinvault.model.StorageStrategy
+import io.github.umutcansu.pinvault.model.UserAuth
+import io.github.umutcansu.pinvault.model.VaultFileAccessPolicy
+import io.github.umutcansu.pinvault.model.VaultFileConfig
+import io.github.umutcansu.pinvault.model.VaultFileEncryption
+import io.github.umutcansu.pinvault.model.VaultFileUnlockPrompt
+import java.util.concurrent.TimeUnit
+
+/** What `start(config)` needs besides the library's own config. */
+internal class ParsedConfig(
+    val config: PinVaultConfig,
+    /** Non-null when JS registered an `environmentGuard`. */
+    val guardTimeoutMs: Long?,
+    /** `android.pinGlobalNetworking` (default true). */
+    val pinGlobalNetworking: Boolean,
+    /** RN's networking options of `android` and `requirePinnedReactNativeNetworking`. */
+    val networking: NetworkingOptions = NetworkingOptions(),
+    /** True when a native security file was applied. */
+    val nativeSecurityApplied: Boolean = false,
+)
+
+/** How React Native's own networking is pinned (see [PinVaultNetworking]). */
+internal data class NetworkingOptions(
+    /** `requirePinnedReactNativeNetworking`: start fails when RN's hooks are not PinVault's. */
+    val requirePinned: Boolean = false,
+    /** `android.keepReactNativeHttpCache`: RN's 10 MiB disk HTTP cache for fetch / XHR (default off). */
+    val keepHttpCache: Boolean = false,
+    /** `android.keepReactNativeCookies`: RN's persistent cookie jar for fetch / XHR (default off). */
+    val keepCookies: Boolean = false,
+)
+
+/**
+ * JSON config from JS → [PinVaultConfig] through the library's own builders,
+ * so every builder rule (`require`) still applies. The JSON keys are the
+ * builder method names. Unknown keys, wrong types and out-of-range sizes are
+ * refused with [BridgeInputException]; builder refusals surface as their
+ * `IllegalArgumentException` (both are `E_INVALID_CONFIG` for JS).
+ *
+ * Not exposed on purpose: `clientKeystore(bytes, password)` (a P12 and its
+ * password would cross the JS bridge — enroll instead), custom
+ * `CertificateConfigApi` / storage providers / integrity providers (native
+ * objects), `reportToPinVaultBackend`.
+ */
+internal object ConfigParser {
+
+    const val MAX_CONFIG_APIS = 16
+    const val MAX_VAULT_FILES = 64
+    const val MAX_PINS = 256
+    const val MAX_PINS_PER_HOST = 16
+    const val KEY_LENGTH = 4096
+
+    /**
+     * @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.
+     */
+    fun parse(
+        json: String,
+        tokens: VaultTokenStore,
+        guardFactory: (timeoutMs: Long) -> EnvironmentGuard,
+        listener: PinVaultConnectionListener?,
+        native: NativeSecurity? = null,
+        release: Boolean = false,
+    ): ParsedConfig {
+        val root = StrictJson.parseObject(json, "config")
+        val builder = PinVaultConfig.Builder()
+
+        root.objList("configApis", MAX_CONFIG_APIS)?.forEach { addConfigApi(builder, it, native, release) }
+        root.objList("vaultFiles", MAX_VAULT_FILES)?.forEach { addVaultFile(builder, it, tokens) }
+        val staticPins = root.obj("staticPins")?.let(::staticPins)
+        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) }
+
+        var guardTimeout: Long? = null
+        root.obj("environmentGuard")?.let { g ->
+            guardTimeout = g.long("timeoutMs", JsEnvironmentGuard.MIN_TIMEOUT_MS, JsEnvironmentGuard.MAX_TIMEOUT_MS)
+                ?: JsEnvironmentGuard.DEFAULT_TIMEOUT_MS
+            g.finish()
+            builder.environmentGuard(guardFactory(guardTimeout!!))
+        }
+
+        var allowFallback = false
+        var pinGlobal = true
+        var keepCache = false
+        var keepCookies = false
+        root.obj("android")?.let { a ->
+            allowFallback = a.bool("requireUnlockedDeviceAllowFallback") == true
+            pinGlobal = a.bool("pinGlobalNetworking") ?: true
+            keepCache = a.bool("keepReactNativeHttpCache") == true
+            keepCookies = a.bool("keepReactNativeCookies") == true
+            a.finish()
+        }
+        val requirePinned = root.bool("requirePinnedReactNativeNetworking") == true
+        if (requirePinned && !pinGlobal) {
+            throw BridgeInputException("config.requirePinnedReactNativeNetworking: contradicts android.pinGlobalNetworking: false")
+        }
+        if (allowFallback && !requireUnlocked) {
+            throw BridgeInputException("config.android.requireUnlockedDeviceAllowFallback: needs requireUnlockedDevice: true")
+        }
+        if (requireUnlocked) builder.requireUnlockedDevice(allowFallback)
+        // iOS-only settings: the iOS side reads them; here only their shape is checked.
+        root.obj("ios")
+
+        root.finish()
+        listener?.let { builder.onConnectionEvent(it) }
+        return ParsedConfig(
+            builder.build(), guardTimeout, pinGlobal,
+            NetworkingOptions(requirePinned, keepCache, keepCookies),
+            nativeSecurityApplied = native != null,
+        )
+    }
+
+    private fun duration(d: Fields): Pair<Long, TimeUnit> {
+        val amount = d.long("amount", 0, 10L * 365 * 24 * 3600 * 1000) ?: throw BridgeInputException("${d.path}.amount: required")
+        val unit = when (val u = d.requireString("unit", 16)) {
+            "MILLISECONDS" -> TimeUnit.MILLISECONDS
+            "SECONDS" -> TimeUnit.SECONDS
+            "MINUTES" -> TimeUnit.MINUTES
+            "HOURS" -> TimeUnit.HOURS
+            "DAYS" -> TimeUnit.DAYS
+            else -> throw BridgeInputException("${d.path}.unit: '$u' is not one of MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS")
+        }
+        d.finish()
+        return amount to unit
+    }
+
+    private fun httpsUrl(f: Fields, key: String): String? {
+        val url = f.string(key, 2048) ?: return null
+        if (!url.startsWith("https://")) throw BridgeInputException("${f.path}.$key: must be an https:// URL")
+        return url
+    }
+
+    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")
+        val pin = HostPin(
+            hostname = hostname,
+            sha256 = pins,
+            version = p.int("version", 0, Int.MAX_VALUE) ?: 0,
+            forceUpdate = p.bool("forceUpdate") ?: false,
+            mtls = p.bool("mtls") ?: false,
+            clientCertVersion = p.int("clientCertVersion", 0, Int.MAX_VALUE),
+        )
+        p.finish()
+        return pin
+    }
+
+    fun staticPins(s: Fields): CertificateConfig {
+        val pins = s.objList("pins", MAX_PINS)?.map(::hostPin) ?: throw BridgeInputException("${s.path}.pins: required")
+        val config = CertificateConfig(
+            version = s.int("version", 0, Int.MAX_VALUE) ?: 0,
+            pins = pins,
+            forceUpdate = s.bool("forceUpdate") ?: false,
+        )
+        s.finish()
+        return config
+    }
+
+    private fun addConfigApi(builder: PinVaultConfig.Builder, b: Fields, native: NativeSecurity?, release: Boolean) {
+        val id = b.requireString("id", 128)
+        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 oneKey = b.string("signaturePublicKey", KEY_LENGTH, multiline = true)
+        val keys = b.stringList("signaturePublicKeys", 16, KEY_LENGTH, multiline = true)
+        if (oneKey != null && keys != null) {
+            throw BridgeInputException("${b.path}: give signaturePublicKey or signaturePublicKeys, not both")
+        }
+        val requiredSignatures = b.int("requiredSignatures", 1, 16)
+        val recoveryKeys = b.stringList("recoveryPublicKeys", 16, KEY_LENGTH, multiline = true)
+        val requiredRecovery = b.int("requiredRecoverySignatures", 1, 16)
+        val allowUnsigned = b.bool("allowUnsigned") == true
+        val serverScope = b.string("serverScope", 128)
+        val allowUnpinned = b.bool("allowUnpinnedConfigApi") == true
+        val allowServerKey = b.bool("allowServerGeneratedKey") == true
+        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 clientCertLabel = b.string("clientCertLabel", 128)
+        val wantPinsFor = b.stringList("wantPinsFor", 256, 255)
+        val renewalUrl = httpsUrl(b, "renewalUrl")
+        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 attestationInterval = b.obj("attestationInterval")?.let(::duration)
+        val tokenHosts = b.stringList("tokenHosts", 64, 255)
+        b.finish()
+
+        // The trust anchors and relaxations: the native security file decides, JS only repeats.
+        val sec = SecurityPolicy.apply(
+            b.path, id,
+            SecurityFields(
+                bootstrapPins, oneKey, keys, requiredSignatures, recoveryKeys, requiredRecovery,
+                serverScope, clientCaPins, allowUnsigned, allowUnpinned, allowServerKey,
+            ),
+            native, release,
+        )
+
+        builder.configApi(id, url) {
+            sec.bootstrapPins?.let { this.bootstrapPins(it) }
+            configEndpoint?.let { this.configEndpoint(it) }
+            healthEndpoint?.let { this.healthEndpoint(it) }
+            sec.oneKey?.let { this.signaturePublicKey(it) }
+            sec.keys?.let { this.signaturePublicKeys(it) }
+            sec.requiredSignatures?.let { this.requiredSignatures(it) }
+            sec.recoveryKeys?.let { this.recoveryPublicKeys(it) }
+            sec.requiredRecovery?.let { this.requiredRecoverySignatures(it) }
+            if (sec.allowUnsigned) this.allowUnsigned()
+            sec.serverScope?.let { this.serverScope(it) }
+            if (sec.allowUnpinned) this.allowUnpinnedConfigApi()
+            if (sec.allowServerKey) this.allowServerGeneratedKey()
+            sec.clientCaPins?.let { this.clientCaPins(it) }
+            maxLifetime?.let { this.maxClientCertLifetimeDays(it) }
+            clientCertHosts?.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) }
+            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) }
+        }
+    }
+
+    private fun addVaultFile(builder: PinVaultConfig.Builder, f: Fields, tokens: VaultTokenStore) {
+        val key = f.requireString("key", 128)
+        val endpoint = f.requireString("endpoint", 512)
+        val signatureKey = 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 maxOfflineAge = f.obj("maxOfflineAge")?.let(::duration)
+        val wipeWhenStale = f.bool("wipeWhenStale") == true
+        f.finish()
+
+        builder.vaultFile(key) {
+            this.endpoint(endpoint)
+            signatureKey?.let { this.signaturePublicKey(it) }
+            updateWithPins?.let { this.updateWithPins(it) }
+            storage?.let { this.storage(it) }
+            configApi?.let { this.configApi(it) }
+            policy?.let { this.accessPolicy(it) }
+            if (policy == VaultFileAccessPolicy.TOKEN || policy == VaultFileAccessPolicy.TOKEN_MTLS) {
+                // Read on every download; the token never leaves native memory.
+                this.accessToken { tokens.get(key) }
+            }
+            encryption?.let { this.encryption(it) }
+            userAuth?.let { this.userAuth(it) }
+            maxOfflineAge?.let { this.maxOfflineAge(it.first, it.second) }
+            if (wipeWhenStale) this.wipeWhenStale()
+        }
+    }
+
+    /** `unlockFile` prompt texts + the content encoding. */
+    fun unlockPrompt(json: String): Pair<VaultFileUnlockPrompt, String> {
+        val p = StrictJson.parseObject(json, "prompt", maxChars = 16 * 1024)
+        val prompt = VaultFileUnlockPrompt(
+            title = p.requireString("title", 256),
+            subtitle = p.string("subtitle", 256),
+            description = p.string("description", 1024),
+            negativeButtonText = p.string("negativeButtonText", 64) ?: "Cancel",
+        )
+        val encoding = ResultMapper.checkEncoding(p.string("encoding", 16) ?: ResultMapper.UTF8)
+        p.finish()
+        return prompt to encoding
+    }
+}

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

@@ -0,0 +1,53 @@
+package io.github.umutcansu.pinvault.reactnative
+
+import io.github.umutcansu.pinvault.model.EnvironmentGuard
+import io.github.umutcansu.pinvault.model.GuardedOperation
+import java.util.UUID
+import java.util.concurrent.CompletableFuture
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.TimeUnit
+
+/**
+ * `environmentGuard` answered by a JS callback. The library asks on a
+ * background thread; this sends `{requestId, operation}` to JS and waits for
+ * [answer] up to [timeoutMs]. Fail closed: no answer in time, an unknown
+ * request id, an interrupt — every one of them is a refusal.
+ *
+ * The answer comes on the native-modules thread, the question is asked on the
+ * library's worker thread, so waiting here never blocks the thread that
+ * delivers the answer.
+ */
+internal class JsEnvironmentGuard(
+    private val timeoutMs: Long,
+    private val ask: (requestId: String, operation: String) -> Unit,
+) : EnvironmentGuard {
+
+    private val pending = ConcurrentHashMap<String, CompletableFuture<Boolean>>()
+
+    override fun allows(operation: GuardedOperation): Boolean {
+        val id = UUID.randomUUID().toString()
+        val answer = CompletableFuture<Boolean>()
+        pending[id] = answer
+        return try {
+            ask(id, operation.name)
+            answer.get(timeoutMs, TimeUnit.MILLISECONDS) == true
+        } catch (_: Exception) {
+            false
+        } finally {
+            pending.remove(id)
+        }
+    }
+
+    /** JS's verdict; ignored when the request is unknown or already timed out. */
+    fun answer(requestId: String, allowed: Boolean) {
+        pending[requestId]?.complete(allowed)
+    }
+
+    fun pendingCount(): Int = pending.size
+
+    companion object {
+        const val DEFAULT_TIMEOUT_MS = 5000L
+        const val MIN_TIMEOUT_MS = 100L
+        const val MAX_TIMEOUT_MS = 30_000L
+    }
+}

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

@@ -0,0 +1,239 @@
+package io.github.umutcansu.pinvault.reactnative
+
+import android.content.Context
+import android.content.pm.ApplicationInfo
+import io.github.umutcansu.pinvault.model.CertificateConfig
+import io.github.umutcansu.pinvault.model.HostPin
+import java.io.FileNotFoundException
+import java.io.IOException
+
+/**
+ * The app's native security file: the trust anchors and relaxations of
+ * `start(config)` declared outside the JS bundle, which an OTA update
+ * (CodePush, Expo Updates) or an edited bundle can change. The file ships in
+ * the APK (`src/main/assets/pinvault_security.json`, or a build type's own
+ * `src/release/assets/`), which the APK signature seals.
+ *
+ * ```json
+ * {
+ *   "configApis": [{
+ *     "id": "default-tls",
+ *     "bootstrapPins": [{ "hostname": "api.example.com", "sha256": ["…", "…"] }],
+ *     "signaturePublicKeys": ["…", "…"], "requiredSignatures": 2,
+ *     "recoveryPublicKeys": ["…"], "requiredRecoverySignatures": 1,
+ *     "serverScope": "default-tls", "clientCaPins": ["…"],
+ *     "allowUnsigned": false, "allowUnpinnedConfigApi": false, "allowServerGeneratedKey": false
+ *   }],
+ *   "staticPins": { "pins": [ … ], "version": 1 }
+ * }
+ * ```
+ *
+ * When the file is there ([apply]):
+ * - every Config API of the JS config must be declared in it (an OTA update
+ *   cannot add a block with keys of its own), and JS `staticPins` must be
+ *   declared too;
+ * - 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.
+ *
+ * Without the file, release builds (the app is not debuggable) refuse those
+ * three relaxations from JS; debug builds take them as before.
+ */
+internal class NativeSecurity(
+    /** Where the file came from, for messages. */
+    val source: String,
+    val blocks: Map<String, Block>,
+    val staticPins: CertificateConfig?,
+) {
+
+    class Block(
+        val bootstrapPins: List<HostPin>?,
+        val signaturePublicKeys: List<String>?,
+        val requiredSignatures: Int?,
+        val recoveryPublicKeys: List<String>?,
+        val requiredRecoverySignatures: Int?,
+        val serverScope: String?,
+        val clientCaPins: List<String>?,
+        val allowUnsigned: Boolean,
+        val allowUnpinnedConfigApi: Boolean,
+        val allowServerGeneratedKey: Boolean,
+    )
+
+    companion object {
+        const val ASSET_NAME = "pinvault_security.json"
+        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]. */
+        fun load(context: Context): NativeSecurity? {
+            val text = try {
+                context.assets.open(ASSET_NAME).bufferedReader(Charsets.UTF_8).use { it.readText() }
+            } catch (_: FileNotFoundException) {
+                return null
+            } catch (e: IOException) {
+                // There, but unreadable: fail closed.
+                throw BridgeInputException("native security file assets/$ASSET_NAME: cannot be read (${e.javaClass.simpleName})")
+            }
+            return parse(text, "assets/$ASSET_NAME")
+        }
+
+        /** True for a release build of the app (not `android:debuggable`). */
+        fun isReleaseBuild(context: Context): Boolean =
+            (context.applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE) == 0
+
+        fun parse(text: String, source: String): NativeSecurity {
+            val root = try {
+                StrictJson.parseObject(text, source, maxChars = MAX_FILE_CHARS)
+            } catch (e: BridgeInputException) {
+                throw BridgeInputException("native security file ${e.message}")
+            }
+            val blocks = LinkedHashMap<String, Block>()
+            try {
+                root.objList("configApis", ConfigParser.MAX_CONFIG_APIS)?.forEach { b ->
+                    val id = b.requireString("id", 128)
+                    if (id in blocks) throw BridgeInputException("${b.path}.id: '$id' is declared twice")
+                    blocks[id] = Block(
+                        bootstrapPins = b.objList("bootstrapPins", ConfigParser.MAX_PINS)?.map(ConfigParser::hostPin),
+                        signaturePublicKeys = b.stringList("signaturePublicKeys", 16, ConfigParser.KEY_LENGTH, multiline = true),
+                        requiredSignatures = b.int("requiredSignatures", 1, 16),
+                        recoveryPublicKeys = b.stringList("recoveryPublicKeys", 16, ConfigParser.KEY_LENGTH, multiline = true),
+                        requiredRecoverySignatures = b.int("requiredRecoverySignatures", 1, 16),
+                        serverScope = b.string("serverScope", 128),
+                        clientCaPins = b.stringList("clientCaPins", 16, 128),
+                        allowUnsigned = b.bool("allowUnsigned") == true,
+                        allowUnpinnedConfigApi = b.bool("allowUnpinnedConfigApi") == true,
+                        allowServerGeneratedKey = b.bool("allowServerGeneratedKey") == true,
+                    )
+                    b.finish()
+                }
+                val staticPins = root.obj("staticPins")?.let(ConfigParser::staticPins)
+                root.finish()
+                if (blocks.isEmpty() && staticPins == null) {
+                    throw BridgeInputException("$source: declares neither configApis nor staticPins")
+                }
+                return NativeSecurity(source, blocks, staticPins)
+            } catch (e: BridgeInputException) {
+                val message = e.message ?: ""
+                throw BridgeInputException(if (message.startsWith("native security file")) message else "native security file $message")
+            } catch (e: IllegalArgumentException) {
+                // A builder / constructor rule (two pins per host, …).
+                throw BridgeInputException("native security file $source: ${e.message}")
+            }
+        }
+
+        // ── Comparison (order of lists does not matter) ─────────────────────
+
+        fun sameKeys(a: List<String>, b: List<String>): Boolean = a.map(String::trim).toSet() == b.map(String::trim).toSet()
+
+        private fun pinKey(p: HostPin) =
+            listOf(p.hostname.lowercase(), p.sha256.sorted().joinToString(","), p.version, p.forceUpdate, p.mtls, p.clientCertVersion)
+                .joinToString("|")
+
+        fun samePins(a: List<HostPin>, b: List<HostPin>): Boolean = a.map(::pinKey).sorted() == b.map(::pinKey).sorted()
+
+        fun sameStaticPins(a: CertificateConfig, b: CertificateConfig): Boolean =
+            a.version == b.version && a.forceUpdate == b.forceUpdate && samePins(a.pins, b.pins)
+    }
+}
+
+/** What JS asked for in one `configApis[i]` entry, before the native policy is applied. */
+internal class SecurityFields(
+    val bootstrapPins: List<HostPin>?,
+    /** `signaturePublicKey` (one) or `signaturePublicKeys`; never both. */
+    val oneKey: String?,
+    val keys: List<String>?,
+    val requiredSignatures: Int?,
+    val recoveryKeys: List<String>?,
+    val requiredRecovery: Int?,
+    val serverScope: String?,
+    val clientCaPins: List<String>?,
+    val allowUnsigned: Boolean,
+    val allowUnpinned: Boolean,
+    val allowServerKey: Boolean,
+)
+
+/** The native policy applied to one block: the values that go to the builder, or a refusal. */
+internal object SecurityPolicy {
+
+    private const val RELAXATIONS_HINT =
+        "a release build takes it only from the app's native security file (assets/${NativeSecurity.ASSET_NAME}, README \"Native security file\")"
+
+    fun apply(path: String, id: String, js: SecurityFields, native: NativeSecurity?, release: Boolean): SecurityFields {
+        if (native == null) {
+            if (release) {
+                if (js.allowUnsigned) throw BridgeInputException("$path.allowUnsigned: refused from JS; $RELAXATIONS_HINT")
+                if (js.allowUnpinned) throw BridgeInputException("$path.allowUnpinnedConfigApi: refused from JS; $RELAXATIONS_HINT")
+                if (js.allowServerKey) throw BridgeInputException("$path.allowServerGeneratedKey: refused from JS; $RELAXATIONS_HINT")
+            }
+            return js
+        }
+        val block = native.blocks[id]
+            ?: throw BridgeInputException("$path: Config API '$id' is not declared in the app's native security file (${native.source})")
+
+        fun fixed(key: String): Nothing =
+            throw BridgeInputException("$path.$key: differs from the app's native security file (${native.source}); the native value is fixed")
+
+        fun relaxation(key: String, js: Boolean, allowed: Boolean) {
+            if (js && !allowed) throw BridgeInputException("$path.$key: refused; the app's native security file (${native.source}) does not allow it")
+        }
+        relaxation("allowUnsigned", js.allowUnsigned, block.allowUnsigned)
+        relaxation("allowUnpinnedConfigApi", js.allowUnpinned, block.allowUnpinnedConfigApi)
+        relaxation("allowServerGeneratedKey", js.allowServerKey, block.allowServerGeneratedKey)
+
+        val pins = block.bootstrapPins?.also { n ->
+            if (js.bootstrapPins != null && !NativeSecurity.samePins(js.bootstrapPins, n)) fixed("bootstrapPins")
+        } ?: js.bootstrapPins
+
+        val oneKey = js.oneKey
+        var keys = js.keys
+        block.signaturePublicKeys?.let { n ->
+            val jsKeys = js.oneKey?.let { listOf(it) } ?: js.keys
+            if (jsKeys == null) {
+                keys = n
+            } else if (!NativeSecurity.sameKeys(jsKeys, n)) {
+                fixed(if (js.oneKey != null) "signaturePublicKey" else "signaturePublicKeys")
+            }
+        }
+
+        fun <T> one(key: String, nativeValue: T?, jsValue: T?): T? {
+            if (nativeValue == null) return jsValue
+            if (jsValue != null && jsValue != nativeValue) fixed(key)
+            return nativeValue
+        }
+
+        fun list(key: String, nativeValue: List<String>?, jsValue: List<String>?): List<String>? {
+            if (nativeValue == null) return jsValue
+            if (jsValue != null && !NativeSecurity.sameKeys(jsValue, nativeValue)) fixed(key)
+            return nativeValue
+        }
+
+        return SecurityFields(
+            bootstrapPins = pins,
+            oneKey = oneKey,
+            keys = keys,
+            requiredSignatures = one("requiredSignatures", block.requiredSignatures, js.requiredSignatures),
+            recoveryKeys = list("recoveryPublicKeys", block.recoveryPublicKeys, js.recoveryKeys),
+            requiredRecovery = one("requiredRecoverySignatures", block.requiredRecoverySignatures, js.requiredRecovery),
+            serverScope = one("serverScope", block.serverScope, js.serverScope),
+            clientCaPins = list("clientCaPins", block.clientCaPins, js.clientCaPins),
+            // The file is the source of truth for the relaxations too.
+            allowUnsigned = block.allowUnsigned,
+            allowUnpinned = block.allowUnpinnedConfigApi,
+            allowServerKey = block.allowServerGeneratedKey,
+        )
+    }
+
+    /** JS `staticPins` against the file: declared there or refused; the file's apply when JS has none. */
+    fun staticPins(path: String, js: CertificateConfig?, native: NativeSecurity?): CertificateConfig? {
+        if (native == null) return js
+        val n = native.staticPins
+        if (n == null) {
+            if (js != null) throw BridgeInputException("$path: not declared in the app's native security file (${native.source})")
+            return null
+        }
+        if (js != null && !NativeSecurity.sameStaticPins(js, n)) {
+            throw BridgeInputException("$path: differs from the app's native security file (${native.source}); the native value is fixed")
+        }
+        return n
+    }
+}