@qntx/wallet-native 0.0.0-stage → 0.4.0

package/cpp/host/KernelFile.cpp

@@ -0,0 +1,120 @@
+#include "KernelFile.hpp"
+
+#include <cerrno>
+#include <cstring>
+#include <stdexcept>
+
+#if defined(_WIN32)
+#error "KernelFile has no Windows implementation"
+#else
+#include <fcntl.h>
+#include <sys/stat.h>
+#include <sys/types.h>
+#include <unistd.h>
+#endif
+
+namespace qntx {
+namespace {
+
+[[noreturn]] void fail(const char* what) {
+  const int saved = errno;
+  throw std::runtime_error(
+      std::string(what) + ": " + std::strerror(saved) + " (errno " + std::to_string(saved) + ")");
+}
+
+void fsyncOrFail(int fd, const char* what, bool full = false) {
+  // Files: on Apple the documented durable barrier is fcntl(F_FULLFSYNC).
+  // Directories: plain fsync everywhere (F_FULLFSYNC is for files only).
+  const int rc =
+#if defined(__APPLE__)
+      full ? ::fcntl(fd, F_FULLFSYNC) : ::fsync(fd);
+#else
+      (::fsync(fd));
+#endif
+  if (rc != 0) {
+    fail(what);
+  }
+}
+
+std::string pathFor(const std::string& directory, const char* leaf) {
+  return directory + "/" + leaf;
+}
+
+} // namespace
+
+std::optional<std::vector<uint8_t>> kernelFileRead(const std::string& directory) {
+  const std::string path = pathFor(directory, "vault.cbor");
+  const int fd = ::open(path.c_str(), O_RDONLY);
+  if (fd < 0) {
+    if (errno == ENOENT) {
+      return std::nullopt;
+    }
+    fail("open vault file");
+  }
+  std::vector<uint8_t> bytes;
+  uint8_t chunk[65536];
+  for (;;) {
+    const ssize_t n = ::read(fd, chunk, sizeof(chunk));
+    if (n < 0) {
+      const int saved = errno;
+      ::close(fd);
+      errno = saved;
+      fail("read vault file");
+    }
+    if (n == 0) {
+      break;
+    }
+    bytes.insert(bytes.end(), chunk, chunk + n);
+  }
+  ::close(fd);
+  return bytes;
+}
+
+void kernelFileWrite(const std::string& directory, const std::vector<uint8_t>& bytes) {
+  const std::string tmp = pathFor(directory, "vault.cbor.tmp");
+  const std::string final = pathFor(directory, "vault.cbor");
+  const int fd = ::open(tmp.c_str(), O_WRONLY | O_CREAT | O_TRUNC, 0600);
+  if (fd < 0) {
+    fail("open temp vault file");
+  }
+  size_t off = 0;
+  while (off < bytes.size()) {
+    const ssize_t n = ::write(fd, bytes.data() + off, bytes.size() - off);
+    if (n <= 0) {
+      const int saved = errno;
+      ::close(fd);
+      ::unlink(tmp.c_str());
+      errno = saved;
+      fail("write temp vault file");
+    }
+    off += static_cast<size_t>(n);
+  }
+  try {
+    fsyncOrFail(fd, "fsync temp vault file", /*full=*/true);
+  } catch (...) {
+    ::close(fd);
+    ::unlink(tmp.c_str());
+    throw;
+  }
+  if (::close(fd) != 0) {
+    ::unlink(tmp.c_str());
+    fail("close temp vault file");
+  }
+  if (::rename(tmp.c_str(), final.c_str()) != 0) {
+    ::unlink(tmp.c_str());
+    fail("rename vault file");
+  }
+  const int dirFd = ::open(directory.c_str(), O_RDONLY);
+  if (dirFd < 0) {
+    fail("open vault directory");
+  }
+  try {
+    fsyncOrFail(dirFd, "fsync vault directory");
+  } catch (...) {
+    ::close(dirFd);
+    throw;
+  }
+  ::close(dirFd);
+}
+
+} // namespace qntx

package/cpp/host/KernelFile.hpp

