@qntx/wallet-native 0.0.0-stage → 0.4.0

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

@@ -0,0 +1,280 @@
+package com.margelo.nitro.qntxwallet
+
+import android.app.KeyguardManager
+import android.content.Context
+import android.content.pm.PackageManager
+import android.os.LocaleList
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyPermanentlyInvalidatedException
+import android.security.keystore.KeyProperties
+import android.security.keystore.StrongBoxUnavailableException
+import androidx.annotation.Keep
+import androidx.biometric.BiometricManager.Authenticators.BIOMETRIC_STRONG
+import androidx.biometric.BiometricManager.Authenticators.DEVICE_CREDENTIAL
+import androidx.biometric.BiometricPrompt
+import androidx.core.content.ContextCompat
+import androidx.fragment.app.FragmentActivity
+import androidx.lifecycle.DefaultLifecycleObserver
+import androidx.lifecycle.Lifecycle
+import androidx.lifecycle.LifecycleOwner
+import com.facebook.proguard.annotations.DoNotStrip
+import com.margelo.nitro.NitroModules
+import java.security.KeyStore
+import java.util.concurrent.Executor
+import java.security.UnrecoverableKeyException
+import javax.crypto.Cipher
+import javax.crypto.KeyGenerator
+import javax.crypto.SecretKey
+import javax.crypto.spec.GCMParameterSpec
+
+/**
+ * Android keystore (W5): one AndroidKeyStore AES-256-GCM key per vault factor
+ * (`qntx-wallet.vault.<factor id>`), StrongBox-backed when present. Every use
+ * needs a fresh BiometricPrompt (strong biometric or device credential) bound
+ * to the cipher through a CryptoObject; the key survives biometric enrollment
+ * changes and dies with the lock screen. The C++ host calls these entry points
+ * with a completion token and receives the result through [nativeComplete].
+ * Sealed bytes are `iv(12) ‖ ciphertext ‖ tag(16)`.
+ */
+@DoNotStrip
+@Keep
+object Keystore {
+  private const val PREFIX = "qntx-wallet.vault."
+  private const val PROVIDER = "AndroidKeyStore"
+  private const val TRANSFORMATION = "AES/GCM/NoPadding"
+  private const val IV_BYTES = 12
+  private const val TAG_BITS = 128
+
+  // Status codes shared with KeystoreAndroid.cpp.
+  private const val OK = 0
+  private const val CANCELLED = 1
+  private const val INVALIDATED = 2
+  private const val UNAVAILABLE = 3
+  private const val FAILED = 4
+
+  @Volatile private var current: BiometricPrompt? = null
+
+  @JvmStatic
+  fun locale(): String = LocaleList.getDefault()[0]?.toLanguageTag() ?: "en"
+
+  @JvmStatic
+  fun seal(token: Long, id: String, secret: ByteArray, title: String, description: String) {
+    val activity = foregroundActivity()
+    if (activity == null || !deviceSecure(activity)) {
+      secret.fill(0)
+      return nativeComplete(token, UNAVAILABLE, null)
+    }
+    val alias = PREFIX + id
+    val cipher = try {
+      keyStore().deleteEntry(alias)
+      Cipher.getInstance(TRANSFORMATION).apply { init(Cipher.ENCRYPT_MODE, generate(alias, activity)) }
+    } catch (e: Exception) {
+      secret.fill(0)
+      return nativeComplete(token, UNAVAILABLE, null)
+    }
+    prompt(activity, title, description, BiometricPrompt.CryptoObject(cipher)) { status, crypto ->
+      try {
+        val authenticated = crypto?.cipher
+        if (status != OK || authenticated == null) {
+          keyStore().deleteEntry(alias)
+          nativeComplete(token, if (status == OK) FAILED else status, null)
+        } else {
+          nativeComplete(token, OK, authenticated.iv + authenticated.doFinal(secret))
+        }
+      } catch (e: Exception) {
+        keyStore().deleteEntry(alias)
+        nativeComplete(token, FAILED, null)
+      } finally {
+        secret.fill(0)
+      }
+    }
+  }
+
+  @JvmStatic
+  fun open(token: Long, id: String, sealed: ByteArray, title: String, description: String) {
+    val activity = foregroundActivity() ?: return nativeComplete(token, UNAVAILABLE, null)
+    if (sealed.size <= IV_BYTES + TAG_BITS / 8) {
+      return nativeComplete(token, FAILED, null)
+    }
+    val alias = PREFIX + id
+    val key = try {
+      keyStore().getKey(alias, null) as? SecretKey
+    } catch (e: UnrecoverableKeyException) {
+      null
+    } ?: return nativeComplete(token, INVALIDATED, null)
+    val cipher = try {
+      Cipher.getInstance(TRANSFORMATION).apply {
+        init(Cipher.DECRYPT_MODE, key, GCMParameterSpec(TAG_BITS, sealed, 0, IV_BYTES))
+      }
+    } catch (e: KeyPermanentlyInvalidatedException) {
+      keyStore().deleteEntry(alias)
+      return nativeComplete(token, INVALIDATED, null)
+    } catch (e: Exception) {
+      return nativeComplete(token, FAILED, null)
+    }
+    prompt(activity, title, description, BiometricPrompt.CryptoObject(cipher)) { status, crypto ->
+      val authenticated = crypto?.cipher
+      if (status != OK || authenticated == null) {
+        nativeComplete(token, if (status == OK) FAILED else status, null)
+        return@prompt
+      }
+      val plain = try {
+        authenticated.doFinal(sealed, IV_BYTES, sealed.size - IV_BYTES)
+      } catch (e: Exception) {
+        return@prompt nativeComplete(token, FAILED, null)
+      }
+      try {
+        nativeComplete(token, OK, plain)
+      } finally {
+        plain.fill(0)
+      }
+    }
+  }
+
+  @JvmStatic
+  fun authenticate(token: Long, title: String, description: String) {
+    val activity = foregroundActivity()
+    if (activity == null || !deviceSecure(activity)) {
+      return nativeComplete(token, UNAVAILABLE, null)
+    }
+    prompt(activity, title, description, null) { status, _ -> nativeComplete(token, status, null) }
+  }
+
+  @JvmStatic
+  fun clear(token: Long) {
+    val status = try {
+      val store = keyStore()
+      store.aliases().toList().filter { it.startsWith(PREFIX) }.forEach(store::deleteEntry)
+      OK
+    } catch (e: Exception) {
+      FAILED
+    }
+    nativeComplete(token, status, null)
+  }
+
+  @JvmStatic
+  fun cancel() {
+    val activity = foregroundActivity() ?: return
+    ContextCompat.getMainExecutor(activity).execute { current?.cancelAuthentication() }
+  }
+
+  private fun foregroundActivity(): FragmentActivity? =
+    NitroModules.applicationContext?.currentActivity as? FragmentActivity
+
+  private fun deviceSecure(context: Context): Boolean =
+    context.getSystemService(KeyguardManager::class.java)?.isDeviceSecure == true
+
+  private fun keyStore(): KeyStore = KeyStore.getInstance(PROVIDER).apply { load(null) }
+
+  private fun generate(alias: String, context: Context): SecretKey {
+    val strongBox = context.packageManager.hasSystemFeature(PackageManager.FEATURE_STRONGBOX_KEYSTORE)
+    return try {
+      generate(alias, strongBox)
+    } catch (e: StrongBoxUnavailableException) {
+      generate(alias, false)
+    }
+  }
+
+  private fun generate(alias: String, strongBox: Boolean): SecretKey {
+    val spec = KeyGenParameterSpec.Builder(
+      alias,
+      KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT,
+    )
+      .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+      .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+      .setKeySize(256)
+      .setUserAuthenticationRequired(true)
+      .setUserAuthenticationParameters(
+        0,
+        KeyProperties.AUTH_BIOMETRIC_STRONG or KeyProperties.AUTH_DEVICE_CREDENTIAL,
+      )
+      .setUnlockedDeviceRequired(true)
+      .setInvalidatedByBiometricEnrollment(false)
+      .setIsStrongBoxBacked(strongBox)
+      .build()
+    return KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, PROVIDER)
+      .apply { init(spec) }
+      .generateKey()
+  }
+
+  /** Shows one system verification on the main thread; [done] runs there with the outcome. */
+  private fun prompt(
+    activity: FragmentActivity,
+    title: String,
+    description: String,
+    crypto: BiometricPrompt.CryptoObject?,
+    done: (Int, BiometricPrompt.CryptoObject?) -> Unit,
+  ) {
+    val executor = ContextCompat.getMainExecutor(activity)
+    executor.execute { whenResumed(activity) { show(activity, executor, title, description, crypto, done) } }
+  }
+
+  // A prompt started while the activity is not resumed — e.g. right after a
+  // Credential Manager sheet finishes and before our activity is back on top —
+  // is cancelled by the framework at once. Start it on the next ON_RESUME.
+  private fun whenResumed(activity: FragmentActivity, action: () -> Unit) {
+    val lifecycle = activity.lifecycle
+    if (lifecycle.currentState.isAtLeast(Lifecycle.State.RESUMED)) {
+      action()
+      return
+    }
+    lifecycle.addObserver(object : DefaultLifecycleObserver {
+      override fun onResume(owner: LifecycleOwner) {
+        lifecycle.removeObserver(this)
+        action()
+      }
+    })
+  }
+
+  private fun show(
+    activity: FragmentActivity,
+    executor: Executor,
+    title: String,
+    description: String,
+    crypto: BiometricPrompt.CryptoObject?,
+    done: (Int, BiometricPrompt.CryptoObject?) -> Unit,
+  ) {
+    val info = BiometricPrompt.PromptInfo.Builder()
+      .setTitle(title)
+      .setDescription(description)
+      .setAllowedAuthenticators(BIOMETRIC_STRONG or DEVICE_CREDENTIAL)
+      .build()
+    val biometricPrompt = BiometricPrompt(
+      activity,
+      executor,
+      object : BiometricPrompt.AuthenticationCallback() {
+        override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
+          current = null
+          done(OK, result.cryptoObject)
+        }
+
+        override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
+          current = null
+          done(statusOf(errorCode), null)
+        }
+      },
+    )
+    current = biometricPrompt
+    try {
+      if (crypto == null) biometricPrompt.authenticate(info) else biometricPrompt.authenticate(info, crypto)
+    } catch (e: Exception) {
+      current = null
+      done(FAILED, null)
+    }
+  }
+
+  private fun statusOf(errorCode: Int): Int = when (errorCode) {
+    BiometricPrompt.ERROR_USER_CANCELED,
+    BiometricPrompt.ERROR_NEGATIVE_BUTTON,
+    BiometricPrompt.ERROR_CANCELED,
+    BiometricPrompt.ERROR_TIMEOUT -> CANCELLED
+    BiometricPrompt.ERROR_NO_DEVICE_CREDENTIAL,
+    BiometricPrompt.ERROR_HW_UNAVAILABLE,
+    BiometricPrompt.ERROR_HW_NOT_PRESENT,
+    BiometricPrompt.ERROR_NO_BIOMETRICS -> UNAVAILABLE
+    else -> FAILED
+  }
+
+  @JvmStatic
+  private external fun nativeComplete(token: Long, status: Int, bytes: ByteArray?)
+}

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

