@qntx/wallet-native 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# @qntx/wallet-native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React Native host for [`@qntx/wallet`](https://www.npmjs.com/package/@qntx/wallet): runs the
+wallet kernel on its own Hermes runtime on a separate thread (the Nitro `KernelHost` object
+shuttles CBOR messages to it across JSI), keeps the
+encrypted vault under the platform's never-backed-up directory, and makes the platform keystore
+(Secure Enclave on iOS, Android Keystore) the vault factor — every unlock and every signing
+request is gated by a system user-presence prompt rendered with kernel-owned text.
+
+```bash
+npm install @qntx/wallet-native @qntx/wallet @qntx/nostr-native @qntx/spark-native
+```
+
+Peer dependencies (exact `@qntx/*` pins are required — the host/kernel protocol and the bundled
+kernel artifacts are built against those releases):
+
+| package                      | range            |
+| ---------------------------- | ---------------- |
+| `@qntx/wallet`               | `0.4.0` (exact)  |
+| `@qntx/nostr-native`         | `0.15.3` (exact) |
+| `@qntx/spark-native`         | `0.5.2` (exact)  |
+| `react-native`               | `~0.88.0`        |
+| `react-native-nitro-modules` | `~0.37.1`        |
+
+The package registers one Nitro hybrid object, `KernelHost`. Everything else the kernel needs —
+keystore, passkey ceremonies, lifecycle, pbkdf2, the vault directory — is injected as JSI host
+objects inside the kernel runtime and is never registered with Nitro. **No Nitro patch or
+`nitro::install` call is needed in the consuming app.**
+
+## Expo configuration
+
+```ts
+// app.config.ts
+export default {
+  ios: {
+    bundleIdentifier: "com.example.app",
+    infoPlist: { NSFaceIDUsageDescription: "Verify your identity to unlock your wallet" },
+  },
+  android: { package: "com.example.app" },
+  plugins: [
+    ["expo-build-properties", { ios: { useFrameworks: "static" }, android: { minSdkVersion: 30 } }],
+  ],
+};
+```
+
+- `ios.infoPlist.NSFaceIDUsageDescription` — required: the keystore evaluates device-owner
+  presence through `LAContext`, which needs the Face ID purpose string.
+- `ios.useFrameworks: "static"` is supported.
+- `android.minSdkVersion: 30` — required: per-use Keystore keys that accept a biometric _or_ the
+  device credential need API 30 (`setUserAuthenticationParameters` semantics).
+
+## Usage
+
+```ts
+import { createNativeWallet } from "@qntx/wallet-native";
+
+const wallet = await createNativeWallet({
+  passkey: {
+    rpId: "example.com",
+    rpName: "Example",
+    walletSalt: "example/wallet",
+    vaultSalt: "example/vault",
+    backupSalt: "example/backup",
+  },
+  autoLock: { platform: "native", backgroundSeconds: 60 },
+});
+```
+
+- `passkey` — relying-party config for the passkey _wallet_ flow (create/restore with a synced
+  passkey). `rpId`, `walletSalt` and `vaultSalt` are permanent identifiers: changing them makes
+  existing passkey factors and passkey-derived wallets unrecoverable. `backupSalt` is the PRF
+  salt for the cloud-backup factor — a third, distinct permanent label.
+- `autoLock` — must be `{ platform: "native", backgroundSeconds }`. The native host owns the
+  signal: it calls `host.lock()` when the app has spent `backgroundSeconds` in the background.
+  A platform authentication prompt on screen does **not** count as background time.
+
+## Passkey domains
+
+Passkey wallets need the platform's domain association:
+
+- **iOS** — `webcredentials:<rpId>` associated domain (requires a paid developer account; free
+  signing cannot hold the entitlement). **Native iOS passkeys are not implemented yet** — the
+  ceremony returns `factor-unavailable`, so `createWithPasskey`/`restoreWithPasskey` cannot be
+  offered on iOS; ship mnemonic restore.
+- **Android** — Credential Manager resolves the RP against
+  `https://<rpId>/.well-known/assetlinks.json` with
+  `delegate_permission/common.get_login_creds` naming the app's package and SHA-256 signing
+  certificate. Android passkeys are implemented via `androidx.credentials`.
+
+## Vault storage and backup
+
+- **iOS** — the vault image lives under `Application Support/qntx-wallet/`, created with
+  `NSFileProtectionComplete` and `NSURLIsExcludedFromBackupKey`. Device-to-device migration and
+  iCloud backups must not carry the vault: it is bound to this device's hardware factor, which
+  cannot leave the Secure Enclave.
+- **Android** — the vault image lives under `noBackupFilesDir/qntx-wallet`, excluded from
+  Auto Backup by construction.
+
+## Security notes
+
+- The hardware vault factor is the only factor kind on this platform. Unlock, vault creation,
+  mnemonic/key export, wallet deletion, cloud-backup enable, reset and every `chain.sign` /
+  `spark.approve` request open a platform authentication ceremony with kernel-owned prompt text
+  (Simplified Chinese under a `zh*` locale, English otherwise).
+- `vault.reset` authenticates the device owner first, then erases the vault and all hardware
+  keys. Devices without a lock screen return `factor-unavailable` — the host should send the
+  user to set one up.
+- `chain.sign` prompts _before_ any secret derivation: the kernel normalizes and decodes the
+  intent, shows the prompt, and only then touches key material.
+- The kernel serializes ceremonies — two concurrent signing requests cannot race two system
+  prompts.
+- `kernel/generated/kernel.manifest.json` inside the package records the kernel bundle's
+  SHA-256 and every pinned protocol dependency; `scripts/compile-kernel.mjs` verifies it when
+  the host is natively built and fails the build on a mismatch. At kernel start the host
+  checks each backend's `abiVersion`.
+- On the iOS simulator the Secure Enclave token and the `.privateKeyUsage` flag are compiled
+  out, so ceremonies run on software keys through the same code path. The app must be
+  code-signed (the default ad-hoc "Sign to Run Locally" identity suffices) — an unsigned
+  binary fails every `SecItem` call with `errSecMissingEntitlement` (-34018), surfaced as
+  `unavailable`.
+
+## License
+
+MIT OR Apache-2.0

