@mwguerra/hull 0.1.0

package/host/src/bindings/http.hpp

@@ -0,0 +1,84 @@
+#pragma once
+// IMPORTANT: httplib before any webview/GTK/X11 headers (Linux macro clash).
+#include <httplib.h>
+
+#include <thread>
+#include <string>
+#include <utility>
+#include <nlohmann/json.hpp>
+#include "dispatcher.hpp"
+#include "keychain.hpp"
+
+using json = nlohmann::json;
+
+// Split a full URL into base ("https://host:port") and path ("/a/b?x=1").
+inline std::pair<std::string, std::string> split_url(const std::string& url) {
+  auto scheme = url.find("://");
+  auto slash = url.find('/', scheme == std::string::npos ? 0 : scheme + 3);
+  if (slash == std::string::npos) return {url, "/"};
+  return {url.substr(0, slash), url.substr(slash)};
+}
+
+inline std::string host_of(const std::string& base) {
+  auto scheme = base.find("://");
+  std::string rest = scheme == std::string::npos ? base : base.substr(scheme + 3);
+  auto colon = rest.find(':');
+  return colon == std::string::npos ? rest : rest.substr(0, colon);
+}
+
+inline void register_http_bindings(Dispatcher& d) {
+  // httpPost(url, body) -> { ok, status, body }
+  d.on("httpPost", [](const json& a, Reply reply) {
+    std::thread([a, reply]() {
+      json out;
+      try {
+        const std::string url = a.at(0).get<std::string>();
+        const json payload = a.at(1);
+        auto [base, path] = split_url(url);
+        httplib::Client cli(base);
+        cli.set_connection_timeout(5);
+        cli.set_read_timeout(15);
+        cli.enable_server_certificate_verification(true);
+        httplib::Headers headers = {{"Accept", "application/json"}};
+        if (auto token = secrets::load(host_of(base), "default"))
+          headers.emplace("Authorization", "Bearer " + *token);
+        auto res = cli.Post(path.c_str(), headers, payload.dump(), "application/json");
+        if (!res) {
+          out = {{"ok", false}, {"error", httplib::to_string(res.error())}};
+        } else {
+          json body;
+          try { body = json::parse(res->body); } catch (...) { body = res->body; }
+          out = {{"ok", res->status >= 200 && res->status < 300}, {"status", res->status}, {"body", body}};
+        }
+      } catch (const std::exception& e) { out = {{"ok", false}, {"error", e.what()}}; }
+      reply(out);
+    }).detach();
+  });
+
+  // httpGet(url) -> { ok, status, body }
+  d.on("httpGet", [](const json& a, Reply reply) {
+    std::thread([a, reply]() {
+      json out;
+      try {
+        const std::string url = a.at(0).get<std::string>();
+        auto [base, path] = split_url(url);
+        httplib::Client cli(base);
+        cli.set_connection_timeout(5);
+        cli.set_read_timeout(15);
+        cli.enable_server_certificate_verification(true);
+        httplib::Headers headers = {{"Accept", "application/json"}};
+        if (auto token = secrets::load(host_of(base), "default"))
+          headers.emplace("Authorization", "Bearer " + *token);
+        auto res = cli.Get(path.c_str(), headers);
+        if (!res) {
+          out = {{"ok", false}, {"error", httplib::to_string(res.error())}};
+        } else {
+          json body;
+          try { body = json::parse(res->body); } catch (...) { body = res->body; }
+          out = {{"ok", res->status >= 200 && res->status < 300}, {"status", res->status}, {"body", body}};
+        }
+      } catch (const std::exception& e) { out = {{"ok", false}, {"error", e.what()}}; }
+      reply(out);
+    }).detach();
+  });
+}

package/host/src/bindings/printer.hpp