@@ -0,0 +1,147 @@
+package com.margelo.nitro.qntxwallet
+
+import android.os.CancellationSignal
+import android.util.Log
+import androidx.annotation.Keep
+import androidx.core.content.ContextCompat
+import androidx.credentials.CreateCredentialResponse
+import androidx.credentials.CreatePublicKeyCredentialRequest
+import androidx.credentials.CreatePublicKeyCredentialResponse
+import androidx.credentials.CredentialManager
+import androidx.credentials.CredentialManagerCallback
+import androidx.credentials.GetCredentialRequest
+import androidx.credentials.GetCredentialResponse
+import androidx.credentials.GetPublicKeyCredentialOption
+import androidx.credentials.PublicKeyCredential
+import androidx.credentials.exceptions.CreateCredentialCancellationException
+import androidx.credentials.exceptions.CreateCredentialException
+import androidx.credentials.exceptions.CreateCredentialNoCreateOptionException
+import androidx.credentials.exceptions.CreateCredentialProviderConfigurationException
+import androidx.credentials.exceptions.CreateCredentialUnsupportedException
+import androidx.credentials.exceptions.GetCredentialCancellationException
+import androidx.credentials.exceptions.GetCredentialException
+import androidx.credentials.exceptions.GetCredentialProviderConfigurationException
+import androidx.credentials.exceptions.GetCredentialUnsupportedException
+import androidx.credentials.exceptions.NoCredentialException
+import androidx.credentials.exceptions.publickeycredential.CreatePublicKeyCredentialDomException
+import androidx.credentials.exceptions.publickeycredential.GetPublicKeyCredentialDomException
+import androidx.fragment.app.FragmentActivity
+import com.facebook.proguard.annotations.DoNotStrip
+import com.margelo.nitro.NitroModules
+
+/**
+ * Android passkey authenticator (W6): Credential Manager with the kernel's
+ * WebAuthn JSON. Requests and responses stay JSON — the kernel builds the
+ * options (PRF eval included) and parses the response itself, so this object
+ * only runs the system ceremony. The C++ host calls [create] and [get] with a
+ * completion token and receives the outcome through [nativeComplete].
+ */
+@DoNotStrip
+@Keep
+object Passkey {
+  // Status codes shared with PasskeyAndroid.cpp.
+  private const val OK = 0
+  private const val CANCELLED = 1
+  private const val UNAVAILABLE = 3
+  private const val FAILED = 4
+  // The exception type only — never the message, which can name the account.
+  private const val TAG = "QntxPasskey"
+
+  @Volatile private var signal: CancellationSignal? = null
+
+  @JvmStatic
+  fun create(token: Long, requestJson: String) {
+    val activity = foregroundActivity() ?: return nativeComplete(token, UNAVAILABLE, null)
+    val cancel = CancellationSignal().also { signal = it }
+    CredentialManager.create(activity).createCredentialAsync(
+      activity,
+      CreatePublicKeyCredentialRequest(requestJson),
+      cancel,
+      ContextCompat.getMainExecutor(activity),
+      object : CredentialManagerCallback<CreateCredentialResponse, CreateCredentialException> {
+        override fun onResult(result: CreateCredentialResponse) {
+          signal = null
+          val response = result as? CreatePublicKeyCredentialResponse
+          nativeComplete(
+            token,
+            if (response == null) FAILED else OK,
+            response?.registrationResponseJson,
+          )
+        }
+
+        override fun onError(e: CreateCredentialException) {
+          signal = null
+          Log.w(TAG, "create failed: ${e.type}")
+          nativeComplete(token, statusOf(e), null)
+        }
+      },
+    )
+  }
+
+  @JvmStatic
+  fun get(token: Long, requestJson: String) {
+    val activity = foregroundActivity() ?: return nativeComplete(token, UNAVAILABLE, null)
+    val cancel = CancellationSignal().also { signal = it }
+    CredentialManager.create(activity).getCredentialAsync(
+      activity,
+      GetCredentialRequest(listOf(GetPublicKeyCredentialOption(requestJson))),
+      cancel,
+      ContextCompat.getMainExecutor(activity),
+      object : CredentialManagerCallback<GetCredentialResponse, GetCredentialException> {
+        override fun onResult(result: GetCredentialResponse) {
+          signal = null
+          val credential = result.credential as? PublicKeyCredential
+          nativeComplete(
+            token,
+            if (credential == null) FAILED else OK,
+            credential?.authenticationResponseJson,
+          )
+        }
+
+        override fun onError(e: GetCredentialException) {
+          signal = null
+          Log.w(TAG, "get failed: ${e.type}")
+          nativeComplete(token, statusOf(e), null)
+        }
+      },
+    )
+  }
+
+  @JvmStatic
+  fun cancel() {
+    signal?.cancel()
+  }
+
+  private fun foregroundActivity(): FragmentActivity? =
+    NitroModules.applicationContext?.currentActivity as? FragmentActivity
+
+  // NotAllowedError is what the platform reports when the user dismisses or
+  // times out the sheet; SecurityError means the RP id is not associated
+  // with this app (assetlinks), i.e. passkeys are unavailable here.
+  private fun statusOf(e: CreateCredentialException): Int = when (e) {
+    is CreateCredentialCancellationException -> CANCELLED
+    is CreateCredentialNoCreateOptionException,
+    is CreateCredentialProviderConfigurationException,
+    is CreateCredentialUnsupportedException -> UNAVAILABLE
+    is CreatePublicKeyCredentialDomException -> domStatus(e.type)
+    else -> FAILED
+  }
+
+  private fun statusOf(e: GetCredentialException): Int = when (e) {
+    is GetCredentialCancellationException -> CANCELLED
+    is NoCredentialException,
+    is GetCredentialProviderConfigurationException,
+    is GetCredentialUnsupportedException -> UNAVAILABLE
+    is GetPublicKeyCredentialDomException -> domStatus(e.type)
+    else -> FAILED
+  }
+
+  private fun domStatus(type: String): Int = when {
+    type.endsWith("NotAllowedError") -> CANCELLED
+    type.endsWith("SecurityError") || type.endsWith("NotSupportedError") -> UNAVAILABLE
+    else -> FAILED
+  }
+
+  @JvmStatic
+  private external fun nativeComplete(token: Long, status: Int, responseJson: String?)
+}

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