package/WalletNative.podspec

@@ -0,0 +1,74 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "WalletNative"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = "https://github.com/qntx/wallet"
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/qntx/wallet.git" }
+  # Swift pods (V1Probe's Nitrogen bridge) depend on this — a module map is required.
+  s.static_framework = true
+
+  s.source_files = [
+    "cpp/runtime/**/*.{h,hpp,c,cpp,mm}",
+    "cpp/host/**/*.{h,hpp,c,cpp,mm}",
+    "cpp/platform/**/*.{h,hpp,c,cpp,mm}",
+  ]
+  s.public_header_files = "cpp/**/*.hpp"
+  s.header_mappings_dir = "cpp"
+
+  s.pod_target_xcconfig = {
+    "DEFINES_MODULE" => "YES",
+    "CLANG_CXX_LANGUAGE_STANDARD" => "c++20",
+    "HEADER_SEARCH_PATHS" => [
+      '"$(PODS_TARGET_SRCROOT)/cpp"',
+      '"$(PODS_ROOT)/hermes-engine/destroot/include"',
+      '"$(PODS_ROOT)/Headers/Public/SparkNative"',
+      '"$(DERIVED_FILE_DIR)/qntx-kernel"',
+    ].join(' '),
+  }
+
+  # Compile the shipped kernel-entry.js to bytecode with the app's own hermesc —
+  # Hermes only loads its own bytecode version, so precompiled hbc cannot ship.
+  # kernel.hpp lands in DERIVED_FILE_DIR/qntx-kernel (a header search path).
+  s.script_phase = {
+    :name => "Compile Kernel Bytecode",
+    :script => <<~SH,
+      if [ -z "$REACT_NATIVE_PATH" ]; then
+        echo "REACT_NATIVE_PATH is not set"
+        exit 1
+      fi
+      . "$REACT_NATIVE_PATH/scripts/xcode/with-environment.sh"
+      "$NODE_BINARY" "$PODS_TARGET_SRCROOT/scripts/compile-kernel.mjs" \
+        "$DERIVED_FILE_DIR/qntx-kernel" "$REACT_NATIVE_PATH"
+    SH
+    :execution_position => :before_compile,
+    :input_files => [
+      "$(PODS_TARGET_SRCROOT)/kernel/generated/kernel-entry.js",
+      "$(PODS_TARGET_SRCROOT)/kernel/generated/kernel.manifest.json",
+      "$(PODS_TARGET_SRCROOT)/scripts/compile-kernel.mjs",
+    ],
+    :output_files => ["$(DERIVED_FILE_DIR)/qntx-kernel/kernel.hpp"],
+  }
+
+  # The kernel's backends.spark binds the qs_* C ABI; the prebuilt
+  # QntxSpark.xcframework ships inside the SparkNative pod.
+  s.frameworks = "LocalAuthentication", "Security"
+
+  s.dependency 'NostrNative'
+  s.dependency 'SparkNative'
+  s.dependency 'React-jsi'
+  s.dependency 'React-callinvoker'
+  s.dependency 'React-hermes'
+  s.dependency 'hermes-engine'
+
+  load 'nitrogen/generated/ios/WalletNative+autolinking.rb'
+  add_nitrogen_files(s)
+  install_modules_dependencies(s)
+end

