@qntx/wallet-native 0.0.0-stage → 0.4.0

package/cpp/runtime/KernelJs.cpp

@@ -0,0 +1,155 @@
+#include "KernelJs.hpp"
+
+#include "KernelBuffer.hpp"
+
+#include <cmath>
+#include <stdexcept>
+
+namespace qntx {
+
+jsi::Function hostFn(
+    jsi::Runtime& rt,
+    const char* name,
+    unsigned int paramCount,
+    jsi::HostFunctionType fn) {
+  return jsi::Function::createFromHostFunction(
+      rt, jsi::PropNameID::forAscii(rt, name), paramCount, std::move(fn));
+}
+
+double finiteNumber(jsi::Runtime& rt, const jsi::Value& value, const char* name) {
+  if (!value.isNumber() || !std::isfinite(value.getNumber())) {
+    throw jsi::JSError(rt, std::string(name) + " expects a finite number");
+  }
+  return value.getNumber();
+}
+
+uint64_t integerInRange(
+    jsi::Runtime& rt,
+    const jsi::Value& value,
+    const char* name,
+    double min,
+    double max) {
+  const double n = finiteNumber(rt, value, name);
+  if (n < min || n > max || std::floor(n) != n) {
+    throw jsi::JSError(rt, std::string(name) + " is out of range");
+  }
+  return static_cast<uint64_t>(n);
+}
+
+ByteView byteViewFromValue(
+    jsi::Runtime& rt,
+    const jsi::Value& value,
+    const char* name,
+    const KernelIntrinsics& intrinsics) {
+  if (!value.isObject()) {
+    throw jsi::JSError(rt, std::string(name) + " expects an ArrayBuffer or TypedArray");
+  }
+  auto object = value.asObject(rt);
+  if (object.isArrayBuffer(rt)) {
+    auto buffer = object.getArrayBuffer(rt);
+    uint8_t* data = buffer.data(rt);
+    const size_t size = buffer.size(rt);
+    return {std::move(buffer), data, size};
+  }
+  const jsi::Value bufferValue =
+      intrinsics.taBufferGet.callWithThis(rt, object);
+  const jsi::Value offsetValue =
+      intrinsics.taByteOffsetGet.callWithThis(rt, object);
+  const jsi::Value lengthValue =
+      intrinsics.taByteLengthGet.callWithThis(rt, object);
+  if (!bufferValue.isObject() || !bufferValue.asObject(rt).isArrayBuffer(rt)) {
+    throw jsi::JSError(rt, std::string(name) + " view is not backed by an ArrayBuffer");
+  }
+  const double offset = finiteNumber(rt, offsetValue, "byteOffset");
+  const double length = finiteNumber(rt, lengthValue, "byteLength");
+  if (offset < 0 || std::floor(offset) != offset ||
+      length < 0 || std::floor(length) != length) {
+    throw jsi::JSError(rt, std::string(name) + " view bounds must be non-negative integers");
+  }
+  auto buffer = bufferValue.asObject(rt).getArrayBuffer(rt);
+  uint8_t* data = buffer.data(rt);
+  const size_t bufferSize = buffer.size(rt);
+  if (offset + length > static_cast<double>(bufferSize)) {
+    throw jsi::JSError(rt, std::string(name) + " view exceeds its ArrayBuffer");
+  }
+  return {std::move(buffer), data + static_cast<size_t>(offset), static_cast<size_t>(length)};
+}
+
+jsi::ArrayBuffer arrayBufferFromBytes(
+    jsi::Runtime& rt,
+    const uint8_t* bytes,
+    size_t size) {
+  auto buffer = std::make_shared<OwningBuffer>(size);
+  if (bytes != nullptr && size > 0) {
+    std::memcpy(buffer->data(), bytes, size);
+  }
+  return rt.createArrayBuffer(std::move(buffer));
+}
+
+jsi::Object makeUint8Array(
+    jsi::Runtime& rt,
+    const KernelIntrinsics& intrinsics,
+    jsi::ArrayBuffer buffer) {
+  return intrinsics.uint8Array
+      .callAsConstructor(rt, jsi::Value(std::move(buffer)))
+      .asObject(rt);
+}
+
+std::shared_ptr<KernelIntrinsics> captureIntrinsics(jsi::Runtime& rt) {
+  auto global = rt.global();
+  auto objectCtor = global.getPropertyAsObject(rt, "Object");
+  auto getPrototypeOf = objectCtor.getPropertyAsFunction(rt, "getPrototypeOf");
+  auto getDescriptor = objectCtor.getPropertyAsFunction(rt, "getOwnPropertyDescriptor");
+
+  auto requireGetter = [&](const char* name,
+                           const jsi::Value& container,
+                           const jsi::Value& key) -> jsi::Function {
+    const jsi::Value descriptor = getDescriptor.call(rt, container, key);
+    const jsi::Value get = descriptor.isObject()
+        ? descriptor.asObject(rt).getProperty(rt, "get")
+        : jsi::Value::undefined();
+    if (!get.isObject() || !get.asObject(rt).isFunction(rt)) {
+      throw std::runtime_error(
+          std::string("kernel globals: missing TypedArray intrinsic ") + name);
+    }
+    return get.asObject(rt).asFunction(rt);
+  };
+
+  auto uint8Array = global.getPropertyAsFunction(rt, "Uint8Array");
+  const jsi::Value typedArrayProto =
+      getPrototypeOf.call(rt, uint8Array.getProperty(rt, "prototype"));
+  const jsi::Value toStringTag =
+      global.getPropertyAsObject(rt, "Symbol").getProperty(rt, "toStringTag");
+  const auto nameKey = [&](const char* name) {
+    return jsi::Value(rt, jsi::String::createFromAscii(rt, name));
+  };
+
+  return std::shared_ptr<KernelIntrinsics>(new KernelIntrinsics{
+      objectCtor.getPropertyAsFunction(rt, "defineProperty"),
+      objectCtor.getPropertyAsFunction(rt, "freeze"),
+      std::move(uint8Array),
+      requireGetter("buffer", typedArrayProto, nameKey("buffer")),
+      requireGetter("byteOffset", typedArrayProto, nameKey("byteOffset")),
+      requireGetter("byteLength", typedArrayProto, nameKey("byteLength")),
+      requireGetter("Symbol.toStringTag", typedArrayProto, toStringTag),
+  });
+}
+
+void defineHiddenGlobal(
+    jsi::Runtime& rt,
+    const KernelIntrinsics& intrinsics,
+    const char* name,
+    jsi::Value value) {
+  jsi::Object descriptor(rt);
+  descriptor.setProperty(rt, "value", std::move(value));
+  descriptor.setProperty(rt, "writable", jsi::Value(false));
+  descriptor.setProperty(rt, "configurable", jsi::Value(false));
+  descriptor.setProperty(rt, "enumerable", jsi::Value(false));
+  intrinsics.defineProperty.call(
+      rt,
+      rt.global(),
+      jsi::Value(rt, jsi::String::createFromAscii(rt, name)),
+      jsi::Value(std::move(descriptor)));
+}
+
+} // namespace qntx