@@ -0,0 +1,28 @@
+package com.margelo.nitro.qntxwallet
+
+import androidx.annotation.Keep
+import com.facebook.proguard.annotations.DoNotStrip
+import com.margelo.nitro.NitroModules
+import java.io.File
+
+/**
+ * Vault directory hook: `<noBackupFilesDir>/qntx-wallet`, pulled from C++
+ * through fbjni — `noBackupFilesDir` needs a Context, which Nitro hands us once
+ * its TurboModule is constructed (before any `createHybridObject("KernelHost")`).
+ */
+object VaultDirectory {
+  @JvmStatic
+  @DoNotStrip
+  @Keep
+  fun resolve(): String {
+    val context = NitroModules.applicationContext
+        ?: throw IllegalStateException(
+            "vault directory: NitroModules.applicationContext is not set")
+    val dir = File(context.noBackupFilesDir, "qntx-wallet")
+    dir.mkdirs()
+    if (!dir.isDirectory) {
+      throw IllegalStateException("vault directory: mkdirs failed")
+    }
+    return dir.absolutePath
+  }
+}

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

@@ -0,0 +1,30 @@
+package com.margelo.nitro.qntxwallet;
+
+import androidx.annotation.Nullable;
+
+import com.facebook.react.bridge.NativeModule;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.module.model.ReactModuleInfoProvider;
+import com.facebook.react.BaseReactPackage;
+
+import java.util.HashMap;
+
+public class WalletNativePackage extends BaseReactPackage {
+  @Nullable
+  @Override
+  public NativeModule getModule(String name, ReactApplicationContext reactContext) {
+    return null;
+  }
+
+  @Override
+  public ReactModuleInfoProvider getReactModuleInfoProvider() {
+    return () -> {
+        return new HashMap<>();
+    };
+  }
+
+  static {
+    WalletNativeOnLoad.initializeNative();
+  }
+
+}