package/android/CMakeLists.txt

@@ -0,0 +1,99 @@
+project(WalletNative)
+cmake_minimum_required(VERSION 3.16)
+
+set(PACKAGE_NAME WalletNative)
+set(CMAKE_VERBOSE_MAKEFILE ON)
+set(CMAKE_CXX_STANDARD 20)
+
+file(GLOB_RECURSE runtime_files CONFIGURE_DEPENDS
+     "${CMAKE_CURRENT_SOURCE_DIR}/../cpp/runtime/*.cpp"
+     "${CMAKE_CURRENT_SOURCE_DIR}/../cpp/host/*.cpp"
+     "${CMAKE_CURRENT_SOURCE_DIR}/../cpp/platform/*.cpp"
+     "${CMAKE_CURRENT_SOURCE_DIR}/src/main/cpp/*.cpp"
+)
+
+add_library(${PACKAGE_NAME} SHARED ${runtime_files})
+target_include_directories(${PACKAGE_NAME} PUBLIC
+     "${CMAKE_CURRENT_SOURCE_DIR}/../cpp"
+     "${CMAKE_CURRENT_SOURCE_DIR}/../cpp/host"
+     "${CMAKE_CURRENT_SOURCE_DIR}/../cpp/platform"
+     "${CMAKE_CURRENT_BINARY_DIR}/qntx-kernel"
+)
+
+# Compile the shipped kernel bundle to bytecode with the app's own hermesc —
+# Hermes only loads its own bytecode version, so precompiled hbc cannot ship.
+# The app's react-native root is passed explicitly (-DQNTX_REACT_NATIVE_PATH)
+# so the script resolves the app's own hermesc version.
+find_program(NODE_EXECUTABLE node REQUIRED)
+if(NOT QNTX_REACT_NATIVE_PATH)
+  message(FATAL_ERROR "QNTX_REACT_NATIVE_PATH is not set — the consuming app must pass -DQNTX_REACT_NATIVE_PATH=<react-native dir>")
+endif()
+set(KERNEL_HEADER "${CMAKE_CURRENT_BINARY_DIR}/qntx-kernel/kernel.hpp")
+add_custom_command(
+     OUTPUT ${KERNEL_HEADER}
+     COMMAND ${NODE_EXECUTABLE}
+             "${CMAKE_CURRENT_SOURCE_DIR}/../scripts/compile-kernel.mjs"
+             "${CMAKE_CURRENT_BINARY_DIR}/qntx-kernel"
+             "${QNTX_REACT_NATIVE_PATH}"
+     DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/../kernel/generated/kernel-entry.js"
+             "${CMAKE_CURRENT_SOURCE_DIR}/../kernel/generated/kernel.manifest.json"
+             "${CMAKE_CURRENT_SOURCE_DIR}/../scripts/compile-kernel.mjs"
+     COMMENT "Compiling the kernel bytecode (hermesc)"
+     VERBATIM
+)
+add_custom_target(qntx-kernel-bytecode DEPENDS ${KERNEL_HEADER})
+add_dependencies(${PACKAGE_NAME} qntx-kernel-bytecode)
+
+# The kernel's backends.spark binds the qs_* C ABI: the prebuilt
+# libqntx_spark.so + header ship inside the app's @qntx/spark-native package
+# (dir passed as -DQNTX_SPARK_NATIVE_PATH, resolved like the react-native dir).
+if(NOT QNTX_SPARK_NATIVE_PATH)
+  message(FATAL_ERROR "QNTX_SPARK_NATIVE_PATH is not set — the consuming app must pass -DQNTX_SPARK_NATIVE_PATH=<@qntx/spark-native dir>")
+endif()
+set(QNTX_SPARK_LIBDIR "${QNTX_SPARK_NATIVE_PATH}/android/src/main/jniLibs/${ANDROID_ABI}")
+if(NOT EXISTS "${QNTX_SPARK_LIBDIR}/libqntx_spark.so")
+  message(FATAL_ERROR "libqntx_spark.so for ${ANDROID_ABI} not found in ${QNTX_SPARK_LIBDIR}")
+endif()
+# The .so carries SONAME since 0.5.1, so the path link records the soname in
+# DT_NEEDED — the loader resolves it from the packaged jniLibs. GLOBAL: this
+# target's link libraries are transitive (plain signature), so
+# add_subdirectory consumers (v1-probe) see and link the same imported target.
+add_library(qntx_spark SHARED IMPORTED GLOBAL)
+set_target_properties(qntx_spark PROPERTIES
+     IMPORTED_LOCATION "${QNTX_SPARK_LIBDIR}/libqntx_spark.so")
+target_include_directories(${PACKAGE_NAME} PRIVATE "${QNTX_SPARK_NATIVE_PATH}/include")
+
+find_package(qntx_nostr-native REQUIRED CONFIG)
+
+# Adds the nitrogen-generated sources, the BUILDING_..._GENERATED_CMAKE_PROJECT
+# define they require, and the fbjni/ReactAndroid/NitroModules prefab links.
+include(${CMAKE_CURRENT_SOURCE_DIR}/../nitrogen/generated/android/WalletNative+autolinking.cmake)
+
+# Same Hermes link pattern as react-native-worklets 0.10.1: the hermes-engine
+# prefab target is hermesvm on RN >= 0.82 and libhermes before that. The version
+# minor comes from the ReactAndroid prefab config.
+find_package(hermes-engine REQUIRED CONFIG)
+
+# The generated autolinking.cmake already defines the FOLLY flags this module
+# needs; the runtime only adds RN_SERIALIZABLE_STATE. (folly-flags.cmake itself
+# is only reachable relative to the consuming app's node_modules, which this
+# module cannot assume when it is built standalone.)
+target_compile_definitions(${PACKAGE_NAME} PRIVATE -DRN_SERIALIZABLE_STATE)
+
+find_library(LOG_LIB log)
+
+target_link_libraries(
+        ${PACKAGE_NAME}
+        fbjni::fbjni
+        ReactAndroid::jsi
+        qntx_spark
+        qntx_nostr-native::NostrNative
+        ${LOG_LIB}
+        android
+)
+
+if(ReactAndroid_VERSION_MINOR GREATER_EQUAL 82)
+  target_link_libraries(${PACKAGE_NAME} hermes-engine::hermesvm)
+else()
+  target_link_libraries(${PACKAGE_NAME} hermes-engine::libhermes)
+endif()

