@qntx/wallet-native 0.0.0-stage → 0.4.0

package/cpp/runtime/KernelGlobals.cpp

@@ -0,0 +1,535 @@
+#include "KernelGlobals.hpp"
+
+#include "../host/KernelFile.hpp"
+
+#include "KernelBackends.hpp"
+#include "KernelKeystore.hpp"
+#include "KernelPasskey.hpp"
+#include "KernelBuffer.hpp"
+#include "KernelJs.hpp"
+#include "platform/KernelPbkdf2.hpp"
+
+#include <atomic>
+#include <chrono>
+#include <cmath>
+#include <condition_variable>
+#include <cstdlib>
+#include <cstring>
+#include <deque>
+#include <mutex>
+#include <stdexcept>
+#include <string>
+#include <thread>
+
+#if defined(__APPLE__) || defined(__ANDROID__)
+#include <pthread.h>
+#include <unistd.h>
+#elif defined(__linux__)
+#include <cerrno>
+#include <sys/random.h>
+#include <unistd.h>
+#endif
+
+#if defined(__ANDROID__)
+#include <fbjni/fbjni.h>
+#endif
+
+namespace qntx {
+
+namespace {
+
+constexpr size_t kRandomLimit = 65536;
+constexpr double kTimerDelayMax = 2147483647.0;
+constexpr double kPbkdf2IterationsMax = 10000000.0;
+constexpr size_t kPbkdf2LengthMax = 1024;
+constexpr size_t kKdfQueueLimit = 8;
+
+void fillRandom(uint8_t* out, size_t size) {
+#if defined(__APPLE__) || defined(__ANDROID__)
+  arc4random_buf(out, size);
+#elif defined(__linux__)
+  size_t filled = 0;
+  while (filled < size) {
+    const ssize_t got = getrandom(out + filled, size - filled, 0);
+    if (got < 0) {
+      if (errno == EINTR) {
+        continue;
+      }
+      std::abort();
+    }
+    filled += static_cast<size_t>(got);
+  }
+#else
+#error "kernel runtime: no platform random source"
+#endif
+}
+
+// One process-wide worker runs every PBKDF2 job, so concurrent kernels cannot
+// spawn unbounded derivation threads. The queue is bounded; the worker thread
+// is intentionally leaked rather than joined (it parks on the condition
+// variable and holds no runtime state).
+struct KdfJob {
+  KernelPbkdf2Hash hash;
+  SecretBytes password;
+  SecretBytes salt;
+  uint32_t iterations;
+  size_t length;
+  std::shared_ptr<KernelPendingCall> call;
+  std::shared_ptr<KernelGlobalsState> state;
+};
+
+struct KdfQueue {
+  std::mutex mutex;
+  std::condition_variable cv;
+  std::deque<KdfJob> jobs;
+  bool workerStarted = false;
+};
+
+KdfQueue& kdfQueue() {
+  static auto* queue = new KdfQueue();
+  return *queue;
+}
+
+void kdfWorkerRun() {
+  auto& queue = kdfQueue();
+  for (;;) {
+    KdfJob job;
+    {
+      std::unique_lock<std::mutex> lock(queue.mutex);
+      queue.cv.wait(lock, [&] { return !queue.jobs.empty(); });
+      job = std::move(queue.jobs.front());
+      queue.jobs.pop_front();
+    }
+    if (!job.state->active->load(std::memory_order_acquire)) {
+      continue;
+    }
+    SecretBytes derived;
+    std::string error;
+    try {
+      derived = kernelPbkdf2(
+          job.hash, job.password, job.salt, job.iterations, job.length);
+    } catch (const std::exception& e) {
+      error = e.what();
+    } catch (...) {
+      error = "unknown pbkdf2 error";
+    }
+    if (!job.state->active->load(std::memory_order_acquire)) {
+      // Runtime torn down mid-derivation: drop the job; the parked call's
+      // `done` was already cleared by teardown, and SecretBytes wipe here.
+      continue;
+    }
+    auto state = job.state;
+    auto call = job.call;
+    // std::function needs a copyable closure: share the result; whichever
+    // side drops it last wipes it.
+    auto result = std::make_shared<SecretBytes>(std::move(derived));
+    state->enqueueTask(
+        [state, call, result, error = std::move(error)](
+            jsi::Runtime& rt) mutable {
+          auto done = std::move(call->done);
+          state->pending.erase(call);
+          if (!done.has_value()) {
+            return;
+          }
+          if (!error.empty()) {
+            done->call(
+                rt,
+                jsi::Value::undefined(),
+                jsi::Value(rt, jsi::String::createFromUtf8(rt, error)));
+            return;
+          }
+          auto buffer =
+              arrayBufferFromBytes(rt, result->data(), result->size());
+          auto array = makeUint8Array(rt, *state->intrinsics, std::move(buffer));
+          done->call(rt, jsi::Value(std::move(array)), jsi::Value::undefined());
+        });
+  }
+}
+
+void kdfWorkerMain() {
+#if defined(__APPLE__)
+  pthread_setname_np("qntx-kdf");
+#elif defined(__ANDROID__)
+  pthread_setname_np(pthread_self(), "qntx-kdf");
+#endif
+  auto body = [] { kdfWorkerRun(); };
+#if defined(__ANDROID__)
+  // The worker calls into javax.crypto over JNI; attach it to the JVM once for
+  // its lifetime (and let the app class loader resolve KernelPbkdf2).
+  facebook::jni::ThreadScope::WithClassLoader(std::move(body));
+#else
+  body();
+#endif
+}
+
+bool kdfSubmit(KdfJob job) {
+  auto& queue = kdfQueue();
+  std::lock_guard<std::mutex> lock(queue.mutex);
+  if (queue.jobs.size() >= kKdfQueueLimit) {
+    return false;
+  }
+  queue.jobs.push_back(std::move(job));
+  if (!queue.workerStarted) {
+    queue.workerStarted = true;
+    std::thread(kdfWorkerMain).detach();
+  }
+  queue.cv.notify_one();
+  return true;
+}
+
+void installPbkdf2(
+    jsi::Runtime& rt,
+    jsi::Object& qntx,
+    const std::shared_ptr<KernelGlobalsState>& state) {
+  qntx.setProperty(
+      rt,
+      "pbkdf2",
+      hostFn(rt, "pbkdf2", 6, [state](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 6) {
+          throw jsi::JSError(
+              rt, "__qntx.pbkdf2 expects (hash, password, salt, iterations, length, done)");
+        }
+        const auto& intrinsics = *state->intrinsics;
+        if (!args[0].isString()) {
+          throw jsi::JSError(
+              rt, "__qntx.pbkdf2 expects (hash, password, salt, iterations, length, done)");
+        }
+        const auto hashName = args[0].asString(rt).utf8(rt);
+        KernelPbkdf2Hash hash;
+        if (hashName == "sha256") {
+          hash = KernelPbkdf2Hash::sha256;
+        } else if (hashName == "sha512") {
+          hash = KernelPbkdf2Hash::sha512;
+        } else {
+          throw jsi::JSError(rt, "__qntx.pbkdf2 hash must be sha256 or sha512");
+        }
+        auto passwordView =
+            byteViewFromValue(rt, args[1], "__qntx.pbkdf2 password", intrinsics);
+        SecretBytes password(passwordView.data, passwordView.size);
+        auto saltView =
+            byteViewFromValue(rt, args[2], "__qntx.pbkdf2 salt", intrinsics);
+        SecretBytes salt(saltView.data, saltView.size);
+        if (!args[5].isObject() || !args[5].asObject(rt).isFunction(rt)) {
+          throw jsi::JSError(
+              rt, "__qntx.pbkdf2 expects (hash, password, salt, iterations, length, done)");
+        }
+        const auto iterations = static_cast<uint32_t>(
+            integerInRange(rt, args[3], "__qntx.pbkdf2 iterations", 1, kPbkdf2IterationsMax));
+        const auto length = static_cast<size_t>(
+            integerInRange(rt, args[4], "__qntx.pbkdf2 length", 1, kPbkdf2LengthMax));
+        auto call = std::make_shared<KernelPendingCall>();
+        call->done = args[5].asObject(rt).asFunction(rt);
+        state->pending.insert(call);
+
+        KdfJob job{
+            hash,
+            std::move(password),
+            std::move(salt),
+            iterations,
+            length,
+            call,
+            state};
+        if (!kdfSubmit(std::move(job))) {
+          state->enqueueTask([state, call](jsi::Runtime& rt) mutable {
+            auto done = std::move(call->done);
+            state->pending.erase(call);
+            if (done.has_value()) {
+              done->call(
+                  rt,
+                  jsi::Value::undefined(),
+                  jsi::Value(rt, jsi::String::createFromAscii(rt, "kdf queue full")));
+            }
+          });
+        }
+        return jsi::Value::undefined();
+      }));
+}
+
+// Runs once before the kernel script: locks down the native TextDecoder,
+// installs the setTimeout/clearTimeout globals Hermes' bundled rejection
+// tracker defers through, and wires that tracker to the private reportUnhandled
+// native. The expression evaluates to the function object; C++ invokes it with
+// `natives`.
+const char kKernelPrelude[] = R"JS((function (natives) {
+  var defineHidden = function (name, value) {
+    Object.defineProperty(globalThis, name, {
+      value: value,
+      writable: false,
+      configurable: false,
+      enumerable: false,
+    });
+  };
+
+  // Hermes 260318099+ (RN 0.88) ships a native TextDecoder — verified against
+  // the host vectors: WHATWG fatal/replacement semantics, BOM strip/ignoreBOM,
+  // streaming, RangeError on unknown labels. Adopt it instead of a shell:
+  // freeze and rebind it hidden so a script cannot swap or tamper with it. The
+  // prelude runs before any script, so Object.freeze is still pristine here.
+  if (typeof TextDecoder !== "function") {
+    throw new Error("kernel prelude: TextDecoder missing");
+  }
+  Object.freeze(TextDecoder.prototype);
+  Object.freeze(TextDecoder);
+  defineHidden("TextDecoder", TextDecoder);
+
+  // Hermes' bundled rejection tracker defers onUnhandled through the literal
+  // globals setTimeout/clearTimeout resolved at call time — Promise.then and
+  // async/await use the engine queue instead and need nothing. These are the
+  // only two timer globals the runtime installs (measured: without them
+  // onUnhandled never fires).
+  var timerSeq = 0;
+  var timerCancels = {};
+  defineHidden("setTimeout", function (fn, ms) {
+    var id = ++timerSeq;
+    var cancel = natives.setTimer(ms === undefined ? 0 : ms, function () {
+      delete timerCancels[id];
+      fn();
+    });
+    timerCancels[id] = cancel;
+    return id;
+  });
+  defineHidden("clearTimeout", function (id) {
+    var cancel = timerCancels[id];
+    if (cancel !== undefined) {
+      delete timerCancels[id];
+      cancel();
+    }
+  });
+
+  if (
+    typeof HermesInternal === "object" &&
+    HermesInternal !== null &&
+    typeof HermesInternal.enablePromiseRejectionTracker === "function"
+  ) {
+    HermesInternal.enablePromiseRejectionTracker({
+      allRejections: true,
+      onHandled: function () {},
+      onUnhandled: function (id, reason) {
+        natives.reportUnhandled(
+          id,
+          reason == null
+            ? "unknown"
+            : String(reason && reason.stack ? reason.stack : reason));
+      },
+    });
+  }
+}))JS";
+
+} // namespace
+
+void installKernelGlobals(
+    jsi::Runtime& rt,
+    const std::shared_ptr<KernelGlobalsState>& state) {
+  auto intrinsics = captureIntrinsics(rt);
+  state->intrinsics = intrinsics;
+
+  auto global = rt.global();
+  auto qntx = jsi::Object(rt);
+
+  qntx.setProperty(
+      rt,
+      "random",
+      hostFn(rt, "random", 1, [state](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 1) {
+          throw jsi::JSError(rt, "__qntx.random expects a byte length");
+        }
+        const auto n = static_cast<size_t>(
+            integerInRange(rt, args[0], "__qntx.random length", 0, kRandomLimit));
+        auto buffer = arrayBufferFromBytes(rt, nullptr, n);
+        fillRandom(buffer.data(rt), buffer.size(rt));
+        return jsi::Value(rt, makeUint8Array(rt, *state->intrinsics, std::move(buffer)));
+      }));
+
+  qntx.setProperty(
+      rt,
+      "now",
+      hostFn(rt, "now", 0, [](jsi::Runtime&, const jsi::Value&, const jsi::Value*, size_t) -> jsi::Value {
+        // Whole milliseconds like Date.now(): vault headers require integer
+        // createdAt timestamps.
+        return jsi::Value(static_cast<double>(
+            std::chrono::duration_cast<std::chrono::milliseconds>(
+                std::chrono::system_clock::now().time_since_epoch())
+                .count()));
+      }));
+
+  qntx.setProperty(
+      rt,
+      "elapsed",
+      hostFn(rt, "elapsed", 0, [](jsi::Runtime&, const jsi::Value&, const jsi::Value*, size_t) -> jsi::Value {
+        return jsi::Value(std::chrono::duration<double, std::milli>(
+            std::chrono::steady_clock::now().time_since_epoch())
+            .count());
+      }));
+
+  const auto makeSetTimer = [&state](jsi::Runtime& rt) -> jsi::Function {
+    return hostFn(rt, "setTimer", 2, [state](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+      if (count < 2 || !args[1].isObject() || !args[1].asObject(rt).isFunction(rt)) {
+        throw jsi::JSError(rt, "__qntx.setTimer expects (delayMs, fn)");
+      }
+      const double delayMs = finiteNumber(rt, args[0], "__qntx.setTimer delay");
+      if (delayMs < 0 || delayMs > kTimerDelayMax) {
+        throw jsi::JSError(rt, "__qntx.setTimer delay out of range");
+      }
+      const auto deadline = std::chrono::steady_clock::now() +
+          std::chrono::milliseconds(static_cast<int64_t>(std::ceil(delayMs)));
+      auto cancel = state->scheduleTimer(deadline, args[1].asObject(rt).asFunction(rt));
+      return jsi::Value(rt, hostFn(rt, "cancel", 0, [cancel = std::move(cancel)](jsi::Runtime&, const jsi::Value&, const jsi::Value*, size_t) mutable -> jsi::Value {
+        cancel();
+        return jsi::Value::undefined();
+      }));
+    });
+  };
+  qntx.setProperty(rt, "setTimer", makeSetTimer(rt));
+
+  installPbkdf2(rt, qntx, state);
+
+  // __qntx.frames — the W2b injection-table shape over the same plumbing:
+  // post, onMessage, and onIntegrityViolation (the host fires that handler
+  // when it refuses a frame on integrity grounds).
+  auto frames = jsi::Object(rt);
+  frames.setProperty(
+      rt,
+      "post",
+      hostFn(rt, "frames.post", 1, [state](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 1 || !args[0].isObject() || !args[0].asObject(rt).isArrayBuffer(rt)) {
+          throw jsi::JSError(rt, "__qntx.frames.post expects an ArrayBuffer");
+        }
+        auto buffer = args[0].asObject(rt).getArrayBuffer(rt);
+        const auto* data = buffer.data(rt);
+        state->postToHost(std::vector<uint8_t>(data, data + buffer.size(rt)));
+        return jsi::Value::undefined();
+      }));
+  frames.setProperty(
+      rt,
+      "onMessage",
+      hostFn(rt, "frames.onMessage", 1, [state](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 1 || !args[0].isObject() || !args[0].asObject(rt).isFunction(rt)) {
+          throw jsi::JSError(rt, "__qntx.frames.onMessage expects a function");
+        }
+        state->messageHandler = args[0].asObject(rt).asFunction(rt);
+        return jsi::Value::undefined();
+      }));
+  frames.setProperty(
+      rt,
+      "onIntegrityViolation",
+      hostFn(rt, "frames.onIntegrityViolation", 1, [state](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 1 || !args[0].isObject() || !args[0].asObject(rt).isFunction(rt)) {
+          throw jsi::JSError(rt, "__qntx.frames.onIntegrityViolation expects a function");
+        }
+        state->integrityHandler = args[0].asObject(rt).asFunction(rt);
+        return jsi::Value::undefined();
+      }));
+  intrinsics->freeze.call(rt, jsi::Value(rt, frames));
+  qntx.setProperty(rt, "frames", jsi::Value(std::move(frames)));
+
+  // __qntx.file — one opaque file image: read() -> Uint8Array | undefined,
+  // write(bytes) atomically replaces. The C++ primitive owns durability
+  // (temp + fsync + rename + dir fsync); failures throw so the file store
+  // rejects instead of silently degrading.
+  auto file = jsi::Object(rt);
+  file.setProperty(
+      rt,
+      "read",
+      hostFn(rt, "file.read", 0, [state](jsi::Runtime& rt, const jsi::Value&, const jsi::Value*, size_t) -> jsi::Value {
+        const auto bytes = kernelFileRead(state->vaultDirectory);
+        if (!bytes.has_value()) {
+          return jsi::Value::undefined();
+        }
+        auto buffer = arrayBufferFromBytes(rt, bytes->data(), bytes->size());
+        return jsi::Value(rt, makeUint8Array(rt, *state->intrinsics, std::move(buffer)));
+      }));
+  file.setProperty(
+      rt,
+      "write",
+      hostFn(rt, "file.write", 1, [state](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 1) {
+          throw jsi::JSError(rt, "__qntx.file.write expects an ArrayBuffer or TypedArray");
+        }
+        const auto view =
+            byteViewFromValue(rt, args[0], "__qntx.file.write", *state->intrinsics);
+        kernelFileWrite(
+            state->vaultDirectory, std::vector<uint8_t>(view.data, view.data + view.size));
+        return jsi::Value::undefined();
+      }));
+  intrinsics->freeze.call(rt, jsi::Value(rt, file));
+  qntx.setProperty(rt, "file", jsi::Value(std::move(file)));
+
+  installKernelBackends(rt, qntx, *intrinsics);
+  installKernelKeystore(rt, qntx, state);
+  installKernelPasskey(rt, qntx, state);
+
+  intrinsics->freeze.call(rt, jsi::Value(rt, qntx));
+  defineHiddenGlobal(rt, *intrinsics, "__qntx", jsi::Value(std::move(qntx)));
+
+  auto cryptoObject = jsi::Object(rt);
+  cryptoObject.setProperty(
+      rt,
+      "getRandomValues",
+      hostFn(rt, "getRandomValues", 1, [state](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 1 || !args[0].isObject()) {
+          throw jsi::JSError(rt, "crypto.getRandomValues expects a TypedArray");
+        }
+        const auto& intrinsics = *state->intrinsics;
+        auto view = args[0].asObject(rt);
+        const jsi::Value tag = intrinsics.taTagGet.callWithThis(rt, view);
+        static const char* const kIntegerArrays[] = {
+            "Int8Array",
+            "Uint8Array",
+            "Uint8ClampedArray",
+            "Int16Array",
+            "Uint16Array",
+            "Int32Array",
+            "Uint32Array",
+            "BigInt64Array",
+            "BigUint64Array",
+        };
+        const std::string tagName =
+            tag.isString() ? tag.asString(rt).utf8(rt) : std::string();
+        bool integerTyped = false;
+        for (const char* allowed : kIntegerArrays) {
+          if (tagName == allowed) {
+            integerTyped = true;
+            break;
+          }
+        }
+        if (!integerTyped) {
+          throw jsi::JSError(
+              rt, "crypto.getRandomValues accepts only integer TypedArrays");
+        }
+        auto bytes =
+            byteViewFromValue(rt, args[0], "crypto.getRandomValues", intrinsics);
+        if (bytes.size > kRandomLimit) {
+          throw jsi::JSError(
+              rt, "QuotaExceededError: crypto.getRandomValues view exceeds 65536 bytes");
+        }
+        fillRandom(bytes.data, bytes.size);
+        return jsi::Value(rt, args[0]);
+      }));
+  intrinsics->freeze.call(rt, jsi::Value(rt, cryptoObject));
+  defineHiddenGlobal(
+      rt, *intrinsics, "crypto", jsi::Value(std::move(cryptoObject)));
+
+  auto natives = jsi::Object(rt);
+  natives.setProperty(rt, "setTimer", makeSetTimer(rt));
+  natives.setProperty(
+      rt,
+      "reportUnhandled",
+      hostFn(rt, "reportUnhandled", 2, [state](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        std::string reason = "unhandled promise rejection";
+        if (count > 0 && args[0].isNumber()) {
+          reason += " id=" +
+              std::to_string(static_cast<long long>(args[0].getNumber()));
+        }
+        if (count > 1 && args[1].isString()) {
+          reason += ": " + args[1].asString(rt).utf8(rt);
+        }
+        state->reportFatal(std::move(reason));
+        return jsi::Value::undefined();
+      }));
+
+  auto prelude = rt.evaluateJavaScript(
+      std::make_shared<jsi::StringBuffer>(kKernelPrelude), "<kernel-prelude>");
+  prelude.asObject(rt).asFunction(rt).call(rt, jsi::Value(std::move(natives)));
+}
+
+} // namespace qntx