package/cpp/runtime/KernelJs.hpp

@@ -0,0 +1,81 @@
+#pragma once
+
+#include <jsi/jsi.h>
+
+#include <cstdint>
+#include <memory>
+#include <string>
+
+namespace qntx {
+
+namespace jsi = facebook::jsi;
+
+// Captured JS intrinsics, taken on the pristine runtime before any script can
+// tamper with the builtins they come from. Every member is a jsi value owned
+// by the kernel thread; teardown resets the holding shared_ptr while the
+// runtime is still alive.
+struct KernelIntrinsics {
+  jsi::Function defineProperty;
+  jsi::Function freeze;
+  jsi::Function uint8Array;
+  // The real %TypedArray%.prototype accessors. Calling them reads internal
+  // slots, so forged objects throw and redefined prototype getters cannot lie.
+  jsi::Function taBufferGet;
+  jsi::Function taByteOffsetGet;
+  jsi::Function taByteLengthGet;
+  jsi::Function taTagGet;
+};
+
+std::shared_ptr<KernelIntrinsics> captureIntrinsics(jsi::Runtime& rt);
+
+jsi::Function hostFn(
+    jsi::Runtime& rt,
+    const char* name,
+    unsigned int paramCount,
+    jsi::HostFunctionType fn);
+
+void defineHiddenGlobal(
+    jsi::Runtime& rt,
+    const KernelIntrinsics& intrinsics,
+    const char* name,
+    jsi::Value value);
+
+double finiteNumber(jsi::Runtime& rt, const jsi::Value& value, const char* name);
+
+uint64_t integerInRange(
+    jsi::Runtime& rt,
+    const jsi::Value& value,
+    const char* name,
+    double min,
+    double max);
+
+// A view into a live ArrayBuffer: `buffer` keeps the storage referenced while
+// `data`/`size` are borrowed from it.
+struct ByteView {
+  jsi::ArrayBuffer buffer;
+  uint8_t* data;
+  size_t size;
+};
+
+// The shared extractor for every byte input. Accepts a real ArrayBuffer or a
+// genuine TypedArray — identified by calling the captured
+// %TypedArray%.prototype getters, which read internal slots: forged plain
+// objects throw TypeError and a redefined Uint8Array.prototype getter cannot
+// lie.
+ByteView byteViewFromValue(
+    jsi::Runtime& rt,
+    const jsi::Value& value,
+    const char* name,
+    const KernelIntrinsics& intrinsics);
+
+jsi::ArrayBuffer arrayBufferFromBytes(
+    jsi::Runtime& rt,
+    const uint8_t* bytes,
+    size_t size);
+
+jsi::Object makeUint8Array(
+    jsi::Runtime& rt,
+    const KernelIntrinsics& intrinsics,
+    jsi::ArrayBuffer buffer);
+
+} // namespace qntx