package/android/build.gradle

@@ -0,0 +1,177 @@
+buildscript {
+  repositories {
+    google()
+    mavenCentral()
+  }
+  dependencies {
+
+    classpath "com.android.tools.build:gradle:9.2.1"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["x86", "x86_64", "armeabi-v7a", "arm64-v8a"]
+}
+
+def isNewArchitectureEnabled() {
+  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
+}
+
+apply plugin: "com.android.library"
+apply plugin: 'org.jetbrains.kotlin.android'
+apply from: '../nitrogen/generated/android/WalletNative+autolinking.gradle'
+
+if (isNewArchitectureEnabled()) {
+  apply plugin: "com.facebook.react"
+
+
+}
+
+def getExtOrDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["WalletNative_" + name]
+}
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["WalletNative_" + name]).toInteger()
+}
+
+android {
+  namespace = "com.margelo.nitro.qntxwallet"
+
+  ndkVersion = getExtOrDefault("ndkVersion")
+  compileSdkVersion = getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    // WD-024: per-use Keystore keys that accept a biometric or the device
+    // credential through BiometricPrompt need API 30.
+    minSdkVersion = 30
+    targetSdkVersion = getExtOrIntegerDefault("targetSdkVersion")
+
+    consumerProguardFiles "consumer-rules.pro"
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -Wextra -fstack-protector-all"
+        // The consuming app's react-native root — resolved through node module
+        // resolution from the app project (as RN's own settings.gradle does);
+        // compile-kernel.mjs then resolves hermesc through it.
+        arguments "-DANDROID_STL=c++_shared", "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON",
+            // The consuming app's react-native dir, resolved through node
+            // module resolution from the app project — a library cannot reach
+            // it by walking up from its own tree.
+            "-DQNTX_REACT_NATIVE_PATH=" + providers.exec {
+                workingDir = rootProject.projectDir
+                commandLine "node", "-p", "require('path').dirname(require.resolve('react-native/package.json'))"
+            }.standardOutput.asText.get().trim(),
+            // The app's @qntx/spark-native dir (header + per-ABI libqntx_spark.so),
+            // resolved the same way.
+            "-DQNTX_SPARK_NATIVE_PATH=" + providers.exec {
+                workingDir = rootProject.projectDir
+                commandLine "node", "-p", "require('path').dirname(require.resolve('@qntx/spark-native/package.json'))"
+            }.standardOutput.asText.get().trim()
+        abiFilters (*reactNativeArchitectures())
+        buildTypes {
+          debug {
+            cppFlags "-O1 -g"
+          }
+          release {
+            cppFlags "-O2"
+          }
+        }
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path = file("CMakeLists.txt")
+    }
+  }
+
+  packagingOptions {
+    excludes = [
+      "META-INF",
+      "META-INF/**",
+      "**/libNitroModules.so",
+      "**/libc++_shared.so",
+      "**/libfbjni.so",
+      "**/libjsi.so",
+      "**/libfolly_json.so",
+      "**/libfolly_runtime.so",
+      "**/libglog.so",
+      "**/libhermes.so",
+      "**/libhermes-executor-debug.so",
+      "**/libhermes_executor.so",
+      "**/libreactnative.so",
+      "**/libreactnativejni.so",
+      "**/libturbomodulejsijni.so",
+      "**/libreact_nativemodule_core.so",
+      "**/libjscexecutor.so",
+      // Linked, not bundled — @qntx/spark-native packages it from its jniLibs.
+      "**/libqntx_spark.so"
+    ]
+  }
+
+  buildFeatures {
+    buildConfig = true
+    prefab = true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled = false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  sourceSets {
+    main {
+      if (isNewArchitectureEnabled()) {
+        java.srcDirs += [
+          "${project.buildDir}/generated/source/codegen/java"
+        ]
+      }
+    }
+  }
+}
+
+dependencies {
+  // For > 0.71, this is replaced by `com.facebook.react:react-android:$version` by the React
+  // gradle plugin — it supplies the fbjni/ReactAndroid prefab packages the generated CMake
+  // autolinking file finds with find_package.
+  //noinspection GradleDynamicVersion
+  implementation "com.facebook.react:react-native:+"
+
+  // Hermes engine prefab — the kernel runtime links hermesvm/libhermes
+  implementation "com.facebook.react:hermes-android"
+
+  // NitroModules core (provides the react-native-nitro-modules prefab + HybridObject runtime)
+  implementation project(":react-native-nitro-modules")
+  implementation project(":qntx_nostr-native")
+
+  // ProcessLifecycleOwner for the background lock (W7) — the version the app
+  // already resolves for androidx.lifecycle.
+  implementation "androidx.lifecycle:lifecycle-process:2.6.2"
+
+  // BiometricPrompt + CryptoObject for the hardware vault factor (W5).
+  implementation "androidx.biometric:biometric:1.1.0"
+
+  // Credential Manager for native passkeys (W6); the Play services provider
+  // backs Google Password Manager.
+  implementation "androidx.credentials:credentials:1.6.0"
+  implementation "androidx.credentials:credentials-play-services-auth:1.6.0"
+}
+
+repositories {
+  mavenCentral()
+  google()
+}

