@mwguerra/hull 0.1.0

package/host/src/main.cpp

@@ -0,0 +1,386 @@
+// Hull host — a single, generic native web-view runtime.
+//
+// Modes:
+//   (window)  --url <devUrl> | --app <file.html>   render the UI in an OS web view
+//   (serve)   --serve <port>                       headless HTTP/SSE bridge (browser dev mode)
+//   --title --width --height --app-id --debug --inspect
+//
+// Bindings register into a transport-agnostic Dispatcher, then are exposed either over
+// the web view (window mode) or over HTTP/SSE (serve mode). --inspect turns on the dev
+// trace (mirrors every call/reply/event on the "__trace" event for the inspector).
+
+// Must precede any libc header so glibc exposes unshare()/CLONE_NEWUSER (Linux sandbox
+// probe). g++ defines this by default; the guard just makes it portable + warning-free.
+#if defined(__linux__) && !defined(_GNU_SOURCE)
+#define _GNU_SOURCE
+#endif
+
+#include <iostream>
+#include <fstream>
+#include <sstream>
+#include <string>
+#include <optional>
+#include <thread>
+#include <nlohmann/json.hpp>
+
+#include "dispatcher.hpp"
+#include "secure.hpp"
+#include "bindings/http.hpp"   // pulls httplib first (Linux X11 macro clash)
+#include "serve.hpp"           // httplib HTTP/SSE bridge server
+#include "webview/webview.h"
+#include "bindings/printer.hpp"
+#include "bindings/storage.hpp"
+#include "bindings/credentials.hpp"
+#include "bindings/database.hpp"
+#include "bindings/files.hpp"
+
+#ifdef _WIN32
+#include <windows.h>
+#include <gdiplus.h>
+#endif
+
+#if defined(__linux__)
+#include <sched.h>      // unshare, CLONE_NEWUSER
+#include <sys/wait.h>   // waitpid
+#include <unistd.h>     // fork, getuid, write, close, readlink
+#include <fcntl.h>      // open
+#include <cstdio>       // snprintf
+#include <cstdlib>      // setenv / getenv / system
+#include <filesystem>   // file:// URL + desktop-integration paths
+#include <glib.h>       // g_set_prgname (window app-id -> desktop icon)
+#endif
+
+using json = nlohmann::json;
+
+namespace {
+
+// Set the window icon at runtime from an image file (the host is generic/prebuilt, so
+// the icon can't be embedded at compile time). Windows: GDI+ loads PNG/ICO into an
+// HICON. macOS/Linux(GTK4) window icons come from the app bundle / .desktop file, so
+// this is a no-op there (documented).
+#if defined(_WIN32)
+void set_window_icon(webview::webview& w, const std::string& path) {
+  auto win = w.window();          // webview 0.12: result<void*>
+  if (!win.ok()) return;
+  HWND hwnd = static_cast<HWND>(win.value());
+  if (!hwnd) return;
+  int n = MultiByteToWideChar(CP_UTF8, 0, path.c_str(), -1, nullptr, 0);
+  if (n <= 0) return;
+  std::wstring wpath(n, L'\0');
+  MultiByteToWideChar(CP_UTF8, 0, path.c_str(), -1, &wpath[0], n);
+  ULONG_PTR token = 0;
+  Gdiplus::GdiplusStartupInput gsi;
+  if (Gdiplus::GdiplusStartup(&token, &gsi, nullptr) != Gdiplus::Ok) return;
+  Gdiplus::Bitmap bmp(wpath.c_str());
+  if (bmp.GetLastStatus() == Gdiplus::Ok) {
+    HICON hIcon = nullptr;
+    if (bmp.GetHICON(&hIcon) == Gdiplus::Ok && hIcon) {
+      SendMessageW(hwnd, WM_SETICON, ICON_BIG, reinterpret_cast<LPARAM>(hIcon));
+      SendMessageW(hwnd, WM_SETICON, ICON_SMALL, reinterpret_cast<LPARAM>(hIcon));
+      // hIcon intentionally kept for the process lifetime (the window owns it).
+    }
+  }
+  // GDI+ left initialized so the icon stays valid.
+}
+#else
+void set_window_icon(webview::webview&, const std::string&) { /* set via app bundle / .desktop */ }
+#endif
+
+#if defined(__linux__)
+// WebKitGTK isolates its web/network subprocesses with bubblewrap, which needs
+// unprivileged user namespaces. When those are blocked — Ubuntu 24.04 enables
+// kernel.apparmor_restrict_unprivileged_userns by default, and many containers lack
+// them — the web process aborts with "bwrap: setting up uid map: Permission denied".
+//
+// Probe in a child process (so the parent's namespaces are untouched) whether bwrap's
+// rootless setup will work: create a user namespace AND write its uid map. The map
+// write is the step that actually fails on Ubuntu 24.04 — its
+// apparmor_restrict_unprivileged_userns lets unshare(CLONE_NEWUSER) succeed but denies
+// writing /proc/self/uid_map ("bwrap: setting up uid map: Permission denied"), so a
+// probe that only tries unshare reports a false positive. If this fails, disable the
+// WebKitGTK sandbox so the app still runs — unless the user made an explicit choice:
+//   WEBKIT_DISABLE_SANDBOX_THIS_IS_DANGEROUS set  -> respect it (CLI/launcher opt-out)
+//   HULL_FORCE_SANDBOX set                         -> keep the sandbox, never auto-disable
+bool userns_available() {
+  pid_t pid = fork();
+  if (pid < 0) return true;                  // can't probe — assume the sandbox works
+  if (pid == 0) {
+    if (unshare(CLONE_NEWUSER) != 0) _exit(1);
+    int fd = open("/proc/self/uid_map", O_WRONLY);
+    if (fd < 0) _exit(1);
+    char buf[64];
+    int n = std::snprintf(buf, sizeof(buf), "0 %d 1\n", (int)getuid());
+    ssize_t w = write(fd, buf, (size_t)n);   // EPERM here => bwrap would fail too
+    close(fd);
+    _exit(w == (ssize_t)n ? 0 : 1);
+  }
+  int status = 0;
+  if (waitpid(pid, &status, 0) < 0) return true;
+  return WIFEXITED(status) && WEXITSTATUS(status) == 0;
+}
+
+void maybe_disable_webkit_sandbox() {
+  if (std::getenv("WEBKIT_DISABLE_SANDBOX_THIS_IS_DANGEROUS")) return; // explicit opt-out
+  if (std::getenv("HULL_FORCE_SANDBOX")) return;                       // forced on
+  if (userns_available()) return;                                     // sandbox will work
+  setenv("WEBKIT_DISABLE_SANDBOX_THIS_IS_DANGEROUS", "1", 1);
+  std::cerr << "hull: unprivileged user namespaces are unavailable; disabling the "
+               "WebKitGTK sandbox so the app can run.\n"
+               "      To keep the sandbox, enable userns (e.g. sudo sysctl "
+               "kernel.apparmor_restrict_unprivileged_userns=0) or set "
+               "HULL_FORCE_SANDBOX=1.\n";
+}
+
+// GTK4 has no runtime "set window icon from a PNG" (unlike Windows GDI+): the title
+// bar / dock / Alt-Tab icon is drawn by the compositor from a .desktop file matched to
+// the window's app-id. So to show an icon on Linux we (1) install the PNG into the user
+// icon theme, (2) write a .desktop whose Icon points at it, and (3) set the window's
+// app-id (via g_set_prgname, before GTK init) to that .desktop's id so they're matched.
+// Works on both Wayland and X11. Idempotent; writes only under XDG data home.
+void install_desktop_integration(const std::string& app_id, const std::string& title,
+                                 const std::string& icon_path) {
+  if (app_id.empty()) return;
+  std::error_code ec;
+  const char* home = std::getenv("HOME");
+  const char* xdg = std::getenv("XDG_DATA_HOME");
+  std::filesystem::path data = (xdg && *xdg) ? std::filesystem::path(xdg)
+      : std::filesystem::path(home ? home : ".") / ".local" / "share";
+
+  // Detect an installed binary (e.g. from a .deb under /opt or /usr). The package
+  // already ships a *visible* /usr/share/applications/<app-id>.desktop + icon, so we must
+  // NOT write a user-level NoDisplay entry — a ~/.local one overrides the system file and
+  // would hide the app from the menu. Set the app-id (for window<->.desktop matching) and
+  // remove any stale dev-created user entry so the installed app shows up.
+  {
+    char buf[4096]; ssize_t n = readlink("/proc/self/exe", buf, sizeof(buf) - 1);
+    std::string p = n > 0 ? std::string(buf, (size_t)n) : "";
+    if (p.rfind("/usr/", 0) == 0 || p.rfind("/opt/", 0) == 0) {
+      const std::filesystem::path stale = data / "applications" / (app_id + ".desktop");
+      std::ifstream in(stale);
+      std::string c((std::istreambuf_iterator<char>(in)), std::istreambuf_iterator<char>());
+      in.close();
+      if (c.find("X-Hull-Generated=true") != std::string::npos) std::filesystem::remove(stale, ec);
+      g_set_prgname(app_id.c_str());
+      return;
+    }
+  }
+
+  // (1) icon -> ~/.local/share/icons/hicolor/256x256/apps/<app-id>.png
+  if (!icon_path.empty() && std::filesystem::exists(icon_path, ec)) {
+    auto icondir = data / "icons" / "hicolor" / "256x256" / "apps";
+    std::filesystem::create_directories(icondir, ec);
+    std::filesystem::copy_file(icon_path, icondir / (app_id + ".png"),
+        std::filesystem::copy_options::overwrite_existing, ec);
+  }
+
+  // (2) ~/.local/share/applications/<app-id>.desktop
+  auto appsdir = data / "applications";
+  std::filesystem::create_directories(appsdir, ec);
+  std::string exe;
+  { char buf[4096]; ssize_t n = readlink("/proc/self/exe", buf, sizeof(buf) - 1);
+    if (n > 0) { buf[n] = '\0'; exe = buf; } }
+  std::ofstream f(appsdir / (app_id + ".desktop"), std::ios::trunc);
+  if (f) {
+    f << "[Desktop Entry]\n"
+      << "Type=Application\n"
+      << "Name=" << (title.empty() ? app_id : title) << "\n"
+      << "Icon=" << app_id << "\n"
+      << "Exec=" << (exe.empty() ? app_id : exe) << "\n"
+      << "StartupWMClass=" << app_id << "\n"
+      << "NoDisplay=true\n"          // matched for the running window, hidden from menus
+      << "X-Hull-Generated=true\n";
+  }
+
+  // (3) match the running window to that .desktop via the Wayland/X11 app-id.
+  g_set_prgname(app_id.c_str());
+}
+
+// Build a percent-encoded file:// URL from a local path. On WebKitGTK we load the
+// packaged app.html by URL (not set_html): set_html gives the document a null base
+// URL, under which <script type="module"> — what the single-file bundle uses — does
+// not execute, so the app renders blank. A real file:// origin runs the modules.
+std::string file_uri(const std::string& path) {
+  std::error_code ec;
+  std::filesystem::path abs = std::filesystem::absolute(path, ec);
+  const std::string p = ec ? path : abs.string();
+  static const char* hex = "0123456789ABCDEF";
+  std::string out = "file://";
+  for (unsigned char c : p) {
+    if (c == '/' || c == '-' || c == '_' || c == '.' || c == '~' ||
+        (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9')) {
+      out += static_cast<char>(c);
+    } else {
+      out += '%'; out += hex[c >> 4]; out += hex[c & 0x0F];
+    }
+  }
+  return out;
+}
+#endif
+
+struct Options {
+  std::optional<std::string> url;
+  std::optional<std::string> app;
+  std::optional<int> serve_port;
+  std::optional<int> inspect_port;
+  std::optional<std::string> icon;
+  std::string title = "Hull App";
+  std::string appId = "Hull";
+  int width = 1100;
+  int height = 760;
+  bool debug = false;
+  bool inspect = false;
+};
+
+std::optional<std::string> next_arg(int argc, char** argv, int& i) {
+  if (i + 1 < argc) return std::string(argv[++i]);
+  return std::nullopt;
+}
+
+Options parse_args(int argc, char** argv) {
+  Options o;
+  for (int i = 1; i < argc; ++i) {
+    std::string a = argv[i];
+    if (a == "--url")         { if (auto v = next_arg(argc, argv, i)) o.url = *v; }
+    else if (a == "--app")    { if (auto v = next_arg(argc, argv, i)) o.app = *v; }
+    else if (a == "--serve")  { if (auto v = next_arg(argc, argv, i)) o.serve_port = std::stoi(*v); }
+    else if (a == "--inspect-port") { if (auto v = next_arg(argc, argv, i)) o.inspect_port = std::stoi(*v); }
+    else if (a == "--title")  { if (auto v = next_arg(argc, argv, i)) o.title = *v; }
+    else if (a == "--app-id") { if (auto v = next_arg(argc, argv, i)) o.appId = *v; }
+    else if (a == "--icon")   { if (auto v = next_arg(argc, argv, i)) o.icon = *v; }
+    else if (a == "--width")  { if (auto v = next_arg(argc, argv, i)) o.width = std::stoi(*v); }
+    else if (a == "--height") { if (auto v = next_arg(argc, argv, i)) o.height = std::stoi(*v); }
+    else if (a == "--debug")  { o.debug = true; }
+    else if (a == "--inspect") { o.inspect = true; }
+  }
+  return o;
+}
+
+std::optional<std::string> read_file(const std::string& path) {
+  std::ifstream f(path, std::ios::binary);
+  if (!f) return std::nullopt;
+  std::ostringstream ss;
+  ss << f.rdbuf();
+  return ss.str();
+}
+
+const char* FALLBACK_HTML =
+  "<!doctype html><html><head><meta charset='utf-8'><title>Hull</title>"
+  "<style>html,body{margin:0;height:100%;font-family:system-ui,sans-serif;"
+  "display:flex;align-items:center;justify-content:center;background:#0f172a;color:#e2e8f0}"
+  ".c{max-width:34rem;padding:2rem;text-align:center}h1{font-size:1.5rem;margin:.2rem 0}"
+  "code{background:#1e293b;padding:.15rem .4rem;border-radius:.3rem;color:#93c5fd}"
+  "p{color:#94a3b8;line-height:1.5}</style></head><body><div class='c'>"
+  "<h1>\xE2\x9B\xB5 Hull</h1>"
+  "<p>No app was provided. Run <code>hull dev</code> during development, "
+  "or <code>hull build</code> to package your UI.</p></div></body></html>";
+
+void register_all(Dispatcher& d, const Options& opt) {
+  d.on("ping", [](const json& a, Reply reply) {
+    reply(json{{"ok", true}, {"echo", a.empty() ? json(nullptr) : a.at(0)}});
+  });
+  d.on("appInfo", [opt](const json&, Reply reply) {
+    reply(json{{"ok", true}, {"appId", opt.appId}, {"secure", secure::active()}});
+  });
+  register_http_bindings(d);
+  register_printer_bindings(d);
+  register_storage_bindings(d);
+  register_credentials_bindings(d);
+  register_database_bindings(d);
+  register_files_bindings(d);
+}
+
+} // namespace
+
+#ifdef _WIN32
+int WINAPI WinMain(HINSTANCE, HINSTANCE, LPSTR, int) {
+  int argc = __argc;
+  char** argv = __argv;
+#else
+int main(int argc, char** argv) {
+#endif
+  Options opt = parse_args(argc, argv);
+  storage::set_app_name(opt.appId);
+
+  Dispatcher d;
+  if (opt.inspect) d.set_trace(true);
+  register_all(d, opt);
+
+  // ---- Serve mode: headless HTTP/SSE bridge (browser dev mode) ----
+  if (opt.serve_port) {
+    try {
+      BridgeServer server(d);
+      d.set_emit_sink([&server](const std::string& e, const json& p) { server.broadcast(e, p); });
+      server.listen("127.0.0.1", *opt.serve_port); // blocks
+    } catch (const std::exception& e) {
+      std::cerr << e.what() << '\n';
+      return 1;
+    }
+    return 0;
+  }
+
+  // ---- Window mode: render in the OS web view ----
+  try {
+#if defined(__linux__)
+    maybe_disable_webkit_sandbox();   // before any GTK/WebKit init (fork is safe here)
+    if (opt.icon) install_desktop_integration(opt.appId, opt.title, *opt.icon);
+#endif
+    webview::webview window(opt.debug, nullptr);
+    window.set_title(opt.title);
+    window.set_size(opt.width, opt.height, WEBVIEW_HINT_NONE);
+    if (opt.icon) set_window_icon(window, *opt.icon);
+
+    // Optional trace server: lets the inspector (a browser tab) observe this native
+    // app's bridge activity. Leaked intentionally — lives for the whole process.
+    BridgeServer* trace = opt.inspect_port ? new BridgeServer(d) : nullptr;
+
+    // emit -> push into the page; also mirror to the inspector trace server if on.
+    d.set_emit_sink([&window, trace](const std::string& event, const json& payload) {
+      const std::string js =
+          "if(window.__bridgeEmit){window.__bridgeEmit(" +
+          json(event).dump() + "," + json(payload.dump()).dump() + ");}";
+      window.dispatch([&window, js] { window.eval(js); });
+      if (trace) trace->broadcast(event, payload);
+    });
+
+    if (trace) {
+      const int port = *opt.inspect_port;
+      std::thread([trace, port] { trace->listen("127.0.0.1", port); }).detach();
+    }
+
+    // bind every dispatcher handler onto window.<name>
+    for (const auto& name : d.names()) {
+      window.bind(
+          name,
+          [&d, &window, name](const std::string& id, const std::string& args_str, void*) {
+            json args;
+            try { args = json::parse(args_str); } catch (...) { args = json::array(); }
+            d.invoke(name, args, [&window, id](const json& res) {
+              window.resolve(id, 0, res.dump());
+            });
+          },
+          nullptr);
+    }
+
+    if (opt.url) {
+      window.navigate(*opt.url);
+    } else if (opt.app) {
+#if defined(__linux__)
+      // Load by file:// URL so module scripts run (set_html's null base blocks them
+      // on WebKitGTK). Fall back to set_html only if the file is missing.
+      if (std::filesystem::exists(*opt.app)) window.navigate(file_uri(*opt.app));
+      else window.set_html(FALLBACK_HTML);
+#else
+      if (auto html = read_file(*opt.app)) window.set_html(*html);
+      else window.set_html(FALLBACK_HTML);
+#endif
+    } else {
+      window.set_html(FALLBACK_HTML);
+    }
+
+    window.run();
+  } catch (const webview::exception& e) {
+    std::cerr << e.what() << '\n';
+    return 1;
+  }
+  return 0;
+}

package/host/src/paths.hpp

@@ -0,0 +1,62 @@
+#pragma once
+// App identity + per-user storage location. Deliberately free of webview/OpenSSL so
+// it can be shared by storage.hpp (encryption) and db_core.hpp (SQLite), and unit-
+// tested standalone.
+#include <string>
+#include <filesystem>
+#include <system_error>
+#include <cstdlib>
+
+namespace fs = std::filesystem;
+
+namespace storage {
+
+// App identity: namespaces the per-user data dir AND the keychain entries so two
+// Hull apps never clash. Set once at startup from --app-id (see host main.cpp).
+inline std::string& app_name() {
+  static std::string n = "Hull";
+  return n;
+}
+inline void set_app_name(const std::string& n) {
+  if (!n.empty()) app_name() = n;
+}
+
+// ---- Resolve and create the per-user data directory ----
+inline fs::path app_data_dir() {
+  fs::path base;
+#if defined(_WIN32)
+  if (const char* p = std::getenv("LOCALAPPDATA")) base = p;
+  else base = fs::temp_directory_path();
+#elif defined(__APPLE__)
+  base = fs::path(std::getenv("HOME") ? std::getenv("HOME") : ".")
+       / "Library" / "Application Support";
+#else
+  if (const char* x = std::getenv("XDG_DATA_HOME")) base = x;
+  else base = fs::path(std::getenv("HOME") ? std::getenv("HOME") : ".") / ".local" / "share";
+#endif
+  fs::path dir = base / app_name();
+  fs::create_directories(dir);
+#if !defined(_WIN32)
+  // Owner-only directory (0700). On Windows, %LOCALAPPDATA% is already per-user.
+  fs::permissions(dir, fs::perms::owner_all, fs::perm_options::replace);
+#endif
+  return dir;
+}
+
+// ---- Restrict a path to the owner (POSIX). Files -> 0600; directories -> 0700,
+// because a directory needs the execute (search) bit to create/rename/read entries
+// inside it (without it, writes into the dir fail with EACCES). ----
+inline void lock_down(const fs::path& p) {
+#if !defined(_WIN32)
+  std::error_code ec;
+  if (fs::exists(p, ec)) {
+    const fs::perms perms = fs::is_directory(p, ec)
+        ? fs::perms::owner_all                                  // 0700 (rwx) for dirs
+        : (fs::perms::owner_read | fs::perms::owner_write);     // 0600 (rw-) for files
+    fs::permissions(p, perms, fs::perm_options::replace, ec);
+  }
+#endif
+  (void)p;
+}
+
+} // namespace storage

package/host/src/secure.hpp

@@ -0,0 +1,124 @@
+#pragma once
+// Pluggable at-rest crypto layer for files + settings (the DB uses SQLCipher under
+// the same flag — see db_core.hpp). Nothing else in the codebase calls crypto
+// directly; everything goes through secure::encrypt / secure::decrypt.
+//
+//   Default build         -> NullCipher: passthrough, ZERO crypto cost (fast).
+//   -DHULL_CRYPTO=ON      -> AES-256-GCM with a per-install key in the OS keychain.
+//
+// The on-disk blob is self-describing, so a secure build can still read old
+// plaintext data, and a default build fails loudly on encrypted data:
+//   byte 0 = 0x00  -> plaintext follows
+//   byte 0 = 0x01  -> AES-256-GCM: [12-byte IV][16-byte tag][ciphertext]
+#include <string>
+#include <optional>
+#include <stdexcept>
+
+namespace secure {
+
+inline constexpr unsigned char TAG_PLAIN = 0x00;
+inline constexpr unsigned char TAG_AES = 0x01;
+
+// true when real crypto is compiled in (the "secure" host build).
+constexpr bool active() {
+#if defined(HULL_CRYPTO)
+  return true;
+#else
+  return false;
+#endif
+}
+
+#if defined(HULL_CRYPTO)
+// ============================ AES-256-GCM backend ============================
+} // namespace secure
+#include <vector>
+#include "paths.hpp"      // storage::app_name (namespaces the key)
+#include "keychain.hpp"   // secrets:: (per-install key in the OS keychain)
+#include <openssl/evp.h>
+#include <openssl/rand.h>
+namespace secure {
+
+inline std::vector<unsigned char> data_key() {
+  // One random 32-byte key per install, stored in the keychain (namespaced by app).
+  if (auto k = secrets::load(storage::app_name(), "secure-key")) {
+    return std::vector<unsigned char>(k->begin(), k->end());
+  }
+  std::vector<unsigned char> key(32);
+  RAND_bytes(key.data(), (int)key.size());
+  secrets::store(storage::app_name(), "secure-key", std::string(key.begin(), key.end()));
+  return key;
+}
+
+inline std::string encrypt(const std::string& plain) {
+  auto key = data_key();
+  std::vector<unsigned char> iv(12), tag(16), ct(plain.size() + 16);
+  RAND_bytes(iv.data(), (int)iv.size());
+
+  EVP_CIPHER_CTX* ctx = EVP_CIPHER_CTX_new();
+  int len = 0, ct_len = 0;
+  EVP_EncryptInit_ex(ctx, EVP_aes_256_gcm(), nullptr, nullptr, nullptr);
+  EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, (int)iv.size(), nullptr);
+  EVP_EncryptInit_ex(ctx, nullptr, nullptr, key.data(), iv.data());
+  EVP_EncryptUpdate(ctx, ct.data(), &len,
+                    reinterpret_cast<const unsigned char*>(plain.data()), (int)plain.size());
+  ct_len = len;
+  EVP_EncryptFinal_ex(ctx, ct.data() + len, &len);
+  ct_len += len;
+  EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_GET_TAG, (int)tag.size(), tag.data());
+  EVP_CIPHER_CTX_free(ctx);
+
+  std::string out;
+  out.push_back((char)TAG_AES);
+  out.append(reinterpret_cast<char*>(iv.data()), iv.size());
+  out.append(reinterpret_cast<char*>(tag.data()), tag.size());
+  out.append(reinterpret_cast<char*>(ct.data()), ct_len);
+  return out;
+}
+
+inline std::optional<std::string> decrypt(const std::string& blob) {
+  if (blob.empty()) return std::string();
+  unsigned char tag0 = (unsigned char)blob[0];
+  if (tag0 == TAG_PLAIN) return blob.substr(1);     // read legacy/plaintext too
+  if (tag0 != TAG_AES || blob.size() < 1 + 12 + 16) return std::nullopt;
+  auto key = data_key();
+  const unsigned char* iv = reinterpret_cast<const unsigned char*>(blob.data() + 1);
+  const unsigned char* tag = iv + 12;
+  const unsigned char* ct = tag + 16;
+  int ct_len = (int)blob.size() - 1 - 12 - 16;
+
+  std::string out(ct_len, '\0');
+  EVP_CIPHER_CTX* ctx = EVP_CIPHER_CTX_new();
+  int len = 0, out_len = 0;
+  EVP_DecryptInit_ex(ctx, EVP_aes_256_gcm(), nullptr, nullptr, nullptr);
+  EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, 12, nullptr);
+  EVP_DecryptInit_ex(ctx, nullptr, nullptr, key.data(), iv);
+  EVP_DecryptUpdate(ctx, reinterpret_cast<unsigned char*>(&out[0]), &len, ct, ct_len);
+  out_len = len;
+  EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_TAG, 16, const_cast<unsigned char*>(tag));
+  int ok = EVP_DecryptFinal_ex(ctx, reinterpret_cast<unsigned char*>(&out[0]) + len, &len);
+  EVP_CIPHER_CTX_free(ctx);
+  if (ok <= 0) return std::nullopt; // tag mismatch -> tampered or wrong key
+  out.resize(out_len + len);
+  return out;
+}
+
+#else
+// ============================ NullCipher (default) ============================
+inline std::string encrypt(const std::string& plain) {
+  std::string out;
+  out.reserve(plain.size() + 1);
+  out.push_back((char)TAG_PLAIN);
+  out += plain;
+  return out;
+}
+
+inline std::optional<std::string> decrypt(const std::string& blob) {
+  if (blob.empty()) return std::string();
+  unsigned char tag0 = (unsigned char)blob[0];
+  if (tag0 == TAG_PLAIN) return blob.substr(1);
+  throw std::runtime_error(
+      "data is encrypted — rebuild the host with -DHULL_CRYPTO=ON (secure build)");
+}
+#endif
+
+} // namespace secure

