@nifrajs/mcp-db 3.3.0 → 4.0.0

package/src/internal/pg-exec.ts

@@ -0,0 +1,386 @@
+/**
+ * The server-enforced layers of `@nifrajs/mcp-db/postgres`: the read-only transaction with its
+ * timeouts, the extended-protocol statement, the cursor, and the plan-level table scope. Nothing here
+ * parses the caller's SQL - the refusals in this file come from the server, and the only text lexed
+ * is the expressions of the server's own verbose plan.
+ *
+ * Bun 1.4.2 sends `sql.unsafe(text)` and `sql.unsafe(text, [])` over the SIMPLE protocol, which runs
+ * several `;`-separated statements. Only a tagged-template call (or `unsafe` with a non-empty value
+ * list) uses the EXTENDED protocol, where the server refuses a second statement with "cannot insert
+ * multiple commands into a prepared statement". So every statement carrying caller text goes through
+ * {@link extended}; `unsafe` is used only for fixed text this file writes.
+ */
+
+import { lexPostgres } from "./pg-lexer.ts"
+import { type DbRefusal, dbRefusal } from "./shared.ts"
+
+/** A pending query: awaitable for object rows, or `.values()` for array rows (checked by readers). */
+export interface PgQuery extends PromiseLike<readonly unknown[]> {
+  values(): PromiseLike<readonly unknown[]>
+}
+
+/** Rows as records: a driver row that is not an object is dropped, never cast. */
+export function records(rows: readonly unknown[]): Record<string, unknown>[] {
+  return rows.filter(
+    (row): row is Record<string, unknown> =>
+      typeof row === "object" && row !== null && !Array.isArray(row),
+  )
+}
+
+/** One connection reserved from the pool (`Bun.SQL`'s `ReservedSQL`, structurally). */
+export interface PgConnection {
+  (strings: TemplateStringsArray, ...values: unknown[]): PgQuery
+  unsafe(text: string): PgQuery
+  release(): void
+}
+
+/** A Postgres client (`Bun.SQL`, structurally): the engine reserves one connection per call. */
+export interface PostgresClient {
+  reserve(): Promise<PgConnection>
+  close(options?: { readonly timeout?: number }): Promise<void>
+}
+
+/** Run caller text as ONE extended-protocol statement with no parameters. */
+export function extended(connection: PgConnection, text: string): PgQuery {
+  const strings: TemplateStringsArray = Object.assign([text], { raw: [text] })
+  return connection(strings)
+}
+
+const WRITE_KEYWORD =
+  /at or near "(insert|update|delete|merge|call|do|copy|create|drop|alter|truncate|grant|revoke|lock|vacuum|analyze|cluster|reindex|refresh|comment|security|import|listen|notify|load|discard|reset|set|show|begin|commit|rollback|savepoint|release|prepare|execute|deallocate|declare|fetch|move|close|checkpoint|explain)"/i
+
+/** Map a driver error to a refusal by its SQLSTATE; only a genuine query error is a failure. */
+export function pgFailure(error: unknown, context = "query failed"): DbRefusal {
+  // Bun.SQL puts the SQLSTATE on `errno`.
+  const state =
+    typeof error === "object" && error !== null && "errno" in error ? error.errno : undefined
+  const message = `${context}: ${error instanceof Error ? error.message : String(error)}`
+  if (typeof state !== "string" || !/^[0-9A-Z]{5}$/.test(state)) {
+    return dbRefusal("NIFRA_DB_DRIVER", message)
+  }
+  const text = error instanceof Error ? error.message : ""
+  if (state === "25006" || state === "25001") return dbRefusal("NIFRA_DB_WRITE_REFUSED", message)
+  if (state === "0A000" && /data-modifying/i.test(text)) {
+    return dbRefusal("NIFRA_DB_WRITE_REFUSED", message)
+  }
+  if (
+    state === "42601" &&
+    (/multiple commands/i.test(text) ||
+      /INTO is not allowed/i.test(text) ||
+      WRITE_KEYWORD.test(text))
+  ) {
+    return dbRefusal("NIFRA_DB_WRITE_REFUSED", message)
+  }
+  if (state === "57014" || state === "55P03" || state === "25P03") {
+    return dbRefusal("NIFRA_DB_TIMEOUT", message)
+  }
+  if (state === "42501") {
+    return dbRefusal(
+      /for (table|view|relation|schema|sequence|materialized view|foreign table)\b/i.test(text)
+        ? "NIFRA_DB_TABLE_EXCLUDED"
+        : "NIFRA_DB_FUNCTION_REFUSED",
+      message,
+    )
+  }
+  if (/^(08|28|3D|53|57P|XX)/.test(state)) return dbRefusal("NIFRA_DB_DRIVER", message)
+  return dbRefusal("NIFRA_DB_QUERY_FAILED", message)
+}
+
+/** Validated milliseconds for a `SET LOCAL` (an integer, so it can be written into the text). */
+function millis(timeoutMs: number): number {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
+    throw new RangeError("timeoutMs must be a positive integer")
+  }
+  return timeoutMs
+}
+
+/**
+ * Run `work` inside `BEGIN READ ONLY` on one reserved connection, with the statement, lock and
+ * idle-in-transaction timeouts set for this transaction only. Always rolls back, so nothing a call
+ * does (a `set_config`, a session setting) outlives it.
+ */
+export async function inReadOnlyTransaction<T>(
+  client: PostgresClient,
+  timeoutMs: number,
+  work: (connection: PgConnection) => Promise<T | DbRefusal>,
+): Promise<T | DbRefusal> {
+  const ms = millis(timeoutMs)
+  let connection: PgConnection
+  try {
+    connection = await client.reserve()
+  } catch (error) {
+    return pgFailure(error, "could not connect")
+  }
+  try {
+    // nifra-expect sql-dynamic: fixed statements; the one interpolation is a validated integer of milliseconds
+    await connection.unsafe(
+      `BEGIN READ ONLY; SET LOCAL statement_timeout = ${ms}; SET LOCAL lock_timeout = ${ms}; SET LOCAL idle_in_transaction_session_timeout = ${ms}`,
+    )
+    return await work(connection)
+  } catch (error) {
+    return pgFailure(error)
+  } finally {
+    try {
+      await connection.unsafe("ROLLBACK")
+    } catch {
+      // A connection the server already closed has nothing to roll back.
+    }
+    connection.release()
+  }
+}
+
+/** A relation (or a function scanned as one) the plan reads, as the plan names it. */
+export interface PlanRelation {
+  readonly schema: string
+  readonly name: string
+}
+
+/** A column of a scanned relation that a plan expression names; `*` is a whole-row reference. */
+export interface PlanColumn {
+  readonly relation: PlanRelation
+  readonly column: string
+}
+
+/** What an `EXPLAIN (VERBOSE, FORMAT JSON)` plan reads, InitPlans and SubPlans included. */
+export interface PlanReads {
+  readonly relations: readonly PlanRelation[]
+  /** Functions in FROM (Function Scan nodes): a system view such as `pg_stat_activity` plans as one. */
+  readonly functions: readonly PlanRelation[]
+  /**
+   * Every relation column an expression of the plan uses: output, filter, join, sort or index
+   * condition. A verbose plan qualifies each one with its scan's unique alias, so an alias or an
+   * expression in the query still names the column it reads.
+   */
+  readonly columns: readonly PlanColumn[]
+  /**
+   * Outputs left out of `columns` because they may be a physical target list: a node under an
+   * aggregate, join or result emitting plain columns of one relation. The planner emits every column
+   * there whether or not the parent uses it, and the parent's own expressions name what it does use.
+   * When the list is not the relation's full column list, it is exactly what was asked for and counts.
+   */
+  readonly outputs: readonly PlanOutput[]
+}
+
+/** Plain columns of one relation that a node outputs, as listed. */
+export interface PlanOutput {
+  readonly relation: PlanRelation
+  readonly columns: readonly string[]
+}
+
+// Nodes that pass their child's rows up unchanged: whether a child's output is used is decided above.
+const PASS_THROUGH_NODES = new Set([
+  "Limit",
+  "Sort",
+  "Incremental Sort",
+  "Material",
+  "Memoize",
+  "Hash",
+  "Gather",
+  "Gather Merge",
+  "Unique",
+  "LockRows",
+])
+
+// Nodes whose own expressions a verbose plan prints in terms of the base columns they use.
+const PROJECTING_NODES = new Set([
+  "Aggregate",
+  "Group",
+  "WindowAgg",
+  "Nested Loop",
+  "Hash Join",
+  "Merge Join",
+  "Result",
+  "ProjectSet",
+])
+
+// Fields that name a node or a relation rather than hold an expression.
+const PLAN_NAME_FIELDS = new Set([
+  "Node Type",
+  "Relation Name",
+  "Schema",
+  "Alias",
+  "Index Name",
+  "CTE Name",
+  "Function Name",
+  "Subplan Name",
+  "Parent Relationship",
+])
+
+/** Every relation and every FROM-clause function a verbose JSON plan scans, and the columns it uses. */
+export function planReads(plan: unknown): PlanReads {
+  const relations = new Map<string, PlanRelation>()
+  const functions = new Map<string, PlanRelation>()
+  const aliases = new Map<string, PlanRelation>()
+  const expressions: string[] = []
+  // Outputs under a projecting parent, resolved once every alias is known.
+  const underProjection: (readonly string[])[] = []
+  const visit = (node: unknown, depth: number, projected: boolean): void => {
+    if (depth > 256 || typeof node !== "object" || node === null) return
+    if (Array.isArray(node)) {
+      for (const item of node) visit(item, depth + 1, projected)
+      return
+    }
+    const field = (key: string): unknown => Reflect.get(node, key)
+    const declared = field("Schema")
+    const schema = typeof declared === "string" ? declared : ""
+    for (const [key, found] of [
+      ["Relation Name", relations],
+      ["Function Name", functions],
+    ] as const) {
+      const name = field(key)
+      if (typeof name === "string") found.set(`${schema}.${name}`, { schema, name })
+    }
+    const relation = field("Relation Name")
+    const alias = field("Alias")
+    if (typeof relation === "string") {
+      aliases.set(typeof alias === "string" ? alias : relation, { schema, name: relation })
+    }
+    // A SubPlan's or InitPlan's result reaches its parent as `(SubPlan n)`, not as base columns.
+    const role = field("Parent Relationship")
+    const own = projected && role !== "SubPlan" && role !== "InitPlan"
+    for (const [key, value] of Object.entries(node)) {
+      if (PLAN_NAME_FIELDS.has(key)) continue
+      if (typeof value === "string") expressions.push(value)
+      else if (Array.isArray(value)) {
+        const texts = value.filter((item): item is string => typeof item === "string")
+        if (key === "Output" && own) underProjection.push(texts)
+        else expressions.push(...texts)
+      }
+    }
+    const type = String(field("Node Type"))
+    visit(field("Plan"), depth + 1, false)
+    visit(
+      field("Plans"),
+      depth + 1,
+      PASS_THROUGH_NODES.has(type) ? own : PROJECTING_NODES.has(type),
+    )
+  }
+  visit(plan, 0, false)
+
+  const outputs: PlanOutput[] = []
+  for (const list of underProjection) {
+    // Plain `alias.column` items of one relation (a dropped column shows as a NULL constant).
+    let relation: PlanRelation | undefined
+    const listed: string[] = []
+    for (const text of list) {
+      if (text.startsWith("NULL::")) continue
+      const tokens = lexPostgres(text).tokens
+      const [qualifier, dot, column] = tokens
+      const named = qualifier?.kind === "word" ? aliases.get(qualifier.value) : undefined
+      if (
+        tokens.length !== 3 ||
+        named === undefined ||
+        dot?.value !== "." ||
+        column?.kind !== "word" ||
+        (relation !== undefined && relation !== named)
+      ) {
+        relation = undefined
+        break
+      }
+      relation = named
+      listed.push(column.value)
+    }
+    if (relation !== undefined) outputs.push({ relation, columns: listed })
+    else expressions.push(...list)
+  }
+
+  const columns = new Map<string, PlanColumn>()
+  for (const text of expressions) {
+    const { tokens } = lexPostgres(text)
+    for (let i = 0; i + 2 < tokens.length; i++) {
+      const [qualifier, dot, column] = [tokens[i], tokens[i + 1], tokens[i + 2]]
+      if (qualifier?.kind !== "word" || dot?.kind !== "punct" || dot.value !== ".") continue
+      const relation = aliases.get(qualifier.value)
+      if (relation === undefined || column === undefined) continue
+      if (column.kind === "word" || (column.kind === "punct" && column.value === "*")) {
+        columns.set(`${relation.schema}.${relation.name}.${column.value}`, {
+          relation,
+          column: column.value,
+        })
+      }
+    }
+  }
+  return {
+    relations: [...relations.values()],
+    functions: [...functions.values()],
+    columns: [...columns.values()],
+    outputs,
+  }
+}
+
+/** The JSON document an `EXPLAIN (FORMAT JSON)` row carries, whatever the driver parsed it into. */
+export function planDocument(rows: readonly unknown[]): unknown {
+  const value = records(rows)[0]?.["QUERY PLAN"]
+  if (typeof value !== "string") return value
+  const parsed: unknown = JSON.parse(value)
+  return parsed
+}
+
+/** Refuse when anything the plan reads (or a table it inherits from) is out of scope. */
+export type ScopeCheck = (
+  connection: PgConnection,
+  reads: PlanReads,
+) => Promise<DbRefusal | undefined>
+
+/** Options for {@link fetchThroughCursor}. */
+export interface CursorOptions {
+  readonly maxRows: number
+  readonly scope: ScopeCheck
+}
+
+/**
+ * Declare the caller's query as a NO SCROLL cursor (the server accepts only SELECT/VALUES there and
+ * refuses a data-modifying WITH), check the plan's relations, then FETCH at most `maxRows + 1` rows.
+ *
+ * The query is wrapped as a subquery so each row also carries the result's column names: Bun returns
+ * array rows without names, and object rows lose a duplicated name. The wrapper's first column is a
+ * JSON array of the names, read from the first row.
+ */
+export async function fetchThroughCursor(
+  connection: PgConnection,
+  sql: string,
+  options: CursorOptions,
+): Promise<{ readonly columns: string[]; readonly rows: unknown[][] } | DbRefusal> {
+  const wrapped = `SELECT (SELECT json_agg(nifra_k)::text FROM json_object_keys(row_to_json(nifra_q)) AS nifra_k) AS nifra_columns, nifra_q.* FROM (\n${sql}\n) AS nifra_q`
+  await extended(connection, `DECLARE nifra_c NO SCROLL CURSOR FOR ${wrapped}`)
+  const plan = planDocument(await extended(connection, `EXPLAIN (VERBOSE, FORMAT JSON) ${wrapped}`))
+  const refusal = await options.scope(connection, planReads(plan))
+  if (refusal !== undefined) return refusal
+  const rowCap = options.maxRows + 1
+  const fetched =
+    // nifra-expect sql-dynamic: a fixed FETCH whose one interpolation is the integer row cap
+    (await connection.unsafe(`FETCH FORWARD ${rowCap} FROM nifra_c`).values()).filter(
+      (row): row is unknown[] => Array.isArray(row),
+    )
+  const first = fetched[0]?.[0]
+  const names: unknown = typeof first === "string" ? JSON.parse(first) : []
+  const columns = Array.isArray(names)
+    ? names.filter((name): name is string => typeof name === "string")
+    : []
+  return { columns, rows: fetched.map((row) => row.slice(1)) }
+}
+
+/** Options for {@link explainThroughServer}. */
+export interface ExplainOptions {
+  readonly analyze: boolean
+  readonly scope: ScopeCheck
+}
+
+/**
+ * Plan the caller's query. The cursor declaration runs first purely as the statement gate (then is
+ * closed), the VERBOSE plan feeds the scope check, and the returned plan is plain `FORMAT JSON` -
+ * with `analyze`, executed inside the same read-only transaction and timeout.
+ */
+export async function explainThroughServer(
+  connection: PgConnection,
+  sql: string,
+  options: ExplainOptions,
+): Promise<{ readonly plan: unknown } | DbRefusal> {
+  await extended(connection, `DECLARE nifra_c NO SCROLL CURSOR FOR ${sql}`)
+  await connection.unsafe("CLOSE nifra_c")
+  const verbose = planDocument(await extended(connection, `EXPLAIN (VERBOSE, FORMAT JSON) ${sql}`))
+  const refusal = await options.scope(connection, planReads(verbose))
+  if (refusal !== undefined) return refusal
+  const mode = options.analyze ? "ANALYZE, FORMAT JSON" : "FORMAT JSON"
+  return { plan: planDocument(await extended(connection, `EXPLAIN (${mode}) ${sql}`)) }
+}