package/android/consumer-rules.pro

@@ -0,0 +1,4 @@
+# Called from native code over JNI or bound to JNI by method-name mangling;
+# R8 would otherwise strip or rename them (the classes have no direct Java
+# call sites inside the app).
+-keep class com.margelo.nitro.qntxwallet.** { *; }

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/cpp/cpp-adapter.cpp

@@ -0,0 +1,29 @@
+#include "WalletNativeOnLoad.hpp"
+#include "host/VaultDirectory.hpp"
+#include "runtime/platform/KernelPbkdf2.hpp"
+#include <fbjni/fbjni.h>
+#include <jni.h>
+
+namespace qntx {
+void kernelVaultDirectoryInit(facebook::jni::alias_ref<jclass> clazz);
+void kernelLifecycleInit(facebook::jni::alias_ref<jclass> clazz);
+void kernelKeystoreInit(facebook::jni::alias_ref<jclass> clazz);
+void kernelPasskeyInit(facebook::jni::alias_ref<jclass> clazz);
+}
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
+  return facebook::jni::initialize(vm, []() {
+    qntx::kernelVaultDirectoryInit(
+        facebook::jni::findClassLocal("com/margelo/nitro/qntxwallet/VaultDirectory"));
+    qntx::kernelLifecycleInit(
+        facebook::jni::findClassLocal("com/margelo/nitro/qntxwallet/AppLifecycle"));
+    qntx::kernelKeystoreInit(
+        facebook::jni::findClassLocal("com/margelo/nitro/qntxwallet/Keystore"));
+    qntx::kernelPasskeyInit(
+        facebook::jni::findClassLocal("com/margelo/nitro/qntxwallet/Passkey"));
+    margelo::nitro::qntxwallet::registerAllNatives();
+    qntx::kernelPbkdf2OnLoad(
+        facebook::jni::Environment::current(),
+        "com/margelo/nitro/qntxwallet/KernelPbkdf2");
+  });
+}