package/cpp/runtime/KernelKeystore.cpp

@@ -0,0 +1,224 @@
+#include "KernelKeystore.hpp"
+
+#include <algorithm>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "../host/Keystore.hpp"
+#include "KernelBuffer.hpp"
+#include "KernelGlobals.hpp"
+#include "KernelJs.hpp"
+
+namespace qntx {
+
+namespace jsi = facebook::jsi;
+
+namespace {
+
+constexpr size_t kFactorIdLength = 32;
+constexpr size_t kTitleMax = 128;
+constexpr size_t kDescriptionMax = 1024;
+constexpr size_t kSecretLength = 32;
+constexpr size_t kSealedMax = 512;
+
+std::string factorId(jsi::Runtime& rt, const jsi::Value& value, const char* name) {
+  if (!value.isString()) {
+    throw jsi::JSError(rt, std::string(name) + " expects a factor id");
+  }
+  auto id = value.asString(rt).utf8(rt);
+  const bool hex = std::all_of(id.begin(), id.end(), [](char c) {
+    return (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f');
+  });
+  if (id.size() != kFactorIdLength || !hex) {
+    throw jsi::JSError(rt, std::string(name) + " factor id must be 32 lowercase hex");
+  }
+  return id;
+}
+
+std::string boundedText(
+    jsi::Runtime& rt,
+    const jsi::Value& value,
+    const char* name,
+    size_t max) {
+  if (!value.isString()) {
+    throw jsi::JSError(rt, std::string(name) + " must be a string");
+  }
+  auto text = value.asString(rt).utf8(rt);
+  if (text.empty() || text.size() > max) {
+    throw jsi::JSError(rt, std::string(name) + " length is out of range");
+  }
+  return text;
+}
+
+KeystorePrompt promptFrom(jsi::Runtime& rt, const jsi::Value* args, const char* name) {
+  return KeystorePrompt{
+      boundedText(rt, args[0], name, kTitleMax),
+      boundedText(rt, args[1], name, kDescriptionMax),
+  };
+}
+
+jsi::Function callbackFrom(jsi::Runtime& rt, const jsi::Value& value, const char* name) {
+  if (!value.isObject() || !value.asObject(rt).isFunction(rt)) {
+    throw jsi::JSError(rt, std::string(name) + " expects a completion function");
+  }
+  return value.asObject(rt).asFunction(rt);
+}
+
+const char* errorCode(KeystoreStatus status) {
+  switch (status) {
+    case KeystoreStatus::cancelled:
+      return "cancelled";
+    case KeystoreStatus::invalidated:
+      return "factor-invalidated";
+    case KeystoreStatus::unavailable:
+      return "factor-unavailable";
+    case KeystoreStatus::ok:
+    case KeystoreStatus::failed:
+      break;
+  }
+  return "unavailable";
+}
+
+// Shared by every keystore call of one runtime: the number of platform calls
+// whose completion has not yet returned (kernel thread only).
+struct KeystoreCalls {
+  int inFlight = 0;
+};
+
+// Parks `done` as a pending call and returns the platform completion that
+// hands the result back on the kernel thread. `withBytes` says whether a
+// success carries bytes (seal, open) or nothing (authenticate, clear).
+KeystoreDone park(
+    const std::shared_ptr<KernelGlobalsState>& state,
+    const std::shared_ptr<KeystoreCalls>& calls,
+    jsi::Function done,
+    bool withBytes) {
+  auto call = std::make_shared<KernelPendingCall>();
+  call->done = std::move(done);
+  state->pending.insert(call);
+  calls->inFlight += 1;
+  // The platform may hold this completion long after a lock tore the runtime
+  // down (a prompt left on screen), so it keeps only a weak reference.
+  std::weak_ptr<KernelGlobalsState> weak = state;
+  return [weak, calls, call, withBytes](KeystoreResult result) {
+    auto state = weak.lock();
+    if (state == nullptr || !state->active->load(std::memory_order_acquire)) {
+      return; // the runtime is gone; teardown already dropped `done`
+    }
+    auto shared = std::make_shared<KeystoreResult>(std::move(result));
+    state->enqueueTask([state, calls, call, shared, withBytes](jsi::Runtime& rt) {
+      calls->inFlight -= 1;
+      auto done = std::move(call->done);
+      state->pending.erase(call);
+      if (!done.has_value()) {
+        return;
+      }
+      if (shared->status != KeystoreStatus::ok) {
+        done->call(
+            rt,
+            jsi::Value::undefined(),
+            jsi::Value(rt, jsi::String::createFromAscii(rt, errorCode(shared->status))));
+        return;
+      }
+      if (!withBytes) {
+        done->call(rt, jsi::Value::undefined(), jsi::Value::undefined());
+        return;
+      }
+      if (shared->bytes.size() == 0) {
+        done->call(
+            rt,
+            jsi::Value::undefined(),
+            jsi::Value(rt, jsi::String::createFromAscii(rt, errorCode(KeystoreStatus::failed))));
+        return;
+      }
+      auto buffer = arrayBufferFromBytes(rt, shared->bytes.data(), shared->bytes.size());
+      auto array = makeUint8Array(rt, *state->intrinsics, std::move(buffer));
+      done->call(rt, jsi::Value(std::move(array)), jsi::Value::undefined());
+    });
+  };
+}
+
+} // namespace
+
+void installKernelKeystore(
+    jsi::Runtime& rt,
+    jsi::Object& qntx,
+    const std::shared_ptr<KernelGlobalsState>& state) {
+  auto calls = std::make_shared<KeystoreCalls>();
+  state->cancelCeremonies.emplace_back([calls] {
+    if (calls->inFlight > 0) {
+      keystoreCancel();
+    }
+  });
+
+  auto keystore = jsi::Object(rt);
+  keystore.setProperty(rt, "locale", jsi::String::createFromUtf8(rt, keystoreLocale()));
+  keystore.setProperty(
+      rt,
+      "seal",
+      hostFn(rt, "keystore.seal", 5, [state, calls](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 5) {
+          throw jsi::JSError(
+              rt, "__qntx.keystore.seal expects (id, secret, title, description, done)");
+        }
+        auto id = factorId(rt, args[0], "__qntx.keystore.seal");
+        auto view = byteViewFromValue(rt, args[1], "__qntx.keystore.seal secret", *state->intrinsics);
+        if (view.size != kSecretLength) {
+          throw jsi::JSError(rt, "__qntx.keystore.seal secret must be 32 bytes");
+        }
+        SecretBytes secret(view.data, view.size);
+        auto prompt = promptFrom(rt, args + 2, "__qntx.keystore.seal prompt");
+        auto done = park(state, calls, callbackFrom(rt, args[4], "__qntx.keystore.seal"), true);
+        keystoreSeal(id, std::move(secret), std::move(prompt), std::move(done));
+        return jsi::Value::undefined();
+      }));
+  keystore.setProperty(
+      rt,
+      "open",
+      hostFn(rt, "keystore.open", 5, [state, calls](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 5) {
+          throw jsi::JSError(
+              rt, "__qntx.keystore.open expects (id, sealed, title, description, done)");
+        }
+        auto id = factorId(rt, args[0], "__qntx.keystore.open");
+        auto view = byteViewFromValue(rt, args[1], "__qntx.keystore.open sealed", *state->intrinsics);
+        if (view.size == 0 || view.size > kSealedMax) {
+          throw jsi::JSError(rt, "__qntx.keystore.open sealed length is out of range");
+        }
+        std::vector<uint8_t> sealed(view.data, view.data + view.size);
+        auto prompt = promptFrom(rt, args + 2, "__qntx.keystore.open prompt");
+        auto done = park(state, calls, callbackFrom(rt, args[4], "__qntx.keystore.open"), true);
+        keystoreOpen(id, std::move(sealed), std::move(prompt), std::move(done));
+        return jsi::Value::undefined();
+      }));
+  keystore.setProperty(
+      rt,
+      "authenticate",
+      hostFn(rt, "keystore.authenticate", 3, [state, calls](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 3) {
+          throw jsi::JSError(
+              rt, "__qntx.keystore.authenticate expects (title, description, done)");
+        }
+        auto prompt = promptFrom(rt, args, "__qntx.keystore.authenticate prompt");
+        auto done =
+            park(state, calls, callbackFrom(rt, args[2], "__qntx.keystore.authenticate"), false);
+        keystoreAuthenticate(std::move(prompt), std::move(done));
+        return jsi::Value::undefined();
+      }));
+  keystore.setProperty(
+      rt,
+      "clear",
+      hostFn(rt, "keystore.clear", 1, [state, calls](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 1) {
+          throw jsi::JSError(rt, "__qntx.keystore.clear expects (done)");
+        }
+        auto done = park(state, calls, callbackFrom(rt, args[0], "__qntx.keystore.clear"), false);
+        keystoreClear(std::move(done));
+        return jsi::Value::undefined();
+      }));
+  state->intrinsics->freeze.call(rt, jsi::Value(rt, keystore));
+  qntx.setProperty(rt, "keystore", jsi::Value(std::move(keystore)));
+}
+
+} // namespace qntx