@@ -0,0 +1,24 @@
+#pragma once
+
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace qntx {
+
+// The vault image file lives in a platform-provided directory
+// (platformVaultDirectory()): <directory>/vault.cbor.
+//
+// The whole file, or nullopt when it does not exist. Throws std::runtime_error
+// naming the failing step and errno — the file store turns that into a typed
+// rejection and never silently treats it as an empty vault.
+std::optional<std::vector<uint8_t>> kernelFileRead(const std::string& directory);
+
+// Atomic replace of vault.cbor in `directory`: write vault.cbor.tmp in the
+// same directory, fsync it, rename it over the target, then fsync the
+// directory so the rename itself is durable. Throws std::runtime_error naming
+// the failing step and errno; a failed write leaves the previous file intact
+// and unlinks the temp file.
+void kernelFileWrite(const std::string& directory, const std::vector<uint8_t>& bytes);
+
+} // namespace qntx

package/cpp/host/Keystore.hpp

@@ -0,0 +1,70 @@
+#pragma once
+
+#include <functional>
+#include <string>
+#include <vector>
+
+#include "../runtime/KernelBuffer.hpp"
+
+namespace qntx {
+
+// The platform keystore behind `__qntx.keystore` (W5): a hardware key per
+// vault factor that seals and opens the factor's KEK behind a system user
+// verification. iOS: Secure Enclave P-256 + ECIES; Android: Keystore
+// AES-256-GCM behind BiometricPrompt. Each function has exactly one strong
+// definition per platform (KeystoreIos.mm, KeystoreAndroid.cpp); host tests
+// link a fake.
+
+struct KeystorePrompt {
+  std::string title;
+  std::string description;
+};
+
+// How a keystore call ended. The binding maps each status to the kernel's
+// error code: cancelled → "cancelled", invalidated → "factor-invalidated",
+// unavailable → "factor-unavailable", failed → "unavailable". The values are
+// part of the Android JNI contract (Keystore.kt).
+enum class KeystoreStatus { ok = 0, cancelled = 1, invalidated = 2, unavailable = 3, failed = 4 };
+
+struct KeystoreResult {
+  KeystoreStatus status = KeystoreStatus::failed;
+  // seal: the platform ciphertext; open: the KEK; empty otherwise.
+  SecretBytes bytes;
+};
+
+// Completion callbacks run exactly once, on any thread.
+using KeystoreDone = std::function<void(KeystoreResult)>;
+
+// Creates the hardware key for vault factor `id` and encrypts `secret` under
+// it. Android prompts (encryption needs the authenticated cipher); iOS does
+// not (ECIES encrypts with the public key).
+void keystoreSeal(
+    const std::string& id,
+    SecretBytes secret,
+    KeystorePrompt prompt,
+    KeystoreDone done);
+
+// Decrypts `sealed` with factor `id`'s key after a fresh system verification
+// that shows `prompt`. A key the system removed (lock screen disabled,
+// device restored) completes `invalidated`.
+void keystoreOpen(
+    const std::string& id,
+    std::vector<uint8_t> sealed,
+    KeystorePrompt prompt,
+    KeystoreDone done);
+
+// A device-owner check with no key involved (vault reset, WD-055).
+void keystoreAuthenticate(KeystorePrompt prompt, KeystoreDone done);
+
+// Deletes every vault key this app created.
+void keystoreClear(KeystoreDone done);
+
+// Dismisses the system prompt of an in-flight call, if any; that call still
+// completes (normally `cancelled`). Called when a kernel runtime tears down.
+void keystoreCancel();
+
+// The platform's preferred language as a BCP 47 tag, read natively so the
+// main runtime cannot choose the prompt language.
+std::string keystoreLocale();
+
+} // namespace qntx

package/cpp/host/Lifecycle.cpp