package/android/src/main/java/com/margelo/nitro/qntxwallet/AppLifecycle.kt

@@ -0,0 +1,35 @@
+package com.margelo.nitro.qntxwallet
+
+import android.os.Handler
+import android.os.Looper
+import androidx.annotation.Keep
+import androidx.lifecycle.DefaultLifecycleObserver
+import androidx.lifecycle.LifecycleOwner
+import androidx.lifecycle.ProcessLifecycleOwner
+import com.facebook.proguard.annotations.DoNotStrip
+
+/**
+ * Process-wide lifecycle: the C++ host calls [install] once (fbjni, first
+ * KernelHost.start); the observer forwards app background/foreground
+ * transitions to the native dispatcher on the main looper.
+ */
+@DoNotStrip
+@Keep
+object AppLifecycle {
+
+    @JvmStatic
+    fun install() {
+        Handler(Looper.getMainLooper()).post {
+            ProcessLifecycleOwner.get().lifecycle.addObserver(object : DefaultLifecycleObserver {
+                override fun onStop(owner: LifecycleOwner) = onAppBackground()
+                override fun onStart(owner: LifecycleOwner) = onAppForeground()
+            })
+        }
+    }
+
+    @JvmStatic
+    private external fun onAppBackground()
+
+    @JvmStatic
+    private external fun onAppForeground()
+}