package/host/src/serve.hpp

@@ -0,0 +1,113 @@
+#pragma once
+// Browser dev-mode transport: exposes the dispatcher over HTTP (UI -> C++) and SSE
+// (C++ -> UI). Reuses cpp-httplib (already linked) — no new dependency. Dev only.
+//
+//   POST /bridge/invoke   { name, args } -> result json
+//   GET  /bridge/events   text/event-stream of { event, payload } (incl. __trace)
+#include <httplib.h>   // before any webview/GTK/X11 headers
+#include <string>
+#include <memory>
+#include <mutex>
+#include <deque>
+#include <set>
+#include <optional>
+#include <future>
+#include <condition_variable>
+#include <atomic>
+#include <chrono>
+#include <nlohmann/json.hpp>
+#include "dispatcher.hpp"
+
+using json = nlohmann::json;
+
+// One connected Server-Sent-Events client: a thread-safe frame queue.
+class SseClient {
+public:
+  void push(const std::string& frame) {
+    { std::lock_guard<std::mutex> lk(m_); q_.push_back(frame); }
+    cv_.notify_one();
+  }
+  void close() { closed_ = true; cv_.notify_all(); }
+  // next frame, or "" on timeout (write a keepalive), or nullopt when closed.
+  std::optional<std::string> pop(int timeout_ms) {
+    std::unique_lock<std::mutex> lk(m_);
+    if (cv_.wait_for(lk, std::chrono::milliseconds(timeout_ms),
+                     [&] { return !q_.empty() || closed_; })) {
+      if (q_.empty()) return std::nullopt; // closed
+      std::string f = q_.front(); q_.pop_front();
+      return f;
+    }
+    return std::string(); // timeout -> keepalive
+  }
+private:
+  std::mutex m_;
+  std::condition_variable cv_;
+  std::deque<std::string> q_;
+  std::atomic<bool> closed_{false};
+};
+
+class BridgeServer {
+public:
+  explicit BridgeServer(Dispatcher& d) : d_(d) {}
+
+  // Push an event/trace frame to every connected SSE client (thread-safe).
+  void broadcast(const std::string& event, const json& payload) {
+    const std::string frame =
+        "data: " + json{{"event", event}, {"payload", payload}}.dump() + "\n\n";
+    std::lock_guard<std::mutex> lk(cm_);
+    for (auto& c : clients_) c->push(frame);
+  }
+
+  void listen(const std::string& host, int port) {
+    httplib::Server svr;
+
+    // CORS (dev only) — the browser runs at the Vite origin, the host at another port.
+    svr.set_post_routing_handler([](const httplib::Request&, httplib::Response& res) {
+      res.set_header("Access-Control-Allow-Origin", "*");
+      res.set_header("Access-Control-Allow-Headers", "Content-Type");
+    });
+    svr.Options(R"(.*)", [](const httplib::Request&, httplib::Response& res) { res.status = 204; });
+
+    svr.Get("/health", [](const httplib::Request&, httplib::Response& res) {
+      res.set_content("ok", "text/plain");
+    });
+
+    // UI -> C++
+    svr.Post("/bridge/invoke", [this](const httplib::Request& req, httplib::Response& res) {
+      json body;
+      try { body = json::parse(req.body); }
+      catch (...) { res.status = 400; res.set_content(R"({"ok":false,"error":"bad json"})", "application/json"); return; }
+      const std::string name = body.value("name", std::string());
+      const json args = body.contains("args") ? body["args"] : json::array();
+      std::promise<json> p;
+      auto fut = p.get_future();
+      d_.invoke(name, args, [&p](const json& result) { p.set_value(result); });
+      res.set_content(fut.get().dump(), "application/json"); // blocks until the handler replies
+    });
+
+    // C++ -> UI (events + dev trace)
+    svr.Get("/bridge/events", [this](const httplib::Request&, httplib::Response& res) {
+      auto client = std::make_shared<SseClient>();
+      { std::lock_guard<std::mutex> lk(cm_); clients_.insert(client); }
+      res.set_chunked_content_provider(
+          "text/event-stream",
+          [client](size_t, httplib::DataSink& sink) {
+            auto f = client->pop(15000);
+            if (!f) return false; // closed
+            const std::string frame = f->empty() ? std::string(": keepalive\n\n") : *f;
+            return sink.write(frame.data(), frame.size());
+          },
+          [this, client](bool) {
+            std::lock_guard<std::mutex> lk(cm_);
+            clients_.erase(client);
+          });
+    });
+
+    svr.listen(host.c_str(), port);
+  }
+
+private:
+  Dispatcher& d_;
+  std::mutex cm_;
+  std::set<std::shared_ptr<SseClient>> clients_;
+};