@@ -0,0 +1,77 @@
+#include "Lifecycle.hpp"
+
+
+
+namespace qntx {
+
+KernelLifecycleDispatcher& KernelLifecycleDispatcher::shared() {
+  static KernelLifecycleDispatcher dispatcher;
+  return dispatcher;
+}
+
+void KernelLifecycleDispatcher::registerHost(
+    const std::weak_ptr<LifecycleLockTarget>& host, int seconds) {
+  std::lock_guard<std::mutex> lock(mutex_);
+  entries_.push_back(Entry{host, seconds, std::nullopt});
+}
+
+void KernelLifecycleDispatcher::unregister(const LifecycleLockTarget* host) {
+  std::lock_guard<std::mutex> lock(mutex_);
+  std::erase_if(entries_, [&](const Entry& entry) {
+    const auto target = entry.host.lock();
+    return !target || target.get() == host;
+  });
+}
+
+void KernelLifecycleDispatcher::onBackground() {
+  std::vector<std::shared_ptr<LifecycleLockTarget>> immediate;
+  {
+    std::lock_guard<std::mutex> lock(mutex_);
+    const auto now = clock_();
+    for (auto& entry : entries_) {
+      const auto host = entry.host.lock();
+      if (!host) {
+        continue;
+      }
+      if (entry.seconds == 0) {
+        immediate.push_back(host);
+      } else {
+        entry.backgroundAtMs = now;
+      }
+    }
+  }
+  // Lock outside the registry mutex — the target's own lock may re-enter here
+  // (unregister on exit).
+  for (const auto& host : immediate) {
+    host->lockForBackground();
+  }
+}
+
+void KernelLifecycleDispatcher::onForeground() {
+  std::vector<std::shared_ptr<LifecycleLockTarget>> expired;
+  {
+    std::lock_guard<std::mutex> lock(mutex_);
+    const auto now = clock_();
+    for (auto& entry : entries_) {
+      const auto host = entry.host.lock();
+      if (!host) {
+        continue;
+      }
+      if (entry.backgroundAtMs.has_value() &&
+          backgroundExpired(*entry.backgroundAtMs, now, entry.seconds)) {
+        expired.push_back(host);
+      }
+      entry.backgroundAtMs.reset();
+    }
+  }
+  for (const auto& host : expired) {
+    host->lockForBackground();
+  }
+}
+
+void KernelLifecycleDispatcher::setClock(std::function<int64_t()> clock) {
+  std::lock_guard<std::mutex> lock(mutex_);
+  clock_ = std::move(clock);
+}
+
+} // namespace qntx

package/cpp/host/Lifecycle.hpp

@@ -0,0 +1,71 @@
+#pragma once
+
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <optional>
+#include <mutex>
+#include <vector>
+
+namespace qntx {
+
+/**
+ * The background-expiry decision: a host whose lock deadline was
+ * `backgroundAtMs + seconds*1000` on the sleep-inclusive monotonic clock is
+ * expired when nowMs is past it. seconds==0 locks the moment the app
+ * backgrounds — the caller never reaches this function for it.
+ */
+inline bool backgroundExpired(int64_t backgroundAtMs, int64_t nowMs, int seconds) {
+  return nowMs >= backgroundAtMs + static_cast<int64_t>(seconds) * 1000;
+}
+
+/** Milliseconds on the clock that keeps running while the device sleeps —
+ *  Apple CLOCK_MONOTONIC, Android CLOCK_BOOTTIME. */
+int64_t sleepInclusiveMonotonicMs();
+
+/** What the platform's lifecycle hooks lock; HybridKernelHost implements it
+ *  (exit(BACKGROUND)). The interface keeps the dispatcher testable without a
+ *  Nitro runtime. */
+class LifecycleLockTarget {
+ public:
+  virtual ~LifecycleLockTarget() = default;
+  virtual void lockForBackground() = 0;
+};
+
+/**
+ * One process-wide registry of live kernel hosts with their
+ * backgroundLockSeconds. `onBackground` stamps every registered host (or locks
+ * it immediately when its seconds is 0); `onForeground` locks the hosts whose
+ * deadline passed while backgrounded. All calls are main-thread safe and take
+ * weak_ptr so a destroyed host is simply skipped.
+ */
+class KernelLifecycleDispatcher {
+ public:
+  static KernelLifecycleDispatcher& shared();
+
+  void registerHost(const std::weak_ptr<LifecycleLockTarget>& host, int seconds);
+  /** Drop the registration — called on every host exit. */
+  void unregister(const LifecycleLockTarget* host);
+
+  void onBackground();
+  void onForeground();
+
+  /** Test seam: the clock defaults to sleepInclusiveMonotonicMs. */
+  void setClock(std::function<int64_t()> clock);
+
+ private:
+  struct Entry {
+    std::weak_ptr<LifecycleLockTarget> host;
+    int seconds;
+    std::optional<int64_t> backgroundAtMs;
+  };
+  std::mutex mutex_;
+  std::vector<Entry> entries_;
+  std::function<int64_t()> clock_ = sleepInclusiveMonotonicMs;
+};
+
+/** Install the platform's app-lifecycle observer exactly once — NSNotificationCenter
+ *  on Apple, ProcessLifecycleOwner on Android. Called from KernelHost.start. */
+void installLifecycleObserver();
+
+} // namespace qntx