package/cpp/host/HybridKernelHost.cpp

@@ -0,0 +1,162 @@
+#include "HybridKernelHost.hpp"
+
+#include "kernel.hpp"
+#include "VaultDirectory.hpp"
+
+#if defined(__ANDROID__)
+#include <android/log.h>
+#elif defined(__APPLE__)
+#include <os/log.h>
+#endif
+
+namespace margelo::nitro::qntxwallet {
+
+namespace {
+
+// A kernel crash reaches JS only as "crashed"; the reason goes to the system
+// log so field reports and device runs can tell causes apart. Kernel error
+// messages are static strings that never echo input or secrets.
+void logKernelCrash(const std::string& reason) {
+#if defined(__ANDROID__)
+  __android_log_print(ANDROID_LOG_ERROR, "QntxKernel", "kernel runtime crashed: %s", reason.c_str());
+#elif defined(__APPLE__)
+  os_log_error(OS_LOG_DEFAULT, "qntx kernel runtime crashed: %{public}s", reason.c_str());
+#else
+  (void)reason;
+#endif
+}
+
+} // namespace
+
+HybridKernelHost::~HybridKernelHost() {
+  std::shared_ptr<qntx::KernelRuntime> runtime;
+  {
+    std::lock_guard<std::mutex> lock(mutex_);
+    runtime = std::move(runtime_);
+  }
+  if (runtime) {
+    runtime->destroy();
+  }
+}
+
+void HybridKernelHost::start(double backgroundLockSeconds) {
+  // Compare as doubles before converting: casting NaN or an out-of-range value
+  // to int is undefined behaviour.
+  if (backgroundLockSeconds != 0 && backgroundLockSeconds != 60 &&
+      backgroundLockSeconds != 300 && backgroundLockSeconds != 900) {
+    throw std::runtime_error("backgroundLockSeconds must be one of 0, 60, 300, 900");
+  }
+  const int seconds = static_cast<int>(backgroundLockSeconds);
+  {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (runtime_ || exited_) {
+      return;
+    }
+  }
+  // The platform observer installs once; this host registers its deadline so
+  // the dispatcher can stamp or lock it on background/foreground transitions.
+  qntx::installLifecycleObserver();
+  qntx::KernelLifecycleDispatcher::shared().registerHost(
+      std::dynamic_pointer_cast<HybridKernelHost>(shared_from_this()), seconds);
+  // Resolved once here: a platform failure rejects start() for the JS caller
+  // instead of surfacing later as a store error inside the kernel.
+  const std::string vaultDirectory = qntx::platformVaultDirectory();
+
+  std::weak_ptr<HybridKernelHost> weak =
+      std::dynamic_pointer_cast<HybridKernelHost>(shared_from_this());
+  qntx::KernelRuntime::Hooks hooks;
+  hooks.onPost = [weak](std::vector<uint8_t> bytes) {
+    if (const auto self = weak.lock()) {
+      std::function<void(const std::shared_ptr<ArrayBuffer>&)> listener;
+      {
+        std::lock_guard<std::mutex> lock(self->mutex_);
+        listener = self->messageListener_;
+      }
+      if (listener) {
+        listener(ArrayBuffer::copy(bytes.data(), bytes.size()));
+      }
+    }
+  };
+  hooks.onError = [weak](std::string reason) {
+    logKernelCrash(reason);
+    if (const auto self = weak.lock()) {
+      self->exit(KernelExitReason::CRASHED);
+    }
+  };
+  hooks.onIntegrity = [weak] {
+    if (const auto self = weak.lock()) {
+      self->exit(KernelExitReason::INTEGRITY);
+    }
+  };
+
+  const auto script = qntx::KernelScript{
+      qntx::KernelScript::Kind::bytecode,
+      std::make_shared<const std::vector<uint8_t>>(
+          qntx::KERNEL_BYTECODE, qntx::KERNEL_BYTECODE + qntx::KERNEL_BYTECODE_SIZE)};
+  const auto runtime =
+      qntx::KernelRuntime::start(script, std::move(hooks), vaultDirectory);
+  {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (exited_) {
+      // An exit (integrity hash check raced a lock) already fired — drop the
+      // fresh runtime instead of resurrecting a dead host.
+      runtime->destroy();
+      return;
+    }
+    runtime_ = runtime;
+  }
+}
+
+void HybridKernelHost::post(const std::shared_ptr<ArrayBuffer>& frame) {
+  if (frame->size() > kMaxFrameBytes) {
+    exit(KernelExitReason::INTEGRITY);
+    return;
+  }
+  std::shared_ptr<qntx::KernelRuntime> runtime;
+  {
+    std::lock_guard<std::mutex> lock(mutex_);
+    runtime = runtime_;
+  }
+  if (runtime) {
+    const auto* data = static_cast<const uint8_t*>(frame->data());
+    runtime->post(std::vector<uint8_t>(data, data + frame->size()));
+  }
+}
+
+void HybridKernelHost::onMessage(
+    const std::function<void(const std::shared_ptr<ArrayBuffer>&)>& listener) {
+  std::lock_guard<std::mutex> lock(mutex_);
+  messageListener_ = listener;
+}
+
+void HybridKernelHost::onExit(const std::function<void(KernelExitReason)>& listener) {
+  std::lock_guard<std::mutex> lock(mutex_);
+  exitListener_ = listener;
+}
+
+void HybridKernelHost::lock() {
+  exit(KernelExitReason::LOCKED);
+}
+
+void HybridKernelHost::exit(KernelExitReason reason) {
+  std::shared_ptr<qntx::KernelRuntime> runtime;
+  std::function<void(KernelExitReason)> listener;
+  {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (exited_) {
+      return;
+    }
+    exited_ = true;
+    runtime = std::move(runtime_);
+    listener = exitListener_;
+  }
+  if (runtime) {
+    runtime->destroy();
+  }
+  qntx::KernelLifecycleDispatcher::shared().unregister(this);
+  if (listener) {
+    listener(reason);
+  }
+}
+
+} // namespace margelo::nitro::qntxwallet

