@qntx/wallet-native 0.0.0-stage → 0.5.2

package/cpp/platform/LifecycleAndroid.cpp

@@ -0,0 +1,55 @@
+// Android background-lock lifecycle: the Kotlin AppLifecycle object registers
+// a ProcessLifecycleOwner observer on the main looper; its DefaultLifecycleObserver
+// callbacks reach the dispatcher through the JNI exports below.
+#include "../host/Lifecycle.hpp"
+
+#ifdef __ANDROID__
+
+#include <fbjni/fbjni.h>
+#include <jni.h>
+#include <stdexcept>
+
+namespace qntx {
+namespace {
+facebook::jni::global_ref<jclass> g_appLifecycleClass;
+} // namespace
+
+void kernelLifecycleInit(facebook::jni::alias_ref<jclass> clazz) {
+  g_appLifecycleClass = facebook::jni::make_global(clazz);
+}
+
+int64_t sleepInclusiveMonotonicMs() {
+  // CLOCK_BOOTTIME counts suspend; CLOCK_MONOTONIC does not.
+  struct timespec ts;
+  ::clock_gettime(CLOCK_BOOTTIME, &ts);
+  return static_cast<int64_t>(ts.tv_sec) * 1000 + ts.tv_nsec / 1000000;
+}
+
+void installLifecycleObserver() {
+  static std::once_flag once;
+  std::call_once(once, [] {
+    facebook::jni::ThreadScope threadScope;
+    if (!g_appLifecycleClass) {
+      throw std::runtime_error("lifecycle: JNI_OnLoad init did not run");
+    }
+    auto install = g_appLifecycleClass->getStaticMethod<void()>("install");
+    install(g_appLifecycleClass.get());
+  });
+}
+
+} // namespace qntx
+
+// The Kotlin object's DefaultLifecycleObserver dispatches here.
+extern "C" JNIEXPORT void JNICALL
+Java_com_margelo_nitro_qntxwallet_AppLifecycle_onAppBackground(
+    JNIEnv*, jclass) {
+  qntx::KernelLifecycleDispatcher::shared().onBackground();
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_margelo_nitro_qntxwallet_AppLifecycle_onAppForeground(
+    JNIEnv*, jclass) {
+  qntx::KernelLifecycleDispatcher::shared().onForeground();
+}
+
+#endif // __ANDROID__

package/cpp/platform/LifecycleIos.mm

@@ -0,0 +1,36 @@
+#import <Foundation/Foundation.h>
+#import <UIKit/UIKit.h>
+
+#include <mutex>
+#include <time.h>
+
+#include "../host/Lifecycle.hpp"
+
+namespace qntx {
+
+int64_t sleepInclusiveMonotonicMs() {
+  // CLOCK_MONOTONIC counts sleep (steady_clock/mach_absolute_time does not).
+  const uint64_t ns = clock_gettime_nsec_np(CLOCK_MONOTONIC);
+  return static_cast<int64_t>(ns / 1000000);
+}
+
+void installLifecycleObserver() {
+  static std::once_flag once;
+  std::call_once(once, [] {
+    auto* center = NSNotificationCenter.defaultCenter;
+    [center addObserverForName:UIApplicationDidEnterBackgroundNotification
+                        object:nil
+                         queue:nil
+                    usingBlock:^(NSNotification*) {
+                      KernelLifecycleDispatcher::shared().onBackground();
+                    }];
+    [center addObserverForName:UIApplicationWillEnterForegroundNotification
+                        object:nil
+                         queue:nil
+                    usingBlock:^(NSNotification*) {
+                      KernelLifecycleDispatcher::shared().onForeground();
+                    }];
+  });
+}
+
+} // namespace qntx

package/cpp/platform/PasskeyAndroid.cpp

@@ -0,0 +1,118 @@
+// Android passkey authenticator: the Kotlin Passkey object runs Credential
+// Manager; this file forwards each request JSON through fbjni with a
+// completion token and resolves the parked completion when Kotlin calls back
+// through nativeComplete (on the main thread).
+#include "../host/Passkey.hpp"
+
+#ifdef __ANDROID__
+
+#include <fbjni/fbjni.h>
+#include <jni.h>
+
+#include <cstdint>
+#include <mutex>
+#include <stdexcept>
+#include <unordered_map>
+#include <utility>
+
+namespace qntx {
+namespace {
+
+namespace jni = facebook::jni;
+
+jni::global_ref<jclass> g_passkeyClass;
+
+std::mutex g_mutex;
+int64_t g_nextToken = 1;
+std::unordered_map<int64_t, PasskeyDone> g_pending;
+
+int64_t park(PasskeyDone done) {
+  std::lock_guard<std::mutex> lock(g_mutex);
+  const int64_t token = g_nextToken++;
+  g_pending.emplace(token, std::move(done));
+  return token;
+}
+
+PasskeyDone take(int64_t token) {
+  std::lock_guard<std::mutex> lock(g_mutex);
+  auto found = g_pending.find(token);
+  if (found == g_pending.end()) {
+    return nullptr;
+  }
+  auto done = std::move(found->second);
+  g_pending.erase(found);
+  return done;
+}
+
+jni::alias_ref<jclass> passkeyClass() {
+  if (!g_passkeyClass) {
+    throw std::runtime_error("passkey: JNI_OnLoad init did not run");
+  }
+  return g_passkeyClass;
+}
+
+// Runs one Kotlin entry point; a JNI failure completes the call as `failed`
+// instead of leaving it parked forever.
+void dispatch(const char* method, const std::string& requestJson, PasskeyDone done) {
+  const int64_t token = park(std::move(done));
+  try {
+    jni::ThreadScope threadScope;
+    auto entry = passkeyClass()->getStaticMethod<void(jlong, jni::alias_ref<jstring>)>(method);
+    entry(passkeyClass(), static_cast<jlong>(token), jni::make_jstring(requestJson));
+  } catch (...) {
+    if (auto parked = take(token)) {
+      parked(PasskeyResult{PasskeyStatus::failed, {}});
+    }
+  }
+}
+
+} // namespace
+
+void kernelPasskeyInit(jni::alias_ref<jclass> clazz) {
+  g_passkeyClass = jni::make_global(clazz);
+}
+
+void passkeyCreate(std::string requestJson, PasskeyDone done) {
+  dispatch("create", requestJson, std::move(done));
+}
+
+void passkeyGet(std::string requestJson, PasskeyDone done) {
+  dispatch("get", requestJson, std::move(done));
+}
+
+void passkeyCancel() {
+  jni::ThreadScope threadScope;
+  auto method = passkeyClass()->getStaticMethod<void()>("cancel");
+  method(passkeyClass());
+}
+
+} // namespace qntx
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_margelo_nitro_qntxwallet_Passkey_nativeComplete(
+    JNIEnv* env, jclass, jlong token, jint status, jstring responseJson) {
+  auto done = qntx::take(static_cast<int64_t>(token));
+  if (!done) {
+    return;
+  }
+  qntx::PasskeyResult result;
+  switch (status) {
+    case static_cast<jint>(qntx::PasskeyStatus::ok):
+    case static_cast<jint>(qntx::PasskeyStatus::cancelled):
+    case static_cast<jint>(qntx::PasskeyStatus::unavailable):
+      result.status = static_cast<qntx::PasskeyStatus>(status);
+      break;
+    default:
+      result.status = qntx::PasskeyStatus::failed;
+  }
+  if (responseJson != nullptr && result.status == qntx::PasskeyStatus::ok) {
+    const char* utf = env->GetStringUTFChars(responseJson, nullptr);
+    if (utf != nullptr) {
+      result.responseJson = utf;
+      env->ReleaseStringUTFChars(responseJson, utf);
+    }
+  }
+  done(std::move(result));
+}
+
+#endif // __ANDROID__

package/cpp/platform/PasskeyIos.mm

@@ -0,0 +1,20 @@
+// iOS passkey authenticator: not available yet. Native passkeys need the
+// app's associated domain (webcredentials), which the current free signing
+// team cannot provision; W6c implements ASAuthorization with PRF once a paid
+// team exists. Until then every ceremony reports `unavailable`, which the
+// kernel surfaces as factor-unavailable (no passkey wallet on this platform).
+#include "../host/Passkey.hpp"
+
+namespace qntx {
+
+void passkeyCreate(std::string, PasskeyDone done) {
+  done(PasskeyResult{PasskeyStatus::unavailable, {}});
+}
+
+void passkeyGet(std::string, PasskeyDone done) {
+  done(PasskeyResult{PasskeyStatus::unavailable, {}});
+}
+
+void passkeyCancel() {}
+
+} // namespace qntx

package/cpp/platform/VaultDirectory.mm

@@ -0,0 +1,58 @@
+// iOS vault directory: Application Support/qntx-wallet/ created with
+// NSFileProtectionComplete and excluded from backup — the vault image must
+// never ride into iCloud or unencrypted backups.
+#include "../host/VaultDirectory.hpp"
+
+#import <Foundation/Foundation.h>
+
+#include <stdexcept>
+
+namespace qntx {
+namespace {
+
+// NSError detail is reduced to its numeric code: failure messages propagate
+// through the kernel's error path and must never carry user-data paths.
+[[noreturn]] void failStep(const char* step, NSError* error) {
+  if (error == nil) {
+    throw std::runtime_error(step);
+  }
+  throw std::runtime_error(
+      std::string(step) + " (Cocoa error " + std::to_string(error.code) + ")");
+}
+
+} // namespace
+
+std::string platformVaultDirectory() {
+  NSFileManager* fileManager = [NSFileManager defaultManager];
+  NSError* error = nil;
+  NSURL* appSupport = [fileManager URLForDirectory:NSApplicationSupportDirectory
+                                          inDomain:NSUserDomainMask
+                                 appropriateForURL:nil
+                                            create:YES
+                                             error:&error];
+  if (appSupport == nil) {
+    failStep("resolve Application Support directory", error);
+  }
+  NSURL* dir = [appSupport URLByAppendingPathComponent:@"qntx-wallet" isDirectory:YES];
+  if (dir == nil) {
+    throw std::runtime_error("resolve vault directory");
+  }
+  error = nil;
+  if (![fileManager createDirectoryAtURL:dir
+             withIntermediateDirectories:YES
+                              attributes:@{NSFileProtectionKey : NSFileProtectionComplete}
+                                   error:&error]) {
+    failStep("create vault directory", error);
+  }
+  error = nil;
+  if (![dir setResourceValue:@YES forKey:NSURLIsExcludedFromBackupKey error:&error]) {
+    failStep("exclude vault directory from backup", error);
+  }
+  const char* path = dir.fileSystemRepresentation;
+  if (path == nullptr) {
+    throw std::runtime_error("resolve vault directory path");
+  }
+  return path;
+}
+
+} // namespace qntx

package/cpp/platform/VaultDirectoryAndroid.cpp

@@ -0,0 +1,35 @@
+// Android vault directory: <noBackupFilesDir>/qntx-wallet, pulled from the
+// Kotlin VaultDirectory.resolve() through fbjni — one supported-API path, no
+// C++-side caching of the path.
+#include "../host/VaultDirectory.hpp"
+
+#ifdef __ANDROID__
+
+#include <fbjni/fbjni.h>
+#include <jni.h>
+#include <stdexcept>
+#include <string>
+
+namespace qntx {
+namespace {
+facebook::jni::global_ref<jclass> g_vaultDirectoryClass;
+} // namespace
+
+void kernelVaultDirectoryInit(facebook::jni::alias_ref<jclass> clazz) {
+  g_vaultDirectoryClass = facebook::jni::make_global(clazz);
+}
+
+std::string platformVaultDirectory() {
+  facebook::jni::ThreadScope threadScope;
+  if (!g_vaultDirectoryClass) {
+    throw std::runtime_error("vault directory: JNI_OnLoad init did not run");
+  }
+  auto method = g_vaultDirectoryClass->getStaticMethod<facebook::jni::JString::javaobject()>(
+      "resolve");
+  auto path = method(g_vaultDirectoryClass.get());
+  return path->toStdString();
+}
+
+} // namespace qntx
+
+#endif // __ANDROID__

package/cpp/runtime/KernelBackends.cpp

@@ -0,0 +1,297 @@
+#include "KernelBackends.hpp"
+
+#include "KernelJs.hpp"
+
+// qntx_spark.h carries its own extern "C" guard since 0.5.1. Every build
+// resolves the bare include through a search path: iOS via the SparkNative
+// pod's headers (added by the WalletNative podspec), Android and the host
+// test via the package's include/ directory.
+#include "qntx_spark.h"
+#include "nostr_native.h"
+
+#include <string>
+
+namespace qntx {
+
+namespace {
+
+constexpr double kUint32Max = 4294967295.0;
+
+// Every qs_* call shares this shape: byte inputs go in as borrowed (data,
+// size) views; the library-owned output is copied into a fresh Uint8Array
+// before qs_free wipes and releases it. A nonzero code throws
+// `qntx_spark:<code>` — the kernel-side wrapper maps it to SparkCryptoError.
+template <typename Invoke>
+jsi::Value callOut(
+    jsi::Runtime& rt,
+    const KernelIntrinsics& intrinsics,
+    Invoke&& invoke) {
+  uint8_t* out = nullptr;
+  size_t outLen = 0;
+  const int32_t code = invoke(&out, &outLen);
+  jsi::Value result;
+  if (code == 0) {
+    auto buffer = arrayBufferFromBytes(rt, out, outLen);
+    result = jsi::Value(
+        rt, makeUint8Array(rt, intrinsics, std::move(buffer)));
+  }
+  if (out != nullptr) {
+    qs_free(out, outLen);
+  }
+  if (code != 0) {
+    throw jsi::JSError(rt, "qntx_spark:" + std::to_string(code));
+  }
+  return result;
+}
+
+uint32_t uint32Arg(
+    jsi::Runtime& rt,
+    const jsi::Value& value,
+    const char* name) {
+  return static_cast<uint32_t>(integerInRange(rt, value, name, 0, kUint32Max));
+}
+
+} // namespace
+
+void installKernelBackends(
+    jsi::Runtime& rt,
+    jsi::Object& qntx,
+    const KernelIntrinsics& intrinsics) {
+  auto spark = jsi::Object(rt);
+
+  spark.setProperty(
+      rt, "abiVersion", jsi::Value(static_cast<double>(qs_abi_version())));
+
+  spark.setProperty(
+      rt,
+      "frostCommit",
+      hostFn(rt, "spark.frostCommit", 2, [&intrinsics](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 2) {
+          throw jsi::JSError(
+              rt, "__qntx.backends.spark.frostCommit expects (hedge, random)");
+        }
+        auto hedge = byteViewFromValue(rt, args[0], "__qntx.backends.spark.frostCommit hedge", intrinsics);
+        auto random = byteViewFromValue(rt, args[1], "__qntx.backends.spark.frostCommit random", intrinsics);
+        return callOut(rt, intrinsics, [&](uint8_t** out, size_t* outLen) {
+          return qs_frost_commit(
+              hedge.data, hedge.size, random.data, random.size, out, outLen);
+        });
+      }));
+
+  spark.setProperty(
+      rt,
+      "frostSign",
+      hostFn(rt, "spark.frostSign", 1, [&intrinsics](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 1) {
+          throw jsi::JSError(
+              rt, "__qntx.backends.spark.frostSign expects (request)");
+        }
+        auto request = byteViewFromValue(rt, args[0], "__qntx.backends.spark.frostSign request", intrinsics);
+        return callOut(rt, intrinsics, [&](uint8_t** out, size_t* outLen) {
+          return qs_frost_sign(request.data, request.size, out, outLen);
+        });
+      }));
+
+  spark.setProperty(
+      rt,
+      "frostAggregate",
+      hostFn(rt, "spark.frostAggregate", 1, [&intrinsics](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 1) {
+          throw jsi::JSError(
+              rt, "__qntx.backends.spark.frostAggregate expects (request)");
+        }
+        auto request = byteViewFromValue(rt, args[0], "__qntx.backends.spark.frostAggregate request", intrinsics);
+        return callOut(rt, intrinsics, [&](uint8_t** out, size_t* outLen) {
+          return qs_frost_aggregate(request.data, request.size, out, outLen);
+        });
+      }));
+
+  spark.setProperty(
+      rt,
+      "eciesEncrypt",
+      hostFn(rt, "spark.eciesEncrypt", 3, [&intrinsics](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 3) {
+          throw jsi::JSError(
+              rt, "__qntx.backends.spark.eciesEncrypt expects (publicKey, plaintext, random)");
+        }
+        auto publicKey = byteViewFromValue(rt, args[0], "__qntx.backends.spark.eciesEncrypt publicKey", intrinsics);
+        auto plaintext = byteViewFromValue(rt, args[1], "__qntx.backends.spark.eciesEncrypt plaintext", intrinsics);
+        auto random = byteViewFromValue(rt, args[2], "__qntx.backends.spark.eciesEncrypt random", intrinsics);
+        return callOut(rt, intrinsics, [&](uint8_t** out, size_t* outLen) {
+          return qs_ecies_encrypt(
+              publicKey.data,
+              publicKey.size,
+              plaintext.data,
+              plaintext.size,
+              random.data,
+              random.size,
+              out,
+              outLen);
+        });
+      }));
+
+  spark.setProperty(
+      rt,
+      "eciesDecrypt",
+      hostFn(rt, "spark.eciesDecrypt", 2, [&intrinsics](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 2) {
+          throw jsi::JSError(
+              rt, "__qntx.backends.spark.eciesDecrypt expects (privateKey, ciphertext)");
+        }
+        auto privateKey = byteViewFromValue(rt, args[0], "__qntx.backends.spark.eciesDecrypt privateKey", intrinsics);
+        auto ciphertext = byteViewFromValue(rt, args[1], "__qntx.backends.spark.eciesDecrypt ciphertext", intrinsics);
+        return callOut(rt, intrinsics, [&](uint8_t** out, size_t* outLen) {
+          return qs_ecies_decrypt(
+              privateKey.data, privateKey.size, ciphertext.data, ciphertext.size, out, outLen);
+        });
+      }));
+
+  spark.setProperty(
+      rt,
+      "splitSecretWithProofs",
+      hostFn(rt, "spark.splitSecretWithProofs", 4, [&intrinsics](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 4) {
+          throw jsi::JSError(
+              rt, "__qntx.backends.spark.splitSecretWithProofs expects (secret, threshold, shares, random)");
+        }
+        auto secret = byteViewFromValue(rt, args[0], "__qntx.backends.spark.splitSecretWithProofs secret", intrinsics);
+        const auto threshold =
+            uint32Arg(rt, args[1], "__qntx.backends.spark.splitSecretWithProofs threshold");
+        const auto shares =
+            uint32Arg(rt, args[2], "__qntx.backends.spark.splitSecretWithProofs shares");
+        auto random = byteViewFromValue(rt, args[3], "__qntx.backends.spark.splitSecretWithProofs random", intrinsics);
+        return callOut(rt, intrinsics, [&](uint8_t** out, size_t* outLen) {
+          return qs_split_secret_with_proofs(
+              secret.data,
+              secret.size,
+              threshold,
+              shares,
+              random.data,
+              random.size,
+              out,
+              outLen);
+        });
+      }));
+
+  intrinsics.freeze.call(rt, jsi::Value(rt, spark));
+
+  // The nostr_native_* calls write fixed-size outputs on the stack and return
+  // 0/1 rather than an allocator + error code, so they do not go through
+  // callOut. Exact-length inputs are checked before the call; verifySerialized
+  // answers with a boolean like nobleBackend instead of throwing.
+  auto nostr = jsi::Object(rt);
+  nostr.setProperty(
+      rt, "abiVersion", jsi::Value(static_cast<double>(nostr_native_abi_version())));
+
+  auto exact32 = [](jsi::Runtime& rt, const ByteView& view, const char* name) {
+    if (view.size != 32) {
+      throw jsi::JSError(rt, std::string(name) + " expects a 32-byte view");
+    }
+  };
+  auto wipe = [](uint8_t* data, size_t size) {
+    volatile uint8_t* p = data;
+    while (size--) {
+      *p++ = 0;
+    }
+  };
+
+  nostr.setProperty(
+      rt,
+      "publicKey",
+      hostFn(rt, "nostr.publicKey", 1, [&intrinsics, &exact32, &wipe](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 1) {
+          throw jsi::JSError(rt, "__qntx.backends.nostr.publicKey expects (secretKey)");
+        }
+        auto sk = byteViewFromValue(rt, args[0], "__qntx.backends.nostr.publicKey secretKey", intrinsics);
+        exact32(rt, sk, "__qntx.backends.nostr.publicKey secretKey");
+        uint8_t out[32];
+        const int ok = nostr_native_public_key(sk.data, out);
+        jsi::Value result;
+        if (ok == 1) {
+          result = jsi::Value(rt, makeUint8Array(rt, intrinsics, arrayBufferFromBytes(rt, out, sizeof out)));
+        }
+        wipe(out, sizeof out);
+        if (ok != 1) {
+          throw jsi::JSError(rt, "nostr_native: publicKey rejected the input");
+        }
+        return result;
+      }));
+
+  nostr.setProperty(
+      rt,
+      "sign",
+      hostFn(rt, "nostr.sign", 3, [&intrinsics, &exact32, &wipe](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 3) {
+          throw jsi::JSError(rt, "__qntx.backends.nostr.sign expects (id, secretKey, auxRand)");
+        }
+        auto id = byteViewFromValue(rt, args[0], "__qntx.backends.nostr.sign id", intrinsics);
+        auto sk = byteViewFromValue(rt, args[1], "__qntx.backends.nostr.sign secretKey", intrinsics);
+        auto aux = byteViewFromValue(rt, args[2], "__qntx.backends.nostr.sign auxRand", intrinsics);
+        exact32(rt, id, "__qntx.backends.nostr.sign id");
+        exact32(rt, sk, "__qntx.backends.nostr.sign secretKey");
+        exact32(rt, aux, "__qntx.backends.nostr.sign auxRand");
+        uint8_t out[64];
+        const int ok = nostr_native_sign(id.data, sk.data, aux.data, out);
+        jsi::Value result;
+        if (ok == 1) {
+          result = jsi::Value(rt, makeUint8Array(rt, intrinsics, arrayBufferFromBytes(rt, out, sizeof out)));
+        }
+        wipe(out, sizeof out);
+        if (ok != 1) {
+          throw jsi::JSError(rt, "nostr_native: sign rejected the input");
+        }
+        return result;
+      }));
+
+  nostr.setProperty(
+      rt,
+      "verifySerialized",
+      hostFn(rt, "nostr.verifySerialized", 4, [&intrinsics](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 4) {
+          throw jsi::JSError(rt, "__qntx.backends.nostr.verifySerialized expects (serialized, id, pubkey, sig)");
+        }
+        auto serialized = byteViewFromValue(rt, args[0], "__qntx.backends.nostr.verifySerialized serialized", intrinsics);
+        auto id = byteViewFromValue(rt, args[1], "__qntx.backends.nostr.verifySerialized id", intrinsics);
+        auto pubkey = byteViewFromValue(rt, args[2], "__qntx.backends.nostr.verifySerialized pubkey", intrinsics);
+        auto sig = byteViewFromValue(rt, args[3], "__qntx.backends.nostr.verifySerialized sig", intrinsics);
+        if (id.size != 32 || pubkey.size != 32 || sig.size != 64) {
+          return jsi::Value(false);
+        }
+        return jsi::Value(nostr_native_verify_serialized(
+            serialized.data, serialized.size, id.data, pubkey.data, sig.data) == 1);
+      }));
+
+  nostr.setProperty(
+      rt,
+      "ecdhX",
+      hostFn(rt, "nostr.ecdhX", 2, [&intrinsics, &exact32, &wipe](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 2) {
+          throw jsi::JSError(rt, "__qntx.backends.nostr.ecdhX expects (secretKey, publicKeyX)");
+        }
+        auto sk = byteViewFromValue(rt, args[0], "__qntx.backends.nostr.ecdhX secretKey", intrinsics);
+        auto pubX = byteViewFromValue(rt, args[1], "__qntx.backends.nostr.ecdhX publicKeyX", intrinsics);
+        exact32(rt, sk, "__qntx.backends.nostr.ecdhX secretKey");
+        exact32(rt, pubX, "__qntx.backends.nostr.ecdhX publicKeyX");
+        uint8_t out[32];
+        const int ok = nostr_native_ecdh_x(sk.data, pubX.data, out);
+        jsi::Value result;
+        if (ok == 1) {
+          result = jsi::Value(rt, makeUint8Array(rt, intrinsics, arrayBufferFromBytes(rt, out, sizeof out)));
+        }
+        wipe(out, sizeof out);
+        if (ok != 1) {
+          throw jsi::JSError(rt, "nostr_native: ecdhX rejected the input");
+        }
+        return result;
+      }));
+
+  intrinsics.freeze.call(rt, jsi::Value(rt, nostr));
+
+  auto backends = jsi::Object(rt);
+  backends.setProperty(rt, "spark", jsi::Value(std::move(spark)));
+  backends.setProperty(rt, "nostr", jsi::Value(std::move(nostr)));
+  intrinsics.freeze.call(rt, jsi::Value(rt, backends));
+  qntx.setProperty(rt, "backends", jsi::Value(std::move(backends)));
+}
+
+} // namespace qntx

package/cpp/runtime/KernelBackends.hpp

@@ -0,0 +1,20 @@
+#pragma once
+
+#include <jsi/jsi.h>
+
+namespace qntx {
+
+namespace jsi = facebook::jsi;
+
+struct KernelIntrinsics;
+
+// Installs `backends` on the `__qntx` object before the caller freezes it:
+// `backends.spark` is the qntx_spark C ABI bound as host functions. Byte
+// inputs are borrowed views (no copy); every qs_* output is copied into a
+// fresh Uint8Array and then freed with qs_free, which wipes the buffer first.
+void installKernelBackends(
+    jsi::Runtime& rt,
+    jsi::Object& qntx,
+    const KernelIntrinsics& intrinsics);
+
+} // namespace qntx

package/cpp/runtime/KernelBuffer.cpp

@@ -0,0 +1,12 @@
+#include "KernelBuffer.hpp"
+
+void qntx::kernelWipe(uint8_t* data, size_t size) {
+  volatile uint8_t* p = data;
+  for (size_t i = 0; i < size; i++) {
+    p[i] = 0;
+  }
+}
+
+void qntx::kernelWipe(std::vector<uint8_t>& bytes) {
+  kernelWipe(bytes.data(), bytes.size());
+}