@@ -0,0 +1,281 @@
+#pragma once
+#include <string>
+#include <vector>
+#include <thread>
+#include <nlohmann/json.hpp>
+#include "dispatcher.hpp"
+
+using json = nlohmann::json;
+
+namespace printing {
+
+struct Printer { std::string name; bool is_default = false; };
+
+std::vector<Printer> list();
+bool print_raw(const std::string& printer, const std::string& job_name,
+               const std::string& bytes);
+// Render plain text as a normal print job (GDI on Windows; text/plain via CUPS on
+// macOS/Linux) so it works with ANY printer — Microsoft Print to PDF, OneNote, and
+// physical laser printers — not just ESC/POS thermal printers. Single page, word-wrapped.
+bool print_text(const std::string& printer, const std::string& job_name,
+                const std::string& text);
+
+// Build a minimal ESC/POS receipt: init, text lines, feed, full cut.
+inline std::string escpos_message(const std::string& text) {
+  std::string out;
+  out += "\x1B\x40";          // ESC @  -> initialize
+  out += text;
+  out += "\n\n\n\n";          // feed
+  out += "\x1D\x56\x00";      // GS V 0 -> full cut
+  return out;
+}
+
+// ----------------------------- Windows -----------------------------
+#if defined(_WIN32)
+} // namespace printing
+#include <windows.h>
+#include <winspool.h>
+namespace printing {
+
+inline std::wstring utf8_to_wide(const std::string& s) {
+  if (s.empty()) return std::wstring();
+  int n = MultiByteToWideChar(CP_UTF8, 0, s.data(), (int)s.size(), nullptr, 0);
+  std::wstring w(n, L'\0');
+  MultiByteToWideChar(CP_UTF8, 0, s.data(), (int)s.size(), &w[0], n);
+  return w;
+}
+
+inline std::vector<Printer> list() {
+  std::vector<Printer> result;
+  DWORD needed = 0, returned = 0;
+  EnumPrintersW(PRINTER_ENUM_LOCAL | PRINTER_ENUM_CONNECTIONS, nullptr, 4,
+                nullptr, 0, &needed, &returned);
+  if (needed == 0) return result;
+  std::vector<BYTE> buf(needed);
+  if (EnumPrintersW(PRINTER_ENUM_LOCAL | PRINTER_ENUM_CONNECTIONS, nullptr, 4,
+                    buf.data(), needed, &needed, &returned)) {
+    auto* info = reinterpret_cast<PRINTER_INFO_4W*>(buf.data());
+    for (DWORD i = 0; i < returned; ++i) {
+      std::wstring w(info[i].pPrinterName);
+      result.push_back({std::string(w.begin(), w.end()), false});
+    }
+  }
+  // Mark the default printer.
+  wchar_t def[256]; DWORD n = 256;
+  if (GetDefaultPrinterW(def, &n)) {
+    std::wstring w(def); std::string d(w.begin(), w.end());
+    for (auto& p : result) if (p.name == d) p.is_default = true;
+  }
+  return result;
+}
+
+inline bool print_raw(const std::string& printer, const std::string& job_name,
+                      const std::string& bytes) {
+  std::wstring wprinter = utf8_to_wide(printer);
+  HANDLE h = nullptr;
+  if (!OpenPrinterW(const_cast<LPWSTR>(wprinter.c_str()), &h, nullptr)) return false;
+
+  std::wstring wjob = utf8_to_wide(job_name);
+  DOC_INFO_1W di{};
+  di.pDocName = const_cast<LPWSTR>(wjob.c_str());
+  di.pDatatype = const_cast<LPWSTR>(L"RAW");  // send bytes verbatim (ESC/POS or plain text)
+
+  bool ok = false;
+  if (StartDocPrinterW(h, 1, reinterpret_cast<LPBYTE>(&di))) {
+    if (StartPagePrinter(h)) {
+      DWORD written = 0;
+      ok = WritePrinter(h, const_cast<char*>(bytes.data()),
+                        (DWORD)bytes.size(), &written) && written == bytes.size();
+      EndPagePrinter(h);
+    }
+    EndDocPrinter(h);
+  }
+  ClosePrinter(h);
+  return ok;
+}
+
+inline bool print_text(const std::string& printer, const std::string& job_name,
+                       const std::string& text) {
+  const std::wstring wprinter = utf8_to_wide(printer);
+  const std::wstring wjob = utf8_to_wide(job_name);
+  const std::wstring wtext = utf8_to_wide(text);
+  // GDI device context for the printer driver -> a real, rendered job (PDF/OneNote/laser).
+  HDC dc = CreateDCW(L"WINSPOOL", wprinter.c_str(), nullptr, nullptr);
+  if (!dc) return false;
+  bool ok = false;
+  DOCINFOW di{}; di.cbSize = sizeof(di); di.lpszDocName = wjob.c_str();
+  if (StartDocW(dc, &di) > 0) {
+    if (StartPage(dc) > 0) {
+      const int dpiX = GetDeviceCaps(dc, LOGPIXELSX);
+      const int dpiY = GetDeviceCaps(dc, LOGPIXELSY);
+      HFONT font = CreateFontW(-MulDiv(11, dpiY, 72), 0, 0, 0, FW_NORMAL, FALSE, FALSE,
+                               FALSE, DEFAULT_CHARSET, OUT_DEFAULT_PRECIS,
+                               CLIP_DEFAULT_PRECIS, DEFAULT_QUALITY,
+                               DEFAULT_PITCH | FF_DONTCARE, L"Segoe UI");
+      HGDIOBJ oldFont = font ? SelectObject(dc, font) : nullptr;
+      RECT r{ dpiX / 2, dpiY / 2,                                  // ~0.5" margins
+              GetDeviceCaps(dc, HORZRES) - dpiX / 2,
+              GetDeviceCaps(dc, VERTRES) - dpiY / 2 };
+      DrawTextW(dc, wtext.c_str(), -1, &r,
+                DT_LEFT | DT_TOP | DT_WORDBREAK | DT_NOPREFIX | DT_EXPANDTABS);
+      if (oldFont) SelectObject(dc, oldFont);
+      if (font) DeleteObject(font);
+      ok = (EndPage(dc) > 0);
+    }
+    EndDoc(dc);
+  }
+  DeleteDC(dc);
+  return ok;
+}
+
+// ----------------------------- macOS / Linux (CUPS) -----------------------------
+#else
+} // namespace printing
+#include <cups/cups.h>
+namespace printing {
+
+inline std::vector<Printer> list() {
+  std::vector<Printer> result;
+  cups_dest_t* dests = nullptr;
+  int n = cupsGetDests(&dests);
+  for (int i = 0; i < n; ++i) {
+    result.push_back({dests[i].name ? dests[i].name : "",
+                      dests[i].is_default != 0});
+  }
+  cupsFreeDests(n, dests);
+  return result;
+}
+
+inline bool print_raw(const std::string& printer, const std::string& job_name,
+                      const std::string& bytes) {
+  int job = cupsCreateJob(CUPS_HTTP_DEFAULT, printer.c_str(), job_name.c_str(),
+                          0, nullptr);
+  if (job == 0) return false;
+  if (cupsStartDocument(CUPS_HTTP_DEFAULT, printer.c_str(), job, job_name.c_str(),
+                        CUPS_FORMAT_RAW, 1) != HTTP_STATUS_CONTINUE)
+    return false;
+  cupsWriteRequestData(CUPS_HTTP_DEFAULT, bytes.data(), bytes.size());
+  return cupsFinishDocument(CUPS_HTTP_DEFAULT, printer.c_str()) == IPP_STATUS_OK;
+}
+
+inline bool print_text(const std::string& printer, const std::string& job_name,
+                       const std::string& text) {
+  int job = cupsCreateJob(CUPS_HTTP_DEFAULT, printer.c_str(), job_name.c_str(), 0, nullptr);
+  if (job == 0) return false;
+  // CUPS_FORMAT_TEXT ("text/plain") -> CUPS renders via its text filter (any printer).
+  if (cupsStartDocument(CUPS_HTTP_DEFAULT, printer.c_str(), job, job_name.c_str(),
+                        CUPS_FORMAT_TEXT, 1) != HTTP_STATUS_CONTINUE)
+    return false;
+  cupsWriteRequestData(CUPS_HTTP_DEFAULT, text.data(), text.size());
+  return cupsFinishDocument(CUPS_HTTP_DEFAULT, printer.c_str()) == IPP_STATUS_OK;
+}
+#endif
+
+} // namespace printing
+
+// ---- Portable raw-TCP sender (e.g. ESC/POS to a network printer on port 9100) ----
+#if defined(_WIN32)
+  #include <winsock2.h>
+  #include <ws2tcpip.h>
+#else
+  #include <sys/socket.h>
+  #include <netdb.h>
+  #include <unistd.h>
+#endif
+
+inline bool print_to_socket(const std::string& host, int port, const std::string& bytes) {
+#if defined(_WIN32)
+  WSADATA wsa;
+  if (WSAStartup(MAKEWORD(2, 2), &wsa) != 0) return false;
+#endif
+  bool ok = false;
+  addrinfo hints{};
+  hints.ai_family = AF_UNSPEC;        // IPv4 or IPv6
+  hints.ai_socktype = SOCK_STREAM;
+  addrinfo* res = nullptr;
+  if (getaddrinfo(host.c_str(), std::to_string(port).c_str(), &hints, &res) == 0) {
+    for (addrinfo* p = res; p; p = p->ai_next) {
+#if defined(_WIN32)
+      SOCKET fd = socket(p->ai_family, p->ai_socktype, p->ai_protocol);
+      if (fd == INVALID_SOCKET) continue;
+#else
+      int fd = ::socket(p->ai_family, p->ai_socktype, p->ai_protocol);
+      if (fd < 0) continue;
+#endif
+      if (connect(fd, p->ai_addr, (int)p->ai_addrlen) == 0) {
+        ok = true;
+        size_t sent = 0;
+        while (sent < bytes.size()) {
+          int n = (int)send(fd, bytes.data() + sent, (int)(bytes.size() - sent), 0);
+          if (n <= 0) { ok = false; break; }
+          sent += (size_t)n;
+        }
+      }
+#if defined(_WIN32)
+      closesocket(fd);
+#else
+      ::close(fd);
+#endif
+      if (ok) break;
+    }
+    freeaddrinfo(res);
+  }
+#if defined(_WIN32)
+  WSACleanup();
+#endif
+  return ok;
+}
+
+// ---- Bindings ----
+inline void register_printer_bindings(Dispatcher& d) {
+  // listPrinters() -> { ok, printers: [{name, isDefault}] }
+  d.on("listPrinters", [](const json&, Reply reply) {
+    json arr = json::array();
+    for (const auto& p : printing::list())
+      arr.push_back({{"name", p.name}, {"isDefault", p.is_default}});
+    reply(json{{"ok", true}, {"printers", arr}});
+  });
+
+  // printMessage(printer, text) -> { ok }
+  // Prints `text` as a normal text document, so it works with ANY printer (Microsoft
+  // Print to PDF, OneNote, physical laser printers). For ESC/POS thermal receipt
+  // printers use printReceipt / printNetwork instead.
+  d.on("printMessage", [](const json& a, Reply reply) {
+    std::thread([a, reply]() {
+      json out;
+      try {
+        bool ok = printing::print_text(a.at(0).get<std::string>(), "App message",
+                                       a.at(1).get<std::string>());
+        out = {{"ok", ok}};
+      } catch (const std::exception& e) { out = {{"ok", false}, {"error", e.what()}}; }
+      reply(out);
+    }).detach();
+  });
+
+  // printReceipt(printer, text) -> { ok }
+  // Raw ESC/POS to a local (spooler) thermal/receipt printer: init, text, feed, cut.
+  d.on("printReceipt", [](const json& a, Reply reply) {
+    std::thread([a, reply]() {
+      json out;
+      try {
+        bool ok = printing::print_raw(a.at(0).get<std::string>(), "App receipt",
+                                      printing::escpos_message(a.at(1).get<std::string>()));
+        out = {{"ok", ok}};
+      } catch (const std::exception& e) { out = {{"ok", false}, {"error", e.what()}}; }
+      reply(out);
+    }).detach();
+  });
+
+  // printNetwork(host, port, text) -> { ok }
+  d.on("printNetwork", [](const json& a, Reply reply) {
+    std::thread([a, reply]() {
+      json out;
+      try {
+        bool ok = print_to_socket(a.at(0).get<std::string>(), a.at(1).get<int>(),
+                                  printing::escpos_message(a.at(2).get<std::string>()));
+        out = {{"ok", ok}};
+      } catch (const std::exception& e) { out = {{"ok", false}, {"error", e.what()}}; }
+      reply(out);
+    }).detach();
+  });
+}