package/cpp/host/Passkey.hpp

@@ -0,0 +1,39 @@
+#pragma once
+
+#include <functional>
+#include <string>
+
+namespace qntx {
+
+// The platform passkey authenticator behind `__qntx.passkey` (W6). The kernel
+// builds the WebAuthn request JSON and parses the response JSON itself; the
+// platform only runs the system ceremony. Android: Credential Manager. iOS:
+// not yet available (W6c needs an associated domain) — every call completes
+// `unavailable`. Each function has exactly one strong definition per platform
+// (PasskeyAndroid.cpp, PasskeyIos.mm); host tests link a fake.
+
+// The binding maps each status to the kernel's error code: cancelled →
+// "cancelled", unavailable → "factor-unavailable", failed → "unavailable".
+// The values are part of the Android JNI contract (Passkey.kt).
+enum class PasskeyStatus { ok = 0, cancelled = 1, unavailable = 3, failed = 4 };
+
+struct PasskeyResult {
+  PasskeyStatus status = PasskeyStatus::failed;
+  // The WebAuthn registration or authentication response JSON on success.
+  std::string responseJson;
+};
+
+// Completion callbacks run exactly once, on any thread.
+using PasskeyDone = std::function<void(PasskeyResult)>;
+
+// Registers a discoverable credential from PublicKeyCredentialCreationOptions JSON.
+void passkeyCreate(std::string requestJson, PasskeyDone done);
+
+// Asserts a credential from PublicKeyCredentialRequestOptions JSON.
+void passkeyGet(std::string requestJson, PasskeyDone done);
+
+// Dismisses the system UI of an in-flight ceremony, if any; that call still
+// completes (normally `cancelled`). Called when a kernel runtime tears down.
+void passkeyCancel();
+
+} // namespace qntx

package/cpp/host/VaultDirectory.hpp

@@ -0,0 +1,16 @@
+#pragma once
+
+#include <string>
+
+namespace qntx {
+
+// The directory the vault image file lives in — resolved once per
+// KernelRuntime::start and passed explicitly to kernelFileRead/kernelFileWrite:
+//   iOS     <Application Support>/qntx-wallet
+//   Android <noBackupFilesDir>/qntx-wallet
+// Defined only by a platform translation unit (platform/VaultDirectory.mm on iOS,
+// platform/VaultDirectoryAndroid.cpp on Android): a host that links neither fails
+// at link time instead of misbehaving at runtime.
+std::string platformVaultDirectory();
+
+} // namespace qntx

package/cpp/platform/KeystoreAndroid.cpp