package/cpp/host/HybridKernelHost.hpp

@@ -0,0 +1,49 @@
+#pragma once
+
+#include "HybridKernelHostSpec.hpp"
+
+#include <functional>
+#include <memory>
+#include <mutex>
+
+#include "host/Lifecycle.hpp"
+
+#include "../runtime/KernelRuntime.hpp"
+
+namespace margelo::nitro::qntxwallet {
+
+// The only Nitro-registered object: drives one kernel runtime. `start`
+// verifies the embedded bytecode's SHA-256 before loading; `post` enforces the
+// 1 MiB frame cap (the inbound queue cap lives inside KernelRuntime::post and
+// reports through the same integrity exit); `lock` destroys the runtime. Exit
+// reasons reach JS through the `onExit` listener, at most once.
+class HybridKernelHost final : public HybridKernelHostSpec,
+                               public qntx::LifecycleLockTarget {
+ public:
+  HybridKernelHost() : HybridObject(TAG) {}
+  ~HybridKernelHost() override;
+
+  void start(double backgroundLockSeconds) override;
+  // The platform's lifecycle dispatcher locks through here (main thread).
+  void lockForBackground() override { exit(KernelExitReason::BACKGROUND); }
+  void post(const std::shared_ptr<ArrayBuffer>& frame) override;
+  void onMessage(const std::function<void(const std::shared_ptr<ArrayBuffer>&)>& listener)
+      override;
+  void onExit(const std::function<void(KernelExitReason)>& listener) override;
+  void lock() override;
+
+ private:
+  static constexpr size_t kMaxFrameBytes = 1024 * 1024;
+
+  // Reports `reason` through onExit once, then tears the runtime down unless
+  // the exit was itself the lock report (the runtime is already gone).
+  void exit(KernelExitReason reason);
+
+  std::mutex mutex_;
+  std::shared_ptr<qntx::KernelRuntime> runtime_;
+  std::function<void(const std::shared_ptr<ArrayBuffer>&)> messageListener_;
+  std::function<void(KernelExitReason)> exitListener_;
+  bool exited_ = false;
+};
+
+} // namespace margelo::nitro::qntxwallet