package/host/src/bindings/storage.hpp

@@ -0,0 +1,71 @@
+#pragma once
+#include <string>
+#include <fstream>
+#include <sstream>
+#include <optional>
+#include <filesystem>
+#include <nlohmann/json.hpp>
+#include "dispatcher.hpp"
+#include "paths.hpp"    // storage::app_data_dir / lock_down
+#include "secure.hpp"   // at-rest crypto layer (NullCipher by default)
+
+namespace fs = std::filesystem;
+using json = nlohmann::json;
+
+namespace storage {
+
+// ---- Key/value settings store (passed through the secure layer at rest) ----
+inline fs::path settings_path() { return app_data_dir() / "settings.dat"; }
+
+inline json read_settings() {
+  std::ifstream f(settings_path(), std::ios::binary);
+  if (!f) return json::object();
+  std::string blob((std::istreambuf_iterator<char>(f)), std::istreambuf_iterator<char>());
+  if (blob.empty()) return json::object();
+  try {
+    auto plain = secure::decrypt(blob);
+    if (!plain) return json::object();
+    return json::parse(*plain);
+  } catch (...) {
+    return json::object();
+  }
+}
+
+inline void write_settings(const json& j) {
+  const std::string blob = secure::encrypt(j.dump());
+  fs::path tmp = settings_path();
+  tmp += ".tmp";
+  { std::ofstream f(tmp, std::ios::binary | std::ios::trunc);
+    f.write(blob.data(), (std::streamsize)blob.size()); }
+  fs::rename(tmp, settings_path()); // atomic replace
+  lock_down(settings_path());
+}
+
+} // namespace storage
+
+inline void register_storage_bindings(Dispatcher& d) {
+  d.on("saveSetting", [&d](const json& a, Reply reply) {
+    try {
+      auto key = a.at(0).get<std::string>();
+      json s = storage::read_settings();
+      s[key] = a.at(1);
+      storage::write_settings(s);
+      d.emit("settings:changed", {{"key", key}, {"value", a.at(1)}});  // C++ -> UI
+      reply(json{{"ok", true}});
+    } catch (const std::exception& e) { reply(json{{"ok", false}, {"error", e.what()}}); }
+  });
+
+  d.on("loadSetting", [](const json& a, Reply reply) {
+    try {
+      json s = storage::read_settings();
+      auto key = a.at(0).get<std::string>();
+      reply(json{{"ok", true}, {"value", s.contains(key) ? s[key] : json(nullptr)}});
+    } catch (const std::exception& e) { reply(json{{"ok", false}, {"error", e.what()}}); }
+  });
+
+  d.on("loadAllSettings", [](const json&, Reply reply) {
+    try {
+      reply(json{{"ok", true}, {"value", storage::read_settings()}});
+    } catch (const std::exception& e) { reply(json{{"ok", false}, {"error", e.what()}}); }
+  });
+}