@@ -0,0 +1,175 @@
+// Android keystore: the Kotlin Keystore object owns the AndroidKeyStore key
+// and the BiometricPrompt; this file forwards each call through fbjni with a
+// completion token and resolves the parked completion when Kotlin calls back
+// through nativeComplete (on the main thread).
+#include "../host/Keystore.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_keystoreClass;
+
+std::mutex g_mutex;
+int64_t g_nextToken = 1;
+std::unordered_map<int64_t, KeystoreDone> g_pending;
+
+int64_t park(KeystoreDone done) {
+  std::lock_guard<std::mutex> lock(g_mutex);
+  const int64_t token = g_nextToken++;
+  g_pending.emplace(token, std::move(done));
+  return token;
+}
+
+KeystoreDone 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> keystoreClass() {
+  if (!g_keystoreClass) {
+    throw std::runtime_error("keystore: JNI_OnLoad init did not run");
+  }
+  return g_keystoreClass;
+}
+
+jni::local_ref<jni::JArrayByte> byteArray(const uint8_t* data, size_t size) {
+  auto array = jni::JArrayByte::newArray(size);
+  array->setRegion(0, static_cast<jsize>(size), reinterpret_cast<const jbyte*>(data));
+  return array;
+}
+
+// Runs one Kotlin entry point; a JNI failure completes the call as `failed`
+// instead of leaving it parked forever.
+template <typename Call>
+void dispatch(KeystoreDone done, Call&& call) {
+  const int64_t token = park(std::move(done));
+  try {
+    jni::ThreadScope threadScope;
+    call(static_cast<jlong>(token));
+  } catch (...) {
+    if (auto parked = take(token)) {
+      parked(KeystoreResult{KeystoreStatus::failed, {}});
+    }
+  }
+}
+
+} // namespace
+
+void kernelKeystoreInit(jni::alias_ref<jclass> clazz) {
+  g_keystoreClass = jni::make_global(clazz);
+}
+
+void keystoreSeal(
+    const std::string& id,
+    SecretBytes secret,
+    KeystorePrompt prompt,
+    KeystoreDone done) {
+  dispatch(std::move(done), [&](jlong token) {
+    auto method = keystoreClass()->getStaticMethod<void(
+        jlong, jni::alias_ref<jstring>, jni::alias_ref<jni::JArrayByte>, jni::alias_ref<jstring>,
+        jni::alias_ref<jstring>)>("seal");
+    method(
+        keystoreClass(),
+        token,
+        jni::make_jstring(id),
+        byteArray(secret.data(), secret.size()),
+        jni::make_jstring(prompt.title),
+        jni::make_jstring(prompt.description));
+  });
+}
+
+void keystoreOpen(
+    const std::string& id,
+    std::vector<uint8_t> sealed,
+    KeystorePrompt prompt,
+    KeystoreDone done) {
+  dispatch(std::move(done), [&](jlong token) {
+    auto method = keystoreClass()->getStaticMethod<void(
+        jlong, jni::alias_ref<jstring>, jni::alias_ref<jni::JArrayByte>, jni::alias_ref<jstring>,
+        jni::alias_ref<jstring>)>("open");
+    method(
+        keystoreClass(),
+        token,
+        jni::make_jstring(id),
+        byteArray(sealed.data(), sealed.size()),
+        jni::make_jstring(prompt.title),
+        jni::make_jstring(prompt.description));
+  });
+}
+
+void keystoreAuthenticate(KeystorePrompt prompt, KeystoreDone done) {
+  dispatch(std::move(done), [&](jlong token) {
+    auto method = keystoreClass()->getStaticMethod<void(
+        jlong, jni::alias_ref<jstring>, jni::alias_ref<jstring>)>("authenticate");
+    method(
+        keystoreClass(),
+        token,
+        jni::make_jstring(prompt.title),
+        jni::make_jstring(prompt.description));
+  });
+}
+
+void keystoreClear(KeystoreDone done) {
+  dispatch(std::move(done), [&](jlong token) {
+    auto method = keystoreClass()->getStaticMethod<void(jlong)>("clear");
+    method(keystoreClass(), token);
+  });
+}
+
+void keystoreCancel() {
+  jni::ThreadScope threadScope;
+  auto method = keystoreClass()->getStaticMethod<void()>("cancel");
+  method(keystoreClass());
+}
+
+std::string keystoreLocale() {
+  jni::ThreadScope threadScope;
+  auto method = keystoreClass()->getStaticMethod<jni::JString::javaobject()>("locale");
+  return method(keystoreClass())->toStdString();
+}
+
+} // namespace qntx
+
+// Kotlin's Keystore.nativeComplete: resolves the parked call. The byte array
+// is copied into wiping storage; Kotlin wipes its own copy afterwards.
+extern "C" JNIEXPORT void JNICALL
+Java_com_margelo_nitro_qntxwallet_Keystore_nativeComplete(
+    JNIEnv* env, jclass, jlong token, jint status, jbyteArray bytes) {
+  auto done = qntx::take(static_cast<int64_t>(token));
+  if (!done) {
+    return;
+  }
+  qntx::KeystoreResult result;
+  result.status = static_cast<qntx::KeystoreStatus>(status);
+  if (status < 0 || status > static_cast<jint>(qntx::KeystoreStatus::failed)) {
+    result.status = qntx::KeystoreStatus::failed;
+  }
+  if (bytes != nullptr && result.status == qntx::KeystoreStatus::ok) {
+    const jsize size = env->GetArrayLength(bytes);
+    qntx::SecretBytes copy(static_cast<size_t>(size));
+    env->GetByteArrayRegion(bytes, 0, size, reinterpret_cast<jbyte*>(copy.data()));
+    result.bytes = std::move(copy);
+  }
+  done(std::move(result));
+}
+
+#endif // __ANDROID__