package/cpp/runtime/KernelKeystore.hpp

@@ -0,0 +1,28 @@
+#pragma once
+
+#include <jsi/jsi.h>
+
+#include <memory>
+
+namespace qntx {
+
+struct KernelGlobalsState;
+
+// Installs the frozen `keystore` object on `__qntx` before the caller freezes
+// it:
+//   locale                                        platform language (BCP 47)
+//   seal(id, secret, title, description, done)    done(sealed | undefined, code | undefined)
+//   open(id, sealed, title, description, done)    done(kek | undefined, code | undefined)
+//   authenticate(title, description, done)        done(undefined, code | undefined)
+//   clear(done)                                   done(undefined, code | undefined)
+// Arguments are validated before the platform sees them (id: 32 lowercase hex;
+// title ≤ 128 and description ≤ 1024 UTF-8 bytes, both non-empty; secret
+// exactly 32 bytes; sealed 1–512 bytes). Completions return to the kernel
+// thread through the pending-call machinery pbkdf2 uses; `code` is the
+// kernel error code for a failure. Teardown cancels an in-flight prompt.
+void installKernelKeystore(
+    facebook::jsi::Runtime& rt,
+    facebook::jsi::Object& qntx,
+    const std::shared_ptr<KernelGlobalsState>& state);
+
+} // namespace qntx