package/cpp/runtime/KernelGlobals.hpp

@@ -0,0 +1,107 @@
+#pragma once
+
+#include <jsi/jsi.h>
+
+#include <atomic>
+#include <chrono>
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <optional>
+#include <string>
+#include <unordered_set>
+#include <vector>
+
+namespace qntx {
+
+// A JSI callback parked while an async platform call (e.g. pbkdf2) runs on a
+// background thread. `done` is only read, moved or cleared on the kernel
+// thread — background threads never touch it.
+struct KernelPendingCall {
+  std::optional<facebook::jsi::Function> done;
+};
+
+// Defined in KernelJs.hpp: captured JS intrinsics (defineProperty,
+// freeze, %TypedArray%.prototype getters, the Uint8Array constructor, …) that
+// host functions call instead of looking properties up on possibly-tampered
+// objects.
+struct KernelIntrinsics;
+
+// Shared state between the host functions installed by installKernelGlobals
+// and the owning KernelRuntime. The jsi members must only be touched on the
+// kernel thread; KernelRuntime clears them before destroying the runtime.
+struct KernelGlobalsState {
+  // Directory the vault image file lives in — resolved by the host once per
+  // KernelRuntime::start (platformVaultDirectory on device builds) and passed
+  // to kernelFileRead/kernelFileWrite by the __qntx.file lambdas. Kernel
+  // thread only after start().
+  std::string vaultDirectory;
+
+  // Copies the posted bytes out of the runtime and reports them to the host.
+  std::function<void(std::vector<uint8_t>)> postToHost;
+
+  // Records a fatal kernel failure reported by JS (unhandled promise
+  // rejection). The runtime tears down after the current task drains.
+  std::function<void(std::string)> reportFatal;
+
+  // Schedules fn at deadline on the kernel task queue. Returns the
+  // cancellation closure: calling it on the kernel thread erases the entry
+  // immediately, releasing the stored jsi::Function. Both are kernel-thread
+  // only — timers never cross threads.
+  using TimerCancel = std::function<void()>;
+  std::function<TimerCancel(std::chrono::steady_clock::time_point, facebook::jsi::Function)>
+      scheduleTimer;
+
+  // Enqueues a task that runs fn(rt) on the kernel thread. Callable from any
+  // thread — background completions use it to return to the runtime.
+  std::function<void(std::function<void(facebook::jsi::Runtime&)>)> enqueueTask;
+
+  // True while the owning runtime is alive. Cleared in teardown AFTER pending
+  // callbacks are dropped, so a KDF worker that sees false may safely release
+  // its job (and the parked KernelPendingCall) off the kernel thread.
+  std::shared_ptr<std::atomic_bool> active;
+
+  // Callbacks parked for in-flight async platform calls. Kernel thread only;
+  // teardown clears every `done` before the runtime is destroyed.
+  std::unordered_set<std::shared_ptr<KernelPendingCall>> pending;
+
+  // Captured intrinsics for the host functions. Kernel thread only; teardown
+  // resets it while the runtime is still alive.
+  std::shared_ptr<KernelIntrinsics> intrinsics;
+
+  // Kernel-side handler for bytes delivered by KernelRuntime::post; installed
+  // by the script through __qntx.setMessageHandler or __qntx.frames.onMessage.
+  // Kernel thread only.
+  std::optional<facebook::jsi::Function> messageHandler;
+
+  // Kernel-side handler the host calls when it refuses an inbound frame on
+  // integrity grounds (oversize, queue full); installed through
+  // __qntx.frames.onIntegrityViolation. Kernel thread only.
+  std::optional<facebook::jsi::Function> integrityHandler;
+
+  // Dismiss in-flight system prompts (keystore, passkey); each installer adds
+  // one and teardown runs them all. Kernel thread only.
+  std::vector<std::function<void()>> cancelCeremonies;
+};
+
+// Installs the kernel's capabilities on a fresh runtime:
+//   globalThis.__qntx   frozen { random, now, elapsed, setTimer, pbkdf2, file,
+//                              frames, backends, keystore, passkey }
+//   globalThis.crypto   frozen { getRandomValues }
+//   globalThis.TextDecoder   the native Hermes decoder (260318099+), frozen
+//                            and rebound hidden
+//   globalThis.setTimeout / clearTimeout   id-based, kernel-thread timers —
+//     Hermes' bundled promise rejection tracker resolves these literals at
+//     call time to defer onUnhandled; Promise.then/async use the engine queue
+//     and need no globals (measured).
+// Each is installed via Object.defineProperty as non-writable,
+// non-configurable and non-enumerable.
+//
+// Also evaluates the kernel prelude — a function expression invoked once with
+// a private `natives` object { setTimer, reportUnhandled }. Private
+// natives are never reachable from globalThis.
+void installKernelGlobals(
+    facebook::jsi::Runtime& runtime,
+    const std::shared_ptr<KernelGlobalsState>& state);
+
+} // namespace qntx