engine: sandboxed public query — flatsql_query_sandboxed (SDN gateway loop G.5)

One read-only SELECT for UNTRUSTED callers, enforced in-engine:
- sqlite3_set_authorizer during prepare: only SELECT / functions /
  recursive CTEs / reads of record vtabs + shadow tables + unified views;
  PRAGMA, ATTACH/DETACH, all DDL/DML (incl. temp), TRANSACTION/SAVEPOINT
  and reads of control tables or sqlite_* reserved names are denied.
  CTE/subquery aliases are recognized against a schema enumeration that
  FAILS CLOSED.
- single-statement (non-whitespace prepare tail rejected),
  sqlite3_stmt_readonly + result-column checks.
- statement timeout via sqlite3_progress_handler (steady-clock deadline;
  SQLITE_OMIT_PROGRESS_CALLBACK removed from the wasm builds — with no
  handler installed the VDBE overhead is a compare per jump op).
- row/byte caps enforced in the step loop: oversized results REJECT,
  never truncate.
- two output modes through the response-artifact readout: record stream
  (all-BLOB cells -> aligned size-prefixed frames, byte-parity with
  queryRawFlatBufferStream) and JSON rows (bare array, column names
  verbatim from SQLite — schema-exact key capitalization by
  construction; blobs base64, NaN/Inf -> null).
- bypasses statement/query/raw-stream caches entirely; no-throw on both
  builds (errors latch with a stable 'sandbox: <code>: ...' prefix).

JS wrappers querySandboxed() on both hosts (emscripten index.js +
standalone.js) with .d.ts; jest suite test/sandbox-query.test.ts covers
the injection/abuse matrix on both hosts (150/150 green). v1.2.0.

Co-Authored-By: Claude Fable 5 <[email protected]>

Author: TJKoury

cpp/CMakeLists.txt

@@ -141,7 +141,6 @@ if(CMAKE_SYSTEM_NAME STREQUAL "Emscripten" OR EMSCRIPTEN)
         SQLITE_OMIT_WAL=1
         SQLITE_OMIT_DEPRECATED=1
         SQLITE_OMIT_SHARED_CACHE=1
-        SQLITE_OMIT_PROGRESS_CALLBACK=1
         SQLITE_DEFAULT_MEMSTATUS=0
         SQLITE_DQS=0
         SQLITE_ENABLE_RTREE=1
@@ -178,6 +177,7 @@ if(CMAKE_SYSTEM_NAME STREQUAL "Emscripten" OR EMSCRIPTEN)
                 \"_flatsql_result_column_name\", \"_flatsql_result_cell_type\", \
                 \"_flatsql_result_cell_number\", \"_flatsql_result_cell_string\", \
                 \"_flatsql_result_cell_blob\", \"_flatsql_result_cell_blob_size\", \
+                \"_flatsql_query_sandboxed\", \
                 \"_flatsql_query_raw_flatbuffer_stream\", \"_flatsql_response_artifact_data\", \
                 \"_flatsql_response_artifact_size\", \"_flatsql_response_artifact_row_count\", \
                 \"_flatsql_response_artifact_column_count\", \"_flatsql_response_artifact_cache_hit\", \
@@ -239,7 +239,6 @@ if(CMAKE_SYSTEM_NAME STREQUAL "Emscripten" OR EMSCRIPTEN)
         SQLITE_OMIT_WAL=1
         SQLITE_OMIT_DEPRECATED=1
         SQLITE_OMIT_SHARED_CACHE=1
-        SQLITE_OMIT_PROGRESS_CALLBACK=1
         SQLITE_DEFAULT_MEMSTATUS=0
         SQLITE_DQS=0
         SQLITE_ENABLE_RTREE=1
@@ -274,6 +273,7 @@ if(CMAKE_SYSTEM_NAME STREQUAL "Emscripten" OR EMSCRIPTEN)
                 \"_flatsql_result_column_name\", \"_flatsql_result_cell_type\", \
                 \"_flatsql_result_cell_number\", \"_flatsql_result_cell_string\", \
                 \"_flatsql_result_cell_blob\", \"_flatsql_result_cell_blob_size\", \
+                \"_flatsql_query_sandboxed\", \
                 \"_flatsql_query_raw_flatbuffer_stream\", \"_flatsql_response_artifact_data\", \
                 \"_flatsql_response_artifact_size\", \"_flatsql_response_artifact_row_count\", \
                 \"_flatsql_response_artifact_column_count\", \"_flatsql_response_artifact_cache_hit\", \
@@ -345,7 +345,6 @@ if(CMAKE_SYSTEM_NAME STREQUAL "Emscripten" OR EMSCRIPTEN)
         SQLITE_OMIT_WAL=1
         SQLITE_OMIT_DEPRECATED=1
         SQLITE_OMIT_SHARED_CACHE=1