package/android/src/main/java/com/margelo/nitro/qntxwallet/KernelPbkdf2.java

@@ -0,0 +1,59 @@
+package com.margelo.nitro.qntxwallet;
+
+import java.security.GeneralSecurityException;
+import java.util.Arrays;
+import javax.crypto.Mac;
+import javax.crypto.spec.SecretKeySpec;
+
+/**
+ * PBKDF2 for the kernel runtime, called from C++ over JNI on the dedicated KDF worker thread.
+ *
+ * Byte-exact RFC 8018 derivation over javax.crypto.Mac — there is no SecretKeyFactory/PBEKeySpec
+ * path, because chars decoded from the password's UTF-8 bytes are provider-specific. All
+ * intermediate arrays the VM hands back (u, t, out) are wiped. Note that SecretKeySpec and JCA
+ * provider internals retain their own non-wipeable copies of the key material; the caller-side
+ * buffers are still zeroed by JniByteArray after return.
+ */
+public final class KernelPbkdf2 {
+  private KernelPbkdf2() {}
+
+  public static byte[] derive(String hmacAlgorithm, byte[] password, byte[] salt, int iterations, int length)
+      throws GeneralSecurityException {
+    SecretKeySpec key = new SecretKeySpec(password, hmacAlgorithm);
+    Mac mac = Mac.getInstance(hmacAlgorithm);
+    mac.init(key);
+    int blockSize = mac.getMacLength();
+    int blocks = (length + blockSize - 1) / blockSize;
+    byte[] out = new byte[blocks * blockSize];
+    byte[] index = new byte[4];
+    int offset = 0;
+    try {
+      for (int block = 1; block <= blocks; block++) {
+        index[0] = (byte) (block >>> 24);
+        index[1] = (byte) (block >>> 16);
+        index[2] = (byte) (block >>> 8);
+        index[3] = (byte) block;
+        mac.update(salt);
+        byte[] u = mac.doFinal(index);
+        byte[] t = u.clone();
+        for (int j = 1; j < iterations; j++) {
+          byte[] next = mac.doFinal(u);
+          Arrays.fill(u, (byte) 0);
+          u = next;
+          for (int k = 0; k < u.length; k++) {
+            t[k] ^= u[k];
+          }
+        }
+        System.arraycopy(t, 0, out, offset, blockSize);
+        offset += blockSize;
+        Arrays.fill(u, (byte) 0);
+        Arrays.fill(t, (byte) 0);
+      }
+      return Arrays.copyOf(out, length);
+    } finally {
+      Arrays.fill(out, (byte) 0);
+      Arrays.fill(index, (byte) 0);
+      Arrays.fill(password, (byte) 0);
+    }
+  }
+}