package/src/internal/pg-lexer.ts

@@ -0,0 +1,279 @@
+/**
+ * A Postgres tokenizer for the parser layer of `@nifrajs/mcp-db/postgres`. It is the SECOND layer: the
+ * server already refuses several statements (extended protocol), anything but a query (the cursor),
+ * and writes (the read-only transaction). This layer adds what the server allows but a dev agent must
+ * not do: call a function that reaches outside the query (server files, locks, other sessions,
+ * settings, notifications, another database), or one that runs SQL from a string where the plan check
+ * cannot see it (`query_to_xml`).
+ *
+ * The lexer follows Postgres with `standard_conforming_strings = on`, which the engine sets on every
+ * connection so the server reads string boundaries exactly as this lexer does.
+ */
+
+/** One lexical unit. Strings, comments and dollar-quoted bodies produce nothing. */
+export interface PgToken {
+  readonly kind: "word" | "punct" | "number" | "param"
+  /** Identifier text (quotes removed, `""` collapsed) or the punctuation character. */
+  readonly value: string
+  /** An unquoted word - the only kind that can be a keyword. */
+  readonly bare: boolean
+  /** Where the token starts in the source. */
+  readonly offset: number
+}
+
+export interface PgLexResult {
+  readonly tokens: readonly PgToken[]
+  /** A string, quoted identifier, comment or dollar-quoted body never closed. */
+  readonly unterminated: boolean
+  /** A `U&"..."` identifier: its escapes can spell any name, so it is refused outright. */
+  readonly unicodeIdentifier: boolean
+}
+
+const WORD_START = /[A-Za-z_\u0080-￿]/
+const WORD_PART = /[A-Za-z0-9_$\u0080-￿]/
+const DOLLAR_TAG = /^\$(?:[A-Za-z_\u0080-￿][A-Za-z0-9_\u0080-￿]*)?\$/
+
+/** Tokenize Postgres SQL far enough to see statements, parentheses and function calls. */
+export function lexPostgres(sql: string): PgLexResult {
+  const tokens: PgToken[] = []
+  let unterminated = false
+  let unicodeIdentifier = false
+  let i = 0
+  const skipString = (escapes: boolean): void => {
+    i++ // past the opening quote
+    while (i < sql.length) {
+      const char = sql[i]
+      if (escapes && char === "\\") {
+        i += 2
+        continue
+      }
+      if (char === "'") {
+        if (sql[i + 1] === "'") {
+          i += 2
+          continue
+        }
+        i++
+        return
+      }
+      i++
+    }
+    unterminated = true
+  }
+  while (i < sql.length) {
+    const char = sql.charAt(i)
+    const next = sql[i + 1]
+    if (/\s/.test(char)) {
+      i++
+    } else if (char === "-" && next === "-") {
+      const end = sql.indexOf("\n", i)
+      i = end === -1 ? sql.length : end + 1
+    } else if (char === "/" && next === "*") {
+      // Postgres block comments nest.
+      let depth = 1
+      i += 2
+      while (i < sql.length && depth > 0) {
+        if (sql[i] === "/" && sql[i + 1] === "*") {
+          depth++
+          i += 2
+        } else if (sql[i] === "*" && sql[i + 1] === "/") {
+          depth--
+          i += 2
+        } else i++
+      }
+      if (depth > 0) unterminated = true
+    } else if (char === "'") {
+      skipString(false)
+    } else if ((char === "E" || char === "e") && next === "'") {
+      i++
+      skipString(true)
+    } else if ((char === "U" || char === "u") && next === "&" && sql[i + 2] === "'") {
+      i += 2
+      skipString(false)
+    } else if ((char === "U" || char === "u") && next === "&" && sql[i + 2] === '"') {
+      unicodeIdentifier = true
+      i += 2
+    } else if (
+      (char === "B" ||
+        char === "b" ||
+        char === "X" ||
+        char === "x" ||
+        char === "N" ||
+        char === "n") &&
+      next === "'"
+    ) {
+      i++
+      skipString(false)
+    } else if (char === '"') {
+      const offset = i
+      let value = ""
+      let closed = false
+      i++
+      while (i < sql.length) {
+        if (sql[i] === '"') {
+          if (sql[i + 1] === '"') {
+            value += '"'
+            i += 2
+            continue
+          }
+          i++
+          closed = true
+          break
+        }
+        value += sql[i]
+        i++
+      }
+      if (!closed) unterminated = true
+      tokens.push({ kind: "word", value, bare: false, offset })
+    } else if (char === "$") {
+      const tag = DOLLAR_TAG.exec(sql.slice(i, i + 64))?.[0]
+      if (tag !== undefined) {
+        const end = sql.indexOf(tag, i + tag.length)
+        if (end === -1) {
+          unterminated = true
+          i = sql.length
+        } else i = end + tag.length
+      } else if (next !== undefined && next >= "0" && next <= "9") {
+        const start = i
+        i++
+        while (i < sql.length && /[0-9]/.test(sql.charAt(i))) i++
+        tokens.push({ kind: "param", value: sql.slice(start, i), bare: false, offset: start })
+      } else {
+        tokens.push({ kind: "punct", value: char, bare: false, offset: i })
+        i++
+      }
+    } else if (WORD_START.test(char)) {
+      const start = i
+      while (i < sql.length && WORD_PART.test(sql.charAt(i))) i++
+      tokens.push({ kind: "word", value: sql.slice(start, i), bare: true, offset: start })
+    } else if (
+      (char >= "0" && char <= "9") ||
+      (char === "." && next !== undefined && /[0-9]/.test(next))
+    ) {
+      // Digits only: a letter right after a number starts a new word, so `1pg_sleep(` still shows
+      // the call (older servers lex it the same way).
+      const start = i
+      while (i < sql.length && /[0-9_.]/.test(sql.charAt(i))) i++
+      if ((sql[i] === "e" || sql[i] === "E") && /[0-9+-]/.test(sql[i + 1] ?? "")) {
+        i += 2
+        while (i < sql.length && /[0-9]/.test(sql.charAt(i))) i++
+      }
+      tokens.push({ kind: "number", value: sql.slice(start, i), bare: false, offset: start })
+    } else {
+      tokens.push({ kind: "punct", value: char, bare: false, offset: i })
+      i++
+    }
+  }
+  return { tokens, unterminated, unicodeIdentifier }
+}
+
+/**
+ * Function-name prefixes the parser layer refuses. Each reaches outside a read-only query or runs SQL
+ * from a string the plan check cannot see; the server lets a read-only transaction call most of them.
+ */
+export const DENIED_FUNCTION_PREFIXES: readonly string[] = [
+  "dblink",
+  "lo_",
+  "pg_read_",
+  "pg_ls_",
+  "pg_stat_file",
+  "pg_terminate_backend",
+  "pg_cancel_backend",
+  "pg_reload_conf",
+  "set_config",
+  "pg_advisory",
+  "pg_try_advisory",
+  "pg_notify",
+  "query_to_xml",
+  "table_to_xml",
+  "cursor_to_xml",
+  "schema_to_xml",
+  "database_to_xml",
+  "pg_file_",
+  "pg_logical_emit_message",
+  "pg_stat_reset",
+  "pg_stat_get_",
+  "pg_switch_wal",
+  "pg_create_restore_point",
+  "pg_promote",
+  "pg_rotate_logfile",
+  "nextval",
+  "setval",
+]
+
+const READ_HEADS = new Set(["select", "with", "values", "table"])
+const LOCKING_STRENGTHS = new Set(["update", "share", "no", "key"])
+
+/** Why the parser layer refused a statement. */
+export type PgLintRefusal =
+  | { readonly kind: "statement"; readonly message: string }
+  | { readonly kind: "function"; readonly message: string; readonly name: string }
+
+/**
+ * Lint one statement: a single read-only query with balanced parentheses, no unicode-escaped
+ * identifier and no denied function call. `undefined` when it passes.
+ */
+export function lintPostgres(sql: string): PgLintRefusal | undefined {
+  const { tokens, unterminated, unicodeIdentifier } = lexPostgres(sql)
+  if (unterminated) {
+    return { kind: "statement", message: "the statement has an unterminated string or comment" }
+  }
+  if (unicodeIdentifier) {
+    return { kind: "statement", message: 'unicode-escaped identifiers (U&"...") are not accepted' }
+  }
+  const terminator = tokens.findIndex((token) => token.kind === "punct" && token.value === ";")
+  if (terminator !== -1 && tokens.slice(terminator + 1).length > 0) {
+    return { kind: "statement", message: "only a single statement is allowed" }
+  }
+  const body = terminator === -1 ? tokens : tokens.slice(0, terminator)
+  const head = body.find((token) => !(token.kind === "punct" && token.value === "("))
+  if (head === undefined) return { kind: "statement", message: "empty query" }
+  if (!head.bare || !READ_HEADS.has(head.value.toLowerCase())) {
+    return {
+      kind: "statement",
+      message: `only a read-only query (SELECT, WITH, VALUES or TABLE) is allowed, not ${head.value.toUpperCase()}`,
+    }
+  }
+  let depth = 0
+  for (const [index, token] of body.entries()) {
+    if (token.kind !== "punct" && token.kind !== "word") continue
+    const next = body[index + 1]
+    if (
+      token.bare &&
+      token.value.toLowerCase() === "for" &&
+      next?.bare === true &&
+      LOCKING_STRENGTHS.has(next.value.toLowerCase())
+    ) {
+      return {
+        kind: "statement",
+        message: "row-locking clauses (FOR UPDATE, FOR SHARE) are refused: they take locks",
+      }
+    }
+    if (token.value === "(" && token.kind === "punct") {
+      depth++
+      const callee = body[index - 1]
+      if (callee?.kind === "word") {
+        const name = callee.value.toLowerCase()
+        if (DENIED_FUNCTION_PREFIXES.some((prefix) => name.startsWith(prefix))) {
+          return {
+            kind: "function",
+            name,
+            message: `${name}() is refused: it reaches outside a read-only query`,
+          }
+        }
+      }
+    } else if (token.value === ")" && token.kind === "punct") {
+      depth--
+      if (depth < 0) {
+        return { kind: "statement", message: "the statement closes a parenthesis it never opened" }
+      }
+    }
+  }
+  if (depth !== 0) return { kind: "statement", message: "the statement leaves a parenthesis open" }
+  return undefined
+}
+
+/** The statement without a final `;` (comments after it included), ready to wrap in a subquery. */
+export function withoutTerminator(sql: string): string {
+  const last = lexPostgres(sql).tokens.at(-1)
+  return last?.kind === "punct" && last.value === ";" ? sql.slice(0, last.offset) : sql
+}