-        SQLITE_OMIT_PROGRESS_CALLBACK=1
         SQLITE_DEFAULT_MEMSTATUS=0
         SQLITE_DQS=0
         SQLITE_ENABLE_RTREE=1

cpp/include/flatsql/database.h

@@ -257,6 +257,22 @@ class FlatSQLDatabase {
 
     RawStreamCacheStats getRawStreamCacheStats() const;
 
+    // ==================== Sandboxed public query (gateway loop G.5) ====================
+    // Execute UNTRUSTED SQL through SQLiteEngine::executeSandboxed: one
+    // read-only SELECT, authorizer-restricted to this database's record
+    // tables / source shadow tables / unified views (control tables created
+    // through plain SQL DDL are NOT readable), with a statement timeout and
+    // row/byte caps. Bypasses every cache (no pollution, no invalidation) —
+    // sandboxed executions are structurally read-only. Never throws; on
+    // failure *errorMessage carries "sandbox: <code>: ..." for sandbox
+    // rejections or "SQL error: ..." for plain SQL errors.
+    bool querySandboxed(const std::string& sql,
+                        const std::vector<Value>& params,
+                        SQLiteEngine::SandboxMode mode,
+                        const SQLiteEngine::SandboxLimits& limits,
+                        SQLiteEngine::SandboxOutput* out,
+                        std::string* errorMessage) noexcept;
+
     // Execute and count without building QueryResult (for benchmarking)
     size_t queryCount(const std::string& sql, const std::vector<Value>& params = {});
 

cpp/include/flatsql/sqlite_engine.h

@@ -113,6 +113,58 @@ class SQLiteEngine {
      */
     bool validateSQL(const std::string& sql, int* paramCountOut, std::string* errOut) noexcept;
 
+    // ==================== Sandboxed public query (gateway loop G.5) ====================
+    // A single-statement, read-only, resource-capped execution path for
+    // UNTRUSTED SQL (the public /api/v1/query surface). Never throws — every
+    // rejection lands in *errOut with a stable "sandbox: <code>: ..." prefix
+    // so hosts can map violations to typed errors. Defense layers:
+    //   1. sqlite3_set_authorizer during prepare: only SQLITE_SELECT /
+    //      SQLITE_FUNCTION / SQLITE_RECURSIVE / SQLITE_READ-on-allowlisted
+    //      tables are permitted; PRAGMA, ATTACH/DETACH, every DDL/DML verb
+    //      (incl. temp objects), TRANSACTION/SAVEPOINT and reads outside
+    //      `allowedTables` are denied (prepare fails).
+    //   2. single-statement: any non-whitespace prepare tail is rejected.
+    //   3. sqlite3_stmt_readonly must be true and the statement must return
+    //      result columns (SELECT-shaped).
+    //   4. sqlite3_progress_handler timeout (steady-clock deadline) —
+    //      runaway statements abort with SQLITE_INTERRUPT.
+    //   5. row / byte caps enforced inside the step loop (reject, not
+    //      truncate).
+    // The sandbox never touches the statement cache or the query/raw-stream
+    // caches, and never invalidates anything (it is structurally read-only).
+
+    enum class SandboxMode {
+        RecordStream,  // all cells BLOB -> aligned [u32le size][bytes] frames
+        JsonRows       // bare JSON array of {"<column>": value} objects
+    };
+
+    struct SandboxLimits {
+        uint64_t maxRows = 0;    // 0 = unlimited
+        uint64_t maxBytes = 0;   // 0 = unlimited (output payload bytes)
+        uint32_t timeoutMs = 0;  // 0 = no deadline
+    };
+
+    struct SandboxOutput {
+        std::vector<uint8_t> payload;  // stream frames or UTF-8 JSON array
+        size_t rowCount = 0;
+        size_t columnCount = 0;
+    };
+
+    /**
+     * Execute untrusted SQL under the sandbox contract above. Never throws.
+     *
+     * @param allowedTables table/view names SQLITE_READ may touch
+     * @return true on success; false with *errOut set ("sandbox: <code>: ..."
+     *         for sandbox rejections, "SQL error: ..." for plain SQL errors)
+     */
+    bool executeSandboxed(const std::string& sql,
+                          const std::vector<Value>& params,
+                          const std::unordered_set<std::string>& allowedTables,
+                          SandboxMode mode,
+                          const SandboxLimits& limits,
+                          SandboxOutput* out,
+                          std::string* errOut) noexcept;
+
     /**
      * Execute a SQL query and return results.
      *

cpp/src/database.cpp

@@ -5,6 +5,7 @@
 #include <limits>
 #include <mutex>
 #include <stdexcept>
+#include <unordered_set>
 
 #ifdef FLATSQL_HAVE_OPENSSL
 #include <openssl/hmac.h>
@@ -909,6 +910,41 @@ bool FlatSQLDatabase::queryRawFlatBufferStream(const std::string& sql,
     return true;
 }
 
+bool FlatSQLDatabase::querySandboxed(const std::string& sql,
+                                     const std::vector<Value>& params,
+                                     SQLiteEngine::SandboxMode mode,
+                                     const SQLiteEngine::SandboxLimits& limits,
+                                     SQLiteEngine::SandboxOutput* out,
+                                     std::string* errorMessage) noexcept {
+    try {
+        std::unique_lock lock(*accessMutex_);
+        if (!sqliteInitialized_) {
+            initializeSQLiteEngine();
+        }
+
+        // The public query surface: record base tables (schema names),
+        // per-source shadow tables ("OMM@celestrak-gp"), and the unified
+        // views (which reuse the base table name). Control tables created
+        // through plain SQL DDL are deliberately absent — the authorizer
+        // denies reading them.
+        std::unordered_set<std::string> allowed;
+        for (const auto& tableDef : schema_.tables) {
+            allowed.insert(tableDef.name);
+        }
+        for (const auto& entry : tables_) {
+            allowed.insert(entry.first);
+        }
+
+        return sqliteEngine_->executeSandboxed(sql, params, allowed, mode, limits, out,
+                                               errorMessage);
+    } catch (...) {
+        if (errorMessage) {
+            try { *errorMessage = "sandbox: internal: sandboxed execution failed"; } catch (...) {}
+        }
+        return false;
+    }
+}
+
 void FlatSQLDatabase::storeRawStreamResultUnlocked(const std::string& key,
                                                    const RawStreamResult& result) {
     const size_t streamBytes = result.stream ? result.stream->size() : 0;

cpp/src/flatsql_capi.cpp

@@ -1355,6 +1355,71 @@ int flatsql_query_raw_flatbuffer_stream(
     }
 }
 
+// Sandboxed public query (gateway loop G.5): one read-only SELECT under an
+// authorizer (record tables / shadow tables / unified views only; no PRAGMA,
+// no ATTACH, no DDL/DML/temp writes), single-statement enforced, statement
+// timeout via the progress handler, row/byte caps enforced in the step loop.
+// mode 0 = record stream (all cells BLOB -> aligned [u32le size][bytes]
+// frames), mode 1 = bare JSON array of {"<column>": value} objects with
+// column names verbatim from SQLite (schema-exact capitalization). The
+// result is read through the response-artifact exports (data/size/row_count/
+// column_count; cache_hit always 0 — sandboxed executions bypass every
+// cache). Limits <= 0 mean "unlimited"; timeoutMs <= 0 means no deadline.
+// Returns 1 on success, 0 with flatsql_get_error() latched ("sandbox:
+// <code>: ..." for sandbox rejections).
+EMSCRIPTEN_KEEPALIVE
+int flatsql_query_sandboxed(
+    void* handle,
+    const char* sql,
+    const uint8_t* paramData,
+    size_t paramLength,
+    int paramCount,
+    int mode,
+    double maxRows,
+    double maxBytes,
+    double timeoutMs
+) {
+    auto* db = static_cast<FlatSQLDatabase*>(handle);
+    const std::string sqlStr = sql ? sql : "";
+
+    std::vector<Value> params;
+    std::string errorMessage;
+    if (!decodeParamsNoThrow(paramData, paramLength, paramCount, &params, &errorMessage)) {
+        clearResponseArtifact();
+        g_lastError = errorMessage;
+        return 0;
+    }
+    if (mode != 0 && mode != 1) {
+        clearResponseArtifact();
+        g_lastError = "sandbox: mode: unknown result mode (0 = record stream, 1 = json rows)";
+        return 0;
+    }
+
+    SQLiteEngine::SandboxLimits limits;
+    if (maxRows > 0) limits.maxRows = static_cast<uint64_t>(maxRows);
+    if (maxBytes > 0) limits.maxBytes = static_cast<uint64_t>(maxBytes);
+    if (timeoutMs > 0) limits.timeoutMs = static_cast<uint32_t>(timeoutMs);
+
+    SQLiteEngine::SandboxOutput output;
+    if (!db->querySandboxed(sqlStr, params,
+                            mode == 0 ? SQLiteEngine::SandboxMode::RecordStream
+                                      : SQLiteEngine::SandboxMode::JsonRows,
+                            limits, &output, &errorMessage)) {
+        clearResponseArtifact();
+        g_lastError = errorMessage;
+        return 0;
+    }
+
+    g_responseArtifactStream =
+        std::make_shared<const std::vector<uint8_t>>(std::move(output.payload));
+    g_responseArtifactRowCount = output.rowCount;
+    g_responseArtifactColumnCount = output.columnCount;
+    g_responseArtifactCacheHit = 0;
+
+    g_lastError.clear();
+    return 1;
+}
+
 EMSCRIPTEN_KEEPALIVE
 const uint8_t* flatsql_response_artifact_data() {
     return g_responseArtifactStream ? g_responseArtifactStream->data() : nullptr;