@rs-native-kit/version-check 0.1.2

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Rajesh Shinde
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,256 @@
+<div align="center">
+
+# 📦 @rs-native-kit/version-check
+
+**Drop-in version-check & force/soft-update orchestration for React Native**
+
+Detect when your users are behind, decide what to do about it, and ship the UI to tell them — all from one config call.
+
+[![CI](https://github.com/rajssinde/rs-native-kit-version-check/actions/workflows/ci.yml/badge.svg)](https://github.com/rajssinde/rs-native-kit-version-check/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)](#)
+[![New Architecture](https://img.shields.io/badge/React%20Native-New%20Architecture-61DAFB?logo=react&logoColor=white)](#requirements)
+[![Platforms](https://img.shields.io/badge/platforms-iOS%20%7C%20Android%20%7C%20Web-lightgrey)](#requirements)
+[![Zero deps](https://img.shields.io/badge/runtime%20deps-zero-success)](#)
+
+</div>
+
+---
+
+## Why this exists
+
+Shipping an update means nothing if half your users are stuck on a version from three releases ago. **`version-check`** answers three questions for you on every app launch:
+
+1. **Is the user out of date?** — compares the running app version against what your store (or your own API) says is current.
+2. **How out of date, and does it matter?** — runs that comparison through a policy engine (hard floor, reminder cadence, staged rollout %) to decide what actually needs to happen.
+3. **What should the UI do about it?** — hands back a typed `ActionPlan` (`FORCE_UPDATE`, `SOFT_UPDATE`, `OPTIONAL_REMINDER`, `NO_ACTION`) that you render with the included components, your own UI, or ignore entirely if you just want the raw decision.
+
+## At a glance
+
+| | |
+|---|---|
+| 📦 Runtime dependencies | **0** — nothing pulled in at install time |
+| 🏬 Store providers | Apple App Store, Google Play, Custom API (Huawei/Amazon/Firebase planned) |
+| ⏱️ Default check cache | 6h TTL, persisted across app restarts |
+| 🔁 Default reminder cadence | Every 3 days after "Later" |
+| 🎯 Staged rollout | 0–100% device-bucketed rollout out of the box |
+| 🧩 Setup | One `configure()` call, or `<VersionManagerProvider>` + a hook |
+| 🖼️ Prebuilt UI | 3 ready-made components, or go fully headless |
+| 🧪 Test coverage | Domain/config logic covered by unit tests, no device required |
+| 🌐 Platforms | iOS, Android, Web (`react-native-web`) |
+
+## Features
+
+- 🏬 **Multi-store version lookup** — App Store, Google Play, or your own Custom API out of the box.
+- 🧠 **Policy engine** — SemVer-aware force-update floor, reminder throttling, and percentage-based staged rollout.
+- 🔐 **Signed remote config** — optionally hot-load update policy from a URL or bundled JSON, verified with Ed25519/HMAC via native OS crypto (never hand-rolled in JS).
+- ⚛️ **React hooks + prebuilt UI** — `useVersionManager`, `<ForceUpdateScreen />`, `<SoftUpdateDialog />`, `<OptionalUpdateBanner />` — or go headless and build your own.
+- 📡 **Event-driven** — subscribe to `stateChanged`, `updateDetected`, `userAction`, and `error` instead of polling.
+- 🌐 **Web-ready** — the same JS API runs under `react-native-web`; no separate SDK.
+- 🪶 **Zero runtime dependencies** — the entire JS surface is hand-written, nothing pulled in at install time.
+- 🧪 **Fully unit-tested domain core** — SemVer engine, policy engine, lifecycle state machine, and config pipeline all run against mocks, no native layer required.
+
+## Requirements
+
+This library ships as a **TurboModule** with no legacy-bridge fallback, so the New Architecture must be enabled.
+
+| Requirement | Minimum | Tested against |
+|---|---|---|
+| React Native | **0.74+**, New Architecture (Fabric/TurboModules) enabled | 0.85.0 |
+| React | 18+ | 19.2.3 |
+| iOS | **15.1+** | Xcode 16.1+ |
+| Android | **API 24** (Android 7.0)+ | compileSdk 36, Kotlin 2.0.21, JDK 17 |
+| Node.js | 20+ | 24.13.0 (see `.nvmrc`) |
+| TypeScript | 5+ (optional, but the package ships full `.d.ts`) | 6.0.3 |
+
+| Platform | Status |
+|---|---|
+| iOS | ✅ Native TurboModule (`ios/VersionCheck.mm`, Ed25519 verification) |
+| Android | ✅ Native TurboModule (Kotlin, WorkManager-backed background scheduling) |
+| Web (`react-native-web`) | ✅ Same JS API, browser-native `fetch`/`localStorage` bridge |
+
+## Installation
+
+```sh
+npm install @rs-native-kit/version-check
+# or
+yarn add @rs-native-kit/version-check
+```
+
+**iOS** — install pods after adding the package:
+
+```sh
+cd ios && pod install
+```
+
+**Android** — no extra steps; the TurboModule autolinks via `react-native.config.js`.
+
+## Quick start
+
+### Core API (framework-agnostic, zero React code pulled in)
+
+```ts
+import { VersionManager } from '@rs-native-kit/version-check';
+
+const manager = VersionManager.configure({
+  stores: {
+    ios: { appStoreId: '123456789' },   // optional — omit to fall back to this app's bundle id
+    android: { packageName: 'com.example.app' }, // optional — omit to use this app's own package name
+  },
+});
+
+await manager.ready(); // waits for config resolution to settle
+const plan = await manager.checkForUpdates();
+
+switch (plan.type) {
+  case 'FORCE_UPDATE':
+    // block the app, show ForceUpdateScreen
+    break;
+  case 'SOFT_UPDATE':
+    // dismissible prompt, show SoftUpdateDialog
+    break;
+  case 'OPTIONAL_REMINDER':
+    // low-intrusion nudge, show OptionalUpdateBanner
+    break;
+  case 'NO_ACTION':
+    // already current
+    break;
+}
+```
+
+### React hooks + prebuilt UI (separate, tree-shakeable entry point)
+
+```tsx
+import {
+  useVersionManager,
+  ForceUpdateScreen,
+  SoftUpdateDialog,
+  OptionalUpdateBanner,
+} from '@rs-native-kit/version-check/ui';
+import { Linking } from 'react-native';
+
+function App() {
+  const { state, isUpdateAvailable, updateInfo, checkForUpdates } =
+    useVersionManager({
+      stores: {
+        ios: { appStoreId: '123456789' },
+        android: { packageName: 'com.example.app' },
+      },
+      policy: {
+        forceUpdateBelow: '2.0.0',
+        reminderIntervalMs: 3 * 24 * 60 * 60 * 1000, // 3 days
+      },
+    });
+
+  if (updateInfo?.isForceUpdate) {
+    return (
+      <ForceUpdateScreen
+        updateInfo={updateInfo}
+        onUpdatePress={() => Linking.openURL(updateInfo.storeUrl)}
+      />
+    );
+  }
+
+  return (
+    <>
+      {/* your app */}
+      {isUpdateAvailable && updateInfo && (
+        <SoftUpdateDialog
+          updateInfo={updateInfo}
+          onUpdatePress={() => Linking.openURL(updateInfo.storeUrl)}
+          onLaterPress={() => {}}
+        />
+      )}
+    </>
+  );
+}
+```
+
+### Events
+
+```ts
+manager.onUpdateDetected(({ updateInfo, actionPlan }) => { /* ... */ });
+manager.onUserAction(({ action, updateInfo }) => { /* 'update_clicked' | 'later_clicked' | ... */ });
+manager.onStateChanged(({ from, to }) => { /* lifecycle transitions */ });
+manager.onError(({ error, phase }) => { /* 'config' | 'check' | 'policy' | 'presentation' */ });
+```
+
+## Configuration reference
+
+Every field below is optional except `stores`, which needs at least one provider configured.
+
+`stores.ios.appStoreId` and `stores.android.packageName` are themselves optional — pass them when you have them (App Store lookups by numeric id are the most reliable), and omit them to fall back automatically to the running app's own bundle id (`IAppInfoProvider.getBundleId()`, resolved at check time) — which *is* the package name on Android, and a supported alternate lookup key (`bundleId=`) against the iTunes Lookup API on iOS:
+
+```ts
+VersionManager.configure({
+  stores: {
+    ios: { region: 'us' },   // appStoreId omitted -> looked up by this app's bundle id
+    android: {},             // packageName omitted -> uses this app's own package name
+    custom: { url: 'https://api.example.com/version.json', headers: {} },
+  },
+  policy: {
+    forceUpdateBelow: '2.0.0',       // SemVer floor — anything older is FORCE_UPDATE
+    reminderIntervalMs: 259_200_000, // how often to re-nag after "Later" (default 3 days)
+    rolloutPercentage: 100,          // staged rollout, 0-100
+  },
+  cache: {
+    ttlMs: 21_600_000,               // how long a store lookup is cached (default 6h)
+    storage: 'persistent',           // 'memory' | 'persistent'
+    bustOnManualCheck: true,
+  },
+  fallback: {
+    onNetworkError: 'useCache',      // 'useCache' | 'useDefaultConfig' | 'noAction'
+    requestTimeoutMs: 8_000,
+    retry: { maxAttempts: 3, backoff: 'exponential-jitter', baseDelayMs: 500 },
+  },
+  remoteConfigUrl: 'https://api.example.com/vm-config.json', // optional hot-reloadable config
+  security: { signatureAlgorithm: 'ed25519', trustedKeyIds: ['prod-key-1'] },
+  logging: { level: 'warn' },
+});
+```
+
+### Store providers
+
+| Provider | Status |
+|---|---|
+| Apple App Store | ✅ Implemented |
+| Google Play | ✅ Implemented |
+| Custom API | ✅ Implemented |
+| Huawei AppGallery | 🚧 Planned — throws `UnsupportedStoreException` today |
+| Amazon Appstore | 🚧 Planned — throws `UnsupportedStoreException` today |
+| Firebase Remote Config | 🚧 Planned — throws `UnsupportedStoreException` today |
+
+### Remote / signed configuration
+
+On top of the options you hardcode at `configure()`, you can layer a **local bundled JSON** and/or a **remote URL**, both wrapped in a signed envelope (`schemaVersion`, `payload`, `signature`) and verified against `security.trustedKeyIds` before any field is trusted. Precedence is `env overrides > remote > local > configure() defaults`, merged field-by-field, with automatic fallback to the last known-good config if a remote fetch fails.
+
+## Lifecycle
+
+```
+UNINITIALIZED → CONFIG_LOADING → IDLE ⇄ VERSION_CHECKING → DECIDING
+                                                              │
+                        ┌─────────────────┬───────────────────┼───────────────────┐
+                        ▼                 ▼                   ▼                   ▼
+              FORCE_UPDATE_DISPLAYED  SOFT_UPDATE_DISPLAYED  REJECTED_WAITING_REMINDER  IDLE
+```
+
+Read the current state any time with `manager.getCurrentState()`, or subscribe via `onStateChanged`.
+
+## Example app
+
+```sh
+yarn
+yarn example ios      # or `yarn example android`, `yarn example web`
+```
+
+## Contributing
+
+- [Development workflow](CONTRIBUTING.md#development-workflow)
+- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
+- [Code of conduct](CODE_OF_CONDUCT.md)
+
+## License
+
+MIT © [Rajesh Shinde](https://github.com/rajssinde)
+
+---

package/VersionCheck.podspec

@@ -0,0 +1,20 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "VersionCheck"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/rajssinde/rs-native-kit-version-check.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
+  s.private_header_files = "ios/**/*.h"
+
+  install_modules_dependencies(s)
+end

package/android/build.gradle

@@ -0,0 +1,56 @@
+buildscript {
+  ext.VersionCheck = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return VersionCheck[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.rsnativekit.versioncheck"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  // Backs the scheduleBackgroundCheck/cancelBackgroundCheck TurboModule methods
+  // (doc 01 §4.1 "scheduler" row, Android WorkManager) — an internal implementation
+  // detail of this library's own native module; consuming apps do not need to declare
+  // this themselves (it is bundled at runtime via normal AAR dependency resolution).
+  implementation "androidx.work:work-runtime-ktx:2.9.1"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,9 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <!-- Doc 01 §4.1/§10 background-scheduler headless JS bridge (Prompt 26). Merged
+         into the host app's manifest by Gradle's normal library-manifest merge. -->
+    <application>
+        <service
+            android:name=".VersionCheckHeadlessTaskService"
+            android:exported="false" />
+    </application>
+</manifest>

package/android/src/main/java/com/rsnativekit/versioncheck/SecureStorageCipher.kt

@@ -0,0 +1,57 @@
+package com.rsnativekit.versioncheck
+
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyProperties
+import android.util.Base64
+import java.security.KeyStore
+import javax.crypto.Cipher
+import javax.crypto.KeyGenerator
+import javax.crypto.SecretKey
+import javax.crypto.spec.GCMParameterSpec
+
+/**
+ * AES/GCM encryption backed by the Android Keystore — java.security/javax.crypto only,
+ * no external Gradle dependency (docs/architecture/03-configuration-system.md §3.4).
+ * The key is generated inside the keystore and never leaves it; only ciphertext + IV
+ * are persisted in SharedPreferences by the caller.
+ */
+internal object SecureStorageCipher {
+  private const val KEYSTORE_PROVIDER = "AndroidKeyStore"
+  private const val KEY_ALIAS = "rs_version_check_secure_storage_key"
+  private const val TRANSFORMATION = "AES/GCM/NoPadding"
+  private const val GCM_TAG_LENGTH_BITS = 128
+
+  private fun getOrCreateKey(): SecretKey {
+    val keyStore = KeyStore.getInstance(KEYSTORE_PROVIDER).apply { load(null) }
+    (keyStore.getKey(KEY_ALIAS, null) as? SecretKey)?.let { return it }
+
+    val keyGenerator = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, KEYSTORE_PROVIDER)
+    val spec =
+      KeyGenParameterSpec.Builder(KEY_ALIAS, KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT)
+        .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+        .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+        .build()
+    keyGenerator.init(spec)
+    return keyGenerator.generateKey()
+  }
+
+  fun encrypt(plainText: String): String {
+    val cipher = Cipher.getInstance(TRANSFORMATION)
+    cipher.init(Cipher.ENCRYPT_MODE, getOrCreateKey())
+    val cipherBytes = cipher.doFinal(plainText.toByteArray(Charsets.UTF_8))
+    val iv = Base64.encodeToString(cipher.iv, Base64.NO_WRAP)
+    val payload = Base64.encodeToString(cipherBytes, Base64.NO_WRAP)
+    return "$iv:$payload"
+  }
+
+  fun decrypt(stored: String): String {
+    val parts = stored.split(":", limit = 2)
+    require(parts.size == 2) { "Malformed secure storage entry" }
+    val iv = Base64.decode(parts[0], Base64.NO_WRAP)
+    val cipherBytes = Base64.decode(parts[1], Base64.NO_WRAP)
+
+    val cipher = Cipher.getInstance(TRANSFORMATION)
+    cipher.init(Cipher.DECRYPT_MODE, getOrCreateKey(), GCMParameterSpec(GCM_TAG_LENGTH_BITS, iv))
+    return String(cipher.doFinal(cipherBytes), Charsets.UTF_8)
+  }
+}

package/android/src/main/java/com/rsnativekit/versioncheck/VersionCheckHeadlessTaskService.kt

@@ -0,0 +1,31 @@
+package com.rsnativekit.versioncheck
+
+import android.content.Intent
+import com.facebook.react.HeadlessJsTaskService
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.jstasks.HeadlessJsTaskConfig
+
+/**
+ * Doc 01 §4.1/§10 "Headless JS task + native WorkManager/BGTaskScheduler bridge" — the
+ * Android half. VersionCheckWorker (WorkManager) starts this service when a scheduled
+ * check fires; this service starts the "VersionCheckBackgroundTask" headless JS task,
+ * which the host app must register once via the `registerVersionCheckHeadlessTask()`
+ * helper exported from '@rs-native-kit/version-check' (same integration shape as
+ * react-native-background-fetch and similar libraries require).
+ */
+class VersionCheckHeadlessTaskService : HeadlessJsTaskService() {
+  override fun getTaskConfig(intent: Intent): HeadlessJsTaskConfig? {
+    val extras = intent.extras
+    return HeadlessJsTaskConfig(
+      TASK_NAME,
+      if (extras != null) Arguments.fromBundle(extras) else Arguments.createMap(),
+      TASK_TIMEOUT_MS,
+      true
+    )
+  }
+
+  companion object {
+    const val TASK_NAME = "VersionCheckBackgroundTask"
+    const val TASK_TIMEOUT_MS = 30_000L
+  }
+}

package/android/src/main/java/com/rsnativekit/versioncheck/VersionCheckModule.kt

@@ -0,0 +1,215 @@
+package com.rsnativekit.versioncheck
+
+import android.content.Context
+import android.content.SharedPreferences
+import android.os.Build
+import android.util.Base64
+import androidx.work.ExistingPeriodicWorkPolicy
+import androidx.work.PeriodicWorkRequestBuilder
+import androidx.work.WorkManager
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import java.security.Signature
+import java.util.Locale
+import java.util.concurrent.TimeUnit
+import javax.crypto.Mac
+import javax.crypto.spec.SecretKeySpec
+
+class VersionCheckModule(reactContext: ReactApplicationContext) :
+  NativeVersionCheckSpec(reactContext) {
+
+  private val prefs: SharedPreferences by lazy {
+    reactApplicationContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+  }
+  private val securePrefs: SharedPreferences by lazy {
+    reactApplicationContext.getSharedPreferences(SECURE_PREFS_NAME, Context.MODE_PRIVATE)
+  }
+
+  // --- App info ---
+
+  override fun getCurrentAppVersion(promise: Promise) {
+    try {
+      val info = reactApplicationContext.packageManager.getPackageInfo(reactApplicationContext.packageName, 0)
+      promise.resolve(info.versionName ?: "")
+    } catch (error: Exception) {
+      promise.reject("get_current_app_version_failed", error)
+    }
+  }
+
+  override fun getBuildNumber(promise: Promise) {
+    try {
+      val info = reactApplicationContext.packageManager.getPackageInfo(reactApplicationContext.packageName, 0)
+      val code = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) info.longVersionCode else info.versionCode.toLong()
+      promise.resolve(code.toString())
+    } catch (error: Exception) {
+      promise.reject("get_build_number_failed", error)
+    }
+  }
+
+  override fun getBundleId(promise: Promise) {
+    promise.resolve(reactApplicationContext.packageName)
+  }
+
+  // --- Device info ---
+
+  override fun getOsVersion(promise: Promise) {
+    promise.resolve(Build.VERSION.RELEASE ?: Build.VERSION.SDK_INT.toString())
+  }
+
+  override fun getDeviceModel(promise: Promise) {
+    promise.resolve("${Build.MANUFACTURER} ${Build.MODEL}")
+  }
+
+  override fun getLocale(promise: Promise) {
+    promise.resolve(Locale.getDefault().toLanguageTag())
+  }
+
+  // --- Key-value storage (SharedPreferences) ---
+
+  override fun storageGet(key: String, promise: Promise) {
+    promise.resolve(prefs.getString(key, null))
+  }
+
+  override fun storageSet(key: String, value: String, promise: Promise) {
+    prefs.edit().putString(key, value).apply()
+    promise.resolve(null)
+  }
+
+  override fun storageRemove(key: String, promise: Promise) {
+    prefs.edit().remove(key).apply()
+    promise.resolve(null)
+  }
+
+  // --- Secure storage (Keystore-backed AES/GCM over SharedPreferences) ---
+
+  override fun secureStorageGet(key: String, promise: Promise) {
+    try {
+      val stored = securePrefs.getString(key, null)
+      if (stored == null) {
+        promise.resolve(null)
+      } else {
+        promise.resolve(SecureStorageCipher.decrypt(stored))
+      }
+    } catch (error: Exception) {
+      promise.reject("secure_storage_get_failed", error)
+    }
+  }
+
+  override fun secureStorageSet(key: String, value: String, promise: Promise) {
+    try {
+      securePrefs.edit().putString(key, SecureStorageCipher.encrypt(value)).apply()
+      promise.resolve(null)
+    } catch (error: Exception) {
+      promise.reject("secure_storage_set_failed", error)
+    }
+  }
+
+  override fun secureStorageRemove(key: String, promise: Promise) {
+    securePrefs.edit().remove(key).apply()
+    promise.resolve(null)
+  }
+
+  // --- Signature verification (doc 03 §3.4) ---
+  //
+  // Trusted key material is embedded at build time via a Gradle-injected BuildConfig
+  // field (TRUSTED_SIGNING_KEYS_JSON, a JSON object mapping keyId -> base64 key
+  // material) rather than shipped from JS, per §3.4's "embedded at build time, not
+  // hardcoded in the JS bundle" requirement. Host apps supply this via
+  // `android.defaultConfig.buildConfigField "String", "TRUSTED_SIGNING_KEYS_JSON", "..."`
+  // in their own build.gradle; if absent, verification fails closed (returns false)
+  // rather than silently trusting an unverifiable document.
+
+  private fun resolveKeyMaterial(keyId: String): ByteArray? {
+    return try {
+      val field = Class.forName("${reactApplicationContext.packageName}.BuildConfig")
+        .getField("TRUSTED_SIGNING_KEYS_JSON")
+      val json = org.json.JSONObject(field.get(null) as String)
+      if (!json.has(keyId)) null else Base64.decode(json.getString(keyId), Base64.NO_WRAP)
+    } catch (error: Exception) {
+      null
+    }
+  }
+
+  override fun verifyEd25519(keyId: String, messageBase64: String, signatureBase64: String, promise: Promise) {
+    try {
+      val keyMaterial = resolveKeyMaterial(keyId)
+      if (keyMaterial == null) {
+        promise.resolve(false)
+        return
+      }
+      // Ed25519 via java.security requires API 33+ (Conscrypt) on stock Android; on
+      // older API levels this throws NoSuchAlgorithmException and verification fails
+      // closed rather than silently succeeding — documented platform-version gap.
+      val keySpec = java.security.spec.X509EncodedKeySpec(keyMaterial)
+      val keyFactory = java.security.KeyFactory.getInstance("Ed25519")
+      val publicKey = keyFactory.generatePublic(keySpec)
+      val signature = Signature.getInstance("Ed25519")
+      signature.initVerify(publicKey)
+      signature.update(Base64.decode(messageBase64, Base64.NO_WRAP))
+      promise.resolve(signature.verify(Base64.decode(signatureBase64, Base64.NO_WRAP)))
+    } catch (error: Exception) {
+      promise.reject("verify_ed25519_failed", error)
+    }
+  }
+
+  override fun verifyHmacSha256(keyId: String, messageBase64: String, macBase64: String, promise: Promise) {
+    try {
+      val keyMaterial = resolveKeyMaterial(keyId)
+      if (keyMaterial == null) {
+        promise.resolve(false)
+        return
+      }
+      val mac = Mac.getInstance("HmacSHA256")
+      mac.init(SecretKeySpec(keyMaterial, "HmacSHA256"))
+      val computed = mac.doFinal(Base64.decode(messageBase64, Base64.NO_WRAP))
+      val expected = Base64.decode(macBase64, Base64.NO_WRAP)
+      promise.resolve(constantTimeEquals(computed, expected))
+    } catch (error: Exception) {
+      promise.reject("verify_hmac_sha256_failed", error)
+    }
+  }
+
+  private fun constantTimeEquals(a: ByteArray, b: ByteArray): Boolean {
+    if (a.size != b.size) return false
+    var diff = 0
+    for (i in a.indices) diff = diff or (a[i].toInt() xor b[i].toInt())
+    return diff == 0
+  }
+
+  // --- Background scheduling (doc 01 §4.1 "scheduler" row) ---
+  //
+  // WorkManager PeriodicWorkRequest, minimum periodic interval is 15 minutes (an
+  // OS-enforced floor on Android, not a choice of this library); requests below that
+  // are rounded up. VersionCheckWorker wakes VersionCheckHeadlessTaskService, which
+  // runs the "VersionCheckBackgroundTask" headless JS task the host app must register
+  // (see registerVersionCheckHeadlessTask() in the JS public API).
+
+  override fun scheduleBackgroundCheck(taskId: String, minIntervalMs: Double, promise: Promise) {
+    try {
+      val intervalMinutes = maxOf(15L, (minIntervalMs / 60_000.0).toLong())
+      val request = PeriodicWorkRequestBuilder<VersionCheckWorker>(intervalMinutes, TimeUnit.MINUTES)
+        .addTag(taskId)
+        .build()
+      WorkManager.getInstance(reactApplicationContext)
+        .enqueueUniquePeriodicWork(taskId, ExistingPeriodicWorkPolicy.UPDATE, request)
+      promise.resolve(null)
+    } catch (error: Exception) {
+      promise.reject("schedule_background_check_failed", error)
+    }
+  }
+
+  override fun cancelBackgroundCheck(taskId: String, promise: Promise) {
+    try {
+      WorkManager.getInstance(reactApplicationContext).cancelUniqueWork(taskId)
+      promise.resolve(null)
+    } catch (error: Exception) {
+      promise.reject("cancel_background_check_failed", error)
+    }
+  }
+
+  companion object {
+    const val NAME = NativeVersionCheckSpec.NAME
+    private const val PREFS_NAME = "rs_version_check_prefs"
+    private const val SECURE_PREFS_NAME = "rs_version_check_secure_prefs"
+  }
+}