package/host/src/db_core.hpp

@@ -0,0 +1,198 @@
+#pragma once
+// SQLite core for Hull: a small, safe, parameterized SQL surface returning JSON.
+// Webview-free on purpose (only paths.hpp + sqlite3 + json) so it can be unit-tested
+// standalone and reused by the bridge bindings (database.hpp).
+//
+// Security/speed posture:
+//  - one statement per exec/query/get (prepare_v2 ignores trailing SQL) -> no stacked
+//    "...; DROP TABLE" injection; multi-statement only via batch([...]) arrays
+//  - parameters are bound, never concatenated (sqlite3_bind_*)
+//  - DB lives in the per-user app dir, chmod 0600 on POSIX
+//  - WAL + NORMAL sync + busy_timeout for speed; foreign_keys + trusted_schema=OFF
+#include <string>
+#include <mutex>
+#include <stdexcept>
+#include <cstdint>
+#include <nlohmann/json.hpp>
+#include "paths.hpp"
+#include "secure.hpp"   // active() + the per-install key (secure build only)
+#include "sqlite3.h"    // vendored SQLite by default; SQLCipher's header in the secure build
+
+using json = nlohmann::json;
+
+namespace hulldb {
+
+// Optional path override (used by tests). Default: <app_data_dir>/app.db
+inline std::string& path_override() { static std::string p; return p; }
+inline void set_db_path(const std::string& p) { path_override() = p; }
+
+inline std::mutex& mtx() { static std::mutex m; return m; }
+
+inline std::string db_file() {
+  if (!path_override().empty()) return path_override();
+  return (storage::app_data_dir() / "app.db").string();
+}
+
+// Lazily open the single connection and apply pragmas. Caller must hold mtx().
+inline sqlite3* handle() {
+  static sqlite3* db = nullptr;
+  if (db) return db;
+  const std::string path = db_file();
+  if (sqlite3_open(path.c_str(), &db) != SQLITE_OK) {
+    std::string err = db ? sqlite3_errmsg(db) : "open failed";
+    if (db) { sqlite3_close(db); db = nullptr; }
+    throw std::runtime_error("sqlite open: " + err);
+  }
+  storage::lock_down(path); // 0600 on POSIX
+#if defined(HULL_CRYPTO)
+  // SQLCipher: set the encryption key (raw 32-byte key from the keychain, hex) as the
+  // very first operation, before any other SQL. The DB file is AES-encrypted at rest.
+  {
+    auto k = secure::data_key();
+    static const char* H = "0123456789abcdef";
+    std::string hex;
+    hex.reserve(k.size() * 2);
+    for (unsigned char c : k) { hex.push_back(H[c >> 4]); hex.push_back(H[c & 0xF]); }
+    const std::string pragma = "PRAGMA key = \"x'" + hex + "'\";";
+    sqlite3_exec(db, pragma.c_str(), nullptr, nullptr, nullptr);
+  }
+#endif
+  for (const char* p : {
+         "PRAGMA journal_mode=WAL;",
+         "PRAGMA synchronous=NORMAL;",
+         "PRAGMA foreign_keys=ON;",
+         "PRAGMA busy_timeout=5000;",
+         "PRAGMA trusted_schema=OFF;",
+       }) {
+    sqlite3_exec(db, p, nullptr, nullptr, nullptr);
+  }
+  return db;
+}
+
+inline std::string b64(const unsigned char* data, int len) {
+  static const char* T =
+      "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  std::string out;
+  out.reserve(((len + 2) / 3) * 4);
+  for (int i = 0; i < len; i += 3) {
+    int n = data[i] << 16;
+    if (i + 1 < len) n |= data[i + 1] << 8;
+    if (i + 2 < len) n |= data[i + 2];
+    out.push_back(T[(n >> 18) & 63]);
+    out.push_back(T[(n >> 12) & 63]);
+    out.push_back(i + 1 < len ? T[(n >> 6) & 63] : '=');
+    out.push_back(i + 2 < len ? T[n & 63] : '=');
+  }
+  return out;
+}
+
+inline void bind_value(sqlite3_stmt* st, int i, const json& v) {
+  if (v.is_null()) sqlite3_bind_null(st, i);
+  else if (v.is_boolean()) sqlite3_bind_int(st, i, v.get<bool>() ? 1 : 0);
+  else if (v.is_number_integer()) sqlite3_bind_int64(st, i, v.get<int64_t>());
+  else if (v.is_number_unsigned()) sqlite3_bind_int64(st, i, (int64_t)v.get<uint64_t>());
+  else if (v.is_number_float()) sqlite3_bind_double(st, i, v.get<double>());
+  else if (v.is_string()) {
+    const std::string s = v.get<std::string>();
+    sqlite3_bind_text(st, i, s.c_str(), (int)s.size(), SQLITE_TRANSIENT);
+  } else {
+    throw std::runtime_error(
+        "unsupported parameter type — use null/boolean/number/string "
+        "(JSON.stringify objects/arrays into a TEXT column)");
+  }
+}
+
+inline void bind_all(sqlite3_stmt* st, const json& params) {
+  if (params.is_null()) return;
+  if (!params.is_array()) throw std::runtime_error("params must be an array");
+  for (int i = 0; i < (int)params.size(); ++i) bind_value(st, i + 1, params[i]);
+}
+
+inline json row_to_json(sqlite3_stmt* st) {
+  json row = json::object();
+  const int cols = sqlite3_column_count(st);
+  for (int c = 0; c < cols; ++c) {
+    const char* name = sqlite3_column_name(st, c);
+    switch (sqlite3_column_type(st, c)) {
+      case SQLITE_INTEGER: row[name] = (int64_t)sqlite3_column_int64(st, c); break;
+      case SQLITE_FLOAT:   row[name] = sqlite3_column_double(st, c); break;
+      case SQLITE_TEXT:
+        row[name] = std::string(reinterpret_cast<const char*>(sqlite3_column_text(st, c)),
+                                sqlite3_column_bytes(st, c));
+        break;
+      case SQLITE_BLOB:
+        row[name] = b64(reinterpret_cast<const unsigned char*>(sqlite3_column_blob(st, c)),
+                        sqlite3_column_bytes(st, c));
+        break;
+      default: row[name] = nullptr; break; // SQLITE_NULL
+    }
+  }
+  return row;
+}
+
+// Run ONE statement (caller holds mtx). Returns { rows, changes, lastInsertRowid }.
+inline json run_one(sqlite3* db, const std::string& sql, const json& params) {
+  sqlite3_stmt* st = nullptr;
+  if (sqlite3_prepare_v2(db, sql.c_str(), -1, &st, nullptr) != SQLITE_OK) {
+    throw std::runtime_error(sqlite3_errmsg(db));
+  }
+  bind_all(st, params);
+  json rows = json::array();
+  int rc;
+  while ((rc = sqlite3_step(st)) == SQLITE_ROW) rows.push_back(row_to_json(st));
+  if (rc != SQLITE_DONE) {
+    std::string e = sqlite3_errmsg(db);
+    sqlite3_finalize(st);
+    throw std::runtime_error(e);
+  }
+  sqlite3_finalize(st);
+  return json{{"rows", rows},
+              {"changes", sqlite3_changes(db)},
+              {"lastInsertRowid", (int64_t)sqlite3_last_insert_rowid(db)}};
+}
+
+// ---- Public API (each throws std::runtime_error on failure) ----
+
+inline json exec(const std::string& sql, const json& params) {
+  std::lock_guard<std::mutex> lock(mtx());
+  json r = run_one(handle(), sql, params);
+  return json{{"ok", true}, {"changes", r["changes"]}, {"lastInsertRowid", r["lastInsertRowid"]}};
+}
+
+inline json query(const std::string& sql, const json& params) {
+  std::lock_guard<std::mutex> lock(mtx());
+  json r = run_one(handle(), sql, params);
+  return json{{"ok", true}, {"rows", r["rows"]}};
+}
+
+inline json get(const std::string& sql, const json& params) {
+  std::lock_guard<std::mutex> lock(mtx());
+  json r = run_one(handle(), sql, params);
+  return json{{"ok", true}, {"row", r["rows"].empty() ? json(nullptr) : r["rows"][0]}};
+}
+
+// Run several statements atomically (one transaction; rollback on any error).
+inline json batch(const json& statements) {
+  if (!statements.is_array()) throw std::runtime_error("batch expects an array of { sql, params }");
+  std::lock_guard<std::mutex> lock(mtx());
+  sqlite3* db = handle();
+  run_one(db, "BEGIN IMMEDIATE;", json(nullptr));
+  try {
+    json results = json::array();
+    for (const auto& s : statements) {
+      const std::string sql = s.at("sql").get<std::string>();
+      const json params = s.contains("params") ? s["params"] : json::array();
+      json r = run_one(db, sql, params);
+      results.push_back({{"changes", r["changes"]},
+                         {"lastInsertRowid", r["lastInsertRowid"]},
+                         {"rows", r["rows"]}});
+    }
+    run_one(db, "COMMIT;", json(nullptr));
+    return json{{"ok", true}, {"results", results}};
+  } catch (...) {
+    try { run_one(db, "ROLLBACK;", json(nullptr)); } catch (...) {}
+    throw;
+  }
+}
+
+} // namespace hulldb