@nifrajs/mcp-db 3.5.0 → 4.0.2

package/README.md

@@ -12,6 +12,8 @@ import { serveDatabaseAsMcp } from "@nifrajs/mcp-db"
 
 const mcp = serveDatabaseAsMcp(new Database("app.db"), {
   tables: ["habits", "entries"],
+  // Refuse any other Host, so a DNS-rebound browser page cannot read the schema tools.
+  allowedHosts: ["localhost", "127.0.0.1", "[::1]"],
 })
 ```
 
@@ -20,6 +22,87 @@ allowlist. `run_query` requires an authorization hook and is guarded by SQLite q
 single-statement/read-only checks, query-plan verification, and bounded output. D1 is not supported
 because it cannot provide the same engine-level read-only guarantee.
 
+## The engine: `@nifrajs/mcp-db/engine`
+
+The read-only SQLite engine behind the MCP server, without the MCP layer. `nifra db` uses it.
+
+```ts
+import { openReadOnlySqlite, querySqlite, readSqliteSchema } from "@nifrajs/mcp-db/engine"
+
+const db = await openReadOnlySqlite("./data/app.db")
+const result = querySqlite(db, "SELECT status, count(*) FROM orders GROUP BY 1", {
+  exclude: ["sessions"],
+  maxRows: 100,
+  maxResultBytes: 100 * 1024,
+})
+if ("code" in result) console.error(result.code, result.fix)
+```
+
+- The file opens with the `readonly` flag and `PRAGMA query_only = ON`, so SQLite itself rejects every
+  write. A WAL database with no writer attached (no `-wal` file yet) is reopened read-write with
+  `query_only` on, which still rejects writes at the engine.
+- A query must be one SELECT (or WITH ... SELECT). Every table its compiled bytecode opens must be
+  exposed (all tables and views minus `exclude`): views read as their base tables, an alias cannot hide
+  a table, and `sqlite_master`, virtual tables and table-valued functions are never exposed.
+- With `redaction`, a query that reads a column `redaction.column` matches is refused
+  (`NIFRA_DB_COLUMN_REFUSED`) wherever the compiled statement reads it: selected under another name,
+  inside an expression, in a filter or an index seek, or through a view. Strings go through
+  `redaction.text`.
+- Results are capped by rows and bytes, bigints beyond 2^53 come back as strings, blobs as
+  `<n bytes>`.
+- Every refusal is a `DbRefusal`: a stable `NIFRA_DB_*` code, a message, a fix and a docs anchor.
+
+## Postgres: `@nifrajs/mcp-db/postgres`
+
+The same result shape and refusal codes for a development Postgres, on `Bun.SQL`.
+
+```ts
+import { isDbRefusal } from "@nifrajs/mcp-db/engine"
+import { connectPostgres, parsePostgresUrl, queryPostgres } from "@nifrajs/mcp-db/postgres"
+
+const target = parsePostgresUrl("postgres://nifra_dev_reader:secret@localhost/app")
+if (isDbRefusal(target)) throw new Error(target.message)
+const client = connectPostgres(target, { timeoutMs: 5000 })
+if (isDbRefusal(client)) throw new Error(client.message)
+const result = await queryPostgres(client, "SELECT id, status FROM orders LIMIT 10", {
+  timeoutMs: 5000,
+  maxRows: 100,
+  maxResultBytes: 100 * 1024,
+  exclude: ["audit_log"],
+})
+await client.close()
+```
+
+Each layer refuses on its own, in this order:
+
+1. **Host.** Only loopback, `*.localhost` and unix sockets connect unless `allowHosts` names the host.
+   URL parameters other than host, port, user, password, database and `sslmode` are ignored.
+2. **Tokenizer.** One SELECT, WITH, VALUES or TABLE statement; row-locking clauses, unicode-escaped
+   identifiers and functions that reach outside a query (server files, `dblink`, `set_config`,
+   advisory locks, `pg_notify`, `nextval`, `query_to_xml`, backend signals) are refused.
+3. **Read-only transaction.** `BEGIN READ ONLY` with `statement_timeout`, `lock_timeout` and
+   `idle_in_transaction_session_timeout` set to `timeoutMs`, always rolled back. Sessions also start
+   with `default_transaction_read_only = on`.
+4. **Role and extensions.** A superuser, a member of a superuser or server-file/program role, or a
+   role that may execute server-file functions is refused (`NIFRA_DB_SUPERUSER`). A role that can use
+   dblink, postgres_fdw, file_fdw or an untrusted language is refused (`NIFRA_DB_EXTENSION`) unless
+   `allowExtensions` names it.
+5. **Cursor.** The statement runs as one extended-protocol `DECLARE ... NO SCROLL CURSOR`, which the
+   server accepts only for SELECT and VALUES and refuses for a data-modifying WITH, then one `FETCH`
+   of `maxRows + 1` rows.
+6. **Plan scope.** Every relation in the `EXPLAIN (VERBOSE)` plan, every table it inherits from, and
+   every `pg_catalog` function scanned in FROM must sit in `schemas` (default `public`) and outside
+   `exclude`. With `redaction`, a column `redaction.column` matches that any plan expression uses
+   (output, filter, join, sort or index condition), or a whole row holding one, is refused
+   (`NIFRA_DB_COLUMN_REFUSED`).
+
+`explainPostgres` returns the plan (with `analyze`, executed inside the same transaction),
+`readPostgresSchema` reads tables, columns, keys and indexes from `pg_catalog`, and `postgresRoleSql`
+writes the SQL for a read-only role (`pg_read_all_data` on 14+, or `GRANT SELECT` per schema with a
+`REVOKE` for each excluded table and its partitions) without running it.
+
+The live tests run against a throwaway server: set `NIFRA_TEST_POSTGRES_URL` to its superuser URL.
+
 ## For AI agents
 
 Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),

package/dist/engine.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `@nifrajs/mcp-db/engine` - the read-only SQLite engine behind `@nifrajs/mcp-db`, without the MCP
+ * layer, plus the result shape and refusal codes both database engines share.
+ *
+ * Read-only is enforced by SQLite, not promised by a parser: {@link openReadOnlySqlite} opens the file
+ * with the `readonly` flag and sets `PRAGMA query_only = ON`, so the engine rejects every write. The
+ * statement gates ({@link gateSqliteStatement}: one statement, SELECT/WITH only, every named relation
+ * exposed) and a table check on the compiled statement (every table its bytecode opens must be
+ * exposed, so views and aliases cannot hide one) sit in front of it, and the caps
+ * ({@link shapeRows}, {@link fitToBytes}) bound what comes back.
+ *
+ *   const db = await openReadOnlySqlite("./data/app.db")
+ *   const result = querySqlite(db, "SELECT status, count(*) FROM orders GROUP BY 1", {
+ *     exclude: ["sessions"],
+ *     maxRows: 100,
+ *     maxResultBytes: 100 * 1024,
+ *   })
+ *   if ("code" in result) console.error(result.code, result.fix)
+ */
+import type { Database } from "bun:sqlite";
+import { type DbPlan, type DbRedaction, type DbRefusal, type DbRows, type DbSchemaReport, type ShapeRowsOptions } from "./internal/shared.js";
+export { boundedSqliteQuery, countSqliteQuery, type DbPlan, type DbRedaction, type DbRefusal, type DbRefusalCode, type DbRows, type DbSchemaColumn, type DbSchemaForeignKey, type DbSchemaIndex, type DbSchemaReport, type DbSchemaTable, dbRefusal, fitToBytes, gateSqliteStatement, isDbRefusal, REDACTED_CELL, type ShapeRowsOptions, type SqliteDatabaseLike, type SqliteGate, shapeRows, toJsonCell, unexposedPlanRelation, } from "./internal/shared.js";
+/**
+ * Resolve a database file against the project root. The file must exist and its real path (symlinks
+ * followed) must sit inside the root's real path, unless `allowFiles` names it.
+ */
+export declare function resolveSqliteFile(root: string, file: string, allowFiles?: readonly string[]): string | DbRefusal;
+/**
+ * Open a SQLite file read-only: the `readonly` flag plus `PRAGMA query_only = ON`.
+ *
+ * Trap: a read-only connection cannot create a WAL database's `-wal` file, so while no writer has the
+ * database open (no `-wal` on disk) the first read fails with SQLITE_CANTOPEN. Only in that case the
+ * file is reopened read-write with `query_only` on, which creates the WAL files the way any client
+ * would and still rejects every write at the engine. With a live writer the `-wal` exists and the
+ * read-only open works.
+ */
+export declare function openReadOnlySqlite(file: string): Promise<Database>;
+/** The tables and views of a SQLite database, lowercased: all of them, and those not excluded. */
+export declare function sqliteRelations(db: Pick<Database, "prepare">, exclude?: readonly string[]): {
+    readonly all: ReadonlySet<string>;
+    readonly exposed: ReadonlySet<string>;
+};
+/** Options for {@link querySqlite} and {@link explainSqlite}. */
+export interface SqliteQueryOptions extends ShapeRowsOptions {
+    /** Tables and views the query may not read (case-insensitive). */
+    readonly exclude?: readonly string[];
+}
+/**
+ * Run one read-only query: the statement gates, the check that every table its bytecode opens is
+ * exposed (every table and view minus `exclude`), the refusal of any column `redaction.column`
+ * masks that the bytecode reads in any form, then at most `maxRows + 1` rows through
+ * {@link shapeRows}. Synchronous: run it where the caller can stop the process (the CLI runs each
+ * call in its own subprocess, killed at the deadline).
+ */
+export declare function querySqlite(db: Pick<Database, "prepare">, sql: string, options: SqliteQueryOptions): DbRows | DbRefusal;
+/** `EXPLAIN QUERY PLAN` for one statement, after the same gates as {@link querySqlite}. */
+export declare function explainSqlite(db: Pick<Database, "prepare">, sql: string, options: Pick<SqliteQueryOptions, "exclude" | "maxResultBytes">): DbPlan | DbRefusal;
+/** Options for {@link readSqliteSchema}. */
+export interface SqliteSchemaOptions {
+    readonly exclude?: readonly string[];
+    /** Describe only this table or view. */
+    readonly table?: string | undefined;
+    readonly redaction?: DbRedaction;
+}
+/**
+ * Describe the exposed tables and views from SQLite's own catalog (`sqlite_master` and the
+ * `pragma_*` table functions, each bound by parameter): columns, primary key, foreign keys, indexes,
+ * and a row count per table.
+ */
+export declare function readSqliteSchema(db: Pick<Database, "prepare">, options?: SqliteSchemaOptions): DbSchemaReport | DbRefusal;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAG1C,OAAO,EAEL,KAAK,MAAM,EACX,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,MAAM,EACX,KAAK,cAAc,EAKnB,KAAK,gBAAgB,EAGtB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,MAAM,EACX,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,MAAM,EACX,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,WAAW,EACX,aAAa,EACb,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,SAAS,EACT,UAAU,EACV,qBAAqB,GACtB,MAAM,sBAAsB,CAAA;AAW7B;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,SAAS,MAAM,EAAO,GACjC,MAAM,GAAG,SAAS,CAuBpB;AAwCD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CA8BxE;AAED,kGAAkG;AAClG,wBAAgB,eAAe,CAC7B,EAAE,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,EAC7B,OAAO,GAAE,SAAS,MAAM,EAAO,GAC9B;IAAE,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAAE,CAS9E;AAkCD,iEAAiE;AACjE,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC;AAuPD;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,EAC7B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,kBAAkB,GAC1B,MAAM,GAAG,SAAS,CAYpB;AAED,2FAA2F;AAC3F,wBAAgB,aAAa,CAC3B,EAAE,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,EAC7B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,IAAI,CAAC,kBAAkB,EAAE,SAAS,GAAG,gBAAgB,CAAC,GAC9D,MAAM,GAAG,SAAS,CAuBpB;AAmBD,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,wCAAwC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,WAAW,CAAA;CACjC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,EAC7B,OAAO,GAAE,mBAAwB,GAChC,cAAc,GAAG,SAAS,CA2F5B"}

package/dist/engine.js

@@ -0,0 +1,494 @@
+/**
+ * `@nifrajs/mcp-db/engine` - the read-only SQLite engine behind `@nifrajs/mcp-db`, without the MCP
+ * layer, plus the result shape and refusal codes both database engines share.
+ *
+ * Read-only is enforced by SQLite, not promised by a parser: {@link openReadOnlySqlite} opens the file
+ * with the `readonly` flag and sets `PRAGMA query_only = ON`, so the engine rejects every write. The
+ * statement gates ({@link gateSqliteStatement}: one statement, SELECT/WITH only, every named relation
+ * exposed) and a table check on the compiled statement (every table its bytecode opens must be
+ * exposed, so views and aliases cannot hide one) sit in front of it, and the caps
+ * ({@link shapeRows}, {@link fitToBytes}) bound what comes back.
+ *
+ *   const db = await openReadOnlySqlite("./data/app.db")
+ *   const result = querySqlite(db, "SELECT status, count(*) FROM orders GROUP BY 1", {
+ *     exclude: ["sessions"],
+ *     maxRows: 100,
+ *     maxResultBytes: 100 * 1024,
+ *   })
+ *   if ("code" in result) console.error(result.code, result.fix)
+ */
+import { closeSync, existsSync, openSync, readSync, realpathSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { boundedSqliteQuery, dbRefusal, fitToBytes, gateSqliteStatement, shapeRows, sqliteCteNames, } from "./internal/shared.js";
+export { boundedSqliteQuery, countSqliteQuery, dbRefusal, fitToBytes, gateSqliteStatement, isDbRefusal, REDACTED_CELL, shapeRows, toJsonCell, unexposedPlanRelation, } from "./internal/shared.js";
+// ---------------------------------------------------------------------------------------------------
+// SQLite: open, scope, query, explain, schema
+// ---------------------------------------------------------------------------------------------------
+const isInside = (root, target) => {
+    const rel = relative(root, target);
+    return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+};
+/**
+ * Resolve a database file against the project root. The file must exist and its real path (symlinks
+ * followed) must sit inside the root's real path, unless `allowFiles` names it.
+ */
+export function resolveSqliteFile(root, file, allowFiles = []) {
+    const candidate = resolve(root, file);
+    if (!existsSync(candidate))
+        return dbRefusal("NIFRA_DB_DRIVER", `no database file at ${file}`);
+    let real;
+    let realRoot;
+    try {
+        real = realpathSync(candidate);
+        realRoot = realpathSync(root);
+    }
+    catch (error) {
+        return dbRefusal("NIFRA_DB_DRIVER", `could not resolve ${file}: ${String(error)}`);
+    }
+    if (isInside(realRoot, real))
+        return real;
+    for (const allowed of allowFiles) {
+        try {
+            if (realpathSync(resolve(root, allowed)) === real)
+                return real;
+        }
+        catch {
+            // An allowFiles entry that does not exist allows nothing.
+        }
+    }
+    return dbRefusal("NIFRA_DB_OUTSIDE_ROOT", `${file} resolves to ${real}, outside the project root ${realRoot}`);
+}
+/** True when the file's header says WAL mode (format versions 2/2 at bytes 18-19). */
+function isWalDatabase(file) {
+    const header = new Uint8Array(20);
+    let fd;
+    try {
+        fd = openSync(file, "r");
+        return readSync(fd, header, 0, 20, 0) === 20 && header[18] === 2 && header[19] === 2;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+const SQLITE_BUSY_TIMEOUT_MS = 2_000;
+/**
+ * Make `close()` finalize every statement prepared on `db`. Otherwise bun:sqlite keeps a connection with
+ * live statements open until they are garbage collected, and the process holds the file until then.
+ */
+function finalizeOnClose(db) {
+    const statements = [];
+    const prepare = db.prepare.bind(db);
+    const close = db.close.bind(db);
+    Object.assign(db, {
+        prepare: (...args) => {
+            const statement = prepare(...args);
+            statements.push(statement);
+            return statement;
+        },
+        close: (throwOnError) => {
+            for (const statement of statements.splice(0))
+                statement.finalize();
+            close(throwOnError);
+        },
+    });
+    return db;
+}
+/**
+ * Open a SQLite file read-only: the `readonly` flag plus `PRAGMA query_only = ON`.
+ *
+ * Trap: a read-only connection cannot create a WAL database's `-wal` file, so while no writer has the
+ * database open (no `-wal` on disk) the first read fails with SQLITE_CANTOPEN. Only in that case the
+ * file is reopened read-write with `query_only` on, which creates the WAL files the way any client
+ * would and still rejects every write at the engine. With a live writer the `-wal` exists and the
+ * read-only open works.
+ */
+export async function openReadOnlySqlite(file) {
+    const { Database } = await import("bun:sqlite");
+    const probe = (db) => {
+        db.run("PRAGMA query_only = ON");
+        // A writer that is mid-recovery or holds the journal lock answers SQLITE_BUSY: wait, not fail.
+        db.run(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
+        db.prepare("SELECT count(*) FROM sqlite_master").all();
+        return db;
+    };
+    // safeIntegers: an INTEGER beyond 2^53 comes back exact (as a bigint) instead of rounded.
+    const readonly = finalizeOnClose(new Database(file, { readonly: true, safeIntegers: true }));
+    try {
+        return probe(readonly);
+    }
+    catch (error) {
+        readonly.close();
+        if (sqliteCode(error) !== "SQLITE_CANTOPEN" ||
+            !isWalDatabase(file) ||
+            existsSync(`${file}-wal`)) {
+            throw error;
+        }
+    }
+    const fallback = finalizeOnClose(new Database(file, { readwrite: true, safeIntegers: true }));
+    try {
+        return probe(fallback);
+    }
+    catch (error) {
+        fallback.close();
+        throw error;
+    }
+}
+/** The tables and views of a SQLite database, lowercased: all of them, and those not excluded. */
+export function sqliteRelations(db, exclude = []) {
+    const excluded = new Set(exclude.map((name) => name.toLowerCase()));
+    const rows = db
+        .prepare("SELECT name FROM sqlite_master WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite\\_%' ESCAPE '\\'")
+        .all();
+    const all = new Set(rows.map((row) => row.name.toLowerCase()));
+    return { all, exposed: new Set([...all].filter((name) => !excluded.has(name))) };
+}
+const SQLITE_WRITE_SYNTAX = /near "(insert|update|delete|replace|create|drop|alter|attach|detach|pragma|vacuum|reindex|analyze|begin|commit|rollback|savepoint|release)": syntax error/i;
+/** The `SQLITE_*` code bun:sqlite puts on an error, if any. */
+const sqliteCode = (error) => typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+/** Map a SQLite error to a refusal: a write the engine rejected is a refusal, not a failure. */
+function sqliteFailure(error, context) {
+    const code = sqliteCode(error);
+    const message = `${context}: ${error instanceof Error ? error.message : String(error)}`;
+    if (typeof code === "string") {
+        if (code.startsWith("SQLITE_READONLY") || code === "SQLITE_AUTH") {
+            return dbRefusal("NIFRA_DB_WRITE_REFUSED", message);
+        }
+        if (code === "SQLITE_INTERRUPT")
+            return dbRefusal("NIFRA_DB_TIMEOUT", message);
+        // SQLite has no data-modifying CTE: `WITH d AS (DELETE ...)` fails to parse at the write.
+        if (code === "SQLITE_ERROR" && SQLITE_WRITE_SYNTAX.test(message)) {
+            return dbRefusal("NIFRA_DB_WRITE_REFUSED", message);
+        }
+        if (code.startsWith("SQLITE_CANTOPEN") ||
+            code.startsWith("SQLITE_CORRUPT") ||
+            code.startsWith("SQLITE_IOERR") ||
+            code === "SQLITE_NOTADB") {
+            return dbRefusal("NIFRA_DB_DRIVER", message);
+        }
+    }
+    return dbRefusal("NIFRA_DB_QUERY_FAILED", message);
+}
+const GATE_MESSAGES = {
+    empty: "empty query",
+    multiple: "only a single statement is allowed",
+    "not-read": "only a read-only query (SELECT, or WITH ... SELECT) is allowed",
+};
+function verifySqlite(db, sql, exclude, masked) {
+    const { all, exposed } = sqliteRelations(db, exclude);
+    const unexposed = (relation) => dbRefusal("NIFRA_DB_TABLE_EXCLUDED", all.has(relation.toLowerCase())
+        ? `the query reads ${JSON.stringify(relation)}, which devDatabase.exclude leaves out`
+        : `the query reads ${JSON.stringify(relation)}, which is not a table or view of this database`);
+    const ctes = new Set(sqliteCteNames(sql));
+    const gate = gateSqliteStatement(sql, (relation) => exposed.has(relation) || ctes.has(relation));
+    if (!gate.ok) {
+        if (gate.reason === "unexposed")
+            return unexposed(gate.relation ?? "");
+        return dbRefusal("NIFRA_DB_WRITE_REFUSED", GATE_MESSAGES[gate.reason]);
+    }
+    let reads;
+    try {
+        reads = bytecodeReads(db, gate.query, masked);
+    }
+    catch (error) {
+        return sqliteFailure(error, "query failed to plan");
+    }
+    const relation = reads.tables.find((name) => !exposed.has(name.toLowerCase()));
+    if (relation !== undefined)
+        return unexposed(relation);
+    if (reads.masked.length > 0) {
+        return dbRefusal("NIFRA_DB_COLUMN_REFUSED", `the query reads ${reads.masked.join(", ")}, masked as ${reads.masked.length === 1 ? "a credential" : "credentials"}`);
+    }
+    return { ok: true, query: gate.query };
+}
+const READ_OPCODES = new Set(["OpenRead", "ReopenIdx", "OpenWrite", "VOpen"]);
+// Each compares a cursor's leading key fields (P4 of them, all when P4 is not a count) with values.
+const KEY_COMPARE_OPCODES = new Set([
+    "SeekGE",
+    "SeekGT",
+    "SeekLE",
+    "SeekLT",
+    "IdxGE",
+    "IdxGT",
+    "IdxLE",
+    "IdxLT",
+    "Found",
+    "NotFound",
+    "NoConflict",
+    "IfNoHope",
+]);
+const ROWID_OPCODES = new Set(["Rowid", "SeekRowid", "NotExists", "IdxRowid"]);
+/**
+ * The record layout behind a cursor on `entry`, from SQLite's own catalog. A rowid table stores its
+ * non-virtual columns in order, then its virtual ones; a WITHOUT ROWID table and an index store the
+ * fields `pragma_index_xinfo` lists. An expression field reads every column its index SQL names.
+ */
+function cursorLayout(db, entry) {
+    const columns = db
+        .prepare("SELECT name, type, pk, hidden FROM pragma_table_xinfo(?) ORDER BY cid")
+        .all(entry.table);
+    let withoutRowid;
+    try {
+        withoutRowid =
+            Number(db
+                .prepare("SELECT wr FROM pragma_table_list WHERE schema = 'main' AND name = ?")
+                .get(entry.table)?.wr ?? 0) === 1;
+    }
+    catch {
+        // pragma_table_list is SQLite 3.37+; Bun on macOS links the system library, which can be older.
+        const created = db
+            .prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?")
+            .get(entry.table)?.sql;
+        withoutRowid = /\)\s*(?:STRICT\s*,\s*)?WITHOUT\s+ROWID\b/i.test(created ?? "");
+    }
+    const keys = columns.filter((column) => Number(column.pk) > 0);
+    const rowid = !withoutRowid && keys.length === 1 && keys[0]?.type.toUpperCase() === "INTEGER"
+        ? keys[0].name
+        : undefined;
+    let index = entry.type === "index" ? entry.name : undefined;
+    if (entry.type === "table" && withoutRowid) {
+        index = db
+            .prepare("SELECT name FROM pragma_index_list(?) WHERE origin = 'pk'")
+            .get(entry.table)?.name;
+    }
+    if (index === undefined) {
+        const stored = [
+            ...columns.filter((column) => Number(column.hidden) !== 2),
+            ...columns.filter((column) => Number(column.hidden) === 2),
+        ];
+        return { table: entry.table, fields: stored.map((column) => [column.name]), keyCount: 0, rowid };
+    }
+    // A substring match can only over-count: an expression field then reads one column too many.
+    const source = (entry.sql ?? "").toLowerCase();
+    const named = columns
+        .map((column) => column.name)
+        .filter((name) => source.includes(name.toLowerCase()));
+    const xinfo = db
+        .prepare("SELECT cid, name, key FROM pragma_index_xinfo(?) ORDER BY seqno")
+        .all(index);
+    return {
+        table: entry.table,
+        fields: xinfo.map((field) => field.name !== null
+            ? [field.name]
+            : Number(field.cid) === -1
+                ? rowid === undefined
+                    ? []
+                    : [rowid]
+                : named),
+        keyCount: xinfo.filter((field) => Number(field.key) === 1).length,
+        rowid,
+    };
+}
+/**
+ * The tables a statement's bytecode opens, mapped from each cursor's root page through
+ * `sqlite_master`: a view reads as its base tables, an alias cannot rename a table (the query plan
+ * would print `SCAN o` for `orders AS o`), and an index read counts as a read of its table. Root
+ * page 1 is `sqlite_master` itself; a cursor on another schema (temp, attached) or a virtual table
+ * (`pragma_*`, `dbstat`, `json_each`) is never exposed.
+ *
+ * With `masked`, also every masked column a cursor on a table or index yields (`Column`), compares
+ * (a seek or index range check, so a filter counts) or reads as the rowid. Values the statement
+ * derives from those reads live in other cursors and registers, so an alias or an expression
+ * cannot hide the column it started from.
+ */
+function bytecodeReads(db, query, masked) {
+    const pages = new Map([
+        [1, { type: "table", name: "sqlite_master", table: "sqlite_master", sql: null }],
+    ]);
+    const catalog = db
+        .prepare('SELECT type, name, tbl_name AS "table", rootpage, sql FROM sqlite_master WHERE rootpage > 0')
+        .all();
+    for (const entry of catalog)
+        pages.set(Number(entry.rootpage), entry);
+    const program = db.prepare(`EXPLAIN ${query}`).all();
+    const reads = new Set();
+    const cursors = new Map();
+    for (const step of program) {
+        if (!READ_OPCODES.has(step.opcode))
+            continue;
+        const page = Number(step.p2);
+        const entry = Number(step.p3) === 0 ? pages.get(page) : undefined;
+        if (entry !== undefined && step.opcode !== "VOpen")
+            cursors.set(Number(step.p1), entry);
+        reads.add(step.opcode === "VOpen"
+            ? "<virtual table>"
+            : Number(step.p3) === 0
+                ? (entry?.table ?? `<root page ${page}>`)
+                : `<schema ${step.p3}>`);
+    }
+    if (masked === undefined)
+        return { tables: [...reads], masked: [] };
+    const layouts = new Map();
+    const layoutOf = (cursor) => {
+        const entry = cursors.get(cursor);
+        if (entry === undefined || entry.name === "sqlite_master")
+            return undefined;
+        let layout = layouts.get(cursor);
+        if (layout === undefined) {
+            layout = cursorLayout(db, entry);
+            layouts.set(cursor, layout);
+        }
+        return layout;
+    };
+    const hits = new Set();
+    const read = (layout, names) => {
+        for (const name of names)
+            if (masked(name))
+                hits.add(`${layout.table}.${name}`);
+    };
+    for (const step of program) {
+        const layout = layoutOf(Number(step.p1));
+        if (layout === undefined)
+            continue;
+        if (step.opcode === "Column")
+            read(layout, layout.fields[Number(step.p2)] ?? []);
+        else if (KEY_COMPARE_OPCODES.has(step.opcode)) {
+            const count = Number(step.p4);
+            const compared = Number.isInteger(count) && count > 0 ? count : layout.keyCount;
+            for (const field of layout.fields.slice(0, compared))
+                read(layout, field);
+        }
+        else if (ROWID_OPCODES.has(step.opcode) && layout.rowid !== undefined) {
+            read(layout, [layout.rowid]);
+        }
+    }
+    return { tables: [...reads], masked: [...hits] };
+}
+/**
+ * Run one read-only query: the statement gates, the check that every table its bytecode opens is
+ * exposed (every table and view minus `exclude`), the refusal of any column `redaction.column`
+ * masks that the bytecode reads in any form, then at most `maxRows + 1` rows through
+ * {@link shapeRows}. Synchronous: run it where the caller can stop the process (the CLI runs each
+ * call in its own subprocess, killed at the deadline).
+ */
+export function querySqlite(db, sql, options) {
+    const verified = verifySqlite(db, sql, options.exclude, options.redaction?.column);
+    if (!("ok" in verified))
+        return verified;
+    try {
+        const statement = db.prepare(boundedSqliteQuery(verified.query, options.maxRows));
+        const rows = statement.values();
+        const columns = [...statement.columnNames];
+        statement.finalize();
+        return shapeRows(columns, rows, options);
+    }
+    catch (error) {
+        return sqliteFailure(error, "query failed");
+    }
+}
+/** `EXPLAIN QUERY PLAN` for one statement, after the same gates as {@link querySqlite}. */
+export function explainSqlite(db, sql, options) {
+    const verified = verifySqlite(db, sql, options.exclude);
+    if (!("ok" in verified))
+        return verified;
+    try {
+        const plan = db
+            .prepare(`EXPLAIN QUERY PLAN ${verified.query}`)
+            .all();
+        const steps = plan.map(({ id, parent, detail }) => ({
+            id: Number(id),
+            parent: Number(parent),
+            detail,
+        }));
+        const fit = fitToBytes(steps.length, (shown) => steps.slice(0, shown), options.maxResultBytes);
+        return {
+            plan: fit?.value ?? [],
+            analyzed: false,
+            truncated: (fit?.shown ?? 0) < steps.length,
+        };
+    }
+    catch (error) {
+        return sqliteFailure(error, "query failed to plan");
+    }
+}
+const quoteSqliteIdentifier = (name) => `"${name.replaceAll('"', '""')}"`;
+/**
+ * Describe the exposed tables and views from SQLite's own catalog (`sqlite_master` and the
+ * `pragma_*` table functions, each bound by parameter): columns, primary key, foreign keys, indexes,
+ * and a row count per table.
+ */
+export function readSqliteSchema(db, options = {}) {
+    const excluded = new Set((options.exclude ?? []).map((name) => name.toLowerCase()));
+    const wanted = options.table?.toLowerCase();
+    let entries;
+    try {
+        entries = db
+            .prepare("SELECT name, type FROM sqlite_master WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite\\_%' ESCAPE '\\' ORDER BY name")
+            .all();
+    }
+    catch (error) {
+        return sqliteFailure(error, "could not read the schema");
+    }
+    const exposed = entries.filter((entry) => !excluded.has(entry.name.toLowerCase()));
+    if (wanted !== undefined && !exposed.some((entry) => entry.name.toLowerCase() === wanted)) {
+        return dbRefusal("NIFRA_DB_TABLE_EXCLUDED", `${JSON.stringify(options.table)} is not an exposed table or view of this database`);
+    }
+    const text = (value) => options.redaction?.text?.(value) ?? value;
+    const tables = [];
+    try {
+        for (const entry of exposed) {
+            if (wanted !== undefined && entry.name.toLowerCase() !== wanted)
+                continue;
+            const columns = db
+                .prepare('SELECT name, type, "notnull" AS required, dflt_value AS dflt, pk FROM pragma_table_info(?) ORDER BY cid')
+                .all(entry.name);
+            const keys = db
+                .prepare('SELECT id, "table" AS ref, "from" AS col, "to" AS refcol FROM pragma_foreign_key_list(?) ORDER BY id, seq')
+                .all(entry.name);
+            const foreignKeys = new Map();
+            for (const key of keys) {
+                const id = Number(key.id);
+                const fk = foreignKeys.get(id) ?? { columns: [], table: key.ref, refs: [] };
+                fk.columns.push(key.col);
+                if (key.refcol !== null)
+                    fk.refs.push(key.refcol);
+                foreignKeys.set(id, fk);
+            }
+            const indexes = db
+                .prepare('SELECT name, "unique" AS uniq FROM pragma_index_list(?) ORDER BY seq')
+                .all(entry.name)
+                .map((index) => ({
+                name: index.name,
+                unique: Number(index.uniq) === 1,
+                columns: db
+                    .prepare("SELECT name FROM pragma_index_info(?) ORDER BY seqno")
+                    .all(index.name)
+                    .map((column) => column.name ?? "<expression>"),
+            }));
+            let rowEstimate = null;
+            if (entry.type === "table") {
+                // nifra-expect sql-dynamic: the table name comes from sqlite_master, quoted as an identifier
+                const counted = db
+                    .prepare(`SELECT count(*) AS n FROM ${quoteSqliteIdentifier(entry.name)}`)
+                    .all();
+                rowEstimate = counted[0] === undefined ? null : Number(counted[0].n);
+            }
+            tables.push({
+                name: entry.name,
+                kind: entry.type,
+                rowEstimate,
+                columns: columns.map((column) => ({
+                    name: column.name,
+                    type: column.type,
+                    nullable: Number(column.required) === 0 && Number(column.pk) === 0,
+                    default: column.dflt === null ? null : text(column.dflt),
+                    primaryKey: Number(column.pk) > 0,
+                    redacted: options.redaction?.column?.(column.name) === true,
+                })),
+                foreignKeys: [...foreignKeys.values()].map((fk) => ({
+                    columns: fk.columns,
+                    references: { table: fk.table, columns: fk.refs },
+                })),
+                indexes,
+            });
+        }
+    }
+    catch (error) {
+        return sqliteFailure(error, "could not read the schema");
+    }
+    return { tables, excludedCount: entries.length - exposed.length };
+}
+//# sourceMappingURL=engine.js.map