package/cpp/runtime/KernelPasskey.cpp

@@ -0,0 +1,137 @@
+#include "KernelPasskey.hpp"
+
+#include <string>
+#include <utility>
+
+#include "../host/Passkey.hpp"
+#include "KernelGlobals.hpp"
+#include "KernelJs.hpp"
+
+namespace qntx {
+
+namespace jsi = facebook::jsi;
+
+namespace {
+
+constexpr size_t kRequestMax = 16 * 1024;
+
+const char* errorCode(PasskeyStatus status) {
+  switch (status) {
+    case PasskeyStatus::cancelled:
+      return "cancelled";
+    case PasskeyStatus::unavailable:
+      return "factor-unavailable";
+    case PasskeyStatus::ok:
+    case PasskeyStatus::failed:
+      break;
+  }
+  return "unavailable";
+}
+
+struct PasskeyCalls {
+  int inFlight = 0; // kernel thread only
+};
+
+std::string requestFrom(jsi::Runtime& rt, const jsi::Value& value, const char* name) {
+  if (!value.isString()) {
+    throw jsi::JSError(rt, std::string(name) + " expects a request JSON string");
+  }
+  auto request = value.asString(rt).utf8(rt);
+  if (request.empty() || request.size() > kRequestMax) {
+    throw jsi::JSError(rt, std::string(name) + " request length is out of range");
+  }
+  return request;
+}
+
+// Parks `done` as a pending call; the returned completion hands the outcome
+// back on the kernel thread. Like the keystore, the platform may hold the
+// completion past teardown, so it keeps the globals state only weakly.
+PasskeyDone park(
+    const std::shared_ptr<KernelGlobalsState>& state,
+    const std::shared_ptr<PasskeyCalls>& calls,
+    jsi::Function done) {
+  auto call = std::make_shared<KernelPendingCall>();
+  call->done = std::move(done);
+  state->pending.insert(call);
+  calls->inFlight += 1;
+  std::weak_ptr<KernelGlobalsState> weak = state;
+  return [weak, calls, call](PasskeyResult result) {
+    auto state = weak.lock();
+    if (state == nullptr || !state->active->load(std::memory_order_acquire)) {
+      return;
+    }
+    auto shared = std::make_shared<PasskeyResult>(std::move(result));
+    state->enqueueTask([state, calls, call, shared](jsi::Runtime& rt) {
+      calls->inFlight -= 1;
+      auto done = std::move(call->done);
+      state->pending.erase(call);
+      if (!done.has_value()) {
+        return;
+      }
+      if (shared->status != PasskeyStatus::ok || shared->responseJson.empty()) {
+        const auto status =
+            shared->status == PasskeyStatus::ok ? PasskeyStatus::failed : shared->status;
+        done->call(
+            rt,
+            jsi::Value::undefined(),
+            jsi::Value(rt, jsi::String::createFromAscii(rt, errorCode(status))));
+        return;
+      }
+      done->call(
+          rt,
+          jsi::Value(rt, jsi::String::createFromUtf8(rt, shared->responseJson)),
+          jsi::Value::undefined());
+    });
+  };
+}
+
+jsi::Function callbackFrom(jsi::Runtime& rt, const jsi::Value& value, const char* name) {
+  if (!value.isObject() || !value.asObject(rt).isFunction(rt)) {
+    throw jsi::JSError(rt, std::string(name) + " expects a completion function");
+  }
+  return value.asObject(rt).asFunction(rt);
+}
+
+} // namespace
+
+void installKernelPasskey(
+    jsi::Runtime& rt,
+    jsi::Object& qntx,
+    const std::shared_ptr<KernelGlobalsState>& state) {
+  auto calls = std::make_shared<PasskeyCalls>();
+  state->cancelCeremonies.emplace_back([calls] {
+    if (calls->inFlight > 0) {
+      passkeyCancel();
+    }
+  });
+
+  auto passkey = jsi::Object(rt);
+  passkey.setProperty(
+      rt,
+      "create",
+      hostFn(rt, "passkey.create", 2, [state, calls](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 2) {
+          throw jsi::JSError(rt, "__qntx.passkey.create expects (requestJson, done)");
+        }
+        auto request = requestFrom(rt, args[0], "__qntx.passkey.create");
+        auto done = park(state, calls, callbackFrom(rt, args[1], "__qntx.passkey.create"));
+        passkeyCreate(std::move(request), std::move(done));
+        return jsi::Value::undefined();
+      }));
+  passkey.setProperty(
+      rt,
+      "get",
+      hostFn(rt, "passkey.get", 2, [state, calls](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        if (count < 2) {
+          throw jsi::JSError(rt, "__qntx.passkey.get expects (requestJson, done)");
+        }
+        auto request = requestFrom(rt, args[0], "__qntx.passkey.get");
+        auto done = park(state, calls, callbackFrom(rt, args[1], "__qntx.passkey.get"));
+        passkeyGet(std::move(request), std::move(done));
+        return jsi::Value::undefined();
+      }));
+  state->intrinsics->freeze.call(rt, jsi::Value(rt, passkey));
+  qntx.setProperty(rt, "passkey", jsi::Value(std::move(passkey)));
+}
+
+} // namespace qntx

package/cpp/runtime/KernelPasskey.hpp

@@ -0,0 +1,23 @@
+#pragma once
+
+#include <jsi/jsi.h>
+
+#include <memory>
+
+namespace qntx {
+
+struct KernelGlobalsState;
+
+// Installs the frozen `passkey` object on `__qntx` before the caller freezes
+// it:
+//   create(requestJson, done)   done(responseJson | undefined, code | undefined)
+//   get(requestJson, done)      done(responseJson | undefined, code | undefined)
+// The request is a non-empty string of at most 16 KiB. Completions return to
+// the kernel thread through the pending-call machinery; `code` is the kernel
+// error code for a failure. Teardown cancels an in-flight ceremony.
+void installKernelPasskey(
+    facebook::jsi::Runtime& rt,
+    facebook::jsi::Object& qntx,
+    const std::shared_ptr<KernelGlobalsState>& state);
+
+